@hienlh/ppm 0.23.11 → 0.23.13

package/CLAUDE.md

@@ -60,6 +60,7 @@ Exceptions (intentionally use real `homedir()`):
 - `fs-browse.service.ts`, `git-dirs.service.ts` — file browser starting from real home
 - `ppmbot/` — bot files in real home
 - `slash-discovery/` — discovers skills from real home
+- `design/design-skill-install.service.ts` — installs the suggested design skill where Claude (`$CLAUDE_CONFIG_DIR/skills`, else `~/.claude/skills`) and Codex (`~/.agents/skills`) read user skills
 - `named-tunnel/cloudflared-cert.ts` — `~/.cloudflared` is where `cloudflared` itself writes `cert.pem`, not PPM's directory
 - `fs-credential-path-guard.ts` — refuses `~/.cloudflared` (alongside the PPM dir) on every fs read/write/transfer door
 - `db-backup/db-backup-paths.ts` — snapshots live in `~/.ppm-backups` *outside* the PPM dir on purpose, so they survive a wipe of it (under an isolated `PPM_HOME` they go back inside that temp dir)
@@ -82,6 +83,7 @@ Related: `configService.save()`/`set()` throw when `load()` has not run, because
 
 - **SDK .env poisoning**: Projects with `ANTHROPIC_API_KEY` in `.env` break SDK tool execution. Provider neutralizes these vars. See `docs/lessons-learned.md`.
 - **File watching**: never `fs.watch(dir, { recursive: true })` on a project root — on Linux that is one inotify watch per subdirectory, `node_modules` included (it once cost 359k watches). Ignored dirs must be pruned at registration time via `src/services/file-watcher/watch-tree.ts`.
+- **A file change marks the flat file index stale, and must never make a request walk the project**: `buildIndex` used to walk with `readdirSync` on the main thread while every change dropped the cache and the explorer refetched `/files/index` 300 ms later. nxsys-workspace (181k entries, 22 MB of JSON) is a 6.2 s walk, so a session writing test artefacts into it kept the event loop stopped back to back until the supervisor's health check (5 s timeout, three strikes) killed the server — and every Claude session under it. Now the walk yields every 256 entries on `setTimeout(0)` (`setImmediate` costs 0.002 ms a yield against 1.09 ms, but starved HTTP to a 16 ms p50 against 1.4 ms), a stale list is rebuilt behind the one held, a request waits for that rebuild at most `REBUILD_GRACE_MS` (1 s — enough that an ordinary project answers fresh and a file just created is in the palette on its first open), and `files:index-changed` goes out only when the rebuilt paths differ. The browser does not refetch on a change either: `file:changed` and `files:index-changed` set `indexStale`, and `ensureIndex` refreshes when the palette, the compare picker or the @-picker opens. Two traps. A rebuild runs only when a request asks for one, so a change landing mid-walk is walked again only if a request saw it (`rewalk`) — rebuilding on a timer would keep a core busy for as long as a session keeps writing. And a first walk that no longer stops the server can outlast **Bun.serve's default 10 s idle timeout** (14 s on a busy scratch server), which cuts the request off with the list nearly built; the route calls `server.timeout(req, 30)` through `c.env`, the server `app.fetch(req, server)` passed.
 - **Project Claude settings**: `.claude/settings.local.json` can restrict tools even with `bypassPermissions`. Provider overrides with empty settings.
 - **Transcript images live in two places**: the base64 payload sits at `message.content[].content[]` inside a tool result, but Claude Code also writes an image-shaped record at the top-level `toolUseResult` field carrying no payload. An assertion like "no `"type":"image"` remains" must be scoped to the former, or it fails against correct code.
 - **Plugin items are named by location, not frontmatter**: Claude Code registers a plugin's skills and commands as `<plugin>:<path>` (`ak-engineer:ak-debug`) and only honours the frontmatter `name` for agents. Kits that self-namespace instead — AgentKit ships `name: ak:debug` — publish a name nothing can resolve. `slash-discovery` mirrors that rule and keeps the declared name as an alias; `src/server/ws/chat.ts` rewrites the alias to the canonical name before the message reaches the SDK.
@@ -89,11 +91,11 @@ Related: `configService.save()`/`set()` throw when `load()` has not run, because
 - **A signed-out Codex account fails slowly, and its retry notices are not errors**: a revoked or expired ChatGPT login does not fail `initialize` or `thread/start` — codex opens the turn, then sends `error` notifications with **`willRetry: true`** ("Reconnecting... N/5", ten of them over ~24s) before a final `willRetry: false`. The cause is only in `error.additionalDetails` (`workspace routing discovery unauthorized (401)`), never the headline. Mapping every `error` to a fatal event made the proxy give up at the first reconnect, and a retrying client then kept a dozen app-servers starting at once until the server stopped answering its health check. `codex-event-mapper.ts` turns retry notices into `status_update`; `codex-auth-failure.ts` recognises the 401 on the first one; `codex-account-auth-state.ts` benches the account (hard exclusion, unlike a quota park) so the turn rotates or fails in milliseconds; and `proxy-agent-turn.ts` caps concurrent proxy turns with a 429. Selection also has to ignore the usage figure for such an account: the usage endpoint keeps serving its last good reading, which made a dead account look emptier than a working one.
 - **Nested subagents are never streamed**: the SDK stamps `parent_tool_use_id` only on agents the session itself spawned. An agent that spawns another agent (a reviewer running `Skill code-review`, a planner calling researchers) produces **zero** stream events for that grandchild, so the Agent card would freeze on the forking step for minutes. Its transcript still lands in `<session>/subagents/agent-<id>.jsonl`, with a meta carrying only `parentAgentId` (raw id, no `agent-` prefix) and no `toolUseId`. `src/services/nested-subagent-spy.ts` tails those during the turn and `subagent-transcript-merger.ts` folds them in flat, time-ordered, on reload — both via `groupSubagentsByCard`, which walks the `parentAgentId` chain to the root card.
 - **A codex subagent is a session file of its own**: codex writes every spawned agent as a full rollout in the same `$CODEX_HOME/sessions` tree, with the same `cwd` as the conversation that spawned it — so a cwd filter alone lists each spawn as a top-level session that opens mid-stream, because a subagent's task is handed over as encrypted scaffolding and never appears as a `UserMessage` in its own transcript. `session_meta.parent_thread_id` is what tells the two apart. The parent names each spawn twice (`SubAgentActivity` `started`/`completed`) under **different item ids** but one `agent_thread_id`, which is why `codex-subagent-thread.ts` keys the card on the thread; `codex-history.ts` then reads the child rollout and hangs it under that Agent card.
-- **Agent teams are implicit and mostly not in `~/.claude/teams/`**: there is no `TeamCreate` tool any more. A team appears as `~/.claude/teams/<sessionId>/inboxes/*.json` with **no `config.json`**, so anything that requires a config sees no team at all. The inboxes only hold what was sent *to* each handle — in practice just the lead's task assignments — so they can neither say who is working nor show a teammate's replies. Both live in the agent transcripts under `~/.claude/projects/<slug>/<sessionId>/subagents/`: `agent-<id>.meta.json` maps the teammate `name` to its transcript, a transcript being appended to means that teammate is running, and its replies are `SendMessage` tool calls inside it. See `src/services/team-member-activity/`. A single teammate transcript reaches several MB, so the member window follows one by byte offset (`?sinceBytes=` on the transcript route, `member-transcript-tail.ts`) instead of re-reading it — an idle poll then costs nothing.
+- **Agent teams are implicit and mostly not in `~/.claude/teams/`**: there is no `TeamCreate` tool any more. A team appears as `~/.claude/teams/<sessionId>/inboxes/*.json` with **no `config.json`**, so anything that requires a config sees no team at all. The inboxes only hold what was sent *to* each handle — in practice just the lead's task assignments — so they can neither say who is working nor show a teammate's replies. Both live in the agent transcripts under `~/.claude/projects/<slug>/<sessionId>/subagents/`: `agent-<id>.meta.json` maps the teammate `name` to its transcript, a transcript being appended to means that teammate is running, and its replies are `SendMessage` tool calls inside it. See `src/services/team-member-activity/`. A single teammate transcript reaches several MB, so the member window follows one by byte offset (`?sinceBytes=` on the transcript route, `member-transcript-tail.ts`) instead of re-reading it — an idle poll then costs nothing. A named agent's meta carries the spawning call's `toolUseId` as well as its `name`, so it is an Agent card *and* a teammate: indexing by card and by name lists it twice, which is how the running-agents bar showed every agent of a fan-out session two times. `agent-transcript-activity.ts` lists a teammate only when no card covers its transcript.
 
 - **An extension panel only gets a tab if a browser tab asked for it**: `use-extension-ws.ts` creates a tab for `webview:create` only when `locallyDispatchedViews` holds a matching entry, i.e. when *this* client dispatched the command. A panel the extension opens on its own initiative exists server-side with no tab to show it. To open one panel from another, call `window.openTab("extension", …, { viewType })` instead — `extension-webview.tsx` then sees a tab with no panel and dispatches the command itself, which *is* a local dispatch. The recovery dispatch forwards only the project path, so any other argument has to be stashed for the target panel to pick up (`packages/ext-git-graph/src/panel-nav.ts`). The command id and the viewType must also be identical: both are turned into a tab slug by stripping a trailing `.view`, and a mismatch silently yields no tab.
 - **Extensions may only spawn `git`, `node`, `bun`, `npx`, `sqlite3`** (`ALLOWED_SPAWN_COMMANDS` in `extension-rpc-handlers.ts`) and the call *throws* for anything else. Reaching for `test`, `cat` or any other coreutil looks fine in review and fails only at runtime — where a surrounding `catch` can turn it into silently missing data rather than an error. `env` is merged over `process.env` (so `PATH` survives) except for `BLOCKED_ENV_KEYS`; `GIT_SEQUENCE_EDITOR` and `GIT_EDITOR` are not blocked, which is what makes a non-interactive `git rebase -i` possible.
-- **A webview inherits nothing from the app, including which theme is on**: the iframe is `sandbox="allow-scripts"` with its own document, so none of the CSS vars `apply-theme.ts` writes to `<html>` reach it and there is no `.dark` class to read. The only question the panel can ask by itself is `prefers-color-scheme` — the *OS* setting — which is why every extension panel rendered dark inside a light app on a dark desktop. `webview-theme.ts` stamps `data-ppm-theme` on the panel's own `<html>` and appends the app's tokens as a `:root[data-ppm-theme]` block, and the panels' dark rules are written as `:root[data-ppm-theme="dark"]` plus `@media (prefers-color-scheme: dark) { :root:not([data-ppm-theme="light"]) }` — a bare `:root` inside that media query is the bug, because it cannot lose to an explicit light. Three things are load-bearing: the injected block is *appended last* and ties on specificity, so a panel rule more specific than one attribute silently wins over the app's colours; the seed goes into `srcDoc` (later changes are `postMessage`d, because rewriting `srcDoc` reloads the panel and a graph would refetch every commit); and `--surface-hover` is derived from `--text` rather than injected, because some app themes give `--panel` and `--panel-2` the same value and a hover mapped from either would be invisible in exactly those themes.
+- **A webview inherits nothing from the app, including which theme is on**: the iframe is `sandbox="allow-scripts"` with its own document, so none of the CSS vars `apply-theme.ts` writes to `<html>` reach it and there is no `.dark` class to read. The only question the panel can ask by itself is `prefers-color-scheme` — the *OS* setting — which is why every extension panel rendered dark inside a light app on a dark desktop. `webview-theme.ts` stamps `data-ppm-theme` on the panel's own `<html>` and appends the app's tokens as a `:root[data-ppm-theme]` block, and the panels' dark rules are written as `:root[data-ppm-theme="dark"]` plus `@media (prefers-color-scheme: dark) { :root:not([data-ppm-theme="light"]) }` — a bare `:root` inside that media query is the bug, because it cannot lose to an explicit light. Three things are load-bearing: the injected block is *appended last* and ties on specificity, so a panel rule more specific than one attribute silently wins over the app's colours; the seed goes into `srcDoc` (later changes are `postMessage`d, because rewriting `srcDoc` reloads the panel and a graph would refetch every commit — and the theme is posted again on every iframe `load`, because the tab pool moves a tab with `appendChild` and a moved iframe reloads from that same `srcDoc`, whose seed is the theme of the moment the HTML arrived); and `--surface-hover` is derived from `--text` rather than injected, because some app themes give `--panel` and `--panel-2` the same value and a hover mapped from either would be invisible in exactly those themes.
 - **A webview panel has no `prompt`/`confirm`/`alert`**: `extension-webview.tsx` mounts the iframe with `sandbox="allow-scripts"` and nothing else, and a sandboxed `prompt()` returns `null` silently — no exception, no console warning. Any answer a panel needs has to be collected by markup it renders itself (`confirmHtml` in `reflog-view.ts`). The same string is a TypeScript template literal, so a backtick anywhere inside it — a `` `code span` `` in a comment is the usual one — ends the literal early and reports as a syntax error at some unrelated token far below.
 - **A Monaco model in PPM is not named after its file**: the editor mounts `<Editor value=... />` with no `path`, so Monaco names models `inmemory://model/N`. A language server has never heard of that, and the `file:` URIs it answers with match no model — so an unrewritten request makes the server answer about a document it was never given, and an unrewritten response makes Monaco treat the open file as a different one (go-to-definition inside the current file tries to *open* it, and diagnostics attach to nothing and never appear). `src/server/ws/lsp.ts` rewrites both directions, including URIs used as object *keys* in a workspace edit's `changes`.
 - **Standalone Monaco's F12 into another file hijacks the current editor**: its default editor service, once a model exists for the target, swaps that model into the editor you are in. The tab keeps its old title and its old dirty state while showing another file's contents. `lsp-navigation.ts` replaces the binding and opens a real tab instead. Peek and find-references are left on Monaco's bindings — they render in place and never navigate — but they need a model to exist for the target, which is what the shadow models in `lsp-shadow-models.ts` are for; there is no public way to give standalone Monaco a model *resolver*, so providers create the models before returning locations.
@@ -101,12 +103,14 @@ Related: `configService.save()`/`set()` throw when `load()` has not run, because
 - **`typescript-language-server` needs TypeScript 5.x**: the 7.x line is the native port and ships no `tsserver.js`, so the server exits at `initialize` with "provides no tsserver". It reads like a broken install rather than the wrong major version, so the registry's install hint pins `typescript@5`.
 - **A compiled PPM reaches none of its own `node_modules`, and is not bun**: `bundledServerEntry` resolves the TypeScript server it ships through `createRequire(import.meta.url)`, which in a compiled binary is `file:///$bunfs/root/…` — so resolution falls back to the process's **cwd**, and the systemd unit's cwd is `~/.ppm`. Measured: started from inside the checkout it answers the real path, started anywhere else `null`, i.e. "TypeScript is not installed" on every release binary and on the unit, for a server the repository does depend on. The second half is the same trap as `<ppm> x @openai/codex app-server`: `process.execPath` is bun only from source, so spawning `[process.execPath, entry]` runs *PPM's CLI* with a script path. Anything that runs a JS entry has to go through `resolveBunPath()` (`bunRuntime()` in `lsp-manager.ts`), and `installLanguageServer` needs it too — which is why a host with no bun at all is reported as not-installed rather than started and left to fail at spawn.
 - **`bun add` in a directory with no `package.json` installs into the parent**: it does not create a manifest where it was asked to. Measured — in `<dir>/sub` with a manifest at `<dir>`, the package landed in `<dir>/node_modules` and `sub` stayed empty. Anything installing into a PPM-owned directory (`lsp-install.ts`, `extension-installer.ts`) must write that directory's own `package.json` first, or the packages appear somewhere above the PPM dir and every later lookup answers "not installed".
-- **A `~/.cargo/bin` proxy exists whether or not the component does, and `Bun.which` cannot see a `PATH` you just set**: `~/.cargo/bin/rust-analyzer` is a symlink to rustup, present on any rustup install — measured on a host where `rustup which rust-analyzer` answered `unknown binary`, the symlink was right there. Found on `PATH` it reports an installed server that prints that error and exits at spawn, i.e. a *broken* server instead of the missing one the Install button is offered for, so `lsp-manager.ts` asks `rustupServerPath` **before** `Bun.which` and takes rustup's 3 ms answer as both the lookup and the installed-check. The same call is the reason a test cannot fake a missing toolchain: `Bun.which` reads the `PATH` the **process started with** and ignores every later write to `process.env.PATH` (so does `Bun.spawn`'s own resolution) — only the explicit `Bun.which(cmd, { PATH })` option is live, which is what `installToolPath` passes.
+- **A `~/.cargo/bin` proxy exists whether or not the component does, and `Bun.which` cannot see a `PATH` you just set**: `~/.cargo/bin/rust-analyzer` is a symlink to rustup, present on any rustup install — measured on a host where `rustup which rust-analyzer` answered `unknown binary`, the symlink was right there. Found on `PATH` it reports an installed server that prints that error and exits at spawn, i.e. a *broken* server instead of the missing one the Install button is offered for, so `lsp-manager.ts` asks `rustupServerPath` **before** `Bun.which` and takes rustup's 3 ms answer as both the lookup and the installed-check. The same call is the reason a test cannot fake a missing toolchain: `Bun.which` reads the `PATH` the **process started with** and ignores every later write to `process.env.PATH` (so does `Bun.spawn`'s own resolution) — only the explicit `Bun.which(cmd, { PATH })` option is live, which is what `installToolPath` passes. A child gets the same snapshot: `Bun.spawn` without `env:` passes the environment the process *started* with, so a variable written to `process.env` afterwards (a `beforeEach` setting one, say) never reaches it, under `bun test` too. Pass `env: process.env` or an argument; `tests/fixtures/fake-tailscale.ts` takes its state file as an argument for that reason.
 - **Standalone Monaco can never turn semantic highlighting on from a theme**: `StandaloneTheme` hardcodes `semanticHighlighting = false` and never reads it from the `defineTheme` data (`IStandaloneThemeData` has no such field), while the `semanticHighlighting.enabled` option defaults to `'configuredByTheme'` — so tokens are fetched, decoded, and change nothing. The only switch is the editor option set to `true` (`code-editor.tsx`). Colours then resolve through the *same* rule trie as TextMate scopes: `getTokenStyleMetadata` joins the type and its modifiers with dots (`variable.readonly.local`) and `ThemeTrieElement.match` falls back segment by segment, so a type with no rule lands on the theme's default foreground — i.e. plain text where the regex tokenizer had colour. `src/web/theme/semantic-token-rules.ts` is that table, and it must cover names outside the specification: `typescript-language-server` sends **`member`** for methods, one of the most common tokens in a TS file.
 - **Monaco's bundled TypeScript service is off entirely, and `setDiagnosticsOptions` is not what does it**: that call silences the validator but leaves all **thirteen** providers in `modeConfigurationDefault` registered, so every `.ts` file had two completion lists and two hovers — the second from a worker that sees one file with no `tsconfig.json` and no `node_modules`. It also cost a *visible* stall: answering a hover at all means fetching `ts.worker.bundle.js` (**13 MB**, the whole TypeScript compiler), and Monaco's hover widget merges every provider and shows "Loading…" until the last one replies — so the real server's answer rendered in milliseconds and then sat behind a spinner. `setModeConfiguration` is the call that unregisters them (`monaco-builtin-typescript.ts`, asserted against Monaco's own default list so an upgrade adding a provider fails a test). Consequence, accepted: a buffer the LSP cannot serve — untitled, external, inline — falls back to word-based suggestions only.
 - **A button in a Monaco hover is a `command:` link in *trusted* markdown, and trust is all-or-nothing unless you narrow it**: a hover can only contain markdown, so the blame hover's actions are `[label](command:id?args)` links reaching ids registered with `monaco.editor.registerCommand`. The renderer *strips* those links unless the `IMarkdownString` is trusted — and `isTrusted: true` allows **every** command on the page's global registry. That hover embeds a commit message, so anyone who can land a commit could write `[click](command:...)` in one and have it render as a working button. Both defences are needed and both are in `blame-hover.ts`: `isTrusted: { enabledCommands: [...] }` (an array is honoured by `toAllowCommandsOption`), and escaping the message so it cannot form a link at all. `supportHtml` stays **off** — the avatar is `![](data:image/svg+xml,...)`, which renders inline at its intrinsic size, so no HTML has to be allowed for it. Escape `<` and `>` too: with `supportHtml` off the renderer does not leave an unknown tag alone, it drops the tag and keeps the text, so a message mentioning a literal `<script>alert(1)</script>` displayed as `alert(1)` — the message silently rewritten in the one view meant to show it verbatim.
 - **Hovering injected text does reach the decoration under it, and Monaco has no `diff` language**: an `after` injected-text annotation sits past the line's last column, and `ContentHoverComputer._getLineDecorations` relaxes its column check by one character *only* for `showIfCollapsed` decorations — which is what makes the blame hover work at all, and why that flag is load-bearing rather than cosmetic. `editor.action.showHover` opens the same hover from the cursor, which is the touch path (gated on `hover: none`, not on a width breakpoint; the mouse target's `injectedText` would identify the tap exactly but is not in Monaco's public typings, so the handler goes by column). Separately: Monaco's 91 basic languages include no `diff` — VS Code's comes from a bundled extension — so a fenced diff block runs the tokenizer and comes back entirely `mtk1`, the theme's default foreground. `monaco-diff-language.ts` registers one and `theme/diff-token-rules.ts` colours it; a Monarch rule whose token name has no theme rule is the same silent no-op as an unmapped semantic token, and a test pairs the two so neither can be added without the other.
+- **Monaco hit-tests the gutter by x, and sizes its glyph margin in lanes**: standalone Monaco ships `glyphMargin` off (`editor.api2.js`), and the code-action lightbulb Monaco puts there when its line has no room is then drawn nowhere. Turned on, the margin is one line height per glyph *lane* in use, so the bulb fills a single 19px lane flush against the editor's edge. Moving it right with CSS looks correct and is a bug: `_hitTestMargin` tells glyph margin from line numbers by the x coordinate alone, so a bulb drawn over the line-number column still opens its menu and the same mousedown selects that whole line, replacing the selection the menu was opened for (measured: `[1,7 -> 2,8]` became `[1,1 -> 2,1]`). `monaco-lightbulb-gutter.ts` widens the margin instead, with two empty glyph-margin widgets. Three traps, all silent. Monaco draws one glyph per (line, lane), highest zIndex first and widgets winning ties, so at zIndex 0 the left widget hid the bulb on line 1. A `persistLane` *decoration* would hold the lanes as well, but any glyph decoration on the bulb's line makes the lightbulb give up the gutter and draw itself over the text. And the width follows the line that uses the most lanes, so both are held on the same line — one lane held on its own widens nothing. Separately, Tailwind's preflight `* { box-sizing: border-box }` makes Monaco's `.action-widget` 8px narrower than the row it measured, which cut the longest code action off with an ellipsis.
 - **The service worker's precache can silently undo any download saving, and both compressions are needed**: `injectManifest` defaults to precaching *everything* in the build output, so the first visit fetched 488 files / 33.3 MB — including the 12.7 MB TypeScript worker that `monaco-builtin-typescript.ts` had just made unnecessary to ever load. A saving measured in the network tab of a warm page is not a saving; measure `precache N entries (X KiB)` in the build output too. `globPatterns` now lists only the boot shell (9 entries / 1.08 MB) with everything else on a runtime `CacheFirst`. Separately, `scripts/precompress-web.ts` writes **both** `.br` and `.gz` siblings and `static-encoding.ts` picks one: brotli alone is not enough, because browsers advertise `br` only on a **secure origin** and PPM is routinely reached over plain HTTP on a LAN. And Monaco is staged locally by `scripts/copy-monaco.ts` with `loader.config({ paths: { vs: "/assets/monaco/vs" } })` — the default is jsdelivr, which means no editor offline and a third party told which files are opened. `vite build` empties `dist/web`, so `copy-monaco` and `precompress-web` must run *after* `build:web` (running `build:web` alone leaves an installed PPM with no Monaco at all).
+- **`FileSink.write()` consumes the whole chunk and returns a number that is not how much of it went in**: the careful-looking `while (off < buf.length) { off += await sink.write(buf.subarray(off)) }` is therefore a loop that re-sends the tail. Measured against `cat`, one 4,924,800-byte frame produced eleven `write()` calls each answering **475072** while everything had already been buffered, and the child received **28,043,840 bytes — 5.7x the frame**. Downstream the damage is silent and total: ffmpeg's rawvideo input is offset for good, so the *first* picture decodes perfectly and every one after it is drawn rolled, with no error from ffmpeg, from the sink, or from the encoder wrapper. One `write()` then `await flush()` is the whole correct form (`writeFrameToSink` in `android-video.ts`). Two things generalise. A frame **counter** cannot see this — every counter in the pipeline reported the right number while 5.7x the bytes left the process — so the test has to measure the bytes a real child receives (`tests/unit/android/android-video-frame-write.test.ts`), and it needs a chunk big enough that the sink buffers in pieces or the bug does not reproduce at all. And a capture that decodes correctly proves nothing if it holds one access unit: the first frame is always right.
 - **A lazy chunk boundary is one static import away from not existing, and it is invisible**: `code-editor.tsx` reaches the language service only through `lazy(() => import("./editor-language-service"))`, which is what keeps the LSP client out of the editor's chunk and — the part that actually costs something — keeps the code that asks the host for a server unreachable until the setting is on. One `import { anything } from "@/hooks/use-lsp"` anywhere on that static path merges the chunk back in and nothing about the UI looks different, so `tests/unit/web/editor-lsp-lazy-boundary.test.ts` enumerates the offenders instead. Importing even a *constant* from the lazy module counts; `import type` does not. Related: `lspEnabled` and `mobileWordWrap` are written with `persistDevicePref` (localStorage only) rather than `persistUiPref`, because the server round-trip that makes prefs survive an origin change also means the last device to write wins everywhere — and a desktop must not start an 854 MB server process for a phone.
 - **Escaping before matching lets a pattern rewrite the text it escaped**: the git graph escaped a commit message to HTML and *then* ran the issue-link rules over the result. The default rule is `#(\d+)`, an apostrophe escapes to `&#39;`, so "Monaco's" rendered as a literal `&#39;s` with `#39` styled as an issue link — every message with an apostrophe in it, which is most of them. `commit-message-html.ts` matches the raw text and escapes only what it emits; the same order matters for the URL and bare-hash rules, which otherwise link something *inside* a URL and split it. That file also shows the way to unit-test code that lives in a webview: write it as a real typed function and inject `fn.toString()`, which Bun returns type-stripped, rather than keeping a second copy inside a template literal where every regex backslash has to be doubled. And a backtick anywhere in a comment inside those template literals — including inside a CSS comment — ends the literal and reports as a syntax error hundreds of lines away; `webview-html.test.ts` now parses the whole injected script with `new Function` so that lands as a failing test instead of a blank panel.
 - **`dateStyle`/`timeStyle` may not be combined with any other `Intl` option**: `toLocaleString(undefined, { dateStyle: "medium", timeStyle: "medium", timeZoneName: "short" })` does not ignore the third option, it *throws* `TypeError: dateStyle and timeStyle may not be used with other DateTimeFormat options`. Behind the `try/catch` that any date formatting picks up sooner or later, that is indistinguishable from a locale which simply has no timezone in its medium format — the commit details panel showed author and committer dates with no zone at all, and no test caught it because the fallback string is perfectly well-formed. A format that needs a companion option has to list every component explicitly (`year`/`month`/`day`/`hour`/`minute`/`second` + `timeZoneName`), and the test worth writing runs the options object through a real `Intl.DateTimeFormat` and asserts the *output* contains a zone.
@@ -121,8 +125,10 @@ Related: `configService.save()`/`set()` throw when `load()` has not run, because
 - **Screen wake lock needs a secure context**: `navigator.wakeLock` does not exist at all over plain HTTP, so reaching PPM at `http://<lan-ip>:<port>` silently disables "keep screen awake" — the very setup (a tablet on the LAN) it was built for. Only HTTPS and `localhost` qualify. The lock is also released by the browser on *every* hide, so `src/web/hooks/use-wake-lock.ts` re-acquires on `visibilitychange` and drops its handle on hide rather than waiting for the `release` event, whose ordering against `visibilitychange` is undefined.
 - **Remote desktop on macOS (avfoundation)**: address the screen by **name** (`-i "Capture screen 0"`), never by index — the device list reorders at runtime when a Continuity Camera joins (index 3 became the iPhone). `-framerate` is ignored (the screen input delivers at display refresh, 120–165 fps, with a stuck pts) → `-use_wallclock_as_timestamps 1` + `-vf fps=30`. ffmpeg-avfoundation ignores SIGTERM/SIGINT → `proc.kill("SIGKILL")` or it leaks one process per session. No Screen Recording grant = **black frames, no error**; no Accessibility grant = silent no-op input — both are pre-flighted in `remote-desktop-requirements.ts`, never inferred from failures. TCC keys the grant to the `bun` executable.
 - **Remote desktop text injection on macOS**: `CGEventKeyboardSetUnicodeString` still carries a keycode, and IMEs that hook by key (OpenKey/EVKey) re-read keycode 0 as a literal "a" (`"日本"` → `"â"`); function/unassigned keycodes produce no text at all. The carrier is Space (`TEXT_CARRIER_KEYCODE`). Text is still subject to the host's active IME (Telex rewrote "World" → "ửold") on every OS.
-- **Remote desktop on Linux is chosen per *session*, not per platform, and Wayland must win the tie**: `process.platform === "linux"` says nothing about how to capture or inject. A Wayland session almost always also runs XWayland, which sets `DISPLAY` and answers `x11grab` **successfully** — with a view of XWayland clients only, i.e. a black or half-empty screen rather than an error. So `remote-desktop-linux-session.ts` checks Wayland *before* X11, and `XDG_SESSION_TYPE` outranks both. It also has to *probe* rather than read the env: a PPM started by its systemd user unit has no `DISPLAY`/`XAUTHORITY` at all while a full desktop runs two feet away, so the fallbacks are the `X<N>` socket in `/tmp/.X11-unix`, the `wayland-N` socket in `$XDG_RUNTIME_DIR`, and for auth the `xauth_*` file Xorg was launched with (`-auth /run/user/1000/xauth_XXXXXX`) before `~/.Xauthority`. ffmpeg is then spawned with that env merged over `process.env`. Wayland *capture* is not implemented — it needs the desktop portal, and this is surfaced as an unmet `video` requirement the user can fix by picking X11 at login, never as "platform unsupported" (which would hide the entry and explain nothing).
+- **Remote desktop on Linux is chosen per *session*, not per platform, and Wayland must win the tie**: `process.platform === "linux"` says nothing about how to capture or inject. A Wayland session almost always also runs XWayland, which sets `DISPLAY` and answers `x11grab` **successfully** — with a view of XWayland clients only, i.e. a black or half-empty screen rather than an error. So `remote-desktop-linux-session.ts` checks Wayland *before* X11, and `XDG_SESSION_TYPE` outranks both. It also has to *probe* rather than read the env: a PPM started by its systemd user unit has no `DISPLAY`/`XAUTHORITY` at all while a full desktop runs two feet away, so the fallbacks are the `X<N>` socket in `/tmp/.X11-unix`, the `wayland-N` socket in `$XDG_RUNTIME_DIR`, and for auth the `xauth_*` file Xorg was launched with (`-auth /run/user/1000/xauth_XXXXXX`) before `~/.Xauthority`. ffmpeg is then spawned with that env merged over `process.env`. Wayland capture goes through a **different backend entirely** (`remote-desktop-capture-wayland.ts`) rather than another ffmpeg grabber — see the portal bullet below.
 - **Key injection on Linux goes through evdev codes, never keysyms**: `XKeysymToKeycode(XK_a)` answers "which key currently *produces* an a", which on an AZERTY host is the physical Q key — so a keysym table silently transposes the whole keyboard for anyone not on a US layout. `remote-desktop-evdev-key-map.ts` maps `KeyboardEvent.code` → evdev code, which names the physical switch just as `code` does; X11 keycode = evdev + 8 (`X11_KEYCODE_OFFSET`), verified against a live server for all 50 spot-checked keys. The same table feeds uinput, which wants the raw code. X11 also has no "type this string" call: `text()` uses the real keymap when the character is in it (all ASCII, no round trip) and otherwise borrows a keycode with no keysyms, binds it to `0x01000000|codepoint`, and needs a real ~12ms delay after the remap — the server applies it at once but the focused *client* only learns from its `MappingNotify`, so a key pressed sooner is read with the old mapping.
+- **Wayland capture is a portal session that must outlive the capture, and the three things that make it work were each measured**: a compositor shares the screen only through `org.freedesktop.portal.ScreenCast`, which is D-Bus, which Bun does not speak — so `remote-desktop-portal.ts` is `bun:ffi` against `libdbus-1.so.3` (present on any host with a session bus). Three findings turn this from impossible to routine. **`OpenPipeWireRemote` is never called**: the documented flow ends by receiving a PipeWire *file descriptor*, which no shell-out (`busctl`, `gdbus`) can hand to a separate process — and it turns out not to be needed, because the node lives in the user's own PipeWire daemon, so a bare `pipewiresrc path=<node>` reaches it through `$XDG_RUNTIME_DIR/pipewire-0` (measured: negotiated `BGRA 1920x1080` with no fd in the pipeline). **The D-Bus connection owns the session** — the node dies with it, so the handle is held for the capture's whole life and `dbus_bus_get_private` is used rather than the shared connection, which is refcounted process-wide. And **`persist_mode: 2` + a stored `restore_token`** (under `getPpmDir()`, 0600) is what stops a consent dialog appearing on the *host's* screen every session, which on a remote desktop is a prompt only someone sitting at the machine could answer; the first session still asks. ffmpeg is not the capture tool here at all: reading PipeWire needs `--enable-libpipewire`, which distributions do not do (Arch's own `ffmpeg 2:9.0.1-4.1` does not), so GStreamer does it — exactly as RustDesk does (`Depends On: gst-plugins-base gst-plugin-pipewire` + `libdbus-1.so.3` linked in; it is Rust, not magic). Four traps in the pipeline, each silent. **`videorate max-rate=30` does not cap** — measured 59 fps through it, and 133 fps at `max-rate=60`; only a capsfilter `video/x-raw,framerate=30/1` caps. That same capsfilter is also **what makes an idle desktop watchable**: a portal stream is damage-driven and a still screen pushed **14 frames in 60 seconds**, so a viewer joining a quiet host would see nothing at all — `videorate` duplicates the last frame and held **29.6 fps on a completely static screen**, which keeps keyframes flowing so a late joiner syncs within one GOP. **`vapostproc` + `video/x-raw(memory:VAMemory)` must pair with `vah264enc`** and not with `x264enc`, or every frame is downloaded back out of VA memory; the GPU path cost **14.9% of a core at 1080p30 against 52% for software conversion uncapped**. And the **portal stream dies under consumer churn** — it wants one long-lived `pipewiresrc`, so anything that reconnects per quality change must re-run the handshake rather than reattach. Measured end to end through `startCapture`: first access unit at **430 ms**, 28.8 fps, 3.2 Mbit/s, SPS parsed from GStreamer's bytes by the same `AccessUnitAssembler` ffmpeg's output feeds. `listDisplays()` still answers `[]` on Wayland and that is correct — the portal's own dialog chooses which output is shared, so PPM neither enumerates nor picks.
+
 - **Xlib's default I/O error handler calls `exit()` on the PPM server**: a logout, a GPU reset or `systemctl restart sddm` makes libX11 print `XIO: fatal IO error` and terminate the *calling process* — every project, terminal and chat session gone because someone logged out of the desktop. `remote-desktop-x11.ts` replaces all three handlers (`XSetErrorHandler`, `XSetIOErrorHandler`, and libX11 ≥ 1.7's `XSetIOErrorExitHandler`, which cancels the exit that happens even when the first one returns) and holds the `JSCallback`s in module scope — a GC'd callback leaves Xlib calling a freed trampoline, i.e. a segfault instead of the crash it was installed to prevent. A connection that took an I/O error has no safe call left on it, not even `XCloseDisplay`, so it is dropped un-closed and the next caller reopens.
 - **`xrandr` the binary and `libXrandr` the library are different packages**: this dev host has `libXrandr.so.2` and no `xrandr`, so anything that shells out to enumerate monitors reports "no displays" on a working desktop. `remote-desktop-displays.ts` reads `XRRGetMonitors` over FFI (`sizeof(XRRMonitorInfo)` = 56 on x86-64: name Atom at 0, primary at 8, x/y/w/h at 20/24/28/32) and falls back to one whole-root-window entry when the library is absent. X11 puts every monitor in one root coordinate space, so a per-monitor capture is a crop — `-video_size WxH -i :0.0+X,Y` — and `-i :0.0` alone grabs the union of all of them.
 - **A uinput injector needs two devices, not one**: libinput classifies a device from the capabilities it declares, and one device advertising both a full keyboard and absolute axes is typically read as a *touchpad* — which then applies pointer acceleration and treats absolute coordinates as relative motion, so the pointer drifts instead of landing. `remote-desktop-input-uinput.ts` creates a pointer device (absolute axes + buttons + wheel + `INPUT_PROP_DIRECT`) and a keyboard device separately, declares every key it will ever send (`UI_SET_KEYBIT`; an undeclared key is dropped by the kernel silently), and `UI_DEV_DESTROY`s both on exit or they pile up in the compositor's device list on every restart. Derive the ioctl numbers from real headers — `_IOW` encodes the struct size, so a wrong `sizeof` yields a different request number and `ioctl` fails with `EINVAL` for no visible reason. uinput carries key *codes*, so there is no `text()` at all: a phone soft keyboard that reports no key codes cannot type on a Wayland host.
@@ -145,6 +151,8 @@ Related: `configService.save()`/`set()` throw when `load()` has not run, because
 
 - **An ANSI palette's neutral ends sit on top of the background, and the fix is not in the palette**: two of the sixteen slots are *defined* to be extremes, so a light theme's `white`/`brightWhite` and a dark theme's `black` land on the background — 1.03–1.18:1 across PPM's six built-in themes, i.e. invisible rather than merely dim. It is not a theoretical slot either: oh-my-posh writes its second prompt line in plain **SGR 37**, correct on the dark terminal it was designed for, and that line was absent on every light theme. Recolouring the slot cannot fix it, because the same `white` is also the text *on* a coloured powerline segment where white is right — only a per-cell decision can tell the two uses apart. `minimumContrastRatio` is xterm's, it defaults to **1 (do nothing)**, and VS Code ships 4.5; it adjusts the foreground against each cell's real background, so segments render byte-identically and only text on the bare background moves. Set it as a *terminal* option, not via a renderer: the WebGL addon is skipped on touch devices, which is where this was reported from. Two traps when measuring a prompt: parse `38;5;`/`37`/`97` as well as `38;2;` truecolor, or plain-ANSI runs read as "no colour set" and the real culprit is invisible to the tooling too — and a `%{`…`%}`-quoted zsh prompt has to have those markers stripped before it is written to a terminal, since the shell normally eats them. `tests/unit/web/terminal-contrast.test.ts` pins the hazard and the mitigation together.
 
+- **xterm stays silent about a selection it already reported, even after clearing it**: `onSelectionChange` fires from `_fireEventIfSelectionChanged`, which compares against the last selection it *reported* — and `clearSelection()` fires the event without resetting that record. xterm itself clears on resize, on a buffer switch and whenever the user types with something selected, so selecting the same text again afterwards reports nothing, and anything driven by the event alone (the terminal's Add to chat bar) silently does not appear. Found by an e2e that selected the same rows twice; `terminal-selection-chat.tsx` also reads the selection on the mouseup that ends a press in the terminal. Related: `getSelectionPosition()` is typed as 1-based and returns 0-based columns and buffer rows, end column exclusive.
+
 - **An overlay on a vendored glyph assumes that glyph is empty, and an icon set migration silently breaks that**: the streaming chat tab draws three bouncing dots absolutely positioned over its 16px bubble icon, which was correct against lucide's hollow `MessageSquare`. Fluent's `chat` is the same bubble with **two message lines drawn inside it**, so after the migration the dots landed on the upper line in the same `currentColor` and the three fused into one lumpy bar — a static-looking smudge at the size a tab renders, reported as a broken animation rather than a wrong glyph, because the dots really were still bouncing. The fix is `chat-empty` (exported as `MessageCircle`), whose two subpaths are byte-identical to `chat`'s first two: same outline, nothing in it. Two things generalise. A glyph's *subpath count* is the cheap test for "does this draw anything inside itself" — `tests/unit/web/tab-streaming-indicator.test.ts` asserts the host glyph contributes exactly the outer edge and its hole, so a MAP edit or a regeneration cannot put a lined glyph back under the dots; and freezing a CSS animation with `animation-play-state: paused` plus a *negative* `animation-delay` renders any phase of its cycle, which is how a bounce this small is compared before and after at all. Note also that `isStreaming` is safe to branch an icon on only because both call sites read `sessionId` exclusively for `type === "chat"`.
 
 - **A Monarch `/$/` rule never runs, so a line-oriented grammar may not use states at all**: Monarch's per-line loop ends the moment the position reaches the end of the line, which means the idiomatic-looking `[/$/, { token: "", next: "@popall" }]` is dead code — the state entered mid-line is *never* left, and it carries into every following line. The `dotenv` grammar (`src/web/lib/monaco-dotenv-language.ts`, since Monaco ships no `.env` language and neither does VS Code) first used a `@value` state entered on `=`; from the first assignment on, the whole file tokenized as a value, so `#KEY=off` came back `string` — the one case the language existed for, still broken while every line *looked* coloured. Everything has to happen in `root`, the way Monaco's own `ini` does, and the test forbids a `next:` outright. Two consequences of statelessness worth knowing: a quoted value must be matched **whole** (`/"(?:[^"\\]|\\.)*"/`), which is the only way a `#` inside it is not read as a comment — at the cost of not colouring an interpolation inside quotes; and an unterminated quote falls through to the bare-value rule instead of swallowing the rest of the file. Separately, this grammar needs **no** `*-token-rules.ts` beside `diff-token-rules.ts`: its token names are Monaco's own (`comment`, `key`, `string`, `variable`, `keyword`, `delimiter`) and `monaco-adapter.ts` defines every PPM theme with `inherit: true`, so the colours arrive from the `vs`/`vs-dark` base and cannot drift from the app's themes — the test reads that pairing out of Monaco's own theme table rather than trusting it. Last trap, when verifying any of this in a browser: a standalone Monaco has **one global theme**, so two editors cannot show two themes at once (the second `create` silently retints the first), and sampling colours right after `setTheme` reads the *old* `mtk` class indices against the new palette — `string` measured as `#FF0000`. One editor, one reload per theme. Do not be misled by a `dotenv-*.js` chunk in the build output: that is shiki's TextMate grammar for a fenced `dotenv` block in markdown (`@shikijs/langs`, reached from `markdown-code-block.tsx`), a separate pipeline Monaco cannot read — there is no TextMate bridge in the editor, which is why a Monarch grammar had to be written even though the repository already ships a dotenv grammar.
@@ -184,6 +192,8 @@ Related: `configService.save()`/`set()` throw when `load()` has not run, because
 - **Design exports are octet-stream Blobs, and the view tabs are real links**: a `blob:` URL has PPM's origin, and a browser that ignores `download` (iOS Safari) would open an HTML one and run the design beside the token in `localStorage`. Print and "Open in new tab" are `<a target=_blank rel="noopener noreferrer">` to tokens minted when the menu opens, because a `noopener` `window.open` cannot report a blocked popup. `allow-modals` is reachable only through a print-purpose token; the CDN hosts the design CSP allows (jsdelivr, unpkg) run any npm or GitHub code, which is accepted.
 - **`tabSessionId()` is the only way to ask a tab for its session**: design tabs hold chat sessions too, so `type === "chat" && metadata.sessionId` makes a design session look unopened, and reopening it starts a plain chat outside design mode (`src/web/lib/tab-session-id.ts`).
 - **Hono's global `cors()` overwrites the `Access-Control-Allow-Origin` a route sets**: headers set before the handler are copied over the handler's response, so `design-preview.ts` re-asserts `null` in a middleware after `next()`, and its unit test mounts `cors()` like the real server. The same re-wrap (`new Response(res.body, res)`) makes Bun lose a `BunFile.slice()` body: behind `cors()` a `rangeFileResponse` 206 for `bytes=2-5` sends `Content-Length: 8` and bytes 2 to EOF. That one is still open; route unit tests mount without `cors()`, which is why none caught it.
+- **A gem installed into PPM's own folder cannot find itself, and a release zip needs a tool Bun does not have**: `gem install --install-dir <dir>` writes a binstub that asks RubyGems for its gem, and `<dir>` is on no gem path — measured, it exits with `Gem::GemNotFoundException` unless spawned with `GEM_PATH` naming `<dir>` (`installedServerEnv`, threaded `resolveCommand` → `LspSession.start`). Solargraph's dependencies (prism, rbs, jaro_winkler) compile C, so a host with no compiler fails with "Failed to build gem native extension" and a message that ends on a log path; `lsp-install.ts` says what is missing instead and deletes the half-install gem leaves "for inspection" (a first install only — a working one being updated keeps its folder). For downloads: `Bun.Archive` answers "Unrecognized archive format" for a zip and GNU tar cannot read one either, so a zip off Windows needs `unzip` or `bsdtar` on PATH (Windows' own `tar.exe` is bsdtar), and a host with neither has no button.
+- **The dev bundle's terminal connects straight to `:8081`, whatever server the page came from**: `use-terminal.ts` bypasses Vite's WebSocket proxy in dev, so under the html-preview harness (random API port) every terminal sits on "Reconnecting…" — and if a dev PPM is up on 8081, an e2e's terminal opens a shell *in that instance* and types into it. Check `ss -ltn` for 8081 first; to test a live terminal, put the scratch API on 8081 itself. React's `StrictMode` also double-mounts it in dev, so each terminal spawns two shells and a handed-over command is typed into both, showing twice in one xterm — dev only; a production build mounts once.
 - **A leading BOM makes parse5 drop the locations of `<html>`, `<head>` and `<body>`**: it is read as body text, so those explicit start tags lose `sourceCodeLocation`. Strip it first and address everything in the BOM-less text (`decodeDesignText`); parse5 offsets are UTF-16 code units of exactly the string parsed, as `String#slice` counts them, and `startTag.attrs` is keyed by the lowercased source name.
 - **The pre-migration database snapshot is skipped whenever `CURRENT_SCHEMA_VERSION` lags the migrations**: `backupBeforeMigrations` returns early for a database already at that version, and the constant sat at 47 while migrations reached 49, so a database at 47 ran 48 and 49 with no snapshot. Bump it with every migration; `db-session-design-slug.test.ts` asserts a migrated database ends at it.
 - **A PreToolUse hook verdict needs `hookSpecificOutput.hookEventName: "PreToolUse"`**: the bundled CLI reads `permissionDecision` only when the event name matches ("Hook returned incorrect event name" otherwise), so without it a Deny the user clicked did not block the tool. `preToolUseDecision()` in `claude-agent-sdk-query-options.ts` builds every verdict.
@@ -194,6 +204,34 @@ Related: `configService.save()`/`set()` throw when `load()` has not run, because
 - **A streaming rollout parser cannot use whole-file look-ahead**: it commits to legacy vs `item_completed` format from the *first* `session_meta`'s `cli_version` (`item_completed` shipped in codex cli 0.154.0) and never revisits that choice mid-file — there is no later point at which re-reading the whole file to check is acceptable for a live tail. A `compacted` or `thread_rolled_back` record rewrites the file's *content*, not its format, so `codex-rollout-tail-parser.ts` resets its de-dupe state on those but keeps the format decision from the header.
 - **`resolveSessionDir` falls back to scanning every Claude project on disk**: given a session id whose encoded project path does not resolve, it walks every `~/.claude/projects/*` looking for a matching `<sessionId>.jsonl` — useful for a session started outside PPM, unsafe if trusted before the caller is known to own that session. `src/services/agent-transcript/session-ownership.ts` is the gate every Agent-session transcript read goes through first instead; the `/ws/global` hub never accepts a client-supplied path for this reason.
 
+- **WebCodecs is secure-context only, so Remote Desktop and the Android viewer cannot show a picture on a plain-HTTP LAN address** — which is how a phone or tablet normally reaches PPM. Measured in one browser at one moment: `VideoDecoder` is `undefined` on `http://192.168.98.96:3210` and present on `http://127.0.0.1:3210`, while `RTCPeerConnection` exists on both. Nothing warns; the viewer just reports "this browser has no WebCodecs" about a browser that is fine, which is why `missingDecoderReason()` branches on `window.isSecureContext` instead. The way out is WebRTC, and in Bun that means a **downloaded binary**: there is no WebRTC stack in the runtime, GStreamer's `webrtcbin` **segfaults PyGObject** on GStreamer 1.28.7 + Python 3.14 (`gst_webrtc_session_description_copy` → `gst_sdp_message_copy` → `g_strdup` on a malformed emails array — it dies just *reading* the offer, and rebuilding the description from SDP text does not help) *and* would put GStreamer + PyGObject on every Windows and macOS host, and `@roamhq/wrtc` only accepts raw i420, i.e. it would discard the hardware H.264 encode and re-encode in software. `mediamtx-*.ts` is the answer: MediaMTX repackages the H.264 ffmpeg already produced (verified — 1920x1080 Main@4.0 in, `video/H264` at the same size out) for 0.6% of a core and 55 MB RSS. Four traps in wiring it. Its **shipped `mediamtx.yml` must never be used**: it listens on every interface with RTMP/HLS/SRT/MoQ/API/metrics/pprof on, and MoQ writes `auto.crt`/`auto.key` beside itself on first start — PPM generates its own config and every switch is spelled out, because MediaMTX *rejects unknown keys* (`json: unknown field`), so a renamed key fails loudly instead of silently leaving a listener open. The **ICE/UDP port cannot be loopback** — WebRTC media is peer-to-peer, so confining it breaks every remote viewer while the page still connects; what protects it is the per-session ICE ufrag/password, which is why a test asserts the port is *not* loopback. `filesrc` **cannot read a FIFO** (it probes for seekability and closes it, so ffmpeg takes EPIPE) — open the FIFO yourself and hand over `fdsrc fd=N`. And the relay answers **404 until the publisher's first packet**, which a quality change re-creates by respawning ffmpeg, so the browser's WHEP handshake must retry rather than fail. Peer-to-peer also means a viewer on the **Cloudflare tunnel** has no route for the media at all: the handshake is proxied over HTTPS and succeeds, then nothing arrives, and Chromium takes **15 s** (measured, no candidate reachable) to call the connection `failed`. So `use-webrtc-canvas-video.ts` gives ICE `CONNECT_DEADLINE_MS` and the connection hook reconnects asking for the WebSocket stream, remembered for the tab in `sessionStorage` — but only where WebCodecs exists: behind the tunnel's HTTPS it does in any browser that ships it, on a plain-HTTP LAN origin it never does, and there the WebRTC error stands. Last: `startCapture` keeps `stdout: "pipe"` in both modes even though nothing reads it when publishing — making it conditional widens Bun's spawn type so `proc.stdout` is possibly-undefined everywhere below, the same family as the `ReturnType<typeof Bun.spawn>` trap above.
+- **`Bun.spawn({ stdin: other.stdout })` is not a pipe between two children**: Bun reads every byte into PPM and writes it back out with a pump of its own (measured: piping 200 MB raised the Bun process's own `rchar` and `wchar` by 200 MB each). Two failures follow, both silent until the reader dies. Under a burst, that pump rejects with `EPIPE`s nothing can catch — 2–3 per remux death with keyframe-sized writes, and `handleFatalError` in `src/server/index.ts` exits the server at 3 in a minute. And a reader that stalls before dying leaves the writer running for good, because Bun is still reading it: gst-launch kept encoding with no `onExit` and the viewer sat on a frozen picture. `remote-desktop-capture-wayland.ts` therefore pumps gst into the remux itself (one awaited `write()` + `flush()` per chunk, the same shape as the `FileSink` entry above) and watches **both** processes, the first to die taking the other down. `wayland-capture-supervision.test.ts` drives it with shell stand-ins; under `bun test` an unhandled rejection is a failed test, which is what makes the burst case assertable at all.
+
+- **The error that ends a turn is in no transcript, so anything rebuilt from history drops it**: a Max Turns stop reaches the browser as an `error` event and a `done` with `resultSubtype: "error_max_turns"`, and Claude's JSONL ends at the turn's last tool result. A reload rebuilds the chat from that transcript, and so does the end of any turn long enough to overflow the 10,000-event reconnect buffer (thinking deltas fill it), where `replayTruncatedRef` refetches history at idle — so the one red line saying why the session stopped vanished, and the notification said "Chat completed". `turn-stop-reader.ts` reads how the last top-level turn ended back from the session trace (a cancel, a newer message or a turn still running means no stop; rows with `parentToolUseId` are a subagent's), `session_state.turnStop` carries it to every greeting, `turn_stop` goes out just before the `done`, and `useChat` keeps it apart from `messages` so a refetch cannot erase it. Several `session_state` builders (model, effort, thinking) omit the field, which is why the client only touches `turnStop` when the key is present. Verify with `node tests/e2e/turn-stop-e2e.mjs` (`PPM_PLAYWRIGHT_MODULE` if Playwright is not installed here).
+- **`PRAGMA auto_vacuum` takes the write lock even when it changes nothing, so `busy_timeout` must be set first**: the session trace set it after `auto_vacuum`/`journal_mode` (copied from `query-audit-db.ts`, which still has that order), and a second process opening the file while another was mid-write got `SQLITE_BUSY` at once — measured: a lock held for 300 ms failed the open outright against a 2 s timeout. Only the full unit suite's server-plus-CLI race caught it. `journal_mode = WAL` on a file already in WAL does *not* wait on a writer, which is why `db.service.ts`'s order is harmless. Put `busy_timeout` first in any opener two processes share.
+- **The Claude SDK interleaves a data-less `system/thinking_tokens` between every two thinking deltas**, so anything folding *consecutive* deltas folds nothing: the trace's coalescer turned one real turn into 92 rows, 84 of them single deltas and ticks. The provider forwards every SDK system message it does not special-case as a bare `{type, subtype}` (`claude-agent-sdk.ts`), and that shape is how to recognise a signal — `trace-coalescer.ts` counts one arriving inside a block on the block (`signals`) instead of closing it. A mock or scripted provider that never sends these hides the bug entirely, which is why the replay test's script now does.
+- **A terminal with no layout is fitted to 2x1, and zsh does not survive 2x1**: xterm's FitAddon never proposes less than 2 columns by 1 row, which is exactly its answer for a 0x0 container. A terminal is mounted with no layout more often than it looks. The dock's active tab is mounted while the dock is hidden (`collectFromDock` marks it active either way), and a phone restores every dock collapsed (`collapseRestoredDockOnMobile`). Fitted at mount, such a terminal got 2x1, and its socket sent that size on open. zsh with a themed prompt then corrupted its own heap redrawing at 2 columns. glibc aborted it with `double free or corruption (!prev)` on the first keystroke after the terminal was shown, up to an hour later and at an ordinary size. That is why every core in `coredumpctl` read 156-269 columns and none pointed at a resize. Replayed against zsh with an oh-my-zsh + oh-my-posh config: left at 2x1 or 2x2, 20 of 20 shells died on that keystroke; at 3x1, 10x1, 2x20, 156x1 or 80x24, none did, and a bare zsh survived 2x1. Every `fit()` in `use-terminal.ts` now asks `proposeDimensions()` first, and `terminalService.resize` drops anything `isUsableTerminalSize` (20x2, `src/shared/terminal-size.ts`) rejects, so a browser on an older bundle cannot do it either. Two lessons for the next one. A crash that lands long after its cause needs the history of the shell's size, and the live PTYs hold it: `stty -F /dev/pts/N size` on each `zsh` under `ppm.service` found a hidden terminal still sitting at 2x1. And the ResizeObserver's own `contentRect` zero check was never enough, because its debounced fit runs 100 ms later, when the tab may already be parked. Verify with `PPM_E2E_DIST=<scratch dist> node tests/e2e/terminal-hidden-resize-e2e.mjs`, which reads the size from the shell's tty rather than from xterm.
+- **A session's "before" for a file is PPM's to keep, because no transcript holds it**: Claude Code records a tool's `toolUseResult.originalFile` only for small files (measured: kept at 9,836 B, gone from 13.6 KB up), an Edit's `old_string` is a fragment at an unknown offset, SDK checkpointing is off, and git HEAD also holds whatever was uncommitted before the session began. So the session review reads `session-baselines/` (see Architecture), filled at PreToolUse **in every permission mode**. That last part is new: before it, a bypass-mode session — the default — installed **no PreToolUse hook at all** (the permission hook is skipped there by design), so anything added to the permission hook does not run for most sessions. `buildToolHooks` therefore gives bypass mode a file-write hook of its own (`PreToolUse[0]` there), while every other mode runs it from the permission hook once that has allowed the write — a denied write records nothing; `permissionHook()` in `claude-agent-sdk.test.ts` finds that `.*` one. Verified against the real CLI in bypass mode: the hook fires for a sub-agent's Write too. A record is hard-linked into place so the **first capture wins**; never "fix" a missing record by writing one later in the session, which would record a state the session itself produced. Shell commands are the exception that proves it: `shell-change-tracker.ts` reads a file's bytes *before* the command runs and records them only if the command moved it, and a file git did not list is HEAD — read from the **pre-command** HEAD, because `git commit` in the same command moves it (the post-command HEAD would name the new content as the "before"). Outside bypass mode that snapshot is taken by the permission hook once it has allowed the command, not by a hook of its own, so it cannot be taken while the approval prompt is still open — an edit made during that wait would otherwise be put on the command (checked with the real CLI: a file edited during a 1.5 s approval wait was not recorded).
+- **Codex's `FileUpdateChange.diff` is a diff only for an update**: for `add` and `delete` it is the file's **raw content**, and an update may end in `\n\nMoved to: <path>`. Parsing all three as a unified diff (`diffToOldNew`) dropped every line without a `+`/`-`/space prefix, so a created file counted +0. The rollout's `item_completed` FileChange carries `changes` as a dict keyed by path, not the live array (`rolloutFileChanges` vs `fileUpdateChanges` in `codex-patch.ts`). One patch over several files is **one** Edit/Write card whose own fields describe only the first file, with `input.files` listing all of them — read `files`, or every file after the first is invisible. And the patch is on disk before PPM hears of it, so its "before" is the diff reverse-applied (`reverse-unified-diff.ts`), which refuses rather than guesses when a hunk does not match.
+- **`@monaco-editor/react` 4.7 disposes a diff's models before the diff editor holding them**, and Monaco 0.55 reports it as an uncaught "TextModel got disposed before DiffEditorWidget model got reset" on every unmount — every closed diff tab, every file a review steps to. `DiffEditor` in `diff-viewer.tsx` is the library component's parent and detaches and disposes the models in its own cleanup, which React runs first because it runs a removed subtree's cleanups parent before child (every layout one before any passive one). The layout effect there is margin, not the fix: measured on React 19.2, a `useEffect` cleanup in the wrapper also runs before the library's passive one. `diff-viewer-dispose-order.test.ts` mounts the real viewer over the real library and goes red without the cleanup. Separately, that file's word-wrap sync forced `wordWrapOverride2` onto the original editor in **inline** mode too, where the original is a hidden 35px column: every line wrapped many rows tall and the inline view padded the visible side to match, so a phone showed one changed line between screens of hatching (`.diagonal-fill`). Monaco itself keeps that editor unwrapped when inline; only a side-by-side original wraps now.
+- **A bounded read of a file stream has to count its own bytes and end with `cancel()`**: on Bun 1.3.11, `Bun.file(f).slice(a, b).stream()` never finishes when `b` is well short of the end of a multi-MB file — the last `read()` neither resolves nor errors (a 4MB file's `slice(0, 259)` hung; `slice(0, size - 1)` and an endless `slice(a)` did not) — so `readLines` takes `toByte` and stops at it itself. And a reader let go of before its end with `releaseLock()` keeps its file descriptor: 2000 early stops left 2000 open, `reader.cancel()` closes it. Both bite the windowed transcript reads in `compact-segment.ts`, which stop early on every scroll up by design; `compact-segment.test.ts` pins both.
+
+- **Rebuilding a table that others reference deletes their rows unless foreign keys are off — and that pragma is ignored inside a transaction**: SQLite's recipe for changing a constraint (create the new table, copy, drop the old one, rename) is how migration 55 let `connections` accept `mysql` / `mariadb`. With `foreign_keys = ON`, `DROP TABLE connections` runs an implicit `DELETE` that cascades through `connection_table_cache`'s `ON DELETE CASCADE` and empties it before the new table exists — no error, just a cache that is gone. `PRAGMA foreign_keys = OFF` is a no-op inside a transaction, so `allowConnectionTypes` in `db.service.ts` turns it off *before* `BEGIN`, reads it back and refuses to run when a caller's transaction kept it on, and restores it afterwards. It also rebuilds from the table's own recorded SQL with only the CHECK replaced, so a column a later migration added is carried over, and keeps the `AUTOINCREMENT` high-water mark, because query-audit rows still name the ids of deleted connections.
+- **SQLite has no `ILIKE`, and its `LIKE` ignores case for ASCII only**: a filter written with Postgres's `ILIKE` is a syntax error on SQLite. Case-insensitive matching goes through each dialect's `likeInsensitive` (`src/services/database/dialect-*.ts`): `ILIKE … ESCAPE E'\\'` on Postgres, plain `LIKE … ESCAPE '\'` on SQLite (already case-blind for ASCII; "Ä" and "ä" stay different because `bun:sqlite` loads no ICU), and `LIKE … ESCAPE CHAR(92)` under the column's own collation on MySQL, where a `_ci` collation ignores case and `LOWER(col)` would give up the index (the escape is named because a server whose `sql_mode` has `NO_BACKSLASH_ESCAPES` gives `LIKE` none, and as `CHAR(92)` because a backslash written as a string literal is spelled differently in each mode). Build filter SQL through the dialect, never by pasting an operator into a string.
+- **A result read as objects loses the columns that share a name**: `SELECT 1 AS a, 2 AS b, 3 AS a` has three columns, but a row object holds one `a`, so a header built from `Object.keys(row)` shows two. bun:sqlite is worse than lossy: its `columnNames` is built from an object's keys too, so the repeat collapses *and moves* — `["b", "a"]` over three values, pairing every value with the wrong name. Read rows as arrays next to the driver's column metadata (postgres.js `.values()`, mysql2 `rowsAsArray: true`, bun:sqlite `.values()`), and for SQLite recover the names with `statementColumnNames` in `sqlite.service.ts`, which prepares the statement again as a subquery — never runs it — because SQLite then renames the repeats to `a:1`, `a:2`.
+- **`git pull` refuses a diverged branch on git ≥ 2.33 unless the repository says how to reconcile**: it fails with "Need to specify how to reconcile divergent branches", so a Pull or Sync button works every time until the first time it is needed. `git-workflow.service.ts` adds `--no-rebase` (a merge, as GitHub Desktop does) only when none of `pull.rebase`, `pull.ff` and `branch.<name>.rebase` is set — passed unconditionally it would override `pull.ff = only` and merge anyway.
+- **`git stash pop`/`apply` without `--index` puts staged changes back unstaged, silently**; with it, git refuses outright when the staged part no longer applies, and touches nothing. So `git-workflow.service.ts` tries `--index` first, falls back to a plain apply, and the UI says the changes "came back unstaged". It also checks the hash of `stash@{n}` before acting, because the list renumbers whenever anything else pushes or drops a stash.
+- **Since git 2.48, `git fetch` creates `refs/remotes/origin/HEAD`, and `%(refname:short)` prints it as `origin`**: a ref list that does not skip symbolic refs (`%(symref)` set) grows a branch called "origin" and an extra label on the default branch's commit. The Git Graph showed both until it skipped them.
+- **Codex renames a new chat during its first turn, so anything holding a session id across a turn has to follow it**: the tab tools' token is minted under PPM's id and handed to the Codex app-server in its environment, for the life of that process. During the first turn Codex emits `session_migrated` and `ws/chat.ts` re-keys `activeSessions` and the sockets to the thread id — so every later `open_file`/`open_preview` named an id with no sockets, and in a new Codex chat the tools answered "no device" while the chat sat open in front of the user. `tab-open-broker.ts` keys its pending calls, limits and delivery by `resolveMigratedSession(id)`. Claude keeps its id, which is why only Codex showed it.
+- **History pairs a tool's result with its call inside one message, so results must be merged into the message that holds the call**: the Claude SDK writes every content block as its own record, so two calls made at once are two assistant records followed by both results. The old merge put every result on the *last* assistant message, which left the first call's card with no result — fine while streaming, then lost when the chat refetches history at the end of the turn. `mergeToolResultMessages` in `jsonl-transcript-parser.ts` routes each result by `toolUseId`, and both history paths (`getMessages` and `parseJsonlTranscript`) use it.
+- **`handleEditorMount` in `code-editor.tsx` is memoised on `[isSql]`, so it sees the props of the render that created it**: a tab can be asked for a line before its editor exists — `open_file` with `line` on an HTML page open in preview mounts Monaco only when it switches to code — and the stale closure revealed the first render's target, i.e. none. It reads `revealTargetRef` now; anything else that handler needs from props has to go through a ref too.
+- **In a Playwright-driven preview check, a page error naming `localStorage` or `serviceWorker` is Playwright's, not the page's**: `addInitScript` runs in every frame, the sandboxed previews included, where storage access throws `SecurityError`, and `serviceWorkers: "block"` injects a read of `navigator.serviceWorker` that an opaque-origin frame refuses too. The bridge reports both as the page's own errors, so the check lists problems the page does not have. Guard init scripts with `window.top !== window` and filter the service-worker one (`ai-tab-tools-e2e.mjs`).
+- **An AI uses PPM's tool only if it does not think it has a better one**: with the user's Playwright MCP available, Opus given `open_preview`'s first description wrote the page, checked it in its own headless browser for four minutes (28 Playwright calls) and opened the tab only at the end — the user watched nothing. Saying *when* to call (as soon as the file is written; the user watches while you fix) and that the check needs no browser of its own put the call 5 s after the Write (Codex's came 34 s after its Write). Opus still opened its own browser afterwards, but only for what the check does not cover: hover tooltips and dark mode. The first run also inherited a max effort, so the two changes are not separated. Claude Code 2.1.280+ defers MCP tools, so a session's first call to either tool costs a `ToolSearch` round first.
+- **A Tailscale Service is three admin steps the CLI cannot take, and its approval is not in the serve config**: `tailscale serve --service=svc:<name>` refuses an untagged node (`service hosts must be tagged nodes`), cannot define the service (the admin console's Services page does) and leaves the host waiting for an admin. Whether that approval happened is only in `status --json`: `Self.CapMap["service-host"]` maps each service this node may host to its VIPs (`[{ "svc:ppm": [...] }]`), and `CapMap["services/<name>"]` is present for a definition the node can see. `--service` forces `--bg`, so tailscaled keeps the handler across PPM restarts and reboots: PPM's switch is a desired state, re-applied by `ensureServiceOnStartup`, and a switch never touched counts an address already pointing at PPM as on (the address this dev host is reached at was set up by hand). A `svc:<name>` pointing anywhere else is never taken over without `replace` (409 `code: "conflict"`), which is also what keeps a dev instance off the live one's name. Two traps in `tailscale up`: on a node with any non-default pref it refuses with `requires mentioning all non-default flags` and prints the command that keeps them, which `tailscale-login.ts` retries once; and a stopped node must get a bare `up`, because any flag, `--json` included, takes it into that same refusal. `tailscale debug prefs` carries the node's private keys (`Config.PrivateNodeKey`, the network-lock key): `parsePrefs` keeps three fields, so never log or return the raw output. On Linux tailscaled takes changes from root and its `OperatorUser` only, which is why the pane's operator step (`sudo tailscale set --operator=<user>`) comes before sign-in. Never run `tailscale up`, `login`, `logout` or a `serve` change against this dev host from a test; `tests/fixtures/fake-tailscale.ts` answers every command the pane uses.
+- **A forwarded page that refuses framing is let into PPM's tab by the hop, never by stripping the header**: the web-preview tab is an iframe on PPM's origin, so Rails' default `X-Frame-Options: SAMEORIGIN`, Django's `DENY` or any CSP `frame-ancestors` rendered a blocked frame. Deleting those headers would let every site frame the dev app, which matters for a public Cloudflare forward. `frame-ancestors.ts` translates instead: SAMEORIGIN becomes `frame-ancestors 'self' <PPM>`, DENY becomes `frame-ancestors <PPM>`, and an existing `frame-ancestors` gains PPM's origins (`'none'` dropped, since it cannot stand beside a source). `X-Frame-Options` cannot name an origin (`ALLOW-FROM` is ignored everywhere), and an enforced `frame-ancestors` makes browsers skip it. PPM's origin has to come from the browser: the server cannot know every name it is reached by (LAN address, tunnel, reverse proxy). So the tab POSTs `location.origin` to `/api/tunnels/frame-ancestors` before its frame loads and again on Reload; the list is in memory like the hops, so a restart forgets it. CSP has no IPv6 literal, so a PPM opened at `http://[::1]:<port>` cannot be named. `bun tests/e2e/forward-hop-framing-e2e.ts` checks the verdict in Chromium, Firefox and WebKit: PPM may frame every page, another site still may not. In a UI e2e, note that Forward opens the tab by itself, so nothing read after Forward is a "before".
+- **Headless Chromium cannot subscribe to push, so a push e2e has to enter at the service worker**: `pushManager.subscribe` there fails with `Registration failed - permission denied`, so no test ever reaches a real FCM endpoint. The two halves are checked apart: the server's by encrypting a real push (`src/services/web-push/`) to a local HTTPS receiver, the worker's with CDP `ServiceWorker.deliverPushMessage` for `push` and a `NotificationEvent` dispatched inside the worker (`page.context().serviceWorkers()` → `evaluate`) for `notificationclick`. Chrome accepts only `userVisibleOnly: true` subscriptions, so `sw.ts` shows a notification for every push and never drops one. Like wake lock and WebCodecs, push needs a secure context, and on iOS a Home Screen install too; the Notifications pane says which one is missing instead of offering a switch that cannot work.
+- **A log line's timestamp is a claim, not its place in the file**: the live `ppm.log.1` held a record stamped `2026-10-06T03:06:13Z` among `20:49Z` ones. The old build logged tool output verbatim (`tool_result: … output=`), that output quoted an example log line from the docs, and the reader took the quoted line for a record of its own. Merged by timestamp, it carried everything after it in the file seven hours forward. `formatLogLine` still writes a multi-line message as it is, so any text that quotes a log line can do it again. `log-columns.ts` therefore orders records by an `order` key: the longest run of in-step timestamps (patience sort), with each line off that run taking the time of the last in-step line before it. `merge()` and the time-range search compare that key, and `ppm.log.3` → `ppm.log` are one chain read in file order; only separate logs are interleaved by time. Related: Show in Logs reaches lines older than the first page with `reach=<id>`, one request capped at `MAX_REACH` (15,000 lines) that answers `reachMissed: "far" | "gone"` rather than leaving an empty selection.
+
 ## UI Rules
 
 When creating or modifying any UI component, you MUST read and follow `docs/design-guidelines.md`, especially the **Mobile-First UI Rules** section. Key rules:
@@ -239,13 +277,16 @@ Before planning or implementing a new feature, read `docs/project-roadmap.md` to
   - **`os.cpus()` cannot express a core that is blocked on I/O**, and the failure is a *confident wrong number* rather than a gap: libuv's Linux `uv_cpu_info` reads the `iowait`, `softirq` and `steal` columns of `/proc/stat` into a throwaway, so a core parked in iowait reports a tiny total delta with no idle in it and `(total-idle)/total` comes out **100%** — one bar of the Overview per-core strip drew solid red, every tick, for a thread that was 3% busy behind a 191 MB/s write. `cpu-memory-collector.ts` samples `/proc/stat` itself (`parseProcStatCores`) and keeps `os.cpus()` as the off-Linux fallback; iowait is folded into not-busy the way `top` and Mission Center both have it, and softirq is counted as kernel time rather than dropped from the total. Do **not** also add `guest`/`guest_nice`: the kernel already counts them inside `user`/`nice`, so summing them deflates every percentage on a host running VMs. The whole-machine `total` hid this — one core's 6-jiffy window barely moves a sum over 24 — so verify per-core figures against `/proc/stat` directly, never against the total.
   - The contract everywhere here is **`undefined` = cannot measure**, and the UI renders that as an em dash. Never substitute `0`: "this GPU has no dedicated memory" and "this GPU has 0 MB of memory" are different claims, and `tests/unit/web/overview-gpu-card-vram.test.tsx` pins the difference.
 - `src/services/db-backup/` — verified `VACUUM INTO` snapshots of `ppm.db` (hourly + at start + before every migration), GFS retention, `ppm backup` / `ppm restore`
-- `src/services/remote-desktop/` — Remote Desktop: one ffmpeg per WS session (`remote-desktop-capture.ts` + per-platform `remote-desktop-capture-input.ts` + `remote-desktop-encoder-args.ts`) → Annex-B H.264 access units → WebCodecs; input via `remote-desktop-input.ts` facade over `remote-desktop-input-{win32,darwin,linux,uinput}.ts` (bun:ffi, no helper binary); host checklist in `remote-desktop-requirements.ts` (ffmpeg install command, macOS TCC pre-flight, Linux session/XTEST/uinput rows); display list in `remote-desktop-displays.ts` (`CGGetActiveDisplayList` order = avfoundation `Capture screen N`, names/bounds via one JXA call; X11 monitors via `XRRGetMonitors`). Linux specifics: `remote-desktop-linux-session.ts` decides X11 vs Wayland and resolves `DISPLAY`/`XAUTHORITY`, `remote-desktop-x11.ts` is the shared Xlib connection, `remote-desktop-evdev-key-map.ts` is the one key table both Linux backends use. Clipboard sync is `remote-desktop-clipboard.ts` (host side, one helper process per read/write) and `src/web/components/remote-desktop/remote-desktop-clipboard-client.ts` (which key combos mean copy/paste, plus the insecure-origin copy fallback). The in-session controls are `remote-desktop-toolbar.tsx` (desktop, RustDesk's grouped menus) and `remote-desktop-mobile-toolbar.tsx` + `remote-desktop-mobile-settings.tsx` (thumb zone), with the scale maths in `remote-desktop-view-style.ts`. Host audio is `remote-desktop-audio.ts` (a second ffmpeg, Opus in Ogg) demuxed by `remote-desktop-ogg-opus.ts` and played by `use-opus-audio-player.ts`; privacy mode is `remote-desktop-privacy.ts` (X grabs + DPMS); host resolution is `remote-desktop-resolution.ts` (XRandR FFI) with the menu collapse and the fit-local decision in `remote-desktop-resolution-list.ts`; the custom image-quality maths ported from RustDesk's `video_qos.rs` are `src/shared/remote-desktop-custom-quality.ts` behind `remote-desktop-custom-quality-dialog.tsx`; screenshot/recording are `remote-desktop-recording.ts` + `use-remote-desktop-recorder.ts` (client-side `MediaRecorder` over the canvas). Codec choice comes from `workingEncoders()` in `media-transcode/ffmpeg-capabilities.ts`, which probes *every* candidate rather than short-circuiting. Routes `src/server/routes/remote-desktop.ts`, WS `src/server/ws/remote-desktop.ts`, UI `src/web/components/remote-desktop/`, e2e `tests/e2e/remote-desktop-e2e.mjs`
+- `src/services/session-trace/` — the session trace ("every run is traceable"): its own `session-trace.db` (outside `db-backup` — a log, not state), one trace per run keyed by the PPM session id with `trace_aliases` for ids a provider migrated to. `ChatService` records every input it handles (`user_message`, `context_added`, `approval_resolved`, `turn_aborted`) and every provider event, text/thinking deltas coalesced per block (`trace-coalescer.ts`), through a batching writer that never throws into a chat (`trace-writer.ts`). Browser half: `src/web/lib/trace-client.ts` (every console level; errors carry the 50 lines before them) posting to `POST /api/trace` keyed by device id, plus the inline watchdog beacon in `index.html`. Read a session with `GET /api/trace/sessions/:id`; retention in `session-trace-cleanup.ts`. Design and as-built notes: `docs/architecture/plugins-and-tracing.md`
+- `src/services/logs/` — the Logs window, which replaced Report Bug. `log-store.ts` reads every log as one list — `ppm.log` and its rotated copies, `cloudflared.log`, and the browser rows the session trace already keeps (`browser-logs.ts`) — indexed per file inode as typed columns (`log-file-index.ts`, `log-columns.ts`: ~450k records in ~13 MB where objects cost ~200 MB), with the text read back a page at a time. `log-live.ts` is the live tail: a one-second poll that runs only while some view is subscribed over `/ws/global` (`logs:subscribe`). `log-issues.ts` is the Issues tab — the last 24 hours of errors and warnings grouped by `src/shared/log-fingerprint.ts`, then sorted by cause by Claude Haiku through `log-ai.ts` (`completeOnce`, the person's own account, no tools), remembered per fingerprint in `<ppm dir>/logs-issues.json`; Auto runs at most every ten minutes and only while something reads the issues. `log-report-draft.ts` drafts a report from chosen lines, `log-environment.ts` is its Environment block, `github-issues.ts` asks GitHub for labels and look-alike open issues — never posts. What the Logs window's own AI is shown and what goes into a report go through `src/shared/log-redact.ts` first, which takes out secrets whatever the switches say (a process's own stderr reaches `ppm.log` unredacted); Add to chat puts lines in a chat as they are. Routes `src/server/routes/logs.ts` (authenticated, like the old bug report's `/api/logs/recent` in `src/server/index.ts`, which nothing in PPM reads any more), shapes `src/shared/logs-model.ts` + `logs-api.ts`. UI `src/web/components/logs/` — a window on desktop, the `logs` tab below `md`, both through `open-logs.ts` — with the pure halves in `src/web/lib/logs/` (`logs-view-model.ts`: folding repeats, ranges; `logs-report.ts`: the issue Markdown and its URL limit). The GitHub button is a real `<a target=_blank>`, so it cannot be popup-blocked, and a body too long for the URL is copied instead
+- `src/services/remote-desktop/` — Remote Desktop: one ffmpeg per WS session (`remote-desktop-capture.ts` + per-platform `remote-desktop-capture-input.ts` + `remote-desktop-encoder-args.ts`) → Annex-B H.264 access units → WebCodecs; input via `remote-desktop-input.ts` facade over `remote-desktop-input-{win32,darwin,linux,uinput}.ts` (bun:ffi, no helper binary); host checklist in `remote-desktop-requirements.ts` (ffmpeg install command, macOS TCC pre-flight, Linux session/XTEST/uinput rows); display list in `remote-desktop-displays.ts` (`CGGetActiveDisplayList` order = avfoundation `Capture screen N`, names/bounds via one JXA call; X11 monitors via `XRRGetMonitors`). Linux specifics: `remote-desktop-linux-session.ts` decides X11 vs Wayland and resolves `DISPLAY`/`XAUTHORITY` (a Wayland session then takes a separate capture backend: `remote-desktop-portal.ts` holds the `org.freedesktop.portal.ScreenCast` session over libdbus FFI and `remote-desktop-capture-wayland.ts` runs `gst-launch-1.0` against the PipeWire node it hands back, producing the same Annex-B stdout ffmpeg does),  `remote-desktop-x11.ts` is the shared Xlib connection, `remote-desktop-evdev-key-map.ts` is the one key table both Linux backends use. Clipboard sync is `remote-desktop-clipboard.ts` (host side, one helper process per read/write) and `src/web/components/remote-desktop/remote-desktop-clipboard-client.ts` (which key combos mean copy/paste, plus the insecure-origin copy fallback). The in-session controls are `remote-desktop-toolbar.tsx` (desktop, RustDesk's grouped menus) and `remote-desktop-mobile-toolbar.tsx` + `remote-desktop-mobile-settings.tsx` (thumb zone), with the scale maths in `remote-desktop-view-style.ts`. Host audio is `remote-desktop-audio.ts` (a second ffmpeg, Opus in Ogg) demuxed by `remote-desktop-ogg-opus.ts` and played by `use-opus-audio-player.ts`; privacy mode is `remote-desktop-privacy.ts` (X grabs + DPMS); host resolution is `remote-desktop-resolution.ts` (XRandR FFI) with the menu collapse and the fit-local decision in `remote-desktop-resolution-list.ts`; the custom image-quality maths ported from RustDesk's `video_qos.rs` are `src/shared/remote-desktop-custom-quality.ts` behind `remote-desktop-custom-quality-dialog.tsx`; screenshot/recording are `remote-desktop-recording.ts` + `use-remote-desktop-recorder.ts` (client-side `MediaRecorder` over the canvas). The WebRTC transport is an optional downloaded relay: `mediamtx-catalog.ts` (pinned version + SHA-256 per platform), `mediamtx-install.service.ts`, `mediamtx-paths.ts`, `mediamtx-config.ts` (the generated config — the one place the relay's exposure is decided) and `mediamtx-process.ts` (one relay per session, free ports, waits until it is really listening); `buildCaptureArgs`'s last argument swaps `pipe:1` for an RTSP push, `remote-desktop-whep-registry.ts` + `POST /api/remote-desktop/whep/:ticket` are the authenticated, **ticket-addressed** handshake proxy, and `use-webrtc-canvas-video.ts` paints the track into the same canvas the WebCodecs path draws to. Settings pane `settings/remote-desktop-settings-section.tsx`. Codec choice comes from `workingEncoders()` in `media-transcode/ffmpeg-capabilities.ts`, which probes *every* candidate rather than short-circuiting. Routes `src/server/routes/remote-desktop.ts`, WS `src/server/ws/remote-desktop.ts`, UI `src/web/components/remote-desktop/`, e2e `tests/e2e/remote-desktop-e2e.mjs`
 - `src/services/git-hunks/` — hunk/line-level stage, unstage and discard (`/api/projects/:name/git/{hunks,stage-hunks,unstage-hunks,discard-hunks}`). `unified-diff.ts` holds the patch surgery (recomputed `@@` counts, unselected deletions demoted to context); the UI is `src/web/components/git/hunk-stage-dialog.tsx`
 - `src/services/git-repos/` — which repository a project's git surfaces run in, when the project folder is a container of checkouts rather than a repository itself. `git-repo-discovery.ts` walks the folder (`GET /git/repos`), the `?repo=` middleware in `src/server/routes/git.ts` scopes every git route to one of them, and the browser side is `src/web/lib/git-repo-scope.ts` (pure decisions and both directions of path rebasing), `src/web/stores/git-repo-store.ts` (the device-local choice), `src/web/hooks/use-git-repo.ts` (what every panel calls) and `src/web/components/git/git-repo-picker.tsx`. Extension panels are opened on the repository, so `packages/ext-git-graph/src/project-scope.ts` maps that path back to the containing project
+- `src/services/git-changes/` + `src/services/git-workflow/` + `src/services/git-discard-journal/` + `src/services/git-commit-draft.service.ts` — Source Control, the Review changes tab and the Git Graph as one flow over the same routes. `GET /git/changes` is the working tree file by file and block by block (one `git status --porcelain=v2`, at most one `git diff` per side, `GIT_OPTIONAL_LOCKS=0`; a block's id is the fingerprint `git-hunks` resolves), every POST on the git router emits `git:changed` on `/ws/global`, a discard is kept for Undo under `<ppm dir>/git-discards/`, and the commit message is one per repository in `chat_drafts` (`git:commit-draft`). UI: `src/web/components/git/git-status-panel.tsx` and its `git-*.tsx` parts (decisions in `src/web/lib/git-changes-view.ts`), the `git-review` tab in `src/web/components/git-review/` over `src/web/lib/git-review-model.ts`, and the Git Graph reaching the same routes through `packages/ext-git-graph/src/ppm-git.ts` — a git write that bypasses them is heard by nobody until the next poll. The Git Graph's file icons are the app's, answered per name by `src/web/components/extensions/webview-file-icons.ts`. Docs `docs/architecture/workspace-and-ui.md` → Source Control, Review changes and Git Graph
 - `src/web/lib/icons.ts` + `src/web/lib/icons.generated.tsx` + `src/web/lib/fluent-icon.tsx` — the product icons (Fluent System Icons 20px Regular, MIT, microsoft/fluentui-system-icons) for the app's own chrome. Every UI icon is imported from `@/lib/icons`; regenerate with `bun scripts/gen-product-icons.ts` after editing its `MAP`
 - `src/server/routes/static-fallback.ts` + `src/web/components/root-error-boundary.tsx` + `src/web/lib/chunk-recovery.ts` + the inline watchdog in `src/web/index.html` — the four halves of not going blank when a chunk is missing: 404 instead of the shell, a boundary above `App`, one guarded purge-and-reload on `vite:preloadError`, and a dependency-free last resort for when the entry never ran at all
 - `src/web/lib/file-icons.tsx` + `src/web/lib/file-icon-name.ts` + `src/web/lib/file-icons.generated.ts` + `src/web/styles/file-icons.generated.css` — the file icon theme (real `vscode-icons` artwork, MIT). `FileIcon` for a component slot, `fileIconElement` for the `icon: ElementType` slots (tab bar, command palette, both through `src/web/lib/tab-type-icons.ts`). Name resolution is the pure half in `file-icon-name.ts` (importable under `bun:test`); the framework preset comes from `src/web/stores/project-framework-store.ts`. Regenerate with `bun scripts/gen-file-icons.ts`
-- `src/services/lsp/` — language servers for the editor. `server-registry.ts` says which binary serves which language and how to find it (project `node_modules/.bin`, then PATH, then PPM's own directory), `lsp-protocol.ts` is the `Content-Length` framing, `lsp-session.ts` owns one child process, `lsp-manager.ts` decides how many exist and shares them by *server + root directory*. `lsp-install.ts` is the Install button's host half, one plan per server: `bun add` of the registry's packages into `<ppm dir>/lsp-servers` — never `-g` — `go install` with `GOBIN` pointed at that same directory, and for rust-analyzer alone `rustup component add` **in the project's directory**, keeping no copy because the component belongs to whichever toolchain that project selects. All three behind `POST /api/project/:name/lsp/install`, which takes a server **id** and never a package name; a toolchain PPM cannot find means no button rather than one that fails; the browser side is `retryUnavailableLspDocuments()` in `lsp-client.ts`, which reopens the files that had no server so an install needs no reopened tab. The same pair exists machine-wide at `/api/lsp/{servers,install}` for `settings/language-servers-section.tsx` — Settings is open on no project, so nothing project-local is consulted there — and that pane reaches the client through a **dynamic** import, because the lazy-boundary test scans all of `src/web`. That pane's Remove (`POST /api/lsp/uninstall`, Settings only — the editor's dialog is only ever shown for a *missing* server) is gated on `origin` from `availability()`, which is where `resolveCommand` found the server: only `ppm` and `rustup` may be removed, because a copy on `PATH` is the user's, one in a project is the repository's and `bundled` is PPM's own dependency. One npm package can serve several rows (`vscode-langservers-extracted` is JSON + HTML + CSS), which `serversSharingInstall` names so the confirmation can say so before the removal takes all three. Bridge at `src/server/ws/lsp.ts` on `/ws/project/:name/lsp`, status at `/api/projects/:name/lsp/status`. Browser side in `src/web/lib/lsp/` (client, Monaco conversions, providers, shadow models, F12 navigation) driven by `src/web/hooks/use-lsp.ts`. All of it is behind the `lspEnabled` setting — off by default, per device, never on below the `md` breakpoint — and mounted by `src/web/components/editor/editor-language-service.tsx`, which `code-editor.tsx` may only reach through `lazy()`. Real-server check: `bun tests/e2e/lsp-e2e.ts`
+- `src/services/lsp/` — language servers for the editor. `server-registry.ts` says which binary serves which language and how to find it (project `node_modules/.bin`, then PATH, then PPM's own directory), `lsp-protocol.ts` is the `Content-Length` framing, `lsp-session.ts` owns one child process, `lsp-manager.ts` decides how many exist and shares them by *server + root directory*. `lsp-install.ts` is the Install button's host half, one plan per server: `bun add` of the registry's packages into `<ppm dir>/lsp-servers` — never `-g` — `go install` with `GOBIN` pointed at that same directory, `gem install --install-dir <lsp dir>/ruby` for Solargraph (spawned with `GEM_PATH` pointing there — `installedServerEnv` — and not offered on Windows, whose `.bat` binstub is unverified), a release download for clangd and lua-language-server (`lsp-release-catalog.ts`, version + SHA-256 per platform; staged beside the target, unpacked, started once with `--version`, then swapped in whole), and for rust-analyzer alone `rustup component add` **in the project's directory**, keeping no copy because the component belongs to whichever toolchain that project selects. All of them behind `POST /api/project/:name/lsp/install`, which takes a server **id** and never a package name; a toolchain PPM cannot find means no button rather than one that fails; the browser side is `retryUnavailableLspDocuments()` in `lsp-client.ts`, which reopens the files that had no server so an install needs no reopened tab. The same pair exists machine-wide at `/api/lsp/{servers,install}` for `settings/language-servers-section.tsx` — Settings is open on no project, so nothing project-local is consulted there — and that pane reaches the client through a **dynamic** import, because the lazy-boundary test scans all of `src/web`. That pane's Remove (`POST /api/lsp/uninstall`, Settings only — the editor's dialog is only ever shown for a *missing* server) is gated on `origin` from `availability()`, which is where `resolveCommand` found the server: only `ppm` and `rustup` may be removed, because a copy on `PATH` is the user's, one in a project is the repository's and `bundled` is PPM's own dependency. One npm package can serve several rows (`vscode-langservers-extracted` is JSON + HTML + CSS), which `serversSharingInstall` names so the confirmation can say so before the removal takes all three. Bridge at `src/server/ws/lsp.ts` on `/ws/project/:name/lsp`, status at `/api/projects/:name/lsp/status`. Browser side in `src/web/lib/lsp/` (client, Monaco conversions, providers, shadow models, F12 navigation) driven by `src/web/hooks/use-lsp.ts`. All of it is behind the `lspEnabled` setting — off by default, per device, never on below the `md` breakpoint — and mounted by `src/web/components/editor/editor-language-service.tsx`, which `code-editor.tsx` may only reach through `lazy()`. Real-server check: `bun tests/e2e/lsp-e2e.ts`
 - `src/web/components/problems/` + `src/web/stores/problems-store.ts` — the Problems panel: a dock tab (`DOCK_ALLOWED_TAB_TYPES`) fed by every mounted editor's `useLsp`, opened from the status bar counts on desktop and the editor's LSP row on mobile. Scoped to the active project because `tab-pool` keeps other projects' editors mounted for keep-alive, so their servers keep publishing
 - `src/services/git-blame/` — `git blame --porcelain` for the editor's inline annotation (`/api/projects/:name/git/blame`); shared shape and formatting in `src/shared/blame.ts`, editor wiring in `src/web/hooks/use-inline-blame.ts`. The annotation's GitLens-style hover adds one `git show --unified=0` per commit *and line* (`/git/commit-line`, parsed by `commit-line-diff.ts`), with the markdown built in `src/web/lib/blame-hover.ts` and its buttons registered in `blame-hover-commands.ts`, which hand off to the Git Graph extension's own views over `ext:command:execute`
 - `dist/web` asset pipeline — `scripts/copy-monaco.ts` stages `monaco-editor/min/vs` under `dist/web/assets/monaco/` (inside `assets/` so it inherits the immutable cache header, the SW runtime cache and the compressed siblings), `scripts/precompress-web.ts` writes `.br`/`.gz` siblings, and `src/server/routes/static-encoding.ts` chooses one per request (honouring `q=0` and `*`, keeping the original MIME, adding `Vary: Accept-Encoding` and the encoding in the ETag). Both scripts run after `build:web` in the `build` chain
@@ -253,6 +294,11 @@ Before planning or implementing a new feature, read `docs/project-roadmap.md` to
 - `scripts/gen-nerd-font.ts` + `src/web/styles/nerd-font.generated.css` + `src/web/styles/fonts/` — the terminal's icon glyphs (Nerd Fonts symbols-only, MIT, ryanoasis/nerd-fonts), subset per icon set so each `@font-face` is fetched only when something draws a character in its range. Regenerate with `bun scripts/gen-nerd-font.ts` after editing its `BLOCKS`; `TERMINAL_FONT_FAMILY` in `src/web/lib/editor-font.ts` is what names the family, and `use-terminal.ts` is what invalidates xterm's glyph atlas when a face lands
 - `src/services/speech-to-text/` — speech to text for the chat mic, run on the host. `whisper-catalog.ts` pins the whisper.cpp build and every model by SHA-256, `whisper-download.ts` streams and hashes in one pass onto a `.part` file, `whisper-install.service.ts` installs under `<ppm dir>/whisper` and proves the binary runs before calling it installed, `whisper-transcribe.service.ts` is one `whisper-cli` run per request (serialised — two at once just make both slow), with `whisper-hallucinations.ts` dropping the sentences the model invents as a second line of defence behind the VAD. Routes `src/server/routes/speech.ts`, browser side `src/web/hooks/use-whisper-voice-input.ts` + `src/web/lib/voice-wav.ts`, Settings pane `src/web/components/settings/voice-settings-section.tsx` (the engine choice only appears once it is installed), e2e `bun tests/e2e/whisper-e2e.ts`
 - `src/services/mcp-oauth/` — MCP sign-in for `needs-auth` servers: `mcp-oauth-flows.ts` (one prompt-less Claude subprocess per flow, opened by the provider's `openMcpControlQuery`), `mcp-status-probe.ts` (cached per-directory status), `mcp-oauth-redirect.ts` (pure redirect/host rules). Routes `src/server/routes/mcp-auth.ts` (public `GET /api/mcp-auth/callback` mounted before auth), chat sync `src/server/ws/chat-mcp-sign-in-sync.ts`, UI `src/web/components/mcp-auth/` (dialog/bottom sheet, chat bar, the list shown in Settings → AI Provider and the AI Resources panel), e2e `tests/e2e/mcp-sign-in-e2e.mjs`
-- `src/services/named-tunnel/` — Named tunnel (stable `https://<prefix>.<zone>` URL via Cloudflare login), orchestrated from `src/server/routes/named-tunnel.ts`, spawned/probed by the supervisor; UI in `src/web/components/tunnels/named-tunnel/`
-- `src/services/design/` — Design mode: a design is `designs/<slug>/` with its canvas data in the git-ignored, unwatched `.design/`. `design-store.service.ts` (folders, `design.json`), `design-snapshots.service.ts` + `design-restore.service.ts`/`design-restore-journal.ts` (history, crash-safe restore), `design-turn-snapshot.ts` (a snapshot after each design turn, scheduled from `chatService.sendMessage`), `design-instructions.ts` + `design-tool-policy.ts` (the per-turn instructions `chatService.prepareSendOptions` adds, and the `acceptEdits` policy), `preview/` (capability tokens, CSP, parse5 `data-ppm-id` instrumentation, print view), `bridge/` (the in-frame script, shipped as source), `source/` (the patchers behind tweaks and move/resize), `comments/`, `export/` and `design-edit-undo-journal.ts`. Routes `src/server/routes/designs.ts` with its `design-*.ts` sub-routers, and `design-preview.ts` for the canvas; protocol `src/shared/design-bridge-protocol.ts`; UI `src/web/components/design/` with client helpers in `src/web/lib/design/`; docs `docs/architecture/workspace-and-ui.md` → Design mode; e2e `tests/e2e/design-mode-e2e.mjs` (fixture server and scripted provider in `tests/e2e/fixtures/design-mode-server.ts` / `design-script-provider.ts`)
+- `src/services/named-tunnel/` — Named tunnel (stable `https://<prefix>.<zone>` URL via Cloudflare login), orchestrated from `src/server/routes/named-tunnel.ts`, spawned/probed by the supervisor; UI in `src/web/components/tunnels/named-tunnel/` (the setup flow, shared by the first-run popup and Settings)
+- `src/services/tailscale/` — Settings → Remote Access → Tailscale, PPM at `https://<name>.<tailnet>.ts.net` through the Tailscale Service `svc:<name>`. `tailscale-cli.ts` finds and runs the CLI (shared with `port-forward/tailscale-forward.ts`), `tailscale-state.ts` reads the setup from `status --json`, `debug prefs` and `serve status --json` and changes nothing, `tailscale-login.ts` is the in-app sign-in (`tailscale up --json`, its link and QR code), `tailscale-app-service.ts` is the switch (the `tailscale_service` config row) and the start-up re-apply. The step order is `currentSetupStep` in `src/shared/tailscale-setup.ts`, shared by the server's refusal messages and the pane's checklist. Routes `src/server/routes/tailscale.ts` (`/api/tailscale`), UI `src/web/components/settings/tailscale/`, fake CLI for tests `tests/fixtures/fake-tailscale.ts`
+- `src/web/components/settings/remote-access/` — Settings → Remote Access, every way to reach PPM itself from another device, one sub-tab each (`remote-access-tab-store.ts`, which `openRemoteAccess(tab)` sets before opening Settings): Tailscale (the pane above, mounted as it is) and Public link (`public-link-pane.tsx`: the `/api/tunnel` switch plus the temporary-vs-own-domain choice, the named-tunnel flow rendered inline). Forwarding a dev server is the sidebar's Port Forwarding section (id `tunnels`), `src/web/components/tunnels/port-forwarding-panel.tsx` over `/api/tunnels`, which the palette's Forward a Port reaches through `open-port-forwarding.ts` (the drawer on a phone). Its two rows say where Tailscale (`/api/tunnels/transports`) and PPM's own Cloudflare domain (`/api/tunnel/named/status`) stand, and their Set up / Manage buttons are the links into these sub-tabs — signing in to either is never done in the panel. `tests/unit/web/remote-access-settings.test.tsx`, `tests/unit/web/port-forwarding-panel.test.tsx`
+- `src/services/design/` — Design mode: a design is `designs/<slug>/` with its canvas data in the git-ignored, unwatched `.design/`. `design-store.service.ts` (folders, `design.json`), `design-snapshots.service.ts` + `design-restore.service.ts`/`design-restore-journal.ts` (history, crash-safe restore), `design-turn-snapshot.ts` (a snapshot after each design turn, scheduled from `chatService.sendMessage`), `design-instructions.ts` + `design-tool-policy.ts` (the per-turn instructions `chatService.prepareSendOptions` adds, and the `acceptEdits` policy), `design-skill-install.service.ts` (Settings → Design's Install for the suggested skill: the pinned npm tarball laid out exactly as upstream's `uipro init --global`, checked by `tests/e2e/design-skill-install-e2e.ts`), `preview/` (capability tokens, CSP, parse5 `data-ppm-id` instrumentation, print view), `bridge/` (the in-frame script, shipped as source), `source/` (the patchers behind tweaks and move/resize), `comments/`, `export/` and `design-edit-undo-journal.ts`. Routes `src/server/routes/designs.ts` with its `design-*.ts` sub-routers, and `design-preview.ts` for the canvas; protocol `src/shared/design-bridge-protocol.ts`; UI `src/web/components/design/` with client helpers in `src/web/lib/design/`; docs `docs/architecture/workspace-and-ui.md` → Design mode; e2e `tests/e2e/design-mode-e2e.mjs` (fixture server and scripted provider in `tests/e2e/fixtures/design-mode-server.ts` / `design-script-provider.ts`)
+- `src/services/tab-tools-mcp/` — the AI's tab tools, `open_file` (optional `line`) and `open_preview`, given to every chat that is not a design session while Settings → AI Provider → *Let the AI open tabs in PPM* (`ai.tab_tools`) is on; Claude's claude.ai Artifact tools are turned off with it (`CLAUDE_CODE_DISABLE_ARTIFACT=1`), and a call made after the setting went off is refused at the endpoint, because a chat keeps the tools it started with. `/api/tab-tools-mcp` (`tab-tools-mcp-endpoint.ts`, mounted before auth) is built from the same parts as `/api/design-mcp`: `src/services/mcp-http-endpoint.ts` (JSON-only Streamable HTTP, a request with an `Origin` refused, 64 KB cap) and `src/services/mcp-session-tokens.ts` (per-session capability tokens, memory only, looked up by SHA-256); `tab-tools-mcp-tokens.ts` binds a token to the session id alone, so a warm spare's token is the one its session's turns mint. `tab-target.ts` resolves the agent's `path` under the editor's own read rules, and `tab-open-broker.ts` sends `tab_open` over the chat WebSocket and waits for the first `tab_open_result` (8 s for a file, 40 s for a page; 4 calls in flight and 20 a minute per session) — `deliverTabOpen` in `src/server/ws/chat.ts` picks the device that sent the turn's message, else every device showing the chat, and never buffers it for replay. Protocol and the per-provider tool names in `src/shared/tab-open-protocol.ts`; provider wiring `tabToolsMcpServers` (`claude-agent-sdk-query-options.ts`) and `tabToolsMcpConfig`/`tabToolsMcpEnv` (`codex-thread-params.ts`), from the access `chatService.prepareSendOptions` mints. Browser: `src/web/lib/open-ai-tab.ts` (answers `tab_open` from `use-chat.ts`: opens the tab, waits for the page, runs its check), `ai-tab-placement.ts` (pure: beside the chat on a desktop, the whole screen on a phone), `html-preview-loads.ts` (which preview shows which page, by load), `tab-tool-call.ts` + `src/web/components/chat/tab-tool-card.tsx` (the card and its Open button). The HTML preview route serves the design canvas's CSP (`buildDesignCsp`, so the design CDNs load) and injects `design/bridge/html-preview-bridge.ts`, the design bridge's core plus its self-check. Docs `docs/architecture/ai-chat-and-providers.md` → AI tab tools; e2e `PPM_PLAYWRIGHT_MODULE=<playwright>/index.mjs node tests/e2e/ai-tab-tools-e2e.mjs` (scripted provider in `tests/e2e/fixtures/tab-tools-server.ts`; `PPM_TAB_TOOLS_WEB_DIR` reuses a scratch build) and `tests/e2e/html-preview-cdn-check-e2e.mjs`
 - `src/services/agent-transcript/` — one hub per `(providerId, sessionId)` streaming an Agent card's or teammate's own transcript live over `/ws/global`, independent of the chat WebSocket and of whether the root turn is still running. `session-ownership.ts` proves the session belongs to the caller's project before any file is named; `agent-transcript-sources.ts` resolves a card/teammate to the exact file(s), including Codex descendants via `session_meta.parent_thread_id`; `agent-transcript-session-hub.ts` + `agent-transcript-hub.ts` are the per-session tail/page/cursor loop, `agent-transcript-session-hub-activity.ts` the separate "who is running" feed. Protocol in `src/shared/agent-transcript-protocol.ts`; UI entry points `src/web/components/chat/{agent-card-summary,agent-session-window-content,agent-session-sheet,running-agents-bar}.tsx` via `use-agent-session-stream.ts`/`use-agent-activity.ts`; docs `docs/architecture/ai-chat-and-providers.md` → Agent session transcripts
+- `src/services/session-file-baselines/` — the session review (the changes bar above the composer and the block-by-block Review tab): `session-file-baselines.service.ts` keeps each file's state from before the session's first write (`<ppm dir>/session-baselines/<session id>/`, first capture wins, 5 MB cap, credential paths never copied, 30-day prune), `session-file-changes.service.ts` compares it with the disk (git HEAD only as a fallback inside the project), `reverse-unified-diff.ts` works a Codex patch's "before" out, `shell-change-tracker.ts` brackets each Claude shell command with `git status`, `session-review-marks.ts` keeps what the user marked reviewed (a snapshot per file under `<session dir>/reviewed/`, written only at the version the browser showed; a file changed after its mark is diffed against the mark). Blocks are cut by `src/shared/review-blocks.ts`, shared because the server cuts them again from the disk before acting on a key the browser sent; `session-review-blocks.ts` records the kept ones per base hash, and `session-review-actions.ts` keeps, reopens and reverts blocks or whole files on disk (`/file-changes/answer`, refused as `stale` unless the file is at the version drawn) and undoes any answer all-or-nothing from its journal (`/file-changes/undo`). `session-file-history.ts` logs each file's state just before and after every call that writes it (`<session dir>/history/`, as line deltas), `session-file-blame.ts` replays that log to name the calls behind each block, and `session-turn-revert.ts` puts a turn's calls back where their lines are still intact (`/file-changes/revert-turn`: a preview first, then `stale` unless every file is at the previewed version). Captured by the Claude PreToolUse file-write hook and the shell hooks around each `Bash` call (`buildToolHooks` in `claude-agent-sdk-query-options.ts`) and by `codex-file-baselines.ts`. Routes `src/server/routes/chat-file-changes.ts`, shapes `src/shared/session-file-changes.ts`; UI `src/web/components/chat/session-changes-bar.tsx` + `session-change-row.tsx`, and `src/web/components/session-review/` (`review-desktop.tsx`, `review-phone.tsx` below `md`, `review-code.tsx` for the blocks and their turn chips, `review-tokens.tsx` for shiki colours), the chat's per-answer pill and tray `src/web/components/chat/turn-change-{rollup,tray,sheet,review}.tsx` over `src/web/hooks/use-turn-review.ts` + `src/web/lib/turn-review.ts` (the list reaches them through `session-changes-context.tsx`), turns from `src/web/lib/session-turns.ts` through `src/web/stores/session-turns-store.ts` (published by the chat, read by `use-session-turns.ts` when no chat is open), Show in chat through `src/web/stores/chat-jump-store.ts`, state `src/web/hooks/use-session-review.ts` over the pure `src/web/lib/session-review-model.ts`, data `src/web/hooks/use-session-file-changes.ts` + `src/web/lib/session-file-changes{,-client}.ts`; docs `docs/architecture/ai-chat-and-providers.md` → Session changes and review; e2e `bun tests/e2e/session-changes-e2e.mjs`
+- `src/services/notification.service.ts` — notifications, configured in Settings → Notifications. `broadcast(type, payload, { stillUnseen })` drops a switched-off event, waits `delay_seconds` (one pending per session: a newer event replaces it) and sends only if `stillUnseen()` still holds — the chat is still unread, and for an approval the same request is still pending (`src/server/ws/chat.ts`); schedules and Jira pass none and always send. `deliver` fans out to push, Telegram and ntfy, plus PPM Cloud's `sendNotification`, which is inert in the server process because that connection lives in the supervisor. Settings shape and defaults in `src/shared/notification-settings.ts`, text and links in `notification-format.ts`. Push is standard Web Push with no dependency, `src/services/web-push/` (VAPID ES256 + RFC 8291 aes128gcm on WebCrypto; keys and subscriptions are the config rows `web_push_vapid` / `web_push_subscriptions` and never reach a browser); the browser half is `src/web/sw.ts` (`push`, and `notificationclick` → `src/web/sw-notification-click.ts`, which hands the session to an open window through `src/web/hooks/use-notification-clicks.ts`) and `src/web/lib/web-push-{support,client}.ts`. Telegram sends through `telegram-notification.service.ts` to the chats in the `telegram_notify_chats` config row, and to nobody else: PPMBot has a bot and chats of its own (`telegram-bots.ts` — the `ppmbot_telegram` row and `clawbot_paired_chats`; both rows sit outside `CONFIG_TABLE_KEYS` like the VAPID key, and an install that shared one bot is split once, on first read). The one-tap Connect link is `telegram-connect.service.ts`, one per bot owner, which polls a bot itself unless PPMBot is reading that bot (Telegram allows one `getUpdates` reader per bot; the bots are compared by id, the digits before the token's colon). ntfy is `ntfy-notification.service.ts`: one JSON publish per notification (the header form cannot carry a non-ASCII title), the config row `ntfy` with its token in `SECRET_CONFIG_KEYS`, dropped when Settings saves a different server so it is not sent to the new one (`PUT /ntfy`; `ppm config set ntfy.server` does not drop it). Both channels take their link back into PPM from `notification-link.ts`: the tunnel URL, else the Tailscale Service address, else localhost — never the LAN address, which is plain HTTP on an insecure origin where the browser withholds every permission PPM asks for. Routes `src/server/routes/notifications.ts` (`/api/notifications/*`), UI `src/web/components/settings/notifications-settings-section.tsx` + `telegram-bot-token-field.tsx` + `ntfy-server-form.tsx`, fake ntfy for tests `tests/helpers/fake-ntfy-server.ts`

package/THIRD-PARTY-NOTICES.md

@@ -17,7 +17,7 @@ bun scripts/gen-nerd-font.ts
 
 ## Product icons
 
-`src/web/lib/icons.generated.tsx` holds the path data for 183 glyphs, emitted by
+`src/web/lib/icons.generated.tsx` holds the path data for 199 glyphs, emitted by
 `scripts/gen-product-icons.ts` at 20px Regular. The outlines are reproduced unchanged;
 only the surrounding component is PPM's. The 15 names Fluent has no glyph for stay on
 `lucide-react`, which is a dependency rather than something vendored here.
@@ -34,7 +34,7 @@ only the surrounding component is PPM's. The 15 names Fluent has no glyph for st
 
 ## File icons
 
-`src/web/styles/file-icons.generated.css` inlines 1193 SVG drawings as data URIs and
+`src/web/styles/file-icons.generated.css` inlines 1195 SVG drawings as data URIs and
 `src/web/lib/file-icons.generated.ts` holds the name-to-glyph tables. Both are emitted by
 `scripts/gen-file-icons.ts` from the packages below: the artwork comes from the icon
 collection, the extension-to-name mapping from `vscode-icons-js`. The drawings are

package/assets/skills/ppm/SKILL.md

@@ -23,7 +23,7 @@ PPM is a local-first web IDE + project manager. This skill describes how to cont
 Invoke when the user asks to:
 - Start, stop, restart, or check the PPM server
 - Manage registered projects (`projects list/add/remove`)
-- Manage database connections stored in PPM config (`db list/add/test/query`)
+- Manage database connections stored in PPM config — PostgreSQL, MySQL / MariaDB, SQLite (`db list/add/test/query`; MySQL and MariaDB need `db driver install mysql` once)
 - Get or set PPM config values (`config get/set`)
 - View PPM logs, status, or report a bug
 - Install, upgrade, or inspect bundled skills / extensions
@@ -35,8 +35,8 @@ Invoke when the user asks to:
 2. **Start server** → `ppm start` (use `--port <n>` to override, `--profile dev` for dev DB)
 3. **List projects** → `ppm projects list`
 4. **Add project** → `ppm projects add <path>`
-5. **List DB connections** → `ppm db list`
-6. **Query a saved DB connection** → `ppm db query <connection-name> "<sql>"`
+5. **List DB connections** → `PPM_AI_CHAT=1 ppm db list`
+6. **Query a saved DB connection** → `PPM_AI_CHAT=1 ppm db query <connection-name> "<sql>"`
 7. **Read config** → `ppm config get <key>` (e.g. `port`, `auth.enabled`)
 8. **Tail logs** → `ppm logs --tail 100` or `ppm logs -f` to follow
 9. **Upgrade PPM** → `ppm upgrade` (or `--check` to only check)
@@ -46,6 +46,7 @@ Invoke when the user asks to:
 
 - Always run `ppm status` before assuming the server is up.
 - Commands exit non-zero on failure and print to stderr. Capture both streams.
+- Set `PPM_AI_CHAT=1` for every `ppm db` command, as above: connections the user has made unavailable to AI are then left out of `db list` and refused by the rest. PPM's own chat sets it already.
 - Most listing commands accept `--json` for structured output; prefer JSON when parsing. Check `--help` if unsure.
 - The config DB is **SQLite**. You may open `~/.ppm/ppm.db` read-only for inspection — see [references/db-schema.md](references/db-schema.md).
 - Do NOT edit the config DB directly while the server is running; use `ppm config set` or the HTTP API.
@@ -71,4 +72,4 @@ This skill covers the `ppm` CLI, its HTTP API, and its config DB. It does **not*
 - Third-party extensions (inspect via `ppm ext list`).
 - The Claude Agent SDK internals (separate skill).
 
-<!-- Generated for PPM v0.23.11 at build time. Re-run `ppm export skill --install` to refresh. -->
+<!-- Generated for PPM v0.23.13 at build time. Re-run `ppm export skill --install` to refresh. -->

package/assets/skills/ppm/references/cli-reference.md

@@ -275,8 +275,8 @@ Add a new database connection
 
 **Options:**
 - `-n, --name <name>` — Connection name (unique)
-- `-t, --type <type>` — Database type: sqlite | postgres
-- `-c, --connection-string <url>` — PostgreSQL connection string
+- `-t, --type <type>` — Database type: postgres | mysql | mariadb | sqlite
+- `-c, --connection-string <url>` — Connection string (postgres://…, mysql://…, mariadb://…)
 - `-f, --file <path>` — SQLite file path (absolute)
 - `-g, --group <group>` — Group name
 - `--color <color>` — Tab color (hex, e.g. #3b82f6)
@@ -307,7 +307,7 @@ List tables in a database connection
 Show table schema (columns, types, constraints)
 
 **Options:**
-- `-s, --schema <schema>` — PostgreSQL schema name (default: `"public"`)
+- `-s, --schema <schema>` — Schema (PostgreSQL, default public) or database (MySQL, default from the connection)
 - `--json` — Output as JSON
 
 **Usage:** `ppm db schema [options] <name> <table>`
@@ -321,7 +321,7 @@ View table data (paginated)
 - `-l, --limit <limit>` — Rows per page (default: `"50"`)
 - `--order <column>` — Order by column
 - `--desc` — Descending order
-- `-s, --schema <schema>` — PostgreSQL schema name (default: `"public"`)
+- `-s, --schema <schema>` — Schema (PostgreSQL, default public) or database (MySQL, default from the connection)
 - `--json` — Output as JSON
 
 **Usage:** `ppm db data [options] <name> <table>`
@@ -335,6 +335,31 @@ Execute a SQL query against a saved connection
 
 **Usage:** `ppm db query [options] <name> <sql>`
 
+### `ppm db driver`
+
+Install or remove the drivers some connections need (MySQL / MariaDB, SSH tunnels)
+
+**Usage:** `ppm db driver [options] [command]`
+
+#### `ppm db driver list`
+
+List database drivers and whether each is installed
+
+**Options:**
+- `--json` — Output as JSON
+
+#### `ppm db driver install`
+
+Download and install a database driver (e.g. mysql)
+
+**Usage:** `ppm db driver install [options] <id>`
+
+#### `ppm db driver remove`
+
+Remove an installed database driver
+
+**Usage:** `ppm db driver remove [options] <id>`
+
 ### `ppm db run`
 
 Execute a SQL file against a saved connection
@@ -660,6 +685,7 @@ View PPM daemon logs
 **Options:**
 - `-n, --tail <lines>` — Number of lines to show (default: `"50"`)
 - `-f, --follow` — Follow log output
+- `-l, --level <level>` — Only this level and above: debug, info, warn, error, fatal
 - `--clear` — Clear log file
 
 ## `ppm open`
@@ -781,7 +807,7 @@ Show recent runs for a schedule
 Manage and inspect discovered skills & commands
 
 **Options:**
-- `--project <path>` — Project path (default: `"C:\\Users\\PC\\ppm-release-0.23.11"`)
+- `--project <path>` — Project path (default: `"C:\\Users\\PC\\ppm-release-prep"`)
 
 **Usage:** `ppm skills [options] [command]`
 
@@ -791,7 +817,7 @@ List all discovered skills and commands
 
 **Options:**
 - `--json` — JSON output
-- `--project <path>` — Project path (default: `"C:\\Users\\PC\\ppm-release-0.23.11"`)
+- `--project <path>` — Project path (default: `"C:\\Users\\PC\\ppm-release-prep"`)
 
 ### `ppm skills search`
 
@@ -799,7 +825,7 @@ Fuzzy search skills and commands
 
 **Options:**
 - `--json` — JSON output
-- `--project <path>` — Project path (default: `"C:\\Users\\PC\\ppm-release-0.23.11"`)
+- `--project <path>` — Project path (default: `"C:\\Users\\PC\\ppm-release-prep"`)
 
 **Usage:** `ppm skills search [options] <query>`
 
@@ -809,7 +835,7 @@ Show detailed info for a specific skill
 
 **Options:**
 - `--json` — JSON output
-- `--project <path>` — Project path (default: `"C:\\Users\\PC\\ppm-release-0.23.11"`)
+- `--project <path>` — Project path (default: `"C:\\Users\\PC\\ppm-release-prep"`)
 
 **Usage:** `ppm skills info [options] <name>`
 

package/assets/skills/ppm/references/common-tasks.md

@@ -36,11 +36,15 @@ ppm projects list --json
 ## Task 4: Add and test a database connection
 
 ```bash
-# Interactive add
-ppm db add
+# PostgreSQL (see `ppm db add --help` for every flag)
+ppm db add --name staging --type postgres --connection-string "postgres://app:secret@db.example.com:5432/myapp"
 
-# Non-interactive (check `ppm db add --help` for full flag list)
-ppm db add --name staging --type postgres --host db.example.com --port 5432 --user app --database myapp
+# MySQL / MariaDB need their driver, installed once
+ppm db driver install mysql
+ppm db add --name shop --type mysql --connection-string "mysql://app:secret@db.example.com:3306/shop"
+
+# SQLite takes an absolute file path
+ppm db add --name local --type sqlite --file /abs/path/to/app.db
 
 # Test the connection
 ppm db test staging