Merge branch 'stack/agent-profiles-5-web-ui' into stack/agent-profiles-8-authoring

# Conflicts:
#	apps/cli/tests/web-agent-presets.e2e.ts
#	packages/client/connection/README.i18n.yaml
#	packages/client/connection/README.md
#	packages/client/connection/README.zh.md
#	packages/client/ui-conversation/src/client/contract/slots.ts
#	packages/client/ui-primitives/tests/icons.spec.tsx
#	packages/client/ui-settings/src/client/contract/slots.ts
#	packages/host/apiproxy/tests/api-proxy-agent-preset.spec.ts

apps/web/tests/approval-composer.e2e.ts

@@ -9,8 +9,8 @@
 // model content as the question composer: the turn cannot complete without it).
 //
 // Geometry is the point of the scenario. The command is unbounded model text,
-// and before the cap a long one grew the card until the refuse/allow buttons
-// left the viewport — an approval the user could see and not answer.
+// and an uncapped card grows with it until the refuse/allow buttons leave the
+// viewport — an approval the user could see and not answer.
 import { readFile } from 'node:fs/promises'
 import { fileURLToPath } from 'node:url'
 import { join } from 'node:path'
@@ -36,8 +36,8 @@ const MODE = webSnapshotMode()
 
 // Irreducible payload: the command has to be long enough to pass the card's
 // height cap, which is the only shape that reproduces an action row pushed off
-// screen. Unrelated tokens, not a repeated word — a repeated word is what the
-// model compressed into `printf 'alpha %.0s' {1..400}` while recording, and a
+// screen. Unrelated tokens, not a repeated word — the model compresses a
+// repeated word into `printf 'alpha %.0s' {1..400}` when recording, and a
 // short command proves nothing here. The formula keeps the source small; the
 // model receives the expanded literal it has to put in the command.
 const TOKENS = Array.from({ length: 220 }, (_, index) => `tok${((index + 1) * 7919 % 99991).toString(36)}`).join(' ')
@@ -115,9 +115,8 @@ describe('web e2e: approval takeover keeps its actions reachable', () => {
       const snapshot = await captureStableAria(page, '[data-approval-key]', scaffold.workspaceCwd)
       await compareOrRefreshGolden(UI_EXPECTED, snapshot, MODE)
 
-      // The regression this scenario exists for: an uncapped card grew with
-      // the command until the action row left the viewport. Measured at the
-      // lane baseline and at a short viewport, on the live panel.
+      // The uncapped-card hazard the header names, measured at the lane
+      // baseline and at a short viewport, on the live panel.
       const original = page.viewportSize() ?? { width: 1680, height: 1000 }
       for (const height of [1000, 700]) {
         await page.setViewportSize({ width: 900, height })

apps/web/tests/chat-long-interactions.e2e.ts

@@ -1,6 +1,7 @@
-// Long-history Chat behavior contract for a future virtualized renderer. Wheel
-// input only navigates to the semantic target; assertions pin content identity
-// and interaction routing rather than scroll geometry or mounted row counts.
+// Long-history Chat behavior contract that stays valid under a virtualized
+// renderer: wheel input only navigates to the semantic target; assertions pin
+// content identity and interaction routing rather than scroll geometry or
+// mounted row counts.
 import { mkdtemp, rm, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'

apps/web/tests/code-mode-round.e2e.ts

@@ -26,7 +26,7 @@ const MODE = webSnapshotMode()
 
 // The scenario's one drive prompt: elicits one program with a bash sub-call
 // and a failing read the program tolerates — the sub-row set the assertions
-// (and the PR gif) need. Never asserted against model prose.
+// need. Never asserted against model prose.
 const PROMPT = 'Using ONE run_code program: run bash `echo CODE_ROUND_OK`, then read the file missing.txt '
   + 'catching its error in the program. Return an object with both outcomes. Then reply DONE and stop.'
 
@@ -104,7 +104,7 @@ describe('web e2e: Code Mode round renders nested sub-calls', () => {
     onTestFailed(() => saveFailureShot(page, 'web-e2e-code-mode-rows'))
     await expect.poll(() => page.getByText('DONE', { exact: true }).count(), { timeout: 15_000 }).toBeGreaterThanOrEqual(1)
     // The parent run_code row wears the code variant with the model-authored
-    // description as its summary (the PR1 presentCall contract).
+    // description as its summary (the presentCall contract).
     const codeRow = page.locator('[data-variant="code"]').first()
     await codeRow.waitFor({ timeout: 10_000 })
     // Nested rows are visible WITHOUT any expand interaction, inside the

apps/web/tests/composer-draft-scroll.e2e.ts

@@ -8,7 +8,7 @@
 // `[data-input-backdrop]` div underneath it, which also carries the claim-token
 // highlight, the chips and the ghost hint.
 //
-// Two layers can only stay together by moving together. They now do: both sit
+// Two layers can only stay together by moving together. They do: both sit
 // inside `[data-input-scroll]`, the composer's single scrolling box, and are as
 // tall as the whole draft — so one offset, applied by the browser, moves the
 // caret and the words in the same frame. Scrolling the textarea and assigning
@@ -192,7 +192,7 @@ function measureComposer(page: Page): Promise<ComposerMetrics> {
  * Absolute glyph coordinates are deliberately absent: they depend on font
  * metrics and would make the fixture fail on a machine that measures text
  * differently — a golden that needs re-recording per platform documents the
- * platform, not the change. What is recorded is the cap, the caret-to-glyph
+ * platform, not the behavior. What is recorded is the cap, the caret-to-glyph
  * relation, and which lines are on screen, each a comparison that survives any
  * layout keeping the coupling.
  * @param top - metrics with the draft scrolled to its start.
@@ -297,10 +297,10 @@ describe('web e2e: composer draft scrolling', () => {
     onTestFailed(() => saveFailureShot(page, 'web-e2e-composer-draft-scroll-wrap-width'))
     // A layer that breaks lines somewhere else puts the words under the wrong
     // caret, and an 8px difference is worth 2 to 5 lines on a wrap-sensitive
-    // draft. The three now share a containing block — the scrollport — so a
-    // scrollbar that consumes layout space costs them the same width; before,
-    // only the textarea scrolled, and WebKit reserved gutter space for it alone
-    // (768 against 776) while chromium and firefox did not.
+    // draft. All three share a containing block — the scrollport — so a
+    // scrollbar that consumes layout space costs them the same width; with
+    // only the textarea scrolling, WebKit reserves gutter space for it alone
+    // (768 against 776) while chromium and firefox do not.
     const metrics = await measureComposer(page)
     expect(metrics.backdropWrapWidth).toBe(metrics.inputWrapWidth)
     // The mirror decides the box height, so it belongs in the same equality —
@@ -315,7 +315,7 @@ describe('web e2e: composer draft scrolling', () => {
     // The reported symptom, isolated. A scroll offset changes and the caret's
     // distance to its own glyphs is re-read before the task ends — before any
     // `scroll` listener could have run. With the layers on one scrollport the
-    // browser moved both, so the distance is unchanged; with the glyph layer
+    // browser moves both, so the distance is unchanged; with the glyph layer
     // catching up in a listener it is off by the whole delta until a later
     // frame, which is a caret flying away from its text mid-gesture.
     const metrics = await measureComposer(page)
@@ -348,9 +348,10 @@ describe('web e2e: composer draft scrolling', () => {
   it('typing at the end of a scrolled draft brings the caret back into view', async () => {
     onTestFailed(() => saveFailureShot(page, 'web-e2e-composer-draft-scroll-edit'))
     // The other way the box moves, and the one that depends on the browser: the
-    // textarea no longer scrolls, so revealing the caret after an edit is a
-    // scroll-into-view that has to walk up to the scrollport. Scroll away from
-    // the caret first, so the edit has somewhere to bring it back from.
+    // textarea holds no scroll offset of its own, so revealing the caret after
+    // an edit is a scroll-into-view that has to walk up to the scrollport.
+    // Scroll away from the caret first, so the edit has somewhere to bring it
+    // back from.
     const input = page.locator('textarea:enabled').first()
     await input.press('End')
     await input.hover()
@@ -368,9 +369,9 @@ describe('web e2e: composer draft scrolling', () => {
     onTestFailed(() => saveFailureShot(page, 'web-e2e-composer-draft-scroll-paste'))
     // The composer suppresses the native paste — the machine owns the draft and
     // the undo log — and restores the caret programmatically, which reveals
-    // nothing on its own: measured in chromium and WebKit, the view stayed
-    // where it was while the caret sat at the end of the pasted block. The
-    // restore now scrolls it into view, and this is the case that proves it.
+    // nothing on its own: in chromium and WebKit the view stays put while the
+    // caret sits at the end of the pasted block, so the restore scrolls it
+    // into view; this case pins it.
     const input = page.locator('textarea:enabled').first()
     await input.fill('one short line')
     await input.press('End')

apps/web/tests/composer-tab-geometry.e2e.ts

@@ -11,12 +11,12 @@
 // gets an absolutely positioned seat instead, laid out against the padding box,
 // which the scrollbar never reduces.
 //
-// So the two tabs disagreed by exactly the bar's width for as long as the
-// transcript overflowed: the card jumped sideways on every tab switch, and
-// inside Chat alone at the moment a growing transcript started to scroll. The
-// column now reserves the gutter unconditionally (`scrollbar-gutter: stable`)
-// and states the overlay branch as a scroll container on the same axes, so both
-// edges are the same edge.
+// Without a shared reservation the two tabs disagree by exactly the bar's
+// width for as long as the transcript overflows: the card jumps sideways on
+// every tab switch, and inside Chat alone at the moment a growing transcript
+// starts to scroll. The column reserves the gutter unconditionally
+// (`scrollbar-gutter: stable`) and states the overlay branch as a scroll
+// container on the same axes, so both edges are the same edge.
 //
 // Only a real engine can show this. The seat's geometry is layout: jsdom gives
 // every element a zero-sized box and reports no scrollbar at all, so a unit spec
@@ -26,14 +26,14 @@
 //
 // The browser is launched WITHOUT Playwright's default `--hide-scrollbars`,
 // which is load-bearing rather than incidental. Under that argument a scroll
-// container's bar consumes no layout width at all, so the two tabs agree before
-// this change as much as after it and every comparison below holds vacuously —
-// measured: the pre-fix cascade leaves both tabs' bands at 0 there, against 8
-// and 0 with the argument dropped. Dropping it is also the faithful
+// container's bar consumes no layout width at all, so the two tabs agree with
+// and without the reservation and every comparison below holds vacuously —
+// measured: the unreserved cascade leaves both tabs' bands at 0 there, against
+// 8 and 0 with the argument dropped. Dropping it is also the faithful
 // configuration: ui-theme's scrollbar.css gives `::-webkit-scrollbar` a width,
 // and a bar that occupies layout space is what the product actually draws.
 //
-// The scenario runs that pre-fix cascade in the page — `scrollbar-gutter: auto`
+// The scenario runs that unreserved cascade in the page — `scrollbar-gutter: auto`
 // on the scroller, `overflow: hidden` on the overlay branch — and measures the
 // same two tabs through it, which is what keeps the equal rectangles above from
 // being explained by a tab switch that never reached the layout. It is the
@@ -64,7 +64,7 @@ const SNAPSHOT_DIR = fileURLToPath(new URL('./snapshots/composer-tab-geometry',
  * that has to be re-recorded per platform. What is recorded is the distance
  * between the two tabs' rectangles, which is zero when the reservation holds and
  * the bar's width when it does not — including under the control, so the golden
- * carries the difference the fix removes rather than only its absence.
+ * carries the shift the unreserved cascade produces rather than only its absence.
  */
 const GEOMETRY_EXPECTED = join(SNAPSHOT_DIR, 'geometry.expected.md')
 const MODE = webSnapshotMode()
@@ -114,10 +114,10 @@ async function setMeasuredViewport(
 }
 
 /**
- * The pre-fix cascade, injected into the page: the reservation dropped and the
- * overlay branch back to a hidden box. `!important` beats the module rules
- * without a rebuild, and the id lets the control be lifted again in the same
- * session.
+ * The unreserved cascade, injected into the page: the reservation dropped and
+ * the overlay branch forced to a hidden box. `!important` beats the module
+ * rules without a rebuild, and the id lets the control be lifted again in the
+ * same session.
  */
 const CONTROL_STYLE_ID = 'composer-tab-geometry-control'
 const CONTROL_CSS = `
@@ -221,9 +221,9 @@ async function compareTabs(page: Page): Promise<TabComparison> {
 }
 
 /**
- * Run the pre-fix cascade in the page for one measurement, then lift it.
+ * Run the unreserved cascade in the page for one measurement, then lift it.
  * @param page - the page under test.
- * @returns the comparison as the column laid out before this change.
+ * @returns the comparison as the column lays out without the reservation.
  */
 async function compareTabsWithoutReservation(page: Page): Promise<TabComparison> {
   await page.evaluate(({ id, css }) => {
@@ -328,7 +328,7 @@ describe('web e2e: input card position across view tabs', () => {
     await expect.poll(async () => (await measureTab(page)).scrolls, { timeout: 10_000 }).toBe(true)
     const comparison = await compareTabs(page)
     expect(comparison.chat.band).toBeGreaterThan(0)
-    // The reservation reaches both states, which is the whole change: the same
+    // The reservation reaches both states, which is the whole point: the same
     // band, on a box that scrolls and on one that only holds a view.
     expect(comparison.chat.gutter).toBe('stable')
     expect(comparison.trajectory.gutter).toBe('stable')
@@ -348,8 +348,8 @@ describe('web e2e: input card position across view tabs', () => {
     await setMeasuredViewport(page, WIDE_VIEWPORT, false)
     const comparison = await compareTabs(page)
     // The reported symptom as a number. At this viewport the card sits at its
-    // width cap, so the pre-fix shift showed up as a centring difference — half
-    // the band on each edge — rather than as a width change.
+    // width cap, so the unreserved cascade's shift shows up as a centring
+    // difference — half the band on each edge — rather than as a width change.
     expect(comparison.leftShift).toBe(0)
     expect(comparison.rightShift).toBe(0)
     expect(comparison.widthShift).toBe(0)
@@ -363,7 +363,7 @@ describe('web e2e: input card position across view tabs', () => {
     await setMeasuredViewport(page, NARROW_VIEWPORT, true)
     const comparison = await compareTabs(page)
     // The other geometry, and a different failure: below the cap the card takes
-    // the column's width, so an unreserved gutter changed its WIDTH by the whole
+    // the column's width, so an unreserved gutter changes its WIDTH by the whole
     // band instead of shifting it by half. Asserted against the capped
     // measurement rather than against the cap's pixel value, which belongs to
     // the stylesheet.
@@ -379,17 +379,17 @@ describe('web e2e: input card position across view tabs', () => {
     onTestFailed(() => saveFailureShot(page, 'web-e2e-composer-tab-geometry-control'))
     await setMeasuredViewport(page, WIDE_VIEWPORT, false)
     // The control: without it, equal rectangles could also mean the tab switch
-    // never reached the layout. Under the pre-fix cascade the Chat scroller keeps
-    // its bar and the Trajectory branch goes back to a hidden box with none, and
-    // the card moves by half the band on each edge.
+    // never reached the layout. Under the unreserved cascade the Chat scroller
+    // keeps its bar and the Trajectory branch becomes a hidden box with none,
+    // and the card moves by half the band on each edge.
     const comparison = await compareTabsWithoutReservation(page)
     expect(comparison.chat.gutter).toBe('auto')
     expect(comparison.chat.band).toBeGreaterThan(0)
     expect(comparison.trajectory.band).toBe(0)
     expect(comparison.leftShift).toBe(comparison.chat.band / 2)
     expect(comparison.rightShift).toBe(comparison.chat.band / 2)
-    // Restoring the sheet restores the fix, so the control cannot leak into the
-    // remaining measurements.
+    // Restoring the sheet restores the reservation, so the control cannot leak
+    // into the remaining measurements.
     const restored = await compareTabs(page)
     expect(restored.leftShift).toBe(0)
     expect(tripwire.pageErrors).toEqual([])

apps/web/tests/conversation-column-overflow.e2e.ts

@@ -1,15 +1,15 @@
 // Web e2e scenario: the conversation column scrolls on one axis only, as the
-// browser actually lays it out. The reported symptom was a horizontal
-// scrollbar under the whole center column once the window (or the sidebar
-// drag) narrowed it — the hero's decorative backdrop ellipse bleeding past the
-// column and becoming user-scrollable.
+// browser actually lays it out. The hazard: a horizontal scrollbar appears
+// under the whole center column once the window (or the sidebar drag) narrows
+// it — the hero's decorative backdrop ellipse bleeds past the column and
+// becomes user-scrollable.
 //
 // The bleed is by construction and stays: `.heroGlow` is sized 1051/776 of the
 // hero box (ConversationRoot.module.css) so the blur scales with the input
-// card. What changed is the scroll container: `[data-conversation-scroll]`
-// scrolls vertically, and a box that scrolls in one axis computes the other
-// axis's initial `visible` to `auto`, so the bleed came back as a bar. The
-// fix states `overflow-x: hidden` there.
+// card. The scroll container is where the bar comes from:
+// `[data-conversation-scroll]` scrolls vertically, and a one-axis scroller
+// computes the other axis's initial `visible` to `auto`, so the bleed becomes
+// a bar; `overflow-x: hidden` on the scroller prevents it.
 //
 // Only a real engine reports that pair — the bleed and the resulting scroll
 // range — so the scenario sweeps viewport widths that bracket the glow's
@@ -36,7 +36,7 @@ const SNAPSHOT_DIR = fileURLToPath(new URL('./snapshots/conversation-column-over
  * Committed golden of the one-axis relation at every stop. It records
  * relations and booleans, never absolute coordinates: the column width follows
  * the viewport and the sidebar, and a golden carrying pixels would document the
- * platform instead of the change.
+ * platform instead of the behavior.
  */
 const GEOMETRY_EXPECTED = join(SNAPSHOT_DIR, 'geometry.expected.md')
 const MODE = webSnapshotMode()
@@ -60,17 +60,20 @@ interface ColumnMetrics {
   columnWidth: number
   /** Resolved `overflow-x` on the conversation scroll container. */
   overflowX: string
-  /** True when the glow's box reaches past the column's content edge — the condition the fix has to survive. */
+  /**
+   * True when the glow's box reaches past the column's content edge — the
+   * condition the `overflow-x: hidden` declaration has to survive.
+   */
   glowBleeds: boolean
   /**
    * `scrollWidth - clientWidth`. Deliberately NOT the assertion: `hidden` and
    * `auto` both report the same value, because `hidden` clips the bleed rather
    * than reflowing it away. Recorded because it is the vacuity guard in
    * numbers — it must stay positive at the narrow stops, or the scenario has
-   * stopped reproducing the situation the fix is for.
+   * stopped reproducing the situation `overflow-x: hidden` exists for.
    */
   bleedRange: number
-  /** True when the column still scrolls vertically — the axis the fix must not take away. */
+  /** True when the column still scrolls vertically — the axis `overflow-x: hidden` must not take away. */
   scrollsVertically: boolean
 }
 
@@ -108,9 +111,10 @@ function measureColumn(page: Page, width: number): Promise<ColumnMetrics> {
  * This is the one signal that separates the two states, and it is why the
  * scenario needs a real engine: `overflow-x: hidden` leaves the box
  * programmatically scrollable and leaves `scrollWidth` untouched, so every
- * property reading agrees across the fix. Only refusing an actual input event
- * differs — measured at the 1200px stop, the shipped column stays at 0 while
- * the same page with `overflow-x: auto` forced on lands at its scroll boundary.
+ * property reading agrees across the two overflow modes. Only refusing an
+ * actual input event differs — measured at the 1200px stop, the shipped
+ * column stays at 0 while the same page with `overflow-x: auto` forced on
+ * lands at its scroll boundary.
  * @param page - the page under test.
  * @returns `scrollLeft` after one horizontal wheel over the column.
  */
@@ -175,10 +179,10 @@ type ColumnStop = ColumnMetrics & {
  * Render the golden body: one line per stop, relations only.
  *
  * Absolute pixels are deliberately absent apart from `scrollLeftAfterWheel`,
- * which the fix pins to 0 by construction. The bleed is recorded as a boolean
- * rather than its width, so the golden survives any platform whose column
- * lands a pixel off — a fixture that has to be re-recorded per platform
- * documents the platform, not the change.
+ * which the shipped overflow mode pins to 0 by construction. The bleed is
+ * recorded as a boolean rather than its width, so the golden survives any
+ * platform whose column lands a pixel off — a fixture that has to be
+ * re-recorded per platform documents the platform, not the behavior.
  * @param stops - the measured stops, in sweep order.
  * @returns the golden body, without a trailing newline.
  */
@@ -272,18 +276,19 @@ describe('web e2e: the conversation column scrolls on one axis', () => {
       // The reported symptom, stated directly: a horizontal wheel over the
       // column moves nothing, at every stop.
       expect(stop.scrollLeftAfterWheel, `viewport ${String(stop.width)}`).toBe(0)
-      // The axis the column is a scroller for must survive the fix.
+      // The axis the column is a scroller for must survive `overflow-x: hidden`.
       expect(stop.scrollsVertically, `viewport ${String(stop.width)}`).toBe(true)
     }
     expect(tripwire.pageErrors).toEqual([])
   }, 120_000)
 
-  it('reports the pre-fix state when the axis is opened back up', async () => {
+  it('scrolls horizontally again once the axis is opened back up (control)', async () => {
     onTestFailed(() => saveFailureShot(page, 'web-e2e-conversation-column-overflow-control'))
     // The mutation control, run in the page rather than against a second
-    // build: it restores exactly what the fix changed — the initial `visible`
-    // that a one-axis scroller computes to `auto` — and shows the same gesture,
-    // at the same timing, carrying the column to its positive scroll boundary.
+    // build: it lifts exactly the `overflow-x: hidden` declaration, so the
+    // initial `visible` that a one-axis scroller computes to `auto` takes
+    // over, and shows the same gesture, at the same timing, carrying the
+    // column to its positive scroll boundary.
     // Without it a `scrollLeft` of 0 could equally mean the wheel never arrived.
     // Injected with an id rather than through `addStyleTag`, so the teardown
     // below can take the sheet out again by selector: it must not outlive this

apps/web/tests/default-model.overlay.yml

@@ -1,6 +1,6 @@
 # The fixture-less web scaffold registers no adapter, so the shipped
 # deepseek-official default would be a route nothing serves — which the
-# composer now correctly refuses to type into. This scenario declares its own
+# composer refuses to type into. This scenario declares its own
 # pi-ai routes and starts the default on one of them.
 - id: agent-default-model
   config:

apps/web/tests/lifecycle-chrome.e2e.ts

@@ -6,9 +6,10 @@
 // client; THIS spec pins the same flow through HTTP RPC + SSE + the host
 // gateway), reload replays everything from the log (zero further model
 // calls), and the theme scenario proves the shipped dark palette actually
-// cascades: attribute -> alias token flip -> painted surface change. Per the
-// lane's scope ruling there is no theme/layout golden (aria is color-blind);
-// the hero's waiting state gets the one golden here.
+// cascades: attribute -> alias token flip -> painted surface change. No
+// theme/layout golden: aria snapshots are color-blind (lane scope: the
+// browser-e2e-lane Agent Note); the hero's waiting state gets the one golden
+// here.
 import { readFile } from 'node:fs/promises'
 import { fileURLToPath } from 'node:url'
 import { join } from 'node:path'
@@ -112,8 +113,8 @@ describe('web e2e: lifecycle & chrome (workspace flow / reload / dark mode)', ()
       const planButton = activePage.getByRole('button', { name: 'Plan mode on, press to turn off' })
       await planButton.waitFor({ timeout: 10_000 })
       // The golden encodes an empty composer, and the button arriving does not
-      // mean the submitted text is gone yet: under load the capture caught a
-      // textbox still holding `/plan`.
+      // mean the submitted text is gone yet: under load the capture can catch
+      // a textbox still holding `/plan`.
       await expect.poll(() => input.inputValue(), { timeout: 10_000 }).toBe('')
       const planSnapshot = await captureStableAria(activePage, '[class*="frame"]', activeScaffold.workspaceCwd)
       await compareOrRefreshGolden(PLAN_ACTIVE_EXPECTED, planSnapshot, MODE)

apps/web/tests/models-settings.e2e.ts

@@ -85,8 +85,9 @@ describe('web e2e: Models settings page configures a dormant provider', () => {
     const key = dialog.getByLabel('API 密钥')
     const save = dialog.getByRole('button', { name: '保存', exact: true })
 
-    // The paste that used to save cleanly and then fail the first turn with a
-    // ByteString TypeError now names the field that holds it.
+    // A key no HTTP header can carry would save cleanly and fail the first
+    // turn with a ByteString TypeError; the form names the offending field
+    // instead.
     await key.fill('sk-\u{1F600}minimax')
     await dialog.getByText('该 API 密钥格式错误，请检查。').waitFor({ timeout: 10_000 })
     await expect.poll(async () => save.isEnabled(), { timeout: 10_000 }).toBe(false)

apps/web/tests/navigation-panes.e2e.ts

@@ -331,7 +331,7 @@ describe('web e2e: navigation & panes over a rich seeded session', () => {
     // Real layout, not jsdom's stub (which computes no geometry at all):
     // squeeze the output pane below its content width and the line must keep
     // its single row and overflow sideways instead of folding. Soft-wrapping
-    // here is what shredded the column alignment this card exists to hold.
+    // here shreds the column alignment this card exists to hold.
     const layout = await card.locator('[class*="_output_"]').first().evaluate((node) => {
       const pane = node as HTMLElement
       const row = pane.querySelector<HTMLElement>('[class*="_line_"]')

apps/web/tests/pin-browse-picker.overlay.yml

@@ -1,4 +1,4 @@
-# Loader overlay for the W5 real-host smoke (`dsh web --patch`): pin the
+# Loader overlay for the real-host smoke (`dsh web --patch`): pin the
 # in-browser directory picker. The shipped row is `-auto`, which resolves to
 # the native OS chooser on a loopback bind with a local display — an
 # interaction a Playwright page cannot drive, so the resolved backend would

apps/web/tests/pwsh-terminal.e2e.ts

@@ -2,8 +2,8 @@
 // whose pwsh call/result is presented by the REAL tool-pwsh on replay (the
 // api-proxy recomputes presentation views from logged args/result content)
 // must render as a bash-shaped terminal card with the parsed exit-status
-// pill — not the generic console-fenced card the pwsh presenter used to
-// emit. The seed is authored, not recorded: its header line carries no `cwd`
+// pill — not a generic console-fenced card. The seed is authored, not
+// recorded: its header line carries no `cwd`
 // field (seedSession writes the session cwd itself, and a Windows temp path
 // substituted into the header would not round-trip through its JSON parse),
 // and no event references the workspace, so the lane replays on any host

apps/web/tests/scaffold.ts

@@ -499,7 +499,7 @@ export async function launchWebScaffold(options: LaunchOptions = {}): Promise<We
     } else if (mode !== 'record' && options.deepSeekMissingCredential !== true) {
       // No fixture and no shipped adapter would leave the tree with ZERO
       // provider routes — a state no product composition has, and one the
-      // composer now correctly refuses to type into. Register the same routes
+      // composer refuses to type into. Register the same routes
       // a fixture would, with streaming that still fails loud: the scenario
       // issues no model calls, and one that slipped in must not pass quietly.
       ctx.effect(() => ctx.llm.registerAdapter(

apps/web/tests/seeded-history.e2e.ts

@@ -292,8 +292,8 @@ describe('web e2e: seeded history renders through cold resume', () => {
     const toolRows = page.locator('[data-variant], [data-sample]')
     await expect.poll(() => toolRows.count(), { timeout: 10_000 }).toBeGreaterThanOrEqual(2)
     expect(await page.getByText('a.txt', { exact: false }).count()).toBeGreaterThan(0)
-    // The bug this fixes: the compaction shadowed the whole recorded surface on
-    // the model side, and the prompt and full tool output are still on screen.
+    // The pinned hazard: compaction shadows the surface on the model side
+    // only — the prompt and full tool output must stay on screen.
     expect(await page.getByText(PROMPT, { exact: true }).count()).toBe(1)
 
     const agent = scaffold.ctx.agents.get(SessionId(SEED_ID))

apps/web/tests/settings-chrome.e2e.ts

@@ -270,7 +270,7 @@ describe('web e2e: settings modal and General preferences', () => {
     await selector.click()
     await page.getByRole('menuitem', { name: 'English' }).click()
     // The settings-owned copy re-registers localized: dialog title, nav,
-    // Appearance labels. (Only the settings namespaces are localized today —
+    // Appearance labels. (Only the settings namespaces are localized —
     // the rest of the app's copy is intentionally out of this row's scope.)
     const enDialog = page.getByRole('dialog', { name: 'Settings' })
     await enDialog.waitFor({ timeout: 10_000 })

apps/web/tests/sidebar-scrollbar.e2e.ts

@@ -1,5 +1,5 @@
 // Web e2e scenario: the sidebar session list's scrollbar as the browser
-// actually lays it out — the observable half of the themed-scrollbar change
+// actually lays it out — the observable half of the themed scrollbars
 // (packages/client/ui-theme/src/styles/scrollbar.css plus the
 // `scrollbar-gutter: stable` reservation on WorkspaceBrowser's `.list`). The
 // ui-theme/ui-workspace unit specs read the CSS text; only a real engine
@@ -17,8 +17,8 @@
 // Headless chromium defaults to an OVERLAY scrollbar: one drawn on top of the
 // content, consuming no layout width unless something reserves space. That is
 // the mode in which the reported symptom exists at all, so this environment
-// reproduces it rather than merely approximating it — measured against clean
-// master, where the list's band is 0 and the bar covers 7px of the relative
+// reproduces it rather than merely approximating it — without either
+// declaration the list's band is 0 and the bar covers 7px of the relative
 // time. (Under a classic space-consuming bar, `clientWidth` already excludes
 // the bar and nothing can be covered; a headed run under xvfb behaves that way
 // and cannot show the symptom.)
@@ -40,9 +40,8 @@
 // neither replaces the other. Removing only the gutter leaves `timeCoveredBy` at
 // 0, because the bar is then 8px wide and the row's right padding is also 8px,
 // so it abuts the timestamp without covering it; `band` catches that case.
-// Removing both — the actual master state — is what produces the reported
-// overlap, and `timeCoveredBy` measures it at 7. Each was mutation-checked with
-// the other assertions in its test silenced.
+// Removing both is what produces the reported overlap, and `timeCoveredBy`
+// measures it at 7.
 //
 // The thumb is a pointer affordance (ui-sidebar rebinds the indirection pair
 // to `transparent` while the pointer is outside the column), so every
@@ -135,7 +134,8 @@ interface ListMetrics {
 /**
  * Measure the sidebar list in the page.
  * @param page - the page under test.
- * @returns the list's resolved scrollbar style and the geometry the fix changes.
+ * @returns the list's resolved scrollbar style and the geometry the
+ * scrollbar-gutter/thin-scrollbar declarations shape.
  */
 function measureList(page: Page): Promise<ListMetrics> {
   return page.evaluate(() => {
@@ -201,8 +201,8 @@ function measureList(page: Page): Promise<ListMetrics> {
       // The bar is drawn in the rightmost `barWidth` of the border box, whether
       // or not that space was reserved. Its width comes from the sheet where the
       // sheet applies, and from the UA's own overlay bar otherwise — 15px is
-      // what this chromium paints, measured against master where the rule is
-      // absent. Taking the UA width as the fallback is what keeps the assertion
+      // what this chromium paints, measured with the rule absent. Taking the
+      // UA width as the fallback is what keeps the assertion
       // honest: assuming 0 there would report no occlusion precisely in the
       // state that has it.
       timeCoveredBy: Math.max(0, time.getBoundingClientRect().right - (listRect.right - barWidth)),
@@ -261,13 +261,14 @@ async function measurePalette(page: Page): Promise<PaletteMetrics> {
 
 /**
  * Render the golden body: the resolved scrollbar style of the list in each
- * palette, plus the geometric relations the fix establishes.
+ * palette, plus the geometric relations the scrollbar-gutter/thin-scrollbar
+ * declarations establish.
  *
  * Absolute coordinates are deliberately absent. `timeRight`, `clientRight`, and
  * `borderRight` depend on the sidebar's laid-out width and on font metrics, so
  * committing them would make the golden fail on a machine whose fonts measure
  * differently — a fixture that has to be re-recorded per platform documents the
- * platform, not the change. What is recorded instead is the band, the overlap,
+ * platform, not the behavior. What is recorded instead is the band, the overlap,
  * and the two orderings, each of which is a difference or a comparison and so
  * survives any layout that keeps the reservation.
  * @param light - metrics measured under the light palette.
@@ -417,12 +418,13 @@ describe('web e2e: sidebar session list scrollbar (reserved gutter / themed thum
     expect(metrics.scrollbarEdgeOffset).toBe(2)
     expect(metrics.rowEdgeInset).toBe(12)
     // The reported symptom, stated directly: no part of the row's relative time
-    // lies under the bar. Measures 7 on clean master — the `h` of `1h` is the
-    // covered part. Unlike the client-edge comparison below it does not go
-    // vacuous under an overlay scrollbar, because it measures against the bar's
-    // own width rather than against a content edge the overlay bar does not
-    // move. It is not a replacement for the band assertion above; see the file
-    // header for which regression each one catches.
+    // lies under the bar. Without either declaration it measures 7 — the `h`
+    // of `1h` is the covered part. Unlike the client-edge comparison below it
+    // does not go vacuous under an overlay scrollbar, because it measures
+    // against the bar's own width rather than against a content edge the
+    // overlay bar does not move. It is not a replacement for the band
+    // assertion above; see the file header for which regression each one
+    // catches.
     expect(metrics.timeCoveredBy).toBe(0)
     // Corollaries of the reservation, kept because they pin where the band sits
     // rather than only that it exists: the time ends inside the content area,
@@ -451,7 +453,7 @@ describe('web e2e: sidebar session list scrollbar (reserved gutter / themed thum
     expect(quiet.band).toBeGreaterThan(0)
     expect(quiet.timeCoveredBy).toBe(0)
     // Scrolling without a pointer — what a keyboard or a touch drag does —
-    // leaves the column quiet. This is the change's one deliberate loss, and
+    // leaves the column quiet. This is the one deliberate loss, and
     // it is pinned here rather than only described, so making a scroll
     // re-reveal the bar has to be a decision rather than a side effect.
     await page.locator('[role="tree"][aria-label="Sessions"]').evaluate((el) => { el.scrollTop += 200 })

apps/web/tests/smoke-real.e2e.ts

@@ -1,4 +1,4 @@
-// W5 real-host smoke: spawn `dsh web` with a real key, walk the full W5 flow
+// Real-host smoke: spawn `dsh web` with a real key, walk the full flow
 // list in a real chromium, screenshot every screen into .artifacts/ for the
 // figma comparison pass. Self-skips without DEEPSEEK_API_KEY (repo e2e
 // convention); vitest.web.config.ts loads the repo-root .env before this file
@@ -11,8 +11,9 @@
 // (frame/handle) rides local names that survive hashing as suffixes; prefer
 // data-* for anything new.
 //
-// Flow order matters: chat rounds first (5 depends on 3's session), geometry
-// and theme after, reload recovery last. Tests run sequentially in-file.
+// Flow order matters: chat rounds first (the bash round reuses the first
+// send's session), geometry and theme after, reload recovery last. Tests run
+// sequentially in-file.
 import type { ChildProcess } from 'node:child_process'
 import { spawn } from 'node:child_process'
 import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
@@ -119,7 +120,7 @@ async function waitForAssistantMarker(baseUrl: string, sessionId: string, marker
   }).toBe(true)
 }
 
-/** W5 screenshot: evidence for the figma comparison, not a failure artifact. */
+/** Real-host smoke screenshot: evidence for the figma comparison, not a failure artifact. */
 async function screen(page: Page, name: string): Promise<void> {
   await page.screenshot({ path: join(REPO_ROOT, '.artifacts', `w5-${name}.png`) })
 }
@@ -465,7 +466,7 @@ describe('dsh web keyless CLI smoke', () => {
   })
 })
 
-describe.skipIf(!process.env.DEEPSEEK_API_KEY || notReady.length > 0)('web smoke (real host, real key, W5)', () => {
+describe.skipIf(!process.env.DEEPSEEK_API_KEY || notReady.length > 0)('web smoke (real host, real key)', () => {
   let child: ChildProcess
   let sessionsDir: string
   let baseUrl: string
@@ -518,7 +519,7 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY || notReady.length > 0)('web smoke
     if (sessionsDir !== undefined) rmSync(sessionsDir, { recursive: true, force: true })
   })
 
-  it('1 cold start: loading page settles into the three-column frame', async () => {
+  it('cold start: loading page settles into the three-column frame', async () => {
     onTestFailed(() => saveFailureShot(page, 'w5-cold-start'))
     await page.waitForSelector('[class*="frame"]', { timeout: 30_000 })
     expect(await page.locator('text=Failed to load plugins').count()).toBe(0)
@@ -527,7 +528,7 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY || notReady.length > 0)('web smoke
     await screen(page, '01-cold-start')
   })
 
-  it('2+3 empty-state first send completes a real model round', async () => {
+  it('empty-state first send completes a real model round', async () => {
     onTestFailed(() => saveFailureShot(page, 'w5-first-round'))
     // This scenario spawns its own server against a fresh $DSH_HOME, so the
     // first-run welcome notice is unacknowledged and its overlay owns pointer
@@ -590,7 +591,7 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY || notReady.length > 0)('web smoke
     await screen(page, '07-back-to-chat')
   })
 
-  it('5 bash differential rendering: tool row click leaves the default details column closed', async () => {
+  it('bash differential rendering: tool row click leaves the default details column closed', async () => {
     onTestFailed(() => saveFailureShot(page, 'w5-tool-details'))
     const input = page.locator('textarea').first()
     await input.fill('请用 bash 工具运行命令 echo w5marker 然后告诉我结果')
@@ -604,12 +605,12 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY || notReady.length > 0)('web smoke
     await screen(page, '08-bash-round')
     expect(await detailsTrack(page)).toBe(0)
     await toolRow.click()
-    // Tool rows no longer drive layout.openDetails; the default column stays closed.
+    // Tool rows do not drive layout.openDetails; the default column stays closed.
     expect(await detailsTrack(page)).toBe(0)
     await screen(page, '09-details-closed')
   }, 150_000)
 
-  it('6 sidebar drag widens the column and resets across reload', async () => {
+  it('sidebar drag widens the column and resets across reload', async () => {
     onTestFailed(() => saveFailureShot(page, 'w5-drag'))
     const before = await firstTrack(page)
     const handle = page.locator('[class*="handle"]').first()
@@ -627,10 +628,11 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY || notReady.length > 0)('web smoke
     expect(await firstTrack(page)).toBe(before)
   })
 
-  it('7 dark mode: the body attribute cascades the token sheets', async () => {
+  it('dark mode: the body attribute cascades the token sheets', async () => {
     onTestFailed(() => saveFailureShot(page, 'w5-dark'))
-    // theme.apply === toggling this attribute (v3 §8); no switcher UI owns it
-    // in P-I, so the acceptance drives the documented mechanism directly.
+    // The body attribute is the documented cascade mechanism; the Settings
+    // gesture is owned by settings-chrome.e2e.ts — drive the attribute
+    // directly here.
     const dark = await page.evaluate(() => {
       document.body.setAttribute('data-ds-dark-theme', '')
       return getComputedStyle(document.body).backgroundColor
@@ -643,7 +645,7 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY || notReady.length > 0)('web smoke
     expect(dark).not.toBe(light)
   })
 
-  it('8 reload recovery: history replays after a fresh boot', async () => {
+  it('reload recovery: history replays after a fresh boot', async () => {
     onTestFailed(() => saveFailureShot(page, 'w5-reload'))
     await page.reload({ waitUntil: 'load' })
     await page.waitForSelector('[class*="frame"]', { timeout: 30_000 })

apps/web/tests/startup-auto-selection.e2e.ts

@@ -3,10 +3,10 @@
 // A page load with a workspace already registered runs
 // `WorkspacesService.startInitialSelection`: it connects the most recent
 // workspace and opens its blank session. `openState` flips to `loading` the
-// moment `open()` lands, which used to drive `data-phase=settling` on the
-// conversation root — `visibility:hidden` over the composer seat and the
-// header for the whole `session.history` round-trip, so the center column went
-// blank and repainted, reading as a full-page refresh on every launch.
+// moment `open()` lands; driving `data-phase=settling` on the conversation
+// root from that flip would hide the composer seat and the header
+// (`visibility:hidden`) for the whole `session.history` round-trip — the
+// center column blanks and repaints like a full-page refresh on every launch.
 //
 // The unit spec pins the phase condition over hand-built stores. What only the
 // assembled application can show is that the path a user actually takes
@@ -19,8 +19,9 @@
 // The round-trip against a loopback host is far too fast to observe, so this
 // scenario HOLDS the `session.history` response open at the browser's network
 // boundary and asserts the visible frame while it is in flight. That gate is
-// what makes the assertions non-vacuous: with the exemption reverted the held
-// window is exactly when `settling` is painted and the composer is hidden.
+// what makes the assertions non-vacuous: without the phase exemption, the
+// held window is exactly when `settling` would be painted and the composer
+// hidden.
 //
 // Zero model calls: registering a workspace and opening its blank session are
 // host RPCs with no model involvement. A stray stream would fail loud with

apps/web/tests/subagent-interrupt-ui.e2e.ts

@@ -185,7 +185,8 @@ describe.skipIf(MODE === 'record')('web e2e: composer interrupt for a running co
     onTestFailed(() => saveFailureShot(page, 'web-e2e-subagent-interrupt-offline'))
     // Simulate a parent that went offline: the catalog delivers
     // parentAvailable: false while the child Activation stays live (the
-    // interrupt RPC itself needs no live parent — PR 1's host coverage).
+    // interrupt RPC itself needs no live parent — covered host-side by
+    // subagent-interrupt.e2e.ts).
     const pattern = '**/api/subagent.list'
     await page.route(pattern, async (route) => {
       const response = await route.fetch()

apps/web/tests/subagent-interrupt.e2e.ts

@@ -4,7 +4,7 @@
 // proves from the real session state that the turn aborted, the follow-up
 // parked without auto-starting a new turn, and a later waking send resumed the
 // preserved FIFO order. No browser: the RPC surface is the product surface
-// under test, and PR-stacked UI coverage owns the composer interaction.
+// under test, and subagent-interrupt-ui.e2e.ts owns the composer interaction.
 import { existsSync } from 'node:fs'
 import { mkdtemp, rm, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'

apps/web/tests/turn-tail-actions.e2e.ts

@@ -1,6 +1,6 @@
 // Web e2e scenario: assistant IconActions belong to the settled answer, so
 // they arrive with `turn/end` and not before. The recorded turn narrates in
-// plain text before its tool call, which is the shape that used to hand the
+// plain text before its tool call, which is the shape that would hand the
 // footer to mid-turn narration for the seconds a tool runs and then move it
 // down. A `hang` sidecar on the SECOND model call parks the turn after the
 // narration and the tool result are durable, so the running state is stable by

apps/web/tests/workspace-management.e2e.ts

@@ -91,8 +91,8 @@ describe('web e2e: workspace management (create / rename / flat view / hover aff
     ).not.toBeUndefined()
     // First adoption births a blank Session+Agent whose workspace attach must
     // settle before a test may delete the registration; re-registration after
-    // a delete mints a fresh blank Session+Agent too (the old cwd-only reuse
-    // path is gone), so callers opt in only where a fresh attach is possible.
+    // a delete mints a fresh blank Session+Agent too (no cwd-based reuse
+    // exists), so callers opt in only where a fresh attach is possible.
     if (options.waitForAgent === true) {
       await expect.poll(() => scaffold.ctx.agents.list().length, { timeout: 10_000 })
         .toBeGreaterThan(agentsBefore)
@@ -254,7 +254,7 @@ describe('web e2e: workspace management (create / rename / flat view / hover aff
     // a supported reversible flow. It creates a fresh Workspace id and does
     // NOT re-adopt the retained (non-blank) Session; the New Session flow
     // mints a fresh blank session and attaches it to the new registration
-    // (the old cwd-only blank reuse is gone, so the account is never empty).
+    // (no cwd-based blank reuse exists, so the account is never empty).
     await adoptDirectory(scaffold.workspaceCwd)
     await expect.poll(
       () => scaffold.ctx.workspace.resolveByPath(scaffold.workspaceCwd),
@@ -482,7 +482,7 @@ describe('web e2e: workspace management (create / rename / flat view / hover aff
     await expect.poll(() => page.getByText('Idle', { exact: true }).count(), { timeout: 5_000 }).toBeGreaterThanOrEqual(1)
     // The card is REACHABLE: it sits 8px off the row, so getting to it means
     // crossing ground that belongs to neither. Hovering it must not dismiss
-    // it — the regression this scenario guards.
+    // it — the hazard this scenario pins.
     const card = page.getByRole('button', { name: `Copy: ${rowTitle}` })
     await card.hover()
     await page.waitForTimeout(POINTER_HOLD_MS)
@@ -515,10 +515,10 @@ describe('web e2e: workspace management (create / rename / flat view / hover aff
     const item = page.getByRole('menuitem', { name: 'Rename' })
     await item.waitFor({ timeout: 5_000 })
     // Into the list, then back up to the trigger across the 4px gap below it:
-    // that return trip used to fire the list's pointerleave and close the
-    // menu, so a hesitating pointer lost it. Order matters — clicking leaves
-    // the pointer ON the trigger, so entering the list has to come first for
-    // the return to be a real departure.
+    // without the gap-crossing grace, that return trip fires the list's
+    // pointerleave and closes the menu — a hesitating pointer loses it.
+    // Order matters — clicking leaves the pointer ON the trigger, so entering
+    // the list has to come first for the return to be a real departure.
     await item.hover()
     await page.waitForTimeout(POINTER_TRANSIT_MS)
     await trigger.hover()

apps/web/vite.config.ts

@@ -73,10 +73,13 @@ const BOOT_GRAMMAR_FILES: readonly string[] = [
   'dist/json.mjs',
 ]
 
-/** Font asset extensions routed to assets/fonts/ (KaTeX's woff2/woff/ttf faces today). */
+/** Font asset extensions routed to assets/fonts/ (KaTeX's woff2/woff/ttf faces). */
 const FONT_EXTENSIONS: readonly string[] = ['.woff2', '.woff', '.ttf']
 
-/** npm package name of a resolved module id (the segment after the LAST `node_modules/` — pnpm nests the real package under an inner node_modules). */
+/**
+ * npm package name of a resolved module id (the segment after the LAST
+ * `node_modules/` — pnpm nests the real package under an inner node_modules).
+ */
 function npmPackageOf(id: string): string | undefined {
   const parts = id.split('/node_modules/')
   if (parts.length === 1) return undefined
@@ -94,7 +97,7 @@ export default defineConfig({
       output: {
         // Output layout: the two main chunks stay at assets/ root; lazy
         // @shikijs/langs grammar chunks group under assets/langs/; fonts
-        // (today all KaTeX faces referenced by vendor.css) group under
+        // (all KaTeX faces referenced by vendor.css) group under
         // assets/fonts/. Sourcemaps need no arrangement: rollup writes each
         // .map next to its js and references it by bare relative filename.
         chunkFileNames(chunk): string {
@@ -128,7 +131,8 @@ export default defineConfig({
     // for Node/type consumers, but the browser bundle must compile src directly
     // so CSS rides vite's pipeline instead of the CSS-externalized lib bundle.
     // Only the shell's normal-package surface is aliased — plugin packages are
-    // NEVER bundled here (web2 shell self-sufficiency); they arrive as runtime
+    // NEVER bundled here (shell self-sufficiency — see
+    // packages/client/web/README.md); they arrive as runtime
     // bundles through the client module system. Order matters — subpath
     // aliases must win over bare-name prefixes.
     alias: [