chore: import upstream snapshot with attribution
Deploy Worker / deploy (push) Failing after 1s
Shellcheck / Check shell scripts (push) Failing after 1s
CI / Build Packages (amd64 - appimage) (push) Has been skipped
CI / Build Packages (amd64 - deb) (push) Has been skipped
CI / Build Packages (amd64 - rpm) (push) Has been skipped
CI / Build Packages (arm64 - appimage) (push) Has been skipped
CI / Build Packages (arm64 - deb) (push) Has been skipped
CI / Test Flags Parsing (push) Failing after 1s
BATS Tests / BATS unit tests (push) Failing after 1s
CI / Build Packages (arm64 - rpm) (push) Has been skipped
CI / Test Build Artifacts (amd64) (push) Has been skipped
CI / Test Build Artifacts (arm64) (push) Has been skipped
CI / Update APT Repository (push) Has been cancelled
CI / Mirror Official .deb to Release (push) Has been cancelled
CI / Update DNF Repository (push) Has been cancelled
CI / Update AUR Package (push) Has been cancelled
CI / Create Release (push) Has been cancelled
Deploy Worker / deploy (push) Failing after 1s
Shellcheck / Check shell scripts (push) Failing after 1s
CI / Build Packages (amd64 - appimage) (push) Has been skipped
CI / Build Packages (amd64 - deb) (push) Has been skipped
CI / Build Packages (amd64 - rpm) (push) Has been skipped
CI / Build Packages (arm64 - appimage) (push) Has been skipped
CI / Build Packages (arm64 - deb) (push) Has been skipped
CI / Test Flags Parsing (push) Failing after 1s
BATS Tests / BATS unit tests (push) Failing after 1s
CI / Build Packages (arm64 - rpm) (push) Has been skipped
CI / Test Build Artifacts (amd64) (push) Has been skipped
CI / Test Build Artifacts (arm64) (push) Has been skipped
CI / Update APT Repository (push) Has been cancelled
CI / Mirror Official .deb to Release (push) Has been cancelled
CI / Update DNF Repository (push) Has been cancelled
CI / Update AUR Package (push) Has been cancelled
CI / Create Release (push) Has been cancelled
This commit is contained in:
wehub-resource-sync
@@ -0,0 +1,94 @@
|
||||
# Functional Test Cases
|
||||
|
||||
Test specifications grouped by feature surface. For live status, see [`../matrix.md`](../matrix.md). For sweep workflow, see [`../runbook.md`](../runbook.md).
|
||||
|
||||
## Files
|
||||
|
||||
| File | Surfaces covered | Tests |
|
||||
|------|------------------|-------|
|
||||
| [`launch.md`](./launch.md) | App startup, doctor, package detection, multi-instance | T01, T02, T13, T14 |
|
||||
| [`tray-and-window-chrome.md`](./tray-and-window-chrome.md) | Tray icon, window decorations, hybrid topbar, hide-to-tray | T03, T04, T07, T08, S08, S13 |
|
||||
| [`shortcuts-and-input.md`](./shortcuts-and-input.md) | URL handler, Quick Entry, global shortcuts | T05, T06, S06, S07, S09, S10, S11, S12, S14, S29, S30, S31, S32, S33, S34, S35, S36, S37 |
|
||||
| [`code-tab-foundations.md`](./code-tab-foundations.md) | Sign-in, Code tab load, folder picker, drag-drop, terminal, file pane | T15, T16, T17, T18, T19, T20 |
|
||||
| [`code-tab-workflow.md`](./code-tab-workflow.md) | Preview, PR monitor, worktrees, auto-archive, side chat, slash menu | T21, T22, T29, T30, T31, T32 |
|
||||
| [`code-tab-handoff.md`](./code-tab-handoff.md) | Notifications, external editor, file manager, connector OAuth, IDE handoff | T23, T24, T25, T34, T38, T39 |
|
||||
| [`routines.md`](./routines.md) | Scheduled tasks, catch-up runs, suspend inhibit, config dir | T26, T27, T28, S19, S20, S21 |
|
||||
| [`extensibility.md`](./extensibility.md) | Plugins, MCP, hooks, CLAUDE.md memory, worktree storage | T11, T33, T35, T36, T37, S27, S28 |
|
||||
| [`distribution.md`](./distribution.md) | DEB, RPM, AppImage, dependency pulls, auto-update | S01, S02, S03, S04, S05, S15, S16, S26 |
|
||||
| [`platform-integration.md`](./platform-integration.md) | Autostart, Cowork, WebGL, PATH inheritance, Computer Use, Dispatch | T09, T10, T12, S17, S18, S22, S23, S24, S25 |
|
||||
|
||||
## Standard test body
|
||||
|
||||
Every test in this directory follows this structure:
|
||||
|
||||
```markdown
|
||||
### T## — Title
|
||||
|
||||
**Severity:** Smoke | Critical | Should | Could
|
||||
**Surface:** human-readable surface tag (e.g. "Code tab → Environment")
|
||||
**Applies to:** All | <subset of rows>
|
||||
**Issues:** linked issue/PR list, or `—`
|
||||
|
||||
**Steps:**
|
||||
1. ...
|
||||
2. ...
|
||||
|
||||
**Expected:** what should happen.
|
||||
|
||||
**Diagnostics on failure:** which captures to attach when filing. See [`../runbook.md#diagnostic-capture`](../runbook.md#diagnostic-capture).
|
||||
|
||||
**References:** docs links, learnings, related issues.
|
||||
|
||||
**Code anchors:** `<file>:<line>` pointers to the upstream code or
|
||||
wrapper script that backs the load-bearing claim above. Added during
|
||||
the grounding sweep — see "Anchor scope" for guidance on where
|
||||
anchors can and can't land.
|
||||
|
||||
**Inventory anchor:** (optional) `<element-id>` from
|
||||
[`../ui-inventory.json`](../ui-inventory.json) — only if the surface
|
||||
shows up in the v7 walker's idle capture. For surfaces inside modals
|
||||
or popups, append a sentence noting which click-chain opens them so
|
||||
the next inventory regeneration can grab them.
|
||||
```
|
||||
|
||||
The Steps and Diagnostics fields are written so they can later become
|
||||
script entry points without a rewrite.
|
||||
|
||||
### Anchor scope
|
||||
|
||||
Where the load-bearing claim lives determines where the anchor goes:
|
||||
|
||||
- **Upstream code** — any file under
|
||||
`build-reference/app-extracted/.vite/build/` (most often `index.js`,
|
||||
the main process). Use `index.js:N` style anchors.
|
||||
- **Our wrapper code** — `scripts/launcher-common.sh`, `scripts/doctor.sh`,
|
||||
`scripts/patches/*.sh`, `scripts/frame-fix-wrapper.js`,
|
||||
`scripts/wco-shim.js`. Use `<repo-relative-path>:N` style anchors.
|
||||
- **Server-rendered (claude.ai SPA)** — anchorable only via the v7
|
||||
walker inventory (`docs/testing/ui-inventory.json`) or a runtime
|
||||
capture from `tools/test-harness/grounding-probe.ts`. Idle-state
|
||||
inventory misses contextual surfaces (modals, popups, slash menus,
|
||||
context menus, side panels) — note that explicitly.
|
||||
- **Upstream `claude` CLI binary** — out of scope for this matrix
|
||||
(e.g. T39 `/desktop` is a CLI slash-command, not in the Electron
|
||||
asar). Mark as Ambiguous and link to a separate CLI matrix if one
|
||||
exists.
|
||||
|
||||
If a claim spans multiple scopes (a wrapper script triggering
|
||||
upstream behavior, e.g. T01's launcher-log + main-window-opens),
|
||||
list all the anchors. The whole point is making the next sweep
|
||||
faster — over-anchoring is fine, missing anchors is not.
|
||||
|
||||
### Drift markers
|
||||
|
||||
When a sweep finds upstream behavior no longer matches the case:
|
||||
|
||||
- **Edited Steps/Expected** — fix the case in place, mention what
|
||||
changed in the commit message. The case is the spec.
|
||||
- **Missing in build X.Y.Z** — prepend a blockquote under the test
|
||||
heading: `> **⚠ Missing in build 1.5354.0** — <one-line note>.
|
||||
Re-verify after next upstream bump.` Use when the feature isn't
|
||||
in the build at all (deprecated, behind unset flag, never shipped).
|
||||
- **Ambiguous** — don't edit; flag in the sweep report. Use when
|
||||
the load-bearing claim could be one of several candidate code
|
||||
paths and static analysis can't disambiguate.
|
||||
@@ -0,0 +1,197 @@
|
||||
# Code Tab — Foundations
|
||||
|
||||
Tests covering Code-tab availability on Linux (officially unsupported per upstream docs), sign-in flow, folder picker, drag-and-drop, and the basic editing surfaces (terminal, file pane). See [`../matrix.md`](../matrix.md) for status.
|
||||
|
||||
## T15 — Sign-in completes in the embedded webview
|
||||
|
||||
> **Drift in build 1.5354.0** — Sign-in is an in-app `mainView.webContents.loadURL` flow, not an `xdg-open` browser handoff. Claude.ai/login renders inside the embedded BrowserView; the resulting `sessionKey` cookie is then exchanged at `${apiHost}/v1/oauth/${org}/authorize` with redirect URI `https://claude.ai/desktop/callback`. No system browser is involved.
|
||||
|
||||
**Severity:** Smoke
|
||||
**Surface:** Auth / embedded webview
|
||||
**Applies to:** All rows
|
||||
**Issues:** —
|
||||
|
||||
**Steps:**
|
||||
1. Launch a fresh app instance (signed-out state).
|
||||
2. Click **Sign in**. Observe claude.ai/login rendering inside the app.
|
||||
3. Authenticate. Observe the in-app navigation completing back to the
|
||||
workspace.
|
||||
|
||||
**Expected:** Sign-in stays inside the embedded webview (`will-navigate`
|
||||
handler `Ihr` keeps `/login/` paths in-app). After auth the
|
||||
`sessionKey` cookie is captured and silently exchanged for an OAuth
|
||||
token via the `desktop/callback` redirect. Account dropdown populates;
|
||||
no auth banner remains.
|
||||
|
||||
**Diagnostics on failure:** DevTools console for the `mainView`
|
||||
BrowserView, network captures of the `/v1/oauth/{org}/authorize` and
|
||||
`/v1/oauth/token` calls, launcher log, cookie jar inspection
|
||||
(`sessionKey` on `.claude.ai`).
|
||||
|
||||
**References:** [Code tab auth troubleshooting](https://code.claude.com/docs/en/desktop#403-or-authentication-errors-in-the-code-tab)
|
||||
|
||||
**Code anchors:**
|
||||
- `build-reference/app-extracted/.vite/build/index.js:141996` — desktop
|
||||
OAuth redirect URI `https://claude.ai/desktop/callback`
|
||||
- `build-reference/app-extracted/.vite/build/index.js:142431` — POST to
|
||||
`${apiHost}/v1/oauth/${org}/authorize` with `Bearer ${sessionKey}`
|
||||
- `build-reference/app-extracted/.vite/build/index.js:216565` — `Ihr`
|
||||
treats `/login/` paths as in-app (not external)
|
||||
- `build-reference/app-extracted/.vite/build/index.js:141316` —
|
||||
`mainView.webContents.loadURL(...)` drives the embedded sign-in
|
||||
|
||||
## T16 — Code tab loads
|
||||
|
||||
**Severity:** Smoke
|
||||
**Surface:** Code tab — top-level UI
|
||||
**Applies to:** All rows
|
||||
**Issues:** —
|
||||
|
||||
**Steps:**
|
||||
1. After sign-in, click the **Code** tab at the top center.
|
||||
2. Wait a few seconds.
|
||||
|
||||
**Expected:** Code tab renders the session UI (sidebar, prompt area, environment dropdown). Per upstream docs the Code tab is "not supported" on Linux — the patched build under this project should render the UI normally or surface a clear, actionable message. Not a blank screen, infinite spinner, or `Error 403: Forbidden`.
|
||||
|
||||
**Diagnostics on failure:** Screenshot, DevTools console, network captures (auth/feature-flag responses), launcher log, the active patch set in `scripts/patches/`.
|
||||
|
||||
**References:** [Use Claude Code Desktop](https://code.claude.com/docs/en/desktop), [Get started with the desktop app](https://code.claude.com/docs/en/desktop-quickstart)
|
||||
|
||||
**Code anchors:**
|
||||
- `build-reference/app-extracted/.vite/build/index.js:525066` —
|
||||
`sidebarMode === "code"` rewrites the BrowserView path to `/epitaxy`
|
||||
- `build-reference/app-extracted/.vite/build/index.js:496066` — Code
|
||||
deeplinks (`claude://code?...`) navigate to `/epitaxy?...`
|
||||
- `build-reference/app-extracted/.vite/build/index.js:105273` — `IHi`
|
||||
recognises `/epitaxy` and `/epitaxy/...` as the Code-tab path
|
||||
- `build-reference/app-extracted/.vite/build/index.js:105346` —
|
||||
`sidebarMode` enum contains `"code"`
|
||||
|
||||
**Inventory anchor:** `…tablist.tab-by-name.code` (role `tab`, label
|
||||
`Code`) — confirms the Code tab is reachable from the new-chat tablist
|
||||
in the captured idle state.
|
||||
|
||||
## T17 — Folder picker opens
|
||||
|
||||
**Severity:** Smoke
|
||||
**Surface:** Code tab → Environment selection
|
||||
**Applies to:** All rows
|
||||
**Issues:** —
|
||||
**Runner:** [`tools/test-harness/src/runners/T17_folder_picker.spec.ts`](../../../tools/test-harness/src/runners/T17_folder_picker.spec.ts) — runtime-attach via SIGUSR1 + main-process `dialog.showOpenDialog` mock + `webContents.executeJavaScript` to drive the renderer. Click chain to reach the folder-picker button awaits selector tuning
|
||||
|
||||
**Steps:**
|
||||
1. In the Code tab, click the environment pill → **Local** → **Select folder**.
|
||||
2. Choose a project directory.
|
||||
|
||||
**Expected:** Native file chooser opens. On Wayland sessions the chooser is `xdg-desktop-portal`-backed (verify with `busctl --user tree org.freedesktop.portal.Desktop`). On X11 sessions the GTK/Qt native picker fires. Selected path appears in the env pill.
|
||||
|
||||
**Diagnostics on failure:** `systemctl --user status xdg-desktop-portal`, `XDG_SESSION_TYPE`, the portal backend in use (`xdg-desktop-portal-kde`, `xdg-desktop-portal-gnome`, `xdg-desktop-portal-wlr`), launcher log.
|
||||
|
||||
**References:** [Local sessions](https://code.claude.com/docs/en/desktop#local-sessions)
|
||||
|
||||
**Code anchors:**
|
||||
- `build-reference/app-extracted/.vite/build/index.js:66403` — IPC
|
||||
channel `claude.web_FileSystem_browseFolder` (renderer → main)
|
||||
- `build-reference/app-extracted/.vite/build/index.js:509188` —
|
||||
`browseFolder` impl calls `dialog.showOpenDialog` with
|
||||
`properties: ["openDirectory", "createDirectory"]`
|
||||
- `build-reference/app-extracted/.vite/build/index.js:450534` —
|
||||
`grantViaPicker` (Operon host-access folder grant) uses the same
|
||||
`["openDirectory"]` shape
|
||||
- `tools/test-harness/src/lib/claudeai.ts:122` — `installOpenDialogMock`
|
||||
intercepts both `(opts)` and `(window, opts)` arities, matching the
|
||||
call sites at index.js:509196 and :450534
|
||||
|
||||
**Inventory anchor:** `root.main.region.button-by-name.select-folder`
|
||||
(role `button`, label `Select folder…`) — the persistent button the
|
||||
T17 runner clicks before the dialog mock fires.
|
||||
|
||||
## T18 — Drag-and-drop files into prompt
|
||||
|
||||
**Severity:** Critical
|
||||
**Surface:** Code tab → Prompt area
|
||||
**Applies to:** All rows
|
||||
**Issues:** —
|
||||
|
||||
**Steps:**
|
||||
1. Open a Code-tab session.
|
||||
2. From the system file manager, drag one or more files into the prompt area.
|
||||
3. Repeat with multiple files at once.
|
||||
|
||||
**Expected:** Files attach to the prompt. The renderer resolves dropped
|
||||
`File` objects to absolute paths via the preload-bridged
|
||||
`claudeAppSettings.filePickers.getPathForFile` (Electron's
|
||||
`webUtils.getPathForFile`). Multi-file drops attach each file. Works on
|
||||
both Wayland and X11.
|
||||
|
||||
**Diagnostics on failure:** Screen recording, `wl-paste --list-types` (Wayland) or `xclip -selection clipboard -t TARGETS -o` (X11) during drag, DevTools console, launcher log.
|
||||
|
||||
**References:** [Add files and context](https://code.claude.com/docs/en/desktop#add-files-and-context-to-prompts)
|
||||
|
||||
**Code anchors:**
|
||||
- `build-reference/app-extracted/.vite/build/mainView.js:9267` —
|
||||
`filePickers.getPathForFile` wraps `webUtils.getPathForFile`
|
||||
- `build-reference/app-extracted/.vite/build/mainView.js:9552` —
|
||||
exposed to the renderer as `window.claudeAppSettings`
|
||||
|
||||
## T19 — Integrated terminal
|
||||
|
||||
**Severity:** Critical
|
||||
**Surface:** Code tab → Terminal pane
|
||||
**Applies to:** All rows
|
||||
**Issues:** —
|
||||
|
||||
**Steps:**
|
||||
1. In a Code-tab session, press `` Ctrl+` `` (or open via the Views menu).
|
||||
2. Confirm the terminal opens in the session's working directory.
|
||||
3. Run `git status`, `npm --version`, `gh auth status`.
|
||||
|
||||
**Expected:** Terminal pane opens in the session's working directory, inherits the same `PATH` Claude sees. Standard commands run cleanly. Terminal pane is local-session-only per docs.
|
||||
|
||||
**Diagnostics on failure:** Terminal pane content, `echo $PATH` from inside the pane, `pwd`, the shell binary in use, launcher log.
|
||||
|
||||
**References:** [Run commands in the terminal](https://code.claude.com/docs/en/desktop#run-commands-in-the-terminal)
|
||||
|
||||
**Code anchors:**
|
||||
- `build-reference/app-extracted/.vite/build/index.js:69135` — IPC
|
||||
channel `claude.web_LocalSessions_startShellPty` (also
|
||||
`resizeShellPty`, `writeShellPty` at :69184, :69210)
|
||||
- `build-reference/app-extracted/.vite/build/index.js:486438` —
|
||||
`startShellPty` body: spawns `node-pty` in
|
||||
`n.worktreePath ?? n.cwd` with `TERM=xterm-256color`
|
||||
- `build-reference/app-extracted/.vite/build/index.js:486463` —
|
||||
`node-pty` dynamic import (optional dep, `package.json` line 100)
|
||||
- `build-reference/app-extracted/.vite/build/index.js:259306` —
|
||||
`shell-path-worker/shellPathWorker.js` resolves the user's interactive
|
||||
PATH; `FX()` (line 259311) returns it for the spawned PTY env
|
||||
|
||||
## T20 — File pane opens and saves
|
||||
|
||||
**Severity:** Critical
|
||||
**Surface:** Code tab → File pane
|
||||
**Applies to:** All rows
|
||||
**Issues:** —
|
||||
|
||||
**Steps:**
|
||||
1. In a Code-tab session, click a file path in chat or diff to open it in the file pane.
|
||||
2. Make a small edit. Click **Save**.
|
||||
3. Modify the file externally (e.g. `echo >> file`). Re-edit in the pane. Observe the on-disk-changed warning.
|
||||
|
||||
**Expected:** File opens in the editor pane. Edits write back to disk on Save. If the file changed on disk since opening, the pane shows the on-disk-changed warning and offers override or discard. (The conflict check is sha256-based, not mtime-based — `writeSessionFile` reads the current bytes, hashes them, and rejects with `Conflict` if the renderer-supplied `expectedHash` doesn't match.)
|
||||
|
||||
**Diagnostics on failure:** `sha256sum <file>` output (and stat mtime for cross-checking), launcher log, DevTools console, screen recording of the warning state.
|
||||
|
||||
**References:** [Open and edit files](https://code.claude.com/docs/en/desktop#open-and-edit-files)
|
||||
|
||||
**Code anchors:**
|
||||
- `build-reference/app-extracted/.vite/build/index.js:68922` — IPC
|
||||
channel `claude.web_LocalSessions_readSessionFile`
|
||||
- `build-reference/app-extracted/.vite/build/index.js:69003` — IPC
|
||||
channel `claude.web_LocalSessions_writeSessionFile` with
|
||||
`expectedHash` argument at position 3
|
||||
- `build-reference/app-extracted/.vite/build/index.js:492874` —
|
||||
`readSessionFile` impl
|
||||
- `build-reference/app-extracted/.vite/build/index.js:492954` —
|
||||
`writeSessionFile` impl: sha256-hashes current on-disk bytes,
|
||||
returns `{ status: nW.Conflict, currentHash }` when `expectedHash`
|
||||
mismatches
|
||||
@@ -0,0 +1,163 @@
|
||||
# Code Tab — Handoffs to Other Apps
|
||||
|
||||
Tests covering desktop notifications, "Open in" external editor, "Show in Files" file manager, connector OAuth round-trips, IDE handoff, and graceful failure of the macOS/Windows-only `/desktop` CLI command. See [`../matrix.md`](../matrix.md) for status.
|
||||
|
||||
## T23 — Desktop notifications fire
|
||||
|
||||
**Severity:** Critical
|
||||
**Surface:** Notifications (libnotify / XDG Notifications)
|
||||
**Applies to:** All rows
|
||||
**Issues:** —
|
||||
|
||||
**Steps:**
|
||||
1. Trigger each notification source: scheduled-task fire ([T27](./routines.md#t27--scheduled-task-fires-and-notifies)), CI completion ([T22](./code-tab-workflow.md#t22--pr-monitoring-via-gh)), Dispatch handoff ([S24](./platform-integration.md#s24--dispatch-spawned-code-session-appears-with-badge-and-notification)).
|
||||
2. Observe each notification appears.
|
||||
3. Click each — confirm it focuses the relevant session.
|
||||
|
||||
**Expected:** Notifications appear in the active DE's notification area (Plasma's notification daemon, Mako on wlroots, gnome-shell, etc.) and are clickable to focus the relevant session.
|
||||
|
||||
**Diagnostics on failure:** `gdbus call --session --dest=org.freedesktop.Notifications --object-path=/org/freedesktop/Notifications --method=org.freedesktop.DBus.Introspectable.Introspect`, `notify-send "test"` (sanity check daemon), launcher log, DE-specific notification logs.
|
||||
|
||||
**References:** [Scheduled tasks](https://code.claude.com/docs/en/desktop-scheduled-tasks), [Monitor pull request status](https://code.claude.com/docs/en/desktop#monitor-pull-request-status)
|
||||
|
||||
**Code anchors:** `build-reference/app-extracted/.vite/build/index.js:494456` (`new hA.Notification(r)` — backed by Electron's libnotify on Linux); `:495110` (`showNotification(title, body, tag, navigateTo)` dispatches Swift on macOS, Electron elsewhere); `:511174`, `:512738` (cu-lock / tool-permission notifications wire a click callback that navigates to `/local_sessions/{sessionId}` to focus the session).
|
||||
|
||||
## T24 — Open in external editor
|
||||
|
||||
**Severity:** Should
|
||||
**Surface:** Code tab → Right-click → Open in
|
||||
**Applies to:** All rows
|
||||
**Issues:** —
|
||||
|
||||
**Steps:**
|
||||
1. Install at least one of: VS Code, Cursor, Zed, Windsurf (any install method —
|
||||
flatpak, AppImage, distro package). Xcode is darwin-only and absent on Linux.
|
||||
2. In the Code tab, right-click a file path → **Open in** → choose the editor.
|
||||
3. Confirm the editor opens at that file.
|
||||
|
||||
**Expected:** Right-click → **Open in** launches the chosen editor with the file
|
||||
path. Editor is invoked by URL scheme (`vscode://file/<path>`,
|
||||
`cursor://file/<path>`, `zed://file/<path>`, `windsurf://file/<path>`) via
|
||||
`shell.openExternal`, which delegates to `xdg-open`'s
|
||||
`x-scheme-handler/<editor>` resolution rather than hard-coded paths.
|
||||
|
||||
**Diagnostics on failure:** `xdg-mime query default x-scheme-handler/vscode` (or
|
||||
`cursor`/`zed`/`windsurf`), `desktop-file-validate` on the editor's `.desktop`
|
||||
file, `xdg-open vscode://file/<path>` from terminal (sanity check), launcher
|
||||
log.
|
||||
|
||||
**References:** [Open files in other apps](https://code.claude.com/docs/en/desktop#open-files-in-other-apps)
|
||||
|
||||
**Code anchors:** `build-reference/app-extracted/.vite/build/index.js:59076`
|
||||
(editor enum: VSCode, Cursor, Zed, Windsurf, Xcode); `:463902` (`Mtt`
|
||||
registry — `vscode://`, `cursor://`, `zed://`, `windsurf://`, `xcode://` with
|
||||
darwin-only flag on Xcode); `:463956` (`getInstalledEditors` probes via
|
||||
`app.getApplicationInfoForProtocol`); `:464011`
|
||||
(`shell.openExternal('<scheme>://file/<encoded-path>:<line>')` — path is
|
||||
URL-encoded but `/` separators are preserved); `:68816` IPC handler
|
||||
`LocalSessions.openInEditor(path, editor, sshConfig, line)`.
|
||||
|
||||
## T25 — Show in Files / file manager
|
||||
|
||||
**Severity:** Should
|
||||
**Surface:** Code tab → Right-click → Show in Files
|
||||
**Applies to:** All rows
|
||||
**Issues:** —
|
||||
|
||||
**Steps:**
|
||||
1. In the Code tab, right-click a file path → "Show in Files" (Linux equivalent of macOS "Show in Finder" / Windows "Show in Explorer").
|
||||
2. Confirm the system file manager opens with the containing folder selected.
|
||||
|
||||
**Expected:** System file manager (Nautilus on GNOME, Dolphin on KDE, Thunar on Xfce, etc.) opens with the file pre-selected. Resolution respects `xdg-mime` defaults.
|
||||
|
||||
**Diagnostics on failure:** `xdg-mime query default inode/directory`, `xdg-open <dir>` from terminal, the menu label rendered (was it Linux-specific or stuck on "Show in Finder"?), launcher log.
|
||||
|
||||
**References:** [Open files in other apps](https://code.claude.com/docs/en/desktop#open-files-in-other-apps)
|
||||
|
||||
**Code anchors:** `build-reference/app-extracted/.vite/build/index.js:66652` IPC
|
||||
handler `FileSystem.showInFolder(path)`; `:509431` impl thin-wraps
|
||||
`hA.shell.showItemInFolder(Tc(path))`. Electron's `showItemInFolder` on Linux
|
||||
falls back to `xdg-open` on the parent directory when no DBus FileManager1
|
||||
service is present, so the file is rarely pre-selected on minimal DEs — only
|
||||
the parent folder opens.
|
||||
|
||||
## T34 — Connector OAuth round-trip
|
||||
|
||||
**Severity:** Critical
|
||||
**Surface:** Connectors → OAuth handoff
|
||||
**Applies to:** All rows
|
||||
**Issues:** —
|
||||
|
||||
**Steps:**
|
||||
1. In a Code-tab session, click **+** → **Connectors** → choose a service (Slack, GitHub, Linear, Notion, Google Calendar).
|
||||
2. Step through the OAuth flow in the system browser.
|
||||
3. Return to Claude Desktop and verify the connector appears in **Settings → Connectors**.
|
||||
4. Use the connector in a prompt (e.g. "list my Slack channels").
|
||||
|
||||
**Expected:** Adding a connector launches the browser via `xdg-open`, OAuth callback hands control back to Claude Desktop, connector appears in Settings, and is usable in subsequent prompts.
|
||||
|
||||
**Diagnostics on failure:** `xdg-mime query default x-scheme-handler/https`, the callback URL scheme, network captures of OAuth redirect, launcher log, DevTools console.
|
||||
|
||||
**References:** [Connect external tools](https://code.claude.com/docs/en/desktop#connect-external-tools), [Connectors for everyday life](https://claude.com/blog/connectors-for-everyday-life)
|
||||
|
||||
**Code anchors:**
|
||||
`build-reference/app-extracted/.vite/build/index.js:524819`
|
||||
(`hA.app.setAsDefaultProtocolClient("claude")` — registers the `claude://`
|
||||
deep-link scheme used by the OAuth callback); `:525026` mainWindow
|
||||
`setWindowOpenHandler` routes external URLs through `MAA(url)` →
|
||||
`:525102`–`:525135` (only `http:`/`https:`/`mailto:`/`tel:`/`sms:`/
|
||||
`ms-(excel|powerpoint|word):` are forwarded to system handlers; everything
|
||||
else is dropped); `:136233` `$a(url)` thin-wraps `hA.shell.openExternal(url)`
|
||||
(this is the single egress point for browser handoff); `:159634`
|
||||
`mcpSubmitOAuthCallbackUrl(serverName, callbackUrl)` and `:159651`
|
||||
`claudeOAuthCallback(authorizationCode, state)` — IPC bridges that consume
|
||||
the deep-link callback. See [`docs/learnings/plugin-install.md`](../../learnings/plugin-install.md)
|
||||
for orgId/sessionKey cookie chain that gates connector listing.
|
||||
|
||||
## T38 — Continue in IDE
|
||||
|
||||
**Severity:** Should
|
||||
**Surface:** Code tab → Continue in menu
|
||||
**Applies to:** All rows
|
||||
**Issues:** —
|
||||
|
||||
**Steps:**
|
||||
1. In a Code-tab session, click the IDE icon (bottom right of session toolbar) → **Continue in** → choose an IDE.
|
||||
2. Confirm the IDE opens at the working directory.
|
||||
|
||||
**Expected:** Selected IDE opens the project at the current working directory. Resolution via `xdg-open` / `.desktop` files.
|
||||
|
||||
**Diagnostics on failure:** `xdg-open <project-dir>` sanity check, `xdg-mime query default x-scheme-handler/vscode` (or matching scheme for the chosen IDE), launcher log, the IDE's `.desktop` file.
|
||||
|
||||
**References:** [Continue in another surface](https://code.claude.com/docs/en/desktop#continue-in-another-surface)
|
||||
|
||||
**Code anchors:** Same IPC surface as [T24](#t24--open-in-external-editor) —
|
||||
`build-reference/app-extracted/.vite/build/index.js:68816`
|
||||
(`LocalSessions.openInEditor(path, editor, sshConfig, line)` accepts a
|
||||
directory path the same way as a file path); `:463902` editor registry;
|
||||
`:464011` `shell.openExternal('<scheme>://file/<cwd>')`. The "Continue in"
|
||||
chooser UI is rendered server-side by claude.ai and not present in the local
|
||||
asar — only the IPC bridge can be code-anchored.
|
||||
|
||||
## T39 — `/desktop` CLI handoff (graceful N/A)
|
||||
|
||||
> **Note** — This test exercises the upstream `claude` CLI binary, not the
|
||||
> Electron app. The CLI ships separately from this packaging (out of
|
||||
> `build-reference/`), so no anchor in `app-extracted/.vite/build/` exists for
|
||||
> the slash-command handler. Re-verify behaviour against the CLI binary that
|
||||
> ships with the upstream version under test (currently 1.5354.0).
|
||||
|
||||
**Severity:** Could
|
||||
**Surface:** CLI `/desktop` command
|
||||
**Applies to:** All rows (Linux equally)
|
||||
**Issues:** —
|
||||
|
||||
**Steps:**
|
||||
1. In a CLI session, run `/desktop`.
|
||||
2. Inspect exit code and output.
|
||||
|
||||
**Expected:** `/desktop` is documented as macOS/Windows-only. On Linux it must fail gracefully — print a clear "not supported on Linux" message and exit cleanly. No partial state transition, no panic, no corrupted session file.
|
||||
|
||||
**Diagnostics on failure:** Full CLI output, exit code, the session file before/after (`~/.claude/sessions/...`), strace if the CLI hangs.
|
||||
|
||||
**References:** [Coming from the CLI](https://code.claude.com/docs/en/desktop#coming-from-the-cli)
|
||||
@@ -0,0 +1,151 @@
|
||||
# Code Tab — Workflow Surfaces
|
||||
|
||||
Tests covering the dev-server preview pane, PR monitoring, worktree isolation, auto-archive, side chat, and the slash command menu. See [`../matrix.md`](../matrix.md) for status.
|
||||
|
||||
## T21 — Dev server preview pane
|
||||
|
||||
**Severity:** Should
|
||||
**Surface:** Code tab → Preview pane
|
||||
**Applies to:** All rows
|
||||
**Issues:** —
|
||||
|
||||
**Steps:**
|
||||
1. In a Code-tab session, ensure `.claude/launch.json` is configured (or let auto-detect populate it).
|
||||
2. Click **Preview** dropdown → **Start**.
|
||||
3. Interact with the embedded browser. Verify auto-verify takes screenshots.
|
||||
4. Stop the server from the dropdown.
|
||||
|
||||
**Expected:** Configured dev server starts. Embedded browser renders the running app. Auto-verify takes screenshots and inspects DOM. Stopping from the dropdown actually stops the process.
|
||||
|
||||
**Diagnostics on failure:** `lsof -i :<port>` to see the server, screenshot of preview pane state, `.claude/launch.json` content, launcher log, DevTools console.
|
||||
|
||||
**References:** [Preview your app](https://code.claude.com/docs/en/desktop#preview-your-app)
|
||||
|
||||
**Code anchors:**
|
||||
- `build-reference/app-extracted/.vite/build/index.js:262175` — `Pae = "Claude Preview"` + `preview_*` MCP tool table (`preview_start`, `preview_stop`, `preview_list`, `preview_screenshot`, `preview_snapshot`, `preview_inspect`, `preview_click`, `preview_fill`, `preview_eval`, `preview_network`, `preview_resize`).
|
||||
- `build-reference/app-extracted/.vite/build/index.js:259604` — `setAutoVerify()` and `parseLaunchJson()` (reads `.claude/launch.json`, honours `autoVerify` flag default-on).
|
||||
- `build-reference/app-extracted/.vite/build/index.js:260015` — `capturePage()` / `captureViaCDP()` drive `preview_screenshot` against the embedded preview WebContents.
|
||||
|
||||
## T22 — PR monitoring via `gh`
|
||||
|
||||
**Severity:** Critical
|
||||
**Surface:** Code tab → CI status bar
|
||||
**Applies to:** All rows
|
||||
**Issues:** —
|
||||
|
||||
**Steps:**
|
||||
1. Ensure `gh` is installed and authenticated (`gh auth status`).
|
||||
2. In a Code-tab session, ask Claude to open a PR for a small change.
|
||||
3. Observe the CI status bar. Toggle **Auto-fix** and **Auto-merge**.
|
||||
4. Run a separate test on a row where `gh` is **not** installed — confirm the missing-`gh` prompt appears the first time a PR action is taken.
|
||||
|
||||
**Expected:** With `gh` present and authenticated, CI status bar surfaces in the session toolbar. Auto-fix and Auto-merge toggles work (auto-merge requires the corresponding GitHub repo setting). If `gh` is missing, the app surfaces a prompt directing the user to https://cli.github.com (auto-install via `installGh` only runs on macOS/brew; Linux returns an error string with the install URL).
|
||||
|
||||
**Diagnostics on failure:** `gh auth status`, `which gh`, launcher log, DevTools console, screenshot of status bar, the GitHub repo's "Allow auto-merge" setting.
|
||||
|
||||
**References:** [Monitor pull request status](https://code.claude.com/docs/en/desktop#monitor-pull-request-status)
|
||||
|
||||
**Code anchors:**
|
||||
- `build-reference/app-extracted/.vite/build/index.js:464281` — `GitHubPrManager` (`prStateCache`, `prChecksCache`); `getPrChecks` at line 464964 fans out to `gh pr view`.
|
||||
- `build-reference/app-extracted/.vite/build/index.js:464368` — `"gh CLI not found in PATH"` throw site that backs the missing-`gh` prompt.
|
||||
- `build-reference/app-extracted/.vite/build/index.js:464480` — `installGh()`: macOS-only `brew install gh`; Linux/Windows return error pointing to https://cli.github.com.
|
||||
- `build-reference/app-extracted/.vite/build/index.js:465019` — `autoMergeRequest { enabledAt }` GraphQL fragment; `enableAutoMerge` / `disableAutoMerge` at lines 465531 / 465556.
|
||||
- `build-reference/app-extracted/.vite/build/index.js:534033` — `AutoFixEngine.handleSessionEvent` toggles on `autoFixEnabled` per session.
|
||||
|
||||
## T29 — Worktree isolation
|
||||
|
||||
**Severity:** Critical
|
||||
**Surface:** Code tab → Sidebar (parallel sessions)
|
||||
**Applies to:** All rows
|
||||
**Issues:** —
|
||||
|
||||
**Steps:**
|
||||
1. In a Code-tab session against a Git project, open two new sessions in parallel via **+ New session**.
|
||||
2. Make different edits in each session.
|
||||
3. Confirm `<project-root>/.claude/worktrees/<branch>` exists for each.
|
||||
4. Archive one session via the sidebar archive icon.
|
||||
|
||||
**Expected:** Each session creates an isolated worktree at `<project-root>/.claude/worktrees/<branch>` (or the dir configured in Settings → Claude Code → "Worktree location"). Edits in one session do not appear in another until committed. Archiving removes the worktree.
|
||||
|
||||
**Diagnostics on failure:** `git worktree list` from project root, `ls -la <project-root>/.claude/worktrees/`, launcher log.
|
||||
|
||||
**References:** [Work in parallel with sessions](https://code.claude.com/docs/en/desktop#work-in-parallel-with-sessions)
|
||||
|
||||
**Code anchors:**
|
||||
- `build-reference/app-extracted/.vite/build/index.js:462835` — `getWorktreeParentDir()`: returns `<baseRepo>/.claude/worktrees`, or `<chillingSlothLocation.customPath>/<basename>` when overridden in Settings.
|
||||
- `build-reference/app-extracted/.vite/build/index.js:462843` — `createWorktree()`: runs `git worktree add` with `core.longpaths=true` under the parent dir.
|
||||
- `build-reference/app-extracted/.vite/build/index.js:463290` — `git worktree remove --force` invoked on archive (cleanup path).
|
||||
- `build-reference/app-extracted/.vite/build/index.js:55231` — `chillingSlothLocation: "default"` settings key (Settings → "Worktree location").
|
||||
|
||||
## T30 — Auto-archive on PR merge
|
||||
|
||||
**Severity:** Should
|
||||
**Surface:** Code tab → Sidebar
|
||||
**Applies to:** All rows
|
||||
**Issues:** —
|
||||
|
||||
**Steps:**
|
||||
1. In Settings → Claude Code, enable **Auto-archive on PR close** (`ccAutoArchiveOnPrClose`).
|
||||
2. Open a PR from a local session. Merge or close it on GitHub.
|
||||
3. Wait up to ~5–6 minutes (sweep runs every 5 minutes, with a 30s startup delay). Observe the sidebar.
|
||||
|
||||
**Expected:** Local session whose PR is `merged` or `closed` is archived from the sidebar on the next sweep tick (≤ ~5 min) after the merge/close event. Cached PR-state lookups have a 1-hour cooldown for sessions whose state isn't yet terminal. Remote and SSH sessions are not affected.
|
||||
|
||||
**Diagnostics on failure:** Screenshot of sidebar, `gh pr view <num>` output (confirming merge state), launcher log, settings file content (`ccAutoArchiveOnPrClose`).
|
||||
|
||||
**References:** [Work in parallel with sessions](https://code.claude.com/docs/en/desktop#work-in-parallel-with-sessions)
|
||||
|
||||
**Code anchors:**
|
||||
- `build-reference/app-extracted/.vite/build/index.js:55269` — default `ccAutoArchiveOnPrClose: !1` setting.
|
||||
- `build-reference/app-extracted/.vite/build/index.js:533517` — sweep cadence constants: `$3n = 300_000` ms (5 min interval), `W3n = 3_600_000` ms (1 h recheck cooldown), `Fst = 10` (concurrent batch size).
|
||||
- `build-reference/app-extracted/.vite/build/index.js:533520` — `AutoArchiveEngine.start()` schedules the 5-min interval + 30s initial delay.
|
||||
- `build-reference/app-extracted/.vite/build/index.js:533537` — `sweep()` gates on `Qi("ccAutoArchiveOnPrClose")` and archives sessions whose `prState` lowercases to `merged` or `closed` (`D3A` predicate at line 533607).
|
||||
- `build-reference/app-extracted/.vite/build/index.js:533571` — `archiveSession(..., { cleanupWorktree: true })` removes the worktree alongside the archive.
|
||||
|
||||
## T31 — Side chat opens
|
||||
|
||||
**Severity:** Should
|
||||
**Surface:** Code tab → Side chat overlay
|
||||
**Applies to:** All rows
|
||||
**Issues:** —
|
||||
|
||||
**Steps:**
|
||||
1. In a Code-tab session, press `Ctrl+;` (or type `/btw` in the prompt).
|
||||
2. Ask a question in the side chat. Confirm the side chat sees the main thread context.
|
||||
3. Close the side chat. Confirm focus returns to the main session and the side chat content is not in the main thread.
|
||||
|
||||
**Expected:** Side chat opens, has access to main-thread context, but its replies do not appear in the main conversation. Closing returns focus.
|
||||
|
||||
**Diagnostics on failure:** Screenshot, launcher log, DevTools console.
|
||||
|
||||
**References:** [Ask a side question](https://code.claude.com/docs/en/desktop#ask-a-side-question-without-derailing-the-session)
|
||||
|
||||
**Code anchors:**
|
||||
- `build-reference/app-extracted/.vite/build/index.js:487025` — side-chat system-prompt suffix: "You are running in a side chat — a lightweight fork… nothing you say here lands in the main transcript."
|
||||
- `build-reference/app-extracted/.vite/build/index.js:487265` — `this.sideChats = new Map()` per-session fork registry.
|
||||
- `build-reference/app-extracted/.vite/build/index.js:491658` — `startSideChat()` implementation; emits `side_chat_ready` / `side_chat_assistant` / `side_chat_turn_end` / `side_chat_closed` / `side_chat_error` events.
|
||||
- `build-reference/app-extracted/.vite/build/mainView.js:7506` — preload IPC bridges: `startSideChat`, `sendSideChatMessage`, `stopSideChat` (the renderer SPA wires `Ctrl+;` / `/btw` to these — UI lives in claude.ai's remote bundle, not build-reference).
|
||||
|
||||
## T32 — Slash command menu
|
||||
|
||||
**Severity:** Should
|
||||
**Surface:** Code tab → Prompt slash menu
|
||||
**Applies to:** All rows
|
||||
**Issues:** —
|
||||
|
||||
**Steps:**
|
||||
1. In a Code-tab session, type `/` in the prompt box.
|
||||
2. Verify built-in commands, custom skills under `~/.claude/skills/`, project skills, and skills from installed plugins all appear.
|
||||
3. Select an entry — confirm it inserts as a highlighted token.
|
||||
|
||||
**Expected:** Slash menu lists every available command/skill. Selection inserts the token correctly.
|
||||
|
||||
**Diagnostics on failure:** Screenshot of slash menu, `ls ~/.claude/skills/`, project `.claude/skills/`, installed plugin manifest, launcher log.
|
||||
|
||||
**References:** [Use skills](https://code.claude.com/docs/en/desktop#use-skills)
|
||||
|
||||
**Code anchors:**
|
||||
- `build-reference/app-extracted/.vite/build/index.js:459463` — `getSupportedCommands({sessionId})` aggregates per-session `slashCommands` + cowork command registry (`p2()`) + built-ins (`Q_t`).
|
||||
- `build-reference/app-extracted/.vite/build/index.js:332711` — `slashCommands: Di.array(Di.string()).optional()` schema field on the session record.
|
||||
- `build-reference/app-extracted/.vite/build/index.js:377670` — `SkillManager` constructor: `skillDir = <agentDir>/.claude/skills`, `_discoverSkills()` walks project skills.
|
||||
- `build-reference/app-extracted/.vite/build/index.js:444678` — private/public skill split under `<skillsRoot>/skills/{private,public}` for plugin-supplied skills.
|
||||
@@ -0,0 +1,168 @@
|
||||
# Distribution — DEB, RPM, AppImage
|
||||
|
||||
Tests covering Ubuntu/DEB-specific install behavior, Fedora/RPM-specific install behavior, AppImage fallback paths, and the auto-update interaction with system package managers. See [`../matrix.md`](../matrix.md) for status.
|
||||
|
||||
## S01 — AppImage launches without manual `libfuse2t64` install
|
||||
|
||||
**Severity:** Critical (for Ubuntu users)
|
||||
**Surface:** AppImage runtime / FUSE
|
||||
**Applies to:** Ubu (and any Ubuntu 24.04+ host)
|
||||
**Issues:** —
|
||||
|
||||
**Steps:**
|
||||
1. Fresh Ubuntu 24.04 install with default packages only.
|
||||
2. Download the project AppImage.
|
||||
3. Make executable and run it.
|
||||
|
||||
**Expected:** AppImage runs without first installing `libfuse2t64`. Either the AppImage bundles its own FUSE shim, the `.desktop`/postinst declares the dep, or the launcher gives a clear error pointing at the package name.
|
||||
|
||||
**Currently:** Fails on Ubuntu 24.04 with `dlopen(): error loading libfuse.so.2`. Workaround: `sudo apt install libfuse2t64`. Not yet filed.
|
||||
|
||||
**Diagnostics on failure:** Full stderr from the AppImage launch, `ldd ./claude-desktop-*.AppImage`, `dpkg -l | grep -i fuse`.
|
||||
|
||||
**References:** —
|
||||
|
||||
**Code anchors:** `scripts/packaging/appimage.sh:226` (downloads the upstream `appimagetool` AppImage as-is — no FUSE shim or static-mksquashfs bundling), `scripts/launcher-common.sh:64` (AppImage forces `--no-sandbox` "due to FUSE constraints"), `.github/workflows/test-artifacts.yml:47` (CI installs `libfuse2` before running the AppImage — i.e. the runtime hard-depends on libfuse2/libfuse2t64). No postinst dep declaration or user-facing FUSE error message exists.
|
||||
|
||||
## S02 — `XDG_CURRENT_DESKTOP=ubuntu:GNOME` doesn't break DE detection
|
||||
|
||||
**Severity:** Critical
|
||||
**Surface:** DE detection / patch gate
|
||||
**Applies to:** Ubu
|
||||
**Issues:** —
|
||||
|
||||
**Steps:**
|
||||
1. On Ubuntu 24.04 (where `XDG_CURRENT_DESKTOP=ubuntu:GNOME`), launch the app.
|
||||
2. Inspect launcher log for any DE-detection branches that should fire as GNOME.
|
||||
3. Audit `scripts/launcher-common.sh` and any DE-gated patches for string-equality checks against `XDG_CURRENT_DESKTOP`.
|
||||
|
||||
**Expected:** DE-detection logic handles Ubuntu's colon-separated value. `contains "GNOME"` or splitting on `:` is the safe pattern; `== "GNOME"` would miss Ubuntu.
|
||||
|
||||
**Diagnostics on failure:** `echo $XDG_CURRENT_DESKTOP`, the relevant launcher.sh code path, launcher log, the patches that ran or didn't.
|
||||
|
||||
**References:** Surfaced via session-capture review.
|
||||
|
||||
**Code anchors:** `scripts/launcher-common.sh:35-44` (Niri auto-detect lowercases `XDG_CURRENT_DESKTOP` and uses `*niri*` glob — handles colon-separated values), `scripts/patches/quick-window.sh:34-35` and `:117-118` (KDE gate uses `.toLowerCase().includes("kde")` — substring, not equality), `scripts/doctor.sh:304` (purely informational `_info "Desktop: $desktop"`, no branching). No `==` equality checks against `XDG_CURRENT_DESKTOP` exist anywhere in shell or patched JS.
|
||||
|
||||
## S03 — DEB install via APT pulls all required runtime deps
|
||||
|
||||
**Severity:** Critical
|
||||
**Surface:** APT repository / dependency declarations
|
||||
**Applies to:** Ubu (any DEB-based distro)
|
||||
**Issues:** [`docs/learnings/apt-worker-architecture.md`](../../learnings/apt-worker-architecture.md)
|
||||
|
||||
**Steps:**
|
||||
1. Add the project's APT repo per the README install instructions.
|
||||
2. `sudo apt install claude-desktop-unofficial` on a fresh container/VM.
|
||||
3. Run `claude-desktop-unofficial` — first launch should succeed with no further package installs.
|
||||
|
||||
**Expected:** All transitive runtime deps are declared in the package and pulled by APT. First launch succeeds without manual `apt install` of any extra package.
|
||||
|
||||
**Diagnostics on failure:** `apt-cache depends claude-desktop-unofficial`, missing-library errors from the launcher, `ldd` against the binary.
|
||||
|
||||
**References:** [`docs/learnings/apt-worker-architecture.md`](../../learnings/apt-worker-architecture.md)
|
||||
|
||||
**Code anchors:** `scripts/packaging/deb.sh:185-197` (DEBIAN/control file — no `Depends:` field is emitted; relies on bundled Electron + the comment "No external dependencies are required at runtime" at line 183), `scripts/packaging/deb.sh:202-230` (postinst only sets chrome-sandbox suid, no dep-pull). Worker chain serving the package: `worker/src/worker.js:22-31` (`DEB_RE`) and `:33-43` (302 → GitHub Releases).
|
||||
|
||||
## S04 — RPM install via DNF pulls all required runtime deps
|
||||
|
||||
**Severity:** Critical
|
||||
**Surface:** DNF repository / dependency declarations
|
||||
**Applies to:** KDE-W, KDE-X, GNOME, Sway, i3, Niri (any RPM-based distro)
|
||||
**Issues:** [`docs/learnings/apt-worker-architecture.md`](../../learnings/apt-worker-architecture.md) *(covers both APT and DNF)*
|
||||
|
||||
**Steps:**
|
||||
1. Add the project's DNF repo per the README.
|
||||
2. `sudo dnf install claude-desktop-unofficial` on a fresh container/VM.
|
||||
3. Run `claude-desktop-unofficial` — first launch should succeed.
|
||||
|
||||
**Expected:** All transitive runtime deps are declared in the RPM and pulled by DNF. First launch succeeds with no further package installs.
|
||||
|
||||
**Diagnostics on failure:** `dnf repoquery --requires claude-desktop-unofficial`, `rpm -qR claude-desktop-unofficial`, launcher missing-library errors.
|
||||
|
||||
**References:** [`docs/learnings/apt-worker-architecture.md`](../../learnings/apt-worker-architecture.md)
|
||||
|
||||
**Code anchors:** `scripts/packaging/rpm.sh:188` (`AutoReqProv: no` — explicitly disables RPM's auto-dep generation; spec declares no `Requires:`), `scripts/packaging/rpm.sh:194-198` (strip + build-id disabled because Electron binaries don't tolerate them — bundled approach). Worker chain: `worker/src/worker.js:28-31` (`RPM_RE`).
|
||||
|
||||
## S05 — Doctor recognises dnf-installed package, doesn't false-flag as AppImage
|
||||
|
||||
**Severity:** Should
|
||||
**Surface:** Doctor package-format detection
|
||||
**Applies to:** KDE-W, KDE-X, GNOME, Sway, i3, Niri
|
||||
**Issues:** —
|
||||
|
||||
**Steps:**
|
||||
1. On a Fedora/Nobara/RPM-based distro with claude-desktop-unofficial installed via dnf, run `claude-desktop-unofficial --doctor`.
|
||||
2. Look for the install-method line.
|
||||
|
||||
**Expected:** Doctor detects rpm install (e.g. via `rpm -qf` against the binary path) and reports it cleanly. No `not found via dpkg (AppImage?)` warning.
|
||||
|
||||
**Currently:** Addressed by #711 — the probe follows ownership: `rpm -qf` against the Electron binary first, `dpkg-query -W claude-desktop-unofficial` only when rpm does not own the path, so dnf installs report cleanly and a stale dpkg record cannot shadow a live rpm install. The `claude-desktop-unofficial not found via dpkg/rpm (AppImage?)` WARN fires only when neither manager owns the install. Needs a re-verify sweep on the affected rows ([T13](./launch.md#t13--doctor-reports-correct-package-format)).
|
||||
|
||||
**Diagnostics on failure:** Full `--doctor` output, `rpm -qf $(which claude-desktop-unofficial)`, the doctor source line that decides the format.
|
||||
|
||||
**References:** [T13](./launch.md#t13--doctor-reports-correct-package-format)
|
||||
|
||||
**Code anchors:** `scripts/doctor.sh:717-768` (`_doctor_check_pkg_version`) — rpm-first ownership probe with a dpkg fallback scoped to `claude-desktop-unofficial`; the not-found WARN is the last resort when neither manager owns the install.
|
||||
|
||||
## S15 — AppImage extraction (`--appimage-extract`) works as documented fallback
|
||||
|
||||
**Severity:** Could
|
||||
**Surface:** AppImage runtime / FUSE-less fallback
|
||||
**Applies to:** Any AppImage row
|
||||
**Issues:** —
|
||||
|
||||
**Steps:**
|
||||
1. On a host without FUSE, run `./claude-desktop-*.AppImage --appimage-extract`.
|
||||
2. Inspect `squashfs-root/`.
|
||||
3. Run `squashfs-root/AppRun`.
|
||||
|
||||
**Expected:** Extraction completes. `squashfs-root/AppRun` launches the app cleanly without FUSE.
|
||||
|
||||
**Diagnostics on failure:** Extraction stderr, `ls squashfs-root/`, AppRun stderr.
|
||||
|
||||
**References:** Linked from the runtime error message when FUSE is missing.
|
||||
|
||||
**Code anchors:** `scripts/packaging/appimage.sh:282` and `:312` (built with stock `appimagetool`, which always supports `--appimage-extract`), `scripts/packaging/appimage.sh:70-118` (`AppRun` script that lives at `squashfs-root/AppRun` after extraction). CI exercises this path: `tests/test-artifact-appimage.sh:36-44` and `.github/workflows/ci.yml:388` both run `--appimage-extract` and assert `squashfs-root/` exists.
|
||||
|
||||
## S16 — AppImage mount cleans up on app exit
|
||||
|
||||
**Severity:** Should
|
||||
**Surface:** AppImage mount lifecycle
|
||||
**Applies to:** Any AppImage row
|
||||
**Issues:** [CLAUDE.md "Common Gotchas"](https://github.com/aaddrick/claude-desktop-debian/blob/main/CLAUDE.md)
|
||||
|
||||
**Steps:**
|
||||
1. Launch the AppImage. Confirm `mount | grep claude` shows the mount.
|
||||
2. Quit the app cleanly via tray → Quit (or `Ctrl+Q`).
|
||||
3. Re-run `mount | grep claude` — mount should be gone.
|
||||
|
||||
**Expected:** AppImage's mount at `/tmp/.mount_claude*` is unmounted and the directory removed when all child Electron processes exit. Stale mounts after force-quit are handled by `pkill -9 -f "mount_claude"` per CLAUDE.md but should not be the common case.
|
||||
|
||||
**Diagnostics on failure:** `mount | grep claude` after exit, `ls -la /tmp/.mount_claude*`, `pgrep -af claude`, `journalctl -k -n 50` for mount errors.
|
||||
|
||||
**References:** [CLAUDE.md "Common Gotchas"](https://github.com/aaddrick/claude-desktop-debian/blob/main/CLAUDE.md)
|
||||
|
||||
**Code anchors:** Mount lifecycle is owned by upstream `appimagetool`'s runtime, not this repo — `scripts/packaging/appimage.sh:282`/`:312` invokes the stock tool with no custom AppRun-side cleanup. `CLAUDE.md:179-183` documents `pkill -9 -f "mount_claude"` as the manual recovery for stale mounts after force-quit. No project-side unmount handler exists; the test asserts upstream behavior, not ours.
|
||||
|
||||
## S26 — Auto-update is disabled when installed via `apt` / `dnf`
|
||||
|
||||
> **⚠ Missing in build 1.5354.0** — No project-side suppression of upstream auto-update exists; the launcher exports `ELECTRON_FORCE_IS_PACKAGED=true`, which causes upstream's `lii()` gate to return true on Linux and the auto-update tick loop to start. Suppression is "accidental" — it relies on Electron's built-in `autoUpdater` module being unimplemented on Linux (so `setFeedURL`/`checkForUpdates` throw, the `error` listener logs, and no download happens). Tracked at [#567](https://github.com/aaddrick/claude-desktop-debian/issues/567); re-verify after next upstream bump.
|
||||
|
||||
**Severity:** Critical
|
||||
**Surface:** Auto-update path
|
||||
**Applies to:** All DEB/RPM rows
|
||||
**Issues:** [#567](https://github.com/aaddrick/claude-desktop-debian/issues/567)
|
||||
|
||||
**Steps:**
|
||||
1. Install via APT or DNF.
|
||||
2. Launch the app and let it sit for ~5 minutes.
|
||||
3. Inspect launcher log + filesystem for any auto-update download attempt.
|
||||
|
||||
**Expected:** When installed via the project's APT or DNF repo, the in-app auto-update path is suppressed. The app does not download replacement binaries (which would race the package manager). Updates flow through `apt upgrade` / `dnf upgrade` only. AppImage installs may continue to self-update or punt to the user.
|
||||
|
||||
**Diagnostics on failure:** Launcher log, network captures (look for downloads from `releases.anthropic.com` or `api.anthropic.com/api/desktop/linux/...`), filesystem changes under `~/.config/Claude/`.
|
||||
|
||||
**References:** [`docs/learnings/apt-worker-architecture.md`](../../learnings/apt-worker-architecture.md)
|
||||
|
||||
**Code anchors:** `scripts/launcher-common.sh:249` (`export ELECTRON_FORCE_IS_PACKAGED=true` — makes upstream think it's installed); `build-reference/app-extracted/.vite/build/index.js:508761-508769` (upstream `lii()` returns `hA.app.isPackaged` on Linux — passes the gate); `:508554-508559` (only suppression hook is enterprise-policy `disableAutoUpdates`, no Linux/distro carve-out); `:508770-508774` (feed URL `https://api.anthropic.com/api/desktop/linux/<arch>/squirrel/update?...`); `:508800-508803` (calls `hA.autoUpdater.setFeedURL` + `.checkForUpdates()` unconditionally on Linux). No patch in `scripts/patches/*.sh` neutralizes the autoUpdater module or sets `disableAutoUpdates`. AppImage continues to ship update info: `scripts/packaging/appimage.sh:308-309` (`gh-releases-zsync` zsync metadata embedded for releases).
|
||||
@@ -0,0 +1,153 @@
|
||||
# Extensibility — Plugins, MCP, Hooks, Memory
|
||||
|
||||
Tests covering the Anthropic & Partners plugin install flow, the plugin browser, MCP server config, hooks, `CLAUDE.md` memory loading, and per-user storage of plugins/worktrees. See [`../matrix.md`](../matrix.md) for status.
|
||||
|
||||
## T11 — Plugin install (Anthropic & Partners)
|
||||
|
||||
**Severity:** Smoke
|
||||
**Surface:** Plugin browser → install flow
|
||||
**Applies to:** All rows
|
||||
**Issues:** [`docs/learnings/plugin-install.md`](../../learnings/plugin-install.md)
|
||||
|
||||
**Steps:**
|
||||
1. In a Code-tab session, click **+** → **Plugins** → **Add plugin**.
|
||||
2. Find an Anthropic & Partners plugin. Click **Install**.
|
||||
3. Verify it lands in **Manage plugins** and its skills appear in the slash menu.
|
||||
4. Re-install the same plugin to verify idempotence.
|
||||
|
||||
**Expected:** Install completes end-to-end: gate logic accepts, backend endpoint responds, plugin appears in the plugin list. Re-install is idempotent.
|
||||
|
||||
**Diagnostics on failure:** DevTools network panel during install, launcher log, `~/.claude/plugins/` content, the gate-logic code path (see learnings doc).
|
||||
|
||||
**References:** [`docs/learnings/plugin-install.md`](../../learnings/plugin-install.md), [Install plugins](https://code.claude.com/docs/en/desktop#install-plugins)
|
||||
|
||||
**Code anchors:** `build-reference/app-extracted/.vite/build/index.js:507181` (`installPlugin` IPC + gate, with `pluginSource === "remote"` branch and CLI fallback); `:507193` log `[CustomPlugins] installPlugin: attempting remote API install`; `:465816` `dx()` returns `~/.claude/plugins`; `:465822` `installed_plugins.json` (idempotency record).
|
||||
|
||||
**Inventory anchor:** `…customize.main.navigation.button-by-name.add-plugin` (role `button`, label `Add plugin`); sibling `…button-by-name.browse-plugins` (label `Browse plugins`). Both are persistent in the Customize panel — anchors the entry-point click chain.
|
||||
|
||||
## T33 — Plugin browser
|
||||
|
||||
**Severity:** Should
|
||||
**Surface:** Plugin browser UI
|
||||
**Applies to:** All rows
|
||||
**Issues:** —
|
||||
|
||||
**Steps:**
|
||||
1. Click **+** → **Plugins** → **Add plugin**.
|
||||
2. Confirm entries from the official Anthropic marketplace appear.
|
||||
3. Install a non-Anthropic plugin end-to-end.
|
||||
4. Verify it shows in **Manage plugins** and contributes its skills to the slash menu.
|
||||
|
||||
**Expected:** Plugin browser opens, shows the marketplace, install completes. Installed plugins appear under Manage plugins and contribute to the slash menu.
|
||||
|
||||
**Diagnostics on failure:** Screenshot of plugin browser, network captures, launcher log, `~/.claude/plugins/` listing.
|
||||
|
||||
**References:** [Install plugins](https://code.claude.com/docs/en/desktop#install-plugins)
|
||||
|
||||
**Code anchors:** `build-reference/app-extracted/.vite/build/index.js:71392` (`CustomPlugins.listMarketplaces` IPC); `:71534` (`listAvailablePlugins` IPC); `:507176` (`listMarketplaces` main-process handler); `:496236` deep-link route `plugins/new` opens the browser surface.
|
||||
|
||||
**Inventory anchor:** `…customize.main.navigation.button-by-name.browse-plugins` (role `button`, label `Browse plugins`); sibling `…link-by-name.connectors` (role `link`, label `Connectors`). The browser surface itself (marketplace listings, install button) appears under a child dialog not captured at idle — re-capture with the dialog open to anchor those.
|
||||
|
||||
## T35 — MCP server config picked up
|
||||
|
||||
**Severity:** Critical
|
||||
**Surface:** MCP / Code tab
|
||||
**Applies to:** All rows
|
||||
**Issues:** —
|
||||
|
||||
**Steps:**
|
||||
1. Add an MCP server to `~/.claude.json` or `<project>/.mcp.json`.
|
||||
2. Open a Code-tab session against the project.
|
||||
3. Type `/` in the prompt — verify MCP-provided tools appear in the slash menu (or invoke one directly).
|
||||
4. Separately, confirm `claude_desktop_config.json` (Chat-tab MCP) is **not** picked up by Code tab.
|
||||
|
||||
**Expected:** MCP servers in `~/.claude.json` or `.mcp.json` start when a Code session opens. Tools appear in the slash menu, calls succeed end-to-end. `claude_desktop_config.json` is separate per upstream docs.
|
||||
|
||||
**Diagnostics on failure:** Server stderr (MCP servers log to stderr), `~/.claude.json` and `.mcp.json` content, launcher log, DevTools console for MCP wire errors.
|
||||
|
||||
**References:** [MCP servers: desktop chat app vs Claude Code](https://code.claude.com/docs/en/desktop#shared-configuration), [`docs/learnings/plugin-install.md`](../../learnings/plugin-install.md)
|
||||
|
||||
**Code anchors:** `build-reference/app-extracted/.vite/build/index.js:215418` (Code-tab loads `<project>/.mcp.json` per scanned dir); `:176766` reads `~/.claude.json`; `:489098` Code-session passes `settingSources: ["user", "project", "local"]` to the agent SDK; `:130821` `claude_desktop_config.json` is the chat-tab path constant (separate userData dir at `:130829` `kee()`), confirming the two trees do not overlap.
|
||||
|
||||
## T36 — Hooks fire
|
||||
|
||||
**Severity:** Critical
|
||||
**Surface:** Hooks runtime
|
||||
**Applies to:** All rows
|
||||
**Issues:** —
|
||||
|
||||
**Steps:**
|
||||
1. Add a `SessionStart` hook in `~/.claude/settings.json` that writes a marker file.
|
||||
2. Open a new Code-tab session.
|
||||
3. Confirm the marker file exists.
|
||||
4. Repeat with `PreToolUse` / `PostToolUse` hooks. Switch transcript view to Verbose to see the hook output.
|
||||
|
||||
**Expected:** Hooks defined in `~/.claude/settings.json` execute at the documented points. Hook output is visible in Verbose transcript mode. A failing hook surfaces a clear error rather than silently breaking the session.
|
||||
|
||||
**Diagnostics on failure:** Hook script stderr, marker file presence, launcher log, settings file content, Verbose transcript output.
|
||||
|
||||
**References:** [Shared configuration](https://code.claude.com/docs/en/desktop#shared-configuration)
|
||||
|
||||
**Code anchors:** `build-reference/app-extracted/.vite/build/index.js:489098` Code-session sets `settingSources: ["user", "project", "local"]` (agent SDK reads `~/.claude/settings.json` hooks from this); `:455717` built-in `PreToolUse` hooks registry the runtime extends; `:455819` `UserPromptSubmit`; `:465680` `PostToolUse`; `:465754` `Stop`; `:493411` runtime emits `hook_started` / `hook_progress` / `hook_response` for `SessionStart` (Verbose transcript path).
|
||||
|
||||
## T37 — `CLAUDE.md` memory loads
|
||||
|
||||
**Severity:** Critical
|
||||
**Surface:** Memory / Code tab session prompt
|
||||
**Applies to:** All rows
|
||||
**Issues:** —
|
||||
|
||||
**Steps:**
|
||||
1. Confirm a project `CLAUDE.md` exists at the working folder.
|
||||
2. Confirm `~/.claude/CLAUDE.md` exists with at least one identifying token.
|
||||
3. Open a Code-tab session against the project.
|
||||
4. Ask Claude "what's in your CLAUDE.md" — verify the response matches on-disk content.
|
||||
5. Edit `CLAUDE.md`. Start a new session — verify the new content is loaded.
|
||||
|
||||
**Expected:** Project `CLAUDE.md` and `CLAUDE.local.md` at the working folder, plus `~/.claude/CLAUDE.md`, are loaded into the session's system prompt. Updates after edit on the next session start.
|
||||
|
||||
**Diagnostics on failure:** `cat CLAUDE.md` and `cat ~/.claude/CLAUDE.md` outputs, launcher log, system-prompt dump if accessible (Verbose transcript may show it).
|
||||
|
||||
**References:** [Shared configuration](https://code.claude.com/docs/en/desktop#shared-configuration)
|
||||
|
||||
**Code anchors:** `build-reference/app-extracted/.vite/build/index.js:259691` working-dir scan reads `CLAUDE.md` and `.claude/CLAUDE.md`; `:455188` global account memory `zhA(accountId, orgId)` is copied to the per-session `.claude/CLAUDE.md` at session start (`[GlobalMemory] Copied CLAUDE.md`); `:283107` `cE()` resolves `CLAUDE_CONFIG_DIR` or `~/.claude`, the dir whose `CLAUDE.md` the agent SDK loads via `settingSources: ["user", ...]` (see T36 anchor at `:489098`).
|
||||
|
||||
## S27 — Plugins install per-user, not into system paths
|
||||
|
||||
**Severity:** Should
|
||||
**Surface:** Plugin storage
|
||||
**Applies to:** All rows
|
||||
**Issues:** —
|
||||
|
||||
**Steps:**
|
||||
1. As a non-root user, install a plugin via the desktop plugin browser.
|
||||
2. Inspect `~/.claude/plugins/` for the install.
|
||||
3. Verify nothing was written under `/usr` or other system-managed trees (`find /usr -newer /tmp/marker -name '*claude*' 2>/dev/null` after `touch /tmp/marker; install plugin`).
|
||||
|
||||
**Expected:** Plugins land under `~/.claude/plugins/` (or the equivalent per-user dir). Never under `/usr`. Non-root install/enable/disable works without `sudo`.
|
||||
|
||||
**Diagnostics on failure:** `find / -name '*<plugin-name>*' 2>/dev/null`, install logs, launcher log.
|
||||
|
||||
**References:** [Install plugins](https://code.claude.com/docs/en/desktop#install-plugins)
|
||||
|
||||
**Code anchors:** `build-reference/app-extracted/.vite/build/index.js:283107` `cE()` resolves the config root to `CLAUDE_CONFIG_DIR` or `~/.claude` — never `/usr`; `:465815` `dx()` returns `<cE()>/plugins`; `:465821`/`:465824`/`:465827` `installed_plugins.json`, `known_marketplaces.json`, `marketplaces/` all sit under `dx()`. No system-path writes in the install path.
|
||||
|
||||
## S28 — Worktree creation surfaces clear error on read-only mounts
|
||||
|
||||
**Severity:** Could
|
||||
**Surface:** Worktree creation on read-only filesystem
|
||||
**Applies to:** All rows (NixOS users hit this most often)
|
||||
**Issues:** —
|
||||
|
||||
**Steps:**
|
||||
1. Place a project on a read-only mount (e.g. squashfs, NFS read-only export, `mount -o ro` bind).
|
||||
2. Open a Code-tab session against it.
|
||||
3. Try to start a parallel session that needs a worktree.
|
||||
|
||||
**Expected:** Worktree creation fails with a clear error pointing at the read-only mount. No silent loss of work, no writes to a wrong directory, no parent-repo corruption.
|
||||
|
||||
**Diagnostics on failure:** `mount | grep <project-path>`, `git worktree add` direct invocation (does it fail the same way?), launcher log, screenshot of error dialog.
|
||||
|
||||
**References:** [Work in parallel with sessions](https://code.claude.com/docs/en/desktop#work-in-parallel-with-sessions)
|
||||
|
||||
**Code anchors:** `build-reference/app-extracted/.vite/build/index.js:462841` worktree parent dir is `<repo>/.claude/worktrees` (or `chillingSlothLocation.customPath` override at `:462836`); `:462928` `git worktree add` failure path returns `null` after `R.error("Failed to create git worktree: …")`; `:462760` `Sbn()` classifies "Permission denied" / "Access is denied" / "could not lock config file" as `"permission-denied"` (the read-only-mount taxonomy bucket).
|
||||
@@ -0,0 +1,77 @@
|
||||
# Launch & Process Lifecycle
|
||||
|
||||
Tests covering app startup, the `--doctor` health check, package-format detection, and multi-instance behavior. See [`../matrix.md`](../matrix.md) for status.
|
||||
|
||||
## T01 — App launch
|
||||
|
||||
**Severity:** Smoke
|
||||
**Surface:** App startup
|
||||
**Applies to:** All rows
|
||||
**Issues:** —
|
||||
**Runner:** [`tools/test-harness/src/runners/T01_app_launch.spec.ts`](../../../tools/test-harness/src/runners/T01_app_launch.spec.ts)
|
||||
|
||||
**Steps:**
|
||||
1. From a clean session, run `claude-desktop-unofficial` (deb/rpm) or launch the AppImage.
|
||||
2. Wait up to 10 seconds.
|
||||
|
||||
**Expected:** Main window opens within ~10s. No error toast, no crash. The launcher log at `~/.cache/claude-desktop-debian/launcher.log` shows the expected backend selection (`Using X11 backend via XWayland` on Wayland sessions, or native Wayland when forced).
|
||||
|
||||
**Diagnostics on failure:** Launcher log, `--doctor` output, session env (`XDG_SESSION_TYPE`, `XDG_CURRENT_DESKTOP`), `dmesg | tail -50`, any crash report under `~/.config/Claude/logs/`.
|
||||
|
||||
**References:** —
|
||||
**Code anchors:** `scripts/launcher-common.sh:98` (X11-via-XWayland log line), `scripts/launcher-common.sh:102` (native-Wayland log line), `build-reference/app-extracted/.vite/build/index.js:524875` (`app.on("ready")` registration), `build-reference/app-extracted/.vite/build/index.js:524881-524931` (main `BrowserWindow` factory `Ori()` — `titleBarStyle`, mainWindow.js preload, initial `show`).
|
||||
|
||||
## T02 — Doctor health check
|
||||
|
||||
**Severity:** Critical
|
||||
**Surface:** CLI / `--doctor`
|
||||
**Applies to:** All rows
|
||||
**Issues:** [PR #538](https://github.com/aaddrick/claude-desktop-debian/pull/538)
|
||||
|
||||
**Steps:**
|
||||
1. Run `claude-desktop-unofficial --doctor`.
|
||||
2. Inspect exit code (`echo $?`) and stdout/stderr.
|
||||
|
||||
**Expected:** Exits 0. All checks PASS or report expected WARN. No FAIL checks. Doctor currently reports display-server, menu-bar mode, Electron path/version, Chrome sandbox perms, SingletonLock, MCP config, Node.js, desktop entry, disk space, and a Cowork section — it does **not** surface the resolved titlebar style. See also [T13](#t13--doctor-reports-correct-package-format) for the package-format detection slice.
|
||||
|
||||
**Diagnostics on failure:** Full `--doctor` output, the install path being inspected (`which claude-desktop-unofficial`), package metadata (`dpkg -S` / `rpm -qf` against the binary).
|
||||
|
||||
**References:** [PR #538](https://github.com/aaddrick/claude-desktop-debian/pull/538)
|
||||
**Code anchors:** `scripts/doctor.sh:280` (`run_doctor` entry point), `scripts/doctor.sh:301-319` (display-server check), `scripts/doctor.sh:401-417` (SingletonLock check), `scripts/doctor.sh:744-753` (exit-code summary).
|
||||
|
||||
## T13 — Doctor reports correct package format
|
||||
|
||||
**Severity:** Should
|
||||
**Surface:** CLI / `--doctor`
|
||||
**Applies to:** All rows (currently `✗` on every Fedora row — see [S05](./distribution.md#s05--doctor-recognises-dnf-installed-package-doesnt-false-flag-as-appimage))
|
||||
**Issues:** — *(no issue filed; surfaced via session-capture review)*
|
||||
|
||||
**Steps:**
|
||||
1. Install via the relevant package manager (`apt` / `dnf`) or AppImage.
|
||||
2. Run `claude-desktop-unofficial --doctor` and look for the install-method line.
|
||||
|
||||
**Expected:** Doctor identifies the install method correctly. On RPM-based distros (Fedora, Nobara) it does **not** report `not found via dpkg/rpm (AppImage?)` for a dnf install. On DEB-based distros it does not assume AppImage when dpkg returns the package metadata.
|
||||
|
||||
**Diagnostics on failure:** `dpkg -S $(which claude-desktop-unofficial)`, `rpm -qf $(which claude-desktop-unofficial)`, full `--doctor` output, the line of doctor source that decides the format.
|
||||
|
||||
**References:** [S05](./distribution.md#s05--doctor-recognises-dnf-installed-package-doesnt-false-flag-as-appimage)
|
||||
**Code anchors:** `scripts/doctor.sh:717-768` (`_doctor_check_pkg_version`) — since #711 the probe follows ownership: `rpm -qf` against the Electron binary first (only the database that installed the file can claim it), then `dpkg-query -W claude-desktop-unofficial` when rpm does not own the path. The `claude-desktop-unofficial not found via dpkg/rpm (AppImage?)` WARN fires only when neither manager owns the install.
|
||||
|
||||
## T14 — Multi-instance behavior
|
||||
|
||||
**Severity:** Critical
|
||||
**Surface:** App lifecycle
|
||||
**Applies to:** All rows
|
||||
**Issues:** [PR #536](https://github.com/aaddrick/claude-desktop-debian/pull/536) (closed, docs-only — no in-tree opt-in flag)
|
||||
|
||||
**Steps:**
|
||||
1. Launch `claude-desktop-unofficial`. Wait for the main window.
|
||||
2. Launch `claude-desktop-unofficial` again from another terminal or `.desktop` invocation.
|
||||
3. Optionally: follow the manual `--user-data-dir` recipe sketched in PR #536 (separate Electron `userData` per profile so each gets its own `SingletonLock` — note the PR was closed, the recipe is not shipped in-tree).
|
||||
|
||||
**Expected:** Second invocation focuses the existing window — no new process. The launcher's `cleanup_stale_lock` removes a `SingletonLock` whose owning PID is no longer running. With separate `--user-data-dir` per profile (manual workaround, not an in-tree feature), each profile runs an independent Electron instance.
|
||||
|
||||
**Diagnostics on failure:** `pgrep -af claude-desktop`, `ls -la ~/.config/Claude/SingletonLock`, launcher log, any "another instance is running" dialog text.
|
||||
|
||||
**References:** [PR #536](https://github.com/aaddrick/claude-desktop-debian/pull/536)
|
||||
**Code anchors:** `build-reference/app-extracted/.vite/build/index.js:525162-525173` (`requestSingleInstanceLock()` + `app.on("second-instance", ...)` — shows existing window, restores if minimized, focuses), `build-reference/app-extracted/.vite/build/index.js:525204-525207` (early-return on lost lock at `app.on("ready")`), `scripts/launcher-common.sh:187-208` (`cleanup_stale_lock` — drops a `SingletonLock` symlink whose `hostname-PID` target points at a dead PID).
|
||||
@@ -0,0 +1,282 @@
|
||||
# Platform Integration
|
||||
|
||||
Tests covering autostart, Cowork integration, WebGL graceful degradation, `.desktop`-launch env inheritance, encrypted env-var storage, the macOS/Windows-only Computer Use feature, and Dispatch session pairing. See [`../matrix.md`](../matrix.md) for status.
|
||||
|
||||
## T09 — AutoStart via XDG
|
||||
|
||||
**Severity:** Critical
|
||||
**Surface:** XDG Autostart
|
||||
**Applies to:** All rows
|
||||
**Issues:** [PR #450](https://github.com/aaddrick/claude-desktop-debian/pull/450)
|
||||
|
||||
**Steps:**
|
||||
1. In Settings, toggle "Open at Login" / "Start at boot" ON.
|
||||
2. Inspect `~/.config/autostart/` for a `.desktop` entry.
|
||||
3. Logout/login. Verify app launches automatically.
|
||||
4. Toggle OFF. Verify the autostart entry is removed.
|
||||
|
||||
**Expected:** Toggling ON creates a `~/.config/autostart/*.desktop` entry that is XDG-spec compliant (not a custom systemd unit or shell hook). After login, app launches automatically. Toggling OFF removes the entry.
|
||||
|
||||
**Diagnostics on failure:** `ls -la ~/.config/autostart/`, content of the .desktop file, `desktop-file-validate` on it, launcher log.
|
||||
|
||||
**References:** [PR #450](https://github.com/aaddrick/claude-desktop-debian/pull/450)
|
||||
|
||||
**Code anchors:**
|
||||
- `scripts/frame-fix-wrapper.js:376` — XDG Autostart shim
|
||||
intercepting `app.{get,set}LoginItemSettings` (writes/removes
|
||||
`$XDG_CONFIG_HOME/autostart/claude-desktop.desktop`).
|
||||
- `scripts/frame-fix-wrapper.js:429` — `buildAutostartContent()`
|
||||
emits the spec-compliant `[Desktop Entry]` block.
|
||||
- `build-reference/app-extracted/.vite/build/index.js:524205` —
|
||||
upstream `isStartupOnLoginEnabled` / `setStartupOnLoginEnabled` IPC
|
||||
surface that the wrapper interposes on.
|
||||
|
||||
## T10 — Cowork integration
|
||||
|
||||
**Severity:** Should
|
||||
**Surface:** Cowork tab + VM daemon
|
||||
**Applies to:** All rows
|
||||
**Issues:** [`docs/learnings/cowork-vm-daemon.md`](../../learnings/cowork-vm-daemon.md)
|
||||
|
||||
**Steps:**
|
||||
1. Sign into the app. Open the Cowork tab.
|
||||
2. Confirm Cowork-specific UI renders (ghost icon in topbar, Cowork menus).
|
||||
3. Trigger a Cowork action that needs the VM daemon.
|
||||
4. Kill the VM daemon process; verify it respawns within the documented timeout.
|
||||
|
||||
**Expected:** Cowork features render. VM daemon spawns when needed, files are visible, daemon respawns within the documented timeout if it crashes.
|
||||
|
||||
**Diagnostics on failure:** `pgrep -af cowork`, daemon logs, launcher log, the respawn-logic code path (see learnings doc).
|
||||
|
||||
**References:** [`docs/learnings/cowork-vm-daemon.md`](../../learnings/cowork-vm-daemon.md)
|
||||
|
||||
**Code anchors:**
|
||||
- `build-reference/app-extracted/.vite/build/index.js:143371` —
|
||||
upstream's Windows named-pipe path (`\\.\pipe\cowork-vm-service`)
|
||||
that `scripts/patches/cowork.sh` Patch 1 rewrites to
|
||||
`$XDG_RUNTIME_DIR/cowork-vm-service.sock`.
|
||||
- `build-reference/app-extracted/.vite/build/index.js:143453` —
|
||||
`kUe()` retry loop (5 attempts, 1 s gap) that the auto-launch
|
||||
injection from Patch 6 piggybacks on after the rewrite.
|
||||
- `scripts/patches/cowork.sh:244` — Patch 6 (auto-launch + stdio
|
||||
pipe + 10 s rate-limited respawn — issue #408).
|
||||
- `scripts/patches/cowork.sh:365` — Patch 6b (extends the
|
||||
reinstall-delete list with `sessiondata.img` / `rootfs.img.zst`
|
||||
so a wedged daemon can self-recover).
|
||||
|
||||
## T12 — WebGL warn-only
|
||||
|
||||
**Severity:** Could
|
||||
**Surface:** Chromium GPU diagnostics
|
||||
**Applies to:** All rows (especially VM rows and hybrid-GPU laptops)
|
||||
**Issues:** —
|
||||
|
||||
**Steps:**
|
||||
1. Launch the app. Open DevTools → navigate to `chrome://gpu`.
|
||||
2. Inspect WebGL1/WebGL2 status.
|
||||
3. Use the app for ~5 minutes — exercise UI, sidebar, settings.
|
||||
|
||||
**Expected:** WebGL1/2 may report as blocklisted (typical on virtio-gpu in VMs and on hybrid GPU laptops). This is informational. UI continues to render without graphical glitches; no feature is broken by the blocklist.
|
||||
|
||||
**Diagnostics on failure:** `chrome://gpu` full content, screenshot of any visual glitch, `glxinfo | head -20` (X11) or `eglinfo` (Wayland), `lspci -k | grep -A2 VGA`.
|
||||
|
||||
**References:** —
|
||||
|
||||
**Code anchors:**
|
||||
- `build-reference/app-extracted/.vite/build/index.js:524809` —
|
||||
`app.disableHardwareAcceleration()` is gated on the user-toggleable
|
||||
`isHardwareAccelerationDisabled` setting; upstream does not pass
|
||||
`--ignore-gpu-blocklist` or `--use-gl=*`, so chrome://gpu reflects
|
||||
Chromium's stock blocklist behaviour.
|
||||
- `build-reference/app-extracted/.vite/build/index.js:500571` —
|
||||
the only `webgl:!1` override is scoped to the feedback popup
|
||||
(`in-memory-feedback` partition); main UI does not disable WebGL.
|
||||
|
||||
## S17 — App launched from `.desktop` inherits shell `PATH`
|
||||
|
||||
**Severity:** Critical
|
||||
**Surface:** `.desktop`-launch env handling
|
||||
**Applies to:** All rows
|
||||
**Issues:** —
|
||||
|
||||
**Steps:**
|
||||
1. Configure `~/.bashrc` (or `~/.zshrc`) with `export PATH="$HOME/.custom-bin:$PATH"` and a custom binary in that dir.
|
||||
2. Launch the app via dmenu/krunner/GNOME Activities/Plasma launcher (i.e. **not** from a terminal).
|
||||
3. Open a Code-tab terminal pane. Run `which <custom-binary>`.
|
||||
4. Repeat for `npm`, `node`, `git`, `gh`.
|
||||
|
||||
**Expected:** Code session can find tools defined in the user's shell profile, even when the app was launched non-interactively. Either the launcher script sources the user's shell profile, or the app reads `~/.bashrc` / `~/.zshrc` to extract `PATH` the way macOS does.
|
||||
|
||||
**Diagnostics on failure:** `echo $PATH` from inside the integrated terminal, the env passed to the app process (`cat /proc/$(pgrep -f electron)/environ | tr '\0' '\n' | grep PATH`), launcher log.
|
||||
|
||||
**References:** [Local sessions](https://code.claude.com/docs/en/desktop#local-sessions), [Session not finding installed tools](https://code.claude.com/docs/en/desktop#session-not-finding-installed-tools)
|
||||
|
||||
**Code anchors:**
|
||||
- `build-reference/app-extracted/.vite/build/index.js:259300` —
|
||||
`SLr()` resolves the bundled `shell-path-worker/shellPathWorker.js`.
|
||||
- `build-reference/app-extracted/.vite/build/index.js:259349` —
|
||||
`NLr()` forks it via `utilityProcess.fork`; on success
|
||||
`FX()` (line 259311) merges the extracted env into `process.env`.
|
||||
- `build-reference/app-extracted/.vite/build/shell-path-worker/shellPathWorker.js:205`
|
||||
— `extractPathFromShell()` runs the user's login shell (`-l -i`)
|
||||
and parses the printed `$PATH` between sentinels (mac-style env
|
||||
inheritance now applied on Linux too).
|
||||
|
||||
## S18 — Local environment editor persists across reboot
|
||||
|
||||
**Severity:** Should
|
||||
**Surface:** Local env editor / encrypted store
|
||||
**Applies to:** All rows
|
||||
**Issues:** —
|
||||
|
||||
**Steps:**
|
||||
1. Open the local environment editor. Add `TEST_VAR=hello`.
|
||||
2. Restart the app — verify variable is still there.
|
||||
3. Reboot the host. Sign back in. Verify variable is still there.
|
||||
|
||||
**Expected:** Variables saved via the local environment editor (per-app, encrypted) survive a logout/login cycle and a full reboot. On Linux this implies the encrypted store is wired to libsecret / kwallet / gnome-keyring and unlocks at session start.
|
||||
|
||||
**Diagnostics on failure:** `secret-tool search` (libsecret), `kwallet5-query` (KDE), `seahorse` UI inspection (GNOME), launcher log, the env-editor IPC call.
|
||||
|
||||
**References:** [Local sessions](https://code.claude.com/docs/en/desktop#local-sessions)
|
||||
|
||||
**Code anchors:**
|
||||
- `build-reference/app-extracted/.vite/build/index.js:259251` —
|
||||
`I2t = new K_({ name: "ccd-environment-config", ... })` electron-store
|
||||
backing file (`~/.config/Claude/ccd-environment-config.json`).
|
||||
- `build-reference/app-extracted/.vite/build/index.js:259253` —
|
||||
`hLr()` writes via `safeStorage.encryptString` (libsecret on Linux).
|
||||
- `build-reference/app-extracted/.vite/build/index.js:259268` —
|
||||
`J1()` decrypts on read; bails to `{}` if `safeStorage` reports
|
||||
encryption unavailable (no keyring backend running).
|
||||
- `build-reference/app-extracted/.vite/build/index.js:70782` —
|
||||
`LocalSessionEnvironment.save` IPC entry that calls into `hLr`.
|
||||
|
||||
## S22 — Computer-use toggle is absent or visibly disabled on Linux
|
||||
|
||||
**Severity:** Should
|
||||
**Surface:** Settings → Desktop app → General
|
||||
**Applies to:** All rows
|
||||
**Issues:** —
|
||||
|
||||
**Steps:**
|
||||
1. Open Settings → Desktop app → General.
|
||||
2. Look for the "Computer use" toggle.
|
||||
|
||||
**Expected:** Toggle either does not render on Linux, or renders as a disabled control with a clear "not supported on Linux" hint. Must not appear functional and silently fail (e.g. flip on but never produce screen-control behavior).
|
||||
|
||||
**Diagnostics on failure:** Screenshot of the Settings page, DevTools inspection of the toggle DOM (is it conditionally hidden? disabled? always-rendered?), launcher log.
|
||||
|
||||
**References:** [Let Claude use your computer](https://code.claude.com/docs/en/desktop#let-claude-use-your-computer), [Dispatch and computer use](https://claude.com/blog/dispatch-and-computer-use)
|
||||
|
||||
**Code anchors:**
|
||||
- `build-reference/app-extracted/.vite/build/index.js:240557` —
|
||||
`qDA = new Set(["darwin", "win32"])` excludes Linux from the
|
||||
computer-use platform set.
|
||||
- `build-reference/app-extracted/.vite/build/index.js:241190` —
|
||||
`TF()` (the master enable check) short-circuits to `false` when
|
||||
`qDA.has(process.platform)` is false, so toggling
|
||||
`chicagoEnabled` on Linux can't activate the feature.
|
||||
- `build-reference/app-extracted/.vite/build/index.js:242387` —
|
||||
`tvr()` returns `{ status: "unsupported", reason: "Computer use
|
||||
is not available on this platform", unsupportedCode:
|
||||
"unsupported_platform" }` for the Settings UI — confirms the
|
||||
toggle should render with a platform-unavailable hint, not silent
|
||||
failure.
|
||||
|
||||
## S23 — Dispatch-spawned sessions don't soft-lock on a never-approvable computer-use prompt
|
||||
|
||||
**Severity:** Critical (for Dispatch users)
|
||||
**Surface:** Dispatch session lifecycle on Linux
|
||||
**Applies to:** All rows with Dispatch enabled
|
||||
**Issues:** —
|
||||
|
||||
**Steps:**
|
||||
1. From a paired phone, dispatch a task that would invoke computer use.
|
||||
2. Observe the Code-tab session that spawns on the desktop.
|
||||
3. Try to interact with other parts of the app.
|
||||
|
||||
**Expected:** Permission prompt times out or denies cleanly rather than hanging the session indefinitely. User can continue interacting with the rest of the app.
|
||||
|
||||
**Diagnostics on failure:** Screenshot of session state, launcher log, sidebar state (is the Dispatch session blocking the whole sidebar?), `pgrep -af claude`.
|
||||
|
||||
**References:** [Sessions from Dispatch](https://code.claude.com/docs/en/desktop#sessions-from-dispatch)
|
||||
|
||||
**Code anchors:**
|
||||
- `build-reference/app-extracted/.vite/build/index.js:512789` —
|
||||
`tool_permission_request` notification handler explicitly skips
|
||||
`toolName.startsWith("computer:")`, so the desktop never queues a
|
||||
user-facing prompt for computer-use tool calls (which couldn't run
|
||||
on Linux anyway — see S22).
|
||||
- `build-reference/app-extracted/.vite/build/index.js:241190` —
|
||||
`TF()` gates computer-use execution off entirely on Linux, so a
|
||||
Dispatch-spawned session that requests it should hit the upstream
|
||||
"Set up computer use" remote-client setup card
|
||||
(`index.js:330114`) rather than block on a desktop prompt.
|
||||
|
||||
## S24 — Dispatch-spawned Code session appears with badge and notification
|
||||
|
||||
**Severity:** Critical
|
||||
**Surface:** Dispatch handoff
|
||||
**Applies to:** All rows with Dispatch enabled
|
||||
**Issues:** —
|
||||
|
||||
**Steps:**
|
||||
1. From a paired phone, dispatch a task that routes to Code (e.g. "fix this bug").
|
||||
2. Observe the desktop sidebar.
|
||||
3. Confirm a desktop notification fires.
|
||||
4. Open the session and confirm 30-min approval expiry per upstream docs.
|
||||
|
||||
**Expected:** Dispatch task creates a sidebar entry tagged **Dispatch**, posts a desktop notification, and lands ready for review. App-permission approvals on this session expire after 30 minutes per upstream docs.
|
||||
|
||||
**Diagnostics on failure:** Screenshot of sidebar (badge present?), notification daemon state, launcher log, the Dispatch pairing config under `~/.config/Claude/`.
|
||||
|
||||
**References:** [Sessions from Dispatch](https://code.claude.com/docs/en/desktop#sessions-from-dispatch), [Dispatch and computer use](https://claude.com/blog/dispatch-and-computer-use)
|
||||
|
||||
**Code anchors:**
|
||||
- `build-reference/app-extracted/.vite/build/index.js:144561` —
|
||||
`Sd = "dispatch_child"` session-type constant.
|
||||
- `build-reference/app-extracted/.vite/build/index.js:512200` —
|
||||
`onRemoteSessionStart` IPC routes a Dispatch-initiated child
|
||||
session into the local sidebar via `dispatchOnRemoteSessionStart`.
|
||||
- `build-reference/app-extracted/.vite/build/index.js:285621` —
|
||||
`notifyDispatchParentIfNeeded()` posts the
|
||||
`Task "<title>" <state>` meta-notification when the dispatch
|
||||
child finishes (lands the result in the parent thread's
|
||||
notification queue).
|
||||
- `build-reference/app-extracted/.vite/build/index.js:285954` —
|
||||
`kind:"dispatch_child"` is the sidebar badge tag.
|
||||
|
||||
## S25 — Mobile pairing survives Linux session restart
|
||||
|
||||
**Severity:** Should
|
||||
**Surface:** Dispatch pairing persistence
|
||||
**Applies to:** All rows with Dispatch enabled
|
||||
**Issues:** —
|
||||
|
||||
**Steps:**
|
||||
1. Pair the desktop with a phone.
|
||||
2. Quit the app fully. Re-launch.
|
||||
3. Try a Dispatch task. Verify pairing still works without re-pairing.
|
||||
4. Logout/login the desktop. Re-test.
|
||||
|
||||
**Expected:** Pairing remains active across app restart and logout/login. Pairing token is stored under `~/.config/Claude/` (or wherever the secure store lives) and survives.
|
||||
|
||||
**Diagnostics on failure:** `ls -la ~/.config/Claude/`, secret-store inspection, launcher log, pairing-flow IPC.
|
||||
|
||||
**References:** [Sessions from Dispatch](https://code.claude.com/docs/en/desktop#sessions-from-dispatch)
|
||||
|
||||
**Code anchors:**
|
||||
- `build-reference/app-extracted/.vite/build/index.js:511984` —
|
||||
`ZEe = "coworkTrustedDeviceToken"` electron-store key for the
|
||||
trusted-device token.
|
||||
- `build-reference/app-extracted/.vite/build/index.js:511989` —
|
||||
`oYn()` writes the token via `safeStorage.encryptString` (libsecret
|
||||
on Linux); `aYn()` (`:512003`) decrypts on read.
|
||||
- `build-reference/app-extracted/.vite/build/index.js:512022` —
|
||||
`gYn()` re-enrolls via `POST /api/auth/trusted_devices` only when
|
||||
there's no cached token, so a successful pair survives restart.
|
||||
- `build-reference/app-extracted/.vite/build/index.js:330229` —
|
||||
`_5r = "bridge-state.json"` (per-org/account bridge state under
|
||||
`~/.config/Claude/bridge-state.json`); `JF()`/`X0A()` at `:330230`
|
||||
read/locate it.
|
||||
@@ -0,0 +1,125 @@
|
||||
# Routines & Scheduled Tasks
|
||||
|
||||
Tests covering the Routines page, scheduled task firing, catch-up runs after suspend, and the suspend-inhibit toggle. See [`../matrix.md`](../matrix.md) for status.
|
||||
|
||||
## T26 — Routines page renders
|
||||
|
||||
**Severity:** Critical
|
||||
**Surface:** Routines page
|
||||
**Applies to:** All rows
|
||||
**Issues:** —
|
||||
|
||||
**Steps:**
|
||||
1. Sign into the app, open the Code tab.
|
||||
2. Click **Routines** in the sidebar.
|
||||
3. Click **New routine** → **Local**.
|
||||
|
||||
**Expected:** Routines list opens. New-routine form shows all schedule presets (Manual, Hourly, Daily, Weekdays, Weekly), permission-mode picker, model picker, working-folder picker, and worktree toggle.
|
||||
|
||||
**Diagnostics on failure:** Screenshot of the Routines page (or the failure state), DevTools console output, launcher log, network captures of the routines API call (`mitmproxy` or DevTools network panel).
|
||||
|
||||
**References:** [Schedule recurring tasks](https://code.claude.com/docs/en/desktop-scheduled-tasks)
|
||||
|
||||
**Code anchors:** `build-reference/app-extracted/.vite/build/index.js:507710` (create payload — `permissionMode`, `model`, `userSelectedFolders`, `useWorktree`, `cronExpression`, `fireAt`); `build-reference/app-extracted/.vite/build/index.js:280299` (`@hourly: "0 * * * *"` preset)
|
||||
|
||||
**Inventory anchors:** `root.complementary.button-by-name.routines` (sidebar entry); `root.complementary.button-by-name.routines.main.region.button-by-name.new-routine` (form trigger); siblings `…button-by-name.all`, `…button-by-name.calendar` (list-view tabs). Preset list (Hourly/Daily/etc.) lives inside the New-routine modal and is not in the idle-state inventory — re-capture with the modal open to anchor.
|
||||
|
||||
## T27 — Scheduled task fires and notifies
|
||||
|
||||
**Severity:** Critical
|
||||
**Surface:** Routines runtime + libnotify
|
||||
**Applies to:** All rows
|
||||
**Issues:** —
|
||||
|
||||
**Steps:**
|
||||
1. Create a Manual task with a simple instruction (e.g. "echo hello").
|
||||
2. Click **Run now**. Observe.
|
||||
3. Optionally: create an Hourly task and verify across the next hour boundary.
|
||||
|
||||
**Expected:** A fresh session starts, appears in the **Scheduled** section of the sidebar, and posts a desktop notification when it begins. Subsequent runs respect the deterministic offset described in upstream docs.
|
||||
|
||||
**Diagnostics on failure:** Launcher log, screenshot of sidebar, `gdbus call --session --dest=org.freedesktop.Notifications --object-path=/org/freedesktop/Notifications --method=org.freedesktop.DBus.Introspectable.Introspect` (verify daemon present), task SKILL.md content under `~/.claude/scheduled-tasks/<task-name>/`.
|
||||
|
||||
**References:** [How scheduled tasks run](https://code.claude.com/docs/en/desktop-scheduled-tasks#how-scheduled-tasks-run)
|
||||
|
||||
**Code anchors:** `build-reference/app-extracted/.vite/build/index.js:282332` (`runNow(A)` — manual dispatch); `build-reference/app-extracted/.vite/build/index.js:512837` (`Rc.showNotification(...,scheduled-${l},...)` — desktop notification on completion); `build-reference/app-extracted/.vite/build/index.js:282654` (`getJitterSecondsForTask` — deterministic per-task offset via `v2r(A, n*60)`, capped by `dispatchJitterMaxMinutes` default 10)
|
||||
|
||||
## T28 — Scheduled task catch-up after suspend
|
||||
|
||||
**Severity:** Should
|
||||
**Surface:** Routines runtime / wake-from-suspend
|
||||
**Applies to:** All rows
|
||||
**Issues:** —
|
||||
|
||||
**Steps:**
|
||||
1. Create an Hourly task.
|
||||
2. Suspend the host (`systemctl suspend`).
|
||||
3. Wait past at least one hourly slot. Wake the host.
|
||||
4. Observe whether a catch-up run starts.
|
||||
|
||||
**Expected:** Exactly one catch-up run for the most recently missed slot (older missed slots are discarded). Notification announces the catch-up. Missed runs older than seven days are not retried.
|
||||
|
||||
**Diagnostics on failure:** Task history in the routines detail page, launcher log, `journalctl --since="-1 day" | grep -i suspend`.
|
||||
|
||||
**References:** [Missed runs](https://code.claude.com/docs/en/desktop-scheduled-tasks#missed-runs)
|
||||
|
||||
**Code anchors:** `build-reference/app-extracted/.vite/build/index.js:281695` (`R2r` — walks back from now, capped at `10080 * 60 * 1e3` ms = 7 days, returns at most one missed slot, dedupes by `IfA` bucket-key); `build-reference/app-extracted/.vite/build/index.js:281942` (`scheduledTaskPostWakeDelayMs` default 60000 ms — gates dispatch after `powerMonitor.on("resume")`); `build-reference/app-extracted/.vite/build/index.js:282569` (catch-up branch: `c ? 0 : this.getJitterSecondsForTask(o.id)` — missed-slot dispatch skips jitter)
|
||||
|
||||
## S19 — `CLAUDE_CONFIG_DIR` redirects scheduled-task storage
|
||||
|
||||
**Severity:** Could
|
||||
**Surface:** Config dir env var
|
||||
**Applies to:** All rows
|
||||
**Issues:** —
|
||||
|
||||
**Steps:**
|
||||
1. In the local environment editor, set `CLAUDE_CONFIG_DIR=/some/other/path`.
|
||||
2. Restart the app.
|
||||
3. Create a scheduled task. Inspect filesystem.
|
||||
|
||||
**Expected:** Tasks resolve under `${CLAUDE_CONFIG_DIR}/scheduled-tasks/<task-name>/SKILL.md` rather than `~/.claude/scheduled-tasks/`. Pre-existing tasks under the old path are not silently dropped.
|
||||
|
||||
**Diagnostics on failure:** `ls -la ${CLAUDE_CONFIG_DIR}/scheduled-tasks/` and `~/.claude/scheduled-tasks/`, launcher log, env dump.
|
||||
|
||||
**References:** [Manage scheduled tasks](https://code.claude.com/docs/en/desktop-scheduled-tasks#manage-scheduled-tasks)
|
||||
|
||||
**Code anchors:** `build-reference/app-extracted/.vite/build/index.js:283108` (`cE()` — resolves `process.env.CLAUDE_CONFIG_DIR ?? ~/.claude`, handles `~` prefix); `build-reference/app-extracted/.vite/build/index.js:283118` (`Tce()` — returns `${cE()}/scheduled-tasks`); `build-reference/app-extracted/.vite/build/index.js:488317` and `:509032` (call sites passing `taskFilesDir: Tce()` into the scheduled-tasks substrate)
|
||||
|
||||
## S20 — "Keep computer awake" inhibits idle suspend
|
||||
|
||||
**Severity:** Should
|
||||
**Surface:** Suspend inhibitor
|
||||
**Applies to:** All rows
|
||||
**Issues:** —
|
||||
|
||||
**Steps:**
|
||||
1. Open Settings → Desktop app → General → "Keep computer awake". Toggle ON.
|
||||
2. Run `systemd-inhibit --list`. Look for a Claude-owned lock with `idle:sleep` what.
|
||||
3. Toggle OFF. Re-run `systemd-inhibit --list` — lock should be gone.
|
||||
|
||||
**Expected:** Toggling ON registers `systemd-inhibit --what=idle:sleep` (or the `org.freedesktop.PowerManagement.Inhibit` DBus call). Toggling OFF releases the lock.
|
||||
|
||||
**Diagnostics on failure:** `systemd-inhibit --list` before/after, `busctl --user tree org.freedesktop.PowerManagement` (if the path uses that backend), launcher log, the relevant settings IPC call.
|
||||
|
||||
**References:** [How scheduled tasks run](https://code.claude.com/docs/en/desktop-scheduled-tasks#how-scheduled-tasks-run)
|
||||
|
||||
**Code anchors:** `build-reference/app-extracted/.vite/build/index.js:241897` (`hA.powerSaveBlocker.start("prevent-app-suspension")` — single block call, ref-counted by `PhA` Set); `build-reference/app-extracted/.vite/build/index.js:241905` (`hA.powerSaveBlocker.stop(BP)` when last claim drops); `build-reference/app-extracted/.vite/build/index.js:241909` (settings binding: `PHe = "keepAwakeEnabled"`); `build-reference/app-extracted/.vite/build/index.js:241914` (`vy.on("keepAwakeEnabled", YHe)` — toggle observer)
|
||||
|
||||
## S21 — Lid-close still suspends per OS policy
|
||||
|
||||
**Severity:** Critical
|
||||
**Surface:** Suspend inhibitor scope
|
||||
**Applies to:** All rows (laptop hosts)
|
||||
**Issues:** —
|
||||
|
||||
**Steps:**
|
||||
1. With "Keep computer awake" ON, close the laptop lid.
|
||||
2. Observe whether the machine suspends.
|
||||
|
||||
**Expected:** Machine still suspends per logind's `HandleLidSwitch=suspend`. The inhibit lock taken in [S20](#s20--keep-computer-awake-inhibits-idle-suspend) targets `idle:sleep`, not `handle-lid-switch`, so lid-close behavior is unaffected.
|
||||
|
||||
**Diagnostics on failure:** `loginctl show-session --property=HandleLidSwitch`, `journalctl --since="-5 minutes"`, the actual `--what=` flags on the Claude-owned inhibitor.
|
||||
|
||||
**References:** [How scheduled tasks run](https://code.claude.com/docs/en/desktop-scheduled-tasks#how-scheduled-tasks-run)
|
||||
|
||||
**Code anchors:** `build-reference/app-extracted/.vite/build/index.js:241897` (only `"prevent-app-suspension"` is passed to `powerSaveBlocker.start` — Electron maps this to `idle:sleep`); no `handle-lid-switch` / `HandleLidSwitch` token anywhere in `index.js` (verified via `grep -nE 'lid|HandleLidSwitch|handle-lid' index.js`)
|
||||
@@ -0,0 +1,363 @@
|
||||
# Shortcuts & Input
|
||||
|
||||
Tests covering URL handling, the Quick Entry global shortcut, and DE-specific shortcut/input failure modes. See [`../matrix.md`](../matrix.md) for status.
|
||||
|
||||
## T05 — `claude://` URL handler opens links in-app
|
||||
|
||||
**Severity:** Smoke
|
||||
**Surface:** URL handler / xdg-open
|
||||
**Applies to:** All rows
|
||||
**Issues:** —
|
||||
|
||||
**Steps:**
|
||||
1. With Claude Desktop running, in another app run `xdg-open 'claude://chat/new?q=hello'` (or click a `claude://` link in a browser/terminal).
|
||||
2. Observe.
|
||||
|
||||
**Expected:** Link is delivered to the running Claude Desktop process — no new browser tab, no crash, no error dialog. (Upstream's `claudeURLHandler` only accepts the `claude:`, `claude-dev:`, `claude-nest:`, `claude-nest-dev:`, `claude-nest-prod:` schemes; bare `https://claude.ai/...` clicks route through the user's default browser, not Claude Desktop. The `.desktop` file registers `MimeType=x-scheme-handler/claude` only, matching the upstream contract.)
|
||||
|
||||
**Diagnostics on failure:** `xdg-mime query default x-scheme-handler/claude`, the registered `.desktop` file content, launcher log, app crash report (if any), `coredumpctl list claude-desktop` (if subprocess died — see [S06](#s06--url-handler-doesnt-segfault-on-native-wayland)).
|
||||
|
||||
**References:** upstream `index.js:495996-496009` (`bEe()` protocol filter), `index.js:524819` (`setAsDefaultProtocolClient("claude")`), `index.js:525140-525148` (macOS `open-url`), `index.js:525162-525172` (Linux/Win `second-instance` argv path), project `scripts/packaging/{deb,rpm,appimage}.sh` (MimeType registration).
|
||||
**Code anchors:** build-reference/app-extracted/.vite/build/index.js:495996, 524819, 525140, 525162
|
||||
|
||||
## T06 — Quick Entry global shortcut (unfocused)
|
||||
|
||||
**Severity:** Critical
|
||||
**Surface:** Global shortcut / Electron globalShortcut
|
||||
**Applies to:** All rows
|
||||
**Issues:** [#404](https://github.com/aaddrick/claude-desktop-debian/issues/404), [#393](https://github.com/aaddrick/claude-desktop-debian/issues/393), [PR #406](https://github.com/aaddrick/claude-desktop-debian/pull/406), [PR #102](https://github.com/aaddrick/claude-desktop-debian/pull/102), [PR #153](https://github.com/aaddrick/claude-desktop-debian/pull/153)
|
||||
|
||||
**Steps:**
|
||||
1. Launch app, focus another application (browser, terminal).
|
||||
2. Press the configured Quick Entry shortcut (default `Ctrl+Alt+Space`).
|
||||
3. Type a prompt and submit.
|
||||
4. Repeat from a different virtual desktop / workspace.
|
||||
|
||||
**Expected:** Quick Entry prompt opens regardless of focused app or workspace. Shortcut is globally registered, not focus-bound. Submitting creates a new session and shows it in the main window.
|
||||
|
||||
**Diagnostics on failure:** Launcher log (look for `Using X11 backend via XWayland (for global hotkey support)` or portal-shortcut markers), `XDG_SESSION_TYPE`, `XDG_CURRENT_DESKTOP`, output of `gdbus call --session --dest=org.freedesktop.portal.Desktop --object-path=/org/freedesktop/portal/desktop --method=org.freedesktop.DBus.Introspectable.Introspect`, the active patch set in `scripts/patches/`.
|
||||
|
||||
**References:** [#404](https://github.com/aaddrick/claude-desktop-debian/issues/404), [#393](https://github.com/aaddrick/claude-desktop-debian/issues/393), [PR #406](https://github.com/aaddrick/claude-desktop-debian/pull/406)
|
||||
**Code anchors:** build-reference/app-extracted/.vite/build/index.js:499376 (`ort` default accelerator: `"Ctrl+Alt+Space"` non-mac, `"Alt+Space"` on mac), 499416 (`globalShortcut.register`), 525287-525290 (Quick Entry trigger callback registered against `Pw.QUICK_ENTRY`).
|
||||
|
||||
## S06 — URL handler doesn't segfault on native Wayland
|
||||
|
||||
**Severity:** Critical (for wlroots rows)
|
||||
**Surface:** URL handler subprocess
|
||||
**Applies to:** Sway, Niri, Hypr-O, Hypr-N (any native-Wayland session)
|
||||
**Issues:** —
|
||||
|
||||
**Steps:**
|
||||
1. Launch the app on a native Wayland session (no XWayland forcing).
|
||||
2. From another app, click a `claude.ai` link or run `xdg-open https://claude.ai/...`.
|
||||
|
||||
**Expected:** Link opens in-app cleanly. No `Failed to connect to Wayland display` errors followed by a SIGSEGV from the URL handler subprocess.
|
||||
|
||||
**Diagnostics on failure:** `coredumpctl info claude-desktop`, `WAYLAND_DISPLAY` env in the subprocess (if capturable via `strace -f -e execve`), launcher log, full env dump.
|
||||
|
||||
**Currently:** Sway capture shows `Failed to connect to Wayland display: No such file or directory (2)` followed by `Segmentation fault` from the URL handler subprocess. The main app process keeps running; the URL handler dies. Not yet filed.
|
||||
|
||||
**References:** —
|
||||
**Code anchors:** build-reference/app-extracted/.vite/build/index.js:495996 (`bEe()` URL handler), 525140-525148 (`open-url` macOS), 525162-525172 (`second-instance` argv path on Linux); project `scripts/launcher-common.sh:96-99` (`--ozone-platform=x11` default), `scripts/launcher-common.sh:41-44` (Niri force-native-Wayland).
|
||||
|
||||
## S07 — `CLAUDE_USE_WAYLAND=1` opt-in path works without crashing
|
||||
|
||||
**Severity:** Should
|
||||
**Surface:** Native Wayland mode
|
||||
**Applies to:** Sway, Niri, Hypr-O, Hypr-N
|
||||
**Issues:** [PR #228](https://github.com/aaddrick/claude-desktop-debian/pull/228), [PR #232](https://github.com/aaddrick/claude-desktop-debian/pull/232)
|
||||
|
||||
**Steps:**
|
||||
1. Set `CLAUDE_USE_WAYLAND=1`. Launch the app.
|
||||
2. Use the app for ~5 minutes — open chats, switch tabs, exercise basic flows.
|
||||
|
||||
**Expected:** App forces native Wayland (no XWayland), continues to render and respond. Previously broken paths in PR #228 still hold.
|
||||
|
||||
**Diagnostics on failure:** Launcher log (confirm Wayland mode active), `--doctor`, full env dump, screenshot of any crash dialog.
|
||||
|
||||
**References:** [PR #228](https://github.com/aaddrick/claude-desktop-debian/pull/228), [PR #232](https://github.com/aaddrick/claude-desktop-debian/pull/232)
|
||||
**Code anchors:** project `scripts/launcher-common.sh:28-29` (`CLAUDE_USE_WAYLAND=1` opt-out of XWayland), 100-111 (native-Wayland Electron flags: `UseOzonePlatform,WaylandWindowDecorations`, `--ozone-platform=wayland`, `--enable-wayland-ime`, `--wayland-text-input-version=3`, `GDK_BACKEND=wayland`).
|
||||
|
||||
## S09 — Quick window patch runs only on KDE (post-#406 gate)
|
||||
|
||||
**Severity:** Critical
|
||||
**Surface:** Patch gate
|
||||
**Applies to:** All rows (verifies the gate, not the feature)
|
||||
**Issues:** [PR #406](https://github.com/aaddrick/claude-desktop-debian/pull/406), [#393](https://github.com/aaddrick/claude-desktop-debian/issues/393)
|
||||
|
||||
**Steps:**
|
||||
1. On a KDE row, launch the app. Inspect launcher log for quick-window-patch markers.
|
||||
2. On a non-KDE row, launch the app. Inspect launcher log — the markers should be absent.
|
||||
|
||||
**Expected:** On KDE sessions the quick-window patch is applied (Quick Entry uses the patched code path). On non-KDE sessions the patch is **not** applied, preventing the [#393](https://github.com/aaddrick/claude-desktop-debian/issues/393) regression on GNOME etc.
|
||||
|
||||
**Diagnostics on failure:** Launcher log, `XDG_CURRENT_DESKTOP`, the patch-gate code path in `scripts/patches/`.
|
||||
|
||||
**References:** [PR #406](https://github.com/aaddrick/claude-desktop-debian/pull/406), [#393](https://github.com/aaddrick/claude-desktop-debian/issues/393)
|
||||
**Code anchors:** project `scripts/patches/quick-window.sh:32-42` (KDE-gated `blur()` insertion), 115-125 (KDE-gated focus/visibility check replacement); upstream sites the patch rewrites are around `index.js:515374-515471` (Quick Entry popup construction + handlers).
|
||||
|
||||
## S10 — Quick Entry popup is transparent (no opaque square frame)
|
||||
|
||||
**Severity:** Should
|
||||
**Surface:** Quick Entry window (KDE Wayland)
|
||||
**Applies to:** KDE-W
|
||||
**Issues:** [#370](https://github.com/aaddrick/claude-desktop-debian/issues/370), [#223](https://github.com/aaddrick/claude-desktop-debian/issues/223), [PR #244](https://github.com/aaddrick/claude-desktop-debian/pull/244)
|
||||
|
||||
**Steps:**
|
||||
1. On KDE Plasma Wayland, invoke Quick Entry.
|
||||
2. Observe the popup background.
|
||||
|
||||
**Expected:** Quick Entry popup renders with a transparent background — no opaque square frame visible behind the rounded prompt UI.
|
||||
|
||||
**Diagnostics on failure:** Screenshot, KDE compositor settings (`kwriteconfig5 --read kwinrc Compositing/Backend`), launcher log, BrowserWindow construction args.
|
||||
|
||||
**References:** [#370](https://github.com/aaddrick/claude-desktop-debian/issues/370) (current open report), [#223](https://github.com/aaddrick/claude-desktop-debian/issues/223) (closed predecessor), [PR #244](https://github.com/aaddrick/claude-desktop-debian/pull/244)
|
||||
**Code anchors:** build-reference/app-extracted/.vite/build/index.js:515380 (`transparent: !0`), 515383 (`backgroundColor: "#00000000"`), 515381 (`frame: !1`), 515377 (`skipTaskbar: !0`).
|
||||
|
||||
## S11 — Quick Entry shortcut fires from any focus on Wayland (mutter XWayland key-grab)
|
||||
|
||||
**Severity:** Critical (for GNOME users)
|
||||
**Surface:** Global shortcut on GNOME mutter
|
||||
**Applies to:** GNOME, Ubu
|
||||
**Issues:** [#404](https://github.com/aaddrick/claude-desktop-debian/issues/404), [PR #406](https://github.com/aaddrick/claude-desktop-debian/pull/406)
|
||||
|
||||
**Steps:**
|
||||
1. On GNOME/mutter Wayland, launch the app.
|
||||
2. Focus another application; press the Quick Entry shortcut.
|
||||
3. Repeat from another virtual desktop.
|
||||
|
||||
**Expected:** Shortcut fires regardless of focused app or workspace.
|
||||
|
||||
**Diagnostics on failure:** Launcher log (note `Using X11 backend via XWayland (for global hotkey support)`), `XDG_CURRENT_DESKTOP`, mutter version (`gnome-shell --version`), the active patch set.
|
||||
|
||||
**Currently:** Fedora 43 GNOME Wayland reproduces [#404](https://github.com/aaddrick/claude-desktop-debian/issues/404) on the default (XWayland) path — mutter doesn't honour the XWayland-side key grab, so the shortcut is focus-bound. The fix is opt-in: launch with `CLAUDE_USE_WAYLAND=1` to use native Wayland + the XDG GlobalShortcuts portal (see [S12](#s12----enable-featuresglobalshortcutsportal-launcher-flag-wired-up-for-gnome-wayland)), which mutter honours on **GNOME ≤ 49**. GNOME Wayland is not auto-flipped (rendering risk; GNOME 50 portal route is a no-op upstream). Re-verify on a GNOME Wayland host.
|
||||
|
||||
**References:** [#404](https://github.com/aaddrick/claude-desktop-debian/issues/404), [PR #406](https://github.com/aaddrick/claude-desktop-debian/pull/406)
|
||||
**Code anchors:** project `scripts/launcher-common.sh` `detect_display_backend` (native Wayland opt-in via `CLAUDE_USE_WAYLAND=1`; only Niri auto-forced) and `build_electron_args` (native-Wayland `GlobalShortcutsPortal` feature); upstream `index.js:499416` (`globalShortcut.register`).
|
||||
|
||||
## S12 — `--enable-features=GlobalShortcutsPortal` launcher flag wired up for GNOME Wayland
|
||||
|
||||
**Severity:** Critical
|
||||
**Surface:** Launcher flag wiring
|
||||
**Applies to:** GNOME, Ubu (any GNOME Wayland)
|
||||
**Issues:** [#404](https://github.com/aaddrick/claude-desktop-debian/issues/404)
|
||||
|
||||
**Steps:**
|
||||
1. On GNOME Wayland, launch the app with `CLAUDE_USE_WAYLAND=1`.
|
||||
2. Inspect the Electron command line via `pgrep -af claude-desktop` — look for `--enable-features=GlobalShortcutsPortal`.
|
||||
3. Test Quick Entry shortcut from unfocused state (see [T06](#t06--quick-entry-global-shortcut-unfocused)).
|
||||
|
||||
**Expected:** With `CLAUDE_USE_WAYLAND=1`, the launcher uses native Wayland and emits `GlobalShortcutsPortal` inside a single merged `--enable-features=…` switch, routing global shortcuts through XDG Desktop Portal instead of X11 key grabs ([#404](https://github.com/aaddrick/claude-desktop-debian/issues/404); GNOME is not auto-flipped — the portal route is opt-in). Note the flag is comma-joined with `UseOzonePlatform,WaylandWindowDecorations`, so match the `GlobalShortcutsPortal` subkey, not an exact `--enable-features=GlobalShortcutsPortal` token.
|
||||
|
||||
**Diagnostics on failure:** Full process argv (`cat /proc/$(pgrep -f 'app\.asar')/cmdline | tr '\0' ' '`), launcher log (expect `Using native Wayland backend (global shortcuts via XDG portal)`), `XDG_CURRENT_DESKTOP`.
|
||||
|
||||
**Currently:** Launcher side implemented — `build_electron_args` adds `GlobalShortcutsPortal` to the native-Wayland feature set (opt-in via `CLAUDE_USE_WAYLAND=1`; GNOME is not auto-flipped). The flag is verified present in argv on that opt-in path (this case launches with `CLAUDE_USE_WAYLAND=1` and passes). Functional global-from-unfocused works on **GNOME ≤ 49** (first registration shows a one-time portal permission dialog). On **GNOME 50 / xdg-desktop-portal ≥ 1.20** it does not yet fire: Electron/Chromium never performs the portal's host `Registry.Register` app-id handshake, so `globalShortcut.register()` returns `false` and the portal is never contacted. Proven via D-Bus capture + a Python portal client; filed upstream as [electron/electron#51875](https://github.com/electron/electron/issues/51875).
|
||||
|
||||
**References:** [#404](https://github.com/aaddrick/claude-desktop-debian/issues/404)
|
||||
**Code anchors:** project `scripts/launcher-common.sh` `detect_display_backend` (tri-state `CLAUDE_USE_WAYLAND` override) + `build_electron_args` (merged `enable_features` array). See [`wayland-global-shortcuts-portal.md`](../../learnings/wayland-global-shortcuts-portal.md).
|
||||
|
||||
## S14 — Global shortcuts via XDG portal work on Niri
|
||||
|
||||
**Severity:** Critical (for Niri users)
|
||||
**Surface:** XDG Desktop Portal `BindShortcuts`
|
||||
**Applies to:** Niri
|
||||
**Issues:** —
|
||||
|
||||
**Steps:**
|
||||
1. On Niri, launch the app (the launcher special-cases Niri to native Wayland + portal).
|
||||
2. Configure the Quick Entry shortcut.
|
||||
3. Observe portal interaction in launcher log.
|
||||
|
||||
**Expected:** `BindShortcuts` succeeds. Configured Quick Entry shortcut is registered and fires.
|
||||
|
||||
**Diagnostics on failure:** Launcher log capture of the `BindShortcuts` call, `busctl --user tree org.freedesktop.portal.Desktop`, Niri version, full env.
|
||||
|
||||
**Currently:** `Failed to call BindShortcuts (error code 5)` — portal global shortcuts fail on Niri. Different root cause from [#404](https://github.com/aaddrick/claude-desktop-debian/issues/404), same user-visible symptom (Quick Entry shortcut doesn't fire). Not yet filed.
|
||||
|
||||
**References:** —
|
||||
**Code anchors:** project `scripts/launcher-common.sh` `detect_display_backend` (Niri force-native-Wayland branch) + `build_electron_args` (native-Wayland `GlobalShortcutsPortal` feature, which Niri now also receives); upstream `index.js:499416` (`globalShortcut.register`, which on native Wayland routes through Electron's `xdg-desktop-portal` `BindShortcuts` path inside Chromium). wlroots' portal ships no GlobalShortcuts backend, so `BindShortcuts` still fails until that lands — this stays a known-failing detector.
|
||||
|
||||
## S29 — Quick Entry popup is created lazily on first shortcut press (closed-to-tray sanity)
|
||||
|
||||
**Severity:** Critical
|
||||
**Surface:** Quick Entry popup lifecycle
|
||||
**Applies to:** All rows
|
||||
**Issues:** [#393](https://github.com/aaddrick/claude-desktop-debian/issues/393)
|
||||
|
||||
**Steps:**
|
||||
1. Launch app, wait for main window to appear, hide-to-tray (close via X — see [T08](./tray-and-window-chrome.md#t08--hide-to-tray-on-close)).
|
||||
2. Confirm no Claude window is mapped (e.g. `wmctrl -l | grep -i claude` returns empty on X11; `swaymsg -t get_tree` for Wayland equivalents).
|
||||
3. Press the Quick Entry shortcut.
|
||||
4. Type `hello`, press Enter.
|
||||
|
||||
**Expected:** Popup appears even though no Claude window was mapped before the keypress. Upstream constructs the popup `BrowserWindow` lazily on first shortcut invocation (`if (!Ko || ...) Ko = new BrowserWindow(...)` near `index.js:515375`), so the popup does not need a pre-existing main window. New chat session is created and reachable on submit.
|
||||
|
||||
**Diagnostics on failure:** Launcher log, `~/.config/Claude/logs/`, `XDG_CURRENT_DESKTOP`, screenshot of empty desktop after shortcut press.
|
||||
|
||||
**References:** [#393](https://github.com/aaddrick/claude-desktop-debian/issues/393), upstream `index.js:515375-515397`
|
||||
**Code anchors:** build-reference/app-extracted/.vite/build/index.js:515374 (`if (!Ko ...) Ko = new BrowserWindow(...)` lazy construction guard), 515394 (`preload: ".vite/build/quickWindow.js"`), 515438 (`Ko.loadFile(".vite/renderer/quick_window/quick-window.html")`).
|
||||
|
||||
## S30 — Quick Entry shortcut becomes a no-op after full app exit
|
||||
|
||||
**Severity:** Should
|
||||
**Surface:** Global shortcut unregistration
|
||||
**Applies to:** All rows
|
||||
**Issues:** —
|
||||
|
||||
**Steps:**
|
||||
1. Launch app. Confirm Quick Entry shortcut works (popup opens).
|
||||
2. Quit Claude Desktop fully via tray → Quit (or `pkill -f app.asar`). Confirm no `electron` processes for the app remain.
|
||||
3. Press the Quick Entry shortcut.
|
||||
|
||||
**Expected:** No popup appears. No error dialog. No zombie process. Electron unregisters the global shortcut on app exit; the shortcut becomes a system-level no-op.
|
||||
|
||||
**Diagnostics on failure:** `pgrep -af app.asar` output, `journalctl --user -e -n 100`, OS-level shortcut bindings (`gsettings list-recursively | grep -i shortcut`).
|
||||
|
||||
**References:** upstream `index.js:499416` (registration site)
|
||||
**Code anchors:** build-reference/app-extracted/.vite/build/index.js:499398-499428 (`nG()` register/unregister wrapper — passing `null` accelerator unregisters), 499416 (`hA.globalShortcut.register`), 499403 (`hA.globalShortcut.unregister`).
|
||||
|
||||
## S31 — Quick Entry submit makes the new chat reachable from any main-window state
|
||||
|
||||
**Severity:** Critical
|
||||
**Surface:** Submit → main window show
|
||||
**Applies to:** All rows
|
||||
**Issues:** [#393](https://github.com/aaddrick/claude-desktop-debian/issues/393), [PR #406](https://github.com/aaddrick/claude-desktop-debian/pull/406)
|
||||
|
||||
**Steps:**
|
||||
1. For each main-window state: (a) visible-and-focused, (b) minimized, (c) hidden-to-tray, (d) on a different workspace, (e) closed via X (project's hide-to-tray override).
|
||||
2. Set the state, then invoke Quick Entry, type `hello`, submit.
|
||||
3. Record what happens to the main window: auto-restored, requires tray click, came to current workspace, stayed on its own workspace.
|
||||
|
||||
**Expected:** The new chat session is **reachable** from each starting state. Acceptance is "user can reach the new chat" — not "main window auto-restored." Upstream calls `mainWin.show()` + `mainWin.focus()` only (`index.js:515566, 515599`), with no `restore()`, no `setVisibleOnAllWorkspaces()`, no `moveTop()`. Whether `show()` un-minimizes or migrates workspaces is purely compositor-dependent. The failure case is "new chat created but the user has no way to surface it" — that's a regression. Anything that reaches the chat (even via a tray click) is upstream-acceptable.
|
||||
|
||||
**Diagnostics on failure:** `~/.config/Claude/logs/`, screenshot at each state, output of `wmctrl -l` (X11) or `swaymsg -t get_tree` (sway), launcher log.
|
||||
|
||||
**Currently:** On non-KDE rows, the post-#406 KDE-only patch gate leaves the upstream code path (`isFocused()` short-circuit) active. Andrej730's #393 GNOME repro shows the stale-`isFocused()` bug can still suppress `show()` in tray-only state. See [S32](#s32--quick-entry-submit-on-gnome-mutter-doesnt-trip-electron-stale-isfocused).
|
||||
|
||||
**References:** [#393](https://github.com/aaddrick/claude-desktop-debian/issues/393), upstream `index.js:515566, 515599, 105164-171`
|
||||
**Code anchors:** build-reference/app-extracted/.vite/build/index.js:515567 (`h1() || ut.show(), ut.focus()` in `gHn()` existing-chat path), 515598-515599 (`h1() || ut.show(), ut.focus()` in `ynt()` new-chat path), 105164-105171 (`h1()` returns `ut.isFocused() || mainView.webContents.isFocused()`).
|
||||
|
||||
## S32 — Quick Entry submit on GNOME mutter doesn't trip Electron stale-`isFocused()`
|
||||
|
||||
**Severity:** Critical (for GNOME users)
|
||||
**Surface:** Electron `BrowserWindow.isFocused()` on Linux
|
||||
**Applies to:** GNOME, Ubu
|
||||
**Issues:** [#393](https://github.com/aaddrick/claude-desktop-debian/issues/393)
|
||||
|
||||
**Steps:**
|
||||
1. On GNOME Wayland, launch the app, then close to tray.
|
||||
2. Confirm the app is in tray-only state (no window mapped, no Dash entry, no taskbar entry).
|
||||
3. Invoke Quick Entry, type `hello`, submit.
|
||||
4. Repeat after re-pinning the app to the Dash and reproducing the tray-only state from there.
|
||||
|
||||
**Expected:** Submit produces a reachable new chat session in both Dash-pinned and not-pinned cases. **The Dash distinction is empirical, not code-driven** — upstream has no notion of Dash presence. The underlying failure mode is Electron's `BrowserWindow.isFocused()` returning stale-true on Linux mutter, which causes upstream's `h1() || ut.show()` short-circuit (`index.js:515566`) to skip `show()`. Andrej730 traced this on #393.
|
||||
|
||||
**Diagnostics on failure:** Bundled `index.js` h1() body (extract via `npx asar extract`); add temporary logging in `h1()` per Andrej730's diff in #393 if reproducing locally; `gnome-shell --version`; `~/.config/Claude/logs/`.
|
||||
|
||||
**Currently:** Open. The KDE-only gate from PR #406 leaves this path unfixed on GNOME. Resolution requires either (a) widening the patch to all DEs by dropping the `isFocused()` fallback in the patched code, or (b) waiting for an upstream Electron fix to `isFocused()` on Linux.
|
||||
|
||||
**References:** [#393](https://github.com/aaddrick/claude-desktop-debian/issues/393) (Andrej730's diagnosis with `eU()` logging output)
|
||||
**Code anchors:** build-reference/app-extracted/.vite/build/index.js:105164-105171 (`h1()` body — the exact short-circuit Andrej730 instrumented), 515567 + 515598 (the two `h1() || ut.show()` call sites the suppression hits).
|
||||
|
||||
## S33 — Quick Entry transparent rendering tracked against bundled Electron version
|
||||
|
||||
**Severity:** Should
|
||||
**Surface:** Bundled Electron version
|
||||
**Applies to:** All rows (relevant where #370 reproduces)
|
||||
**Issues:** [#370](https://github.com/aaddrick/claude-desktop-debian/issues/370)
|
||||
|
||||
**Steps:**
|
||||
1. After install, capture the Electron version bundled with the app: extract `app.asar.unpacked` and run the bundled Electron with `--version`, or read it from the bundled binary's metadata.
|
||||
2. Record the version in [`../matrix.md`](../matrix.md) per row, alongside the [S10](#s10--quick-entry-popup-is-transparent-no-opaque-square-frame) status.
|
||||
|
||||
**Expected:** Captured version is recorded. If the version is **41.0.4 through 41.x.y** and S10 fails, the upstream electron/electron#50213 regression hypothesis (per @noctuum's bisect on #370) holds and the issue is blocked on upstream. If the version is **41.0.3 or earlier** and S10 fails, the bisect is wrong — investigate. If the version is **a later release that includes a CSD-rendering fix** and S10 still fails, the upstream-regression hypothesis is also wrong.
|
||||
|
||||
**Diagnostics on failure:** Output of the version capture command, link to electron/electron#50213, the BrowserWindow construction args from the bundled `index.js`.
|
||||
|
||||
**Currently:** Per @noctuum's bisect, 41.0.4 introduced the regression. No upstream fix shipped as of last check.
|
||||
|
||||
**References:** [#370](https://github.com/aaddrick/claude-desktop-debian/issues/370), upstream `index.js:515380, 515383` (already sets `transparent: true` and `backgroundColor: "#00000000"`)
|
||||
**Code anchors:** build-reference/app-extracted/.vite/build/index.js:515380 (`transparent: !0`), 515383 (`backgroundColor: "#00000000"`), 515374-515397 (popup `BrowserWindow` construction args block, including `frame: !1`, `hasShadow: Zr`, `type: Zr ? "panel" : void 0`).
|
||||
|
||||
## S34 — Quick Entry shortcut focuses fullscreen main window instead of showing popup
|
||||
|
||||
**Severity:** Should
|
||||
**Surface:** Shortcut behavior on fullscreen main
|
||||
**Applies to:** All rows
|
||||
**Issues:** —
|
||||
|
||||
**Steps:**
|
||||
1. Launch app. Put the main window into native fullscreen (F11 or platform equivalent).
|
||||
2. Press the Quick Entry shortcut.
|
||||
|
||||
**Expected:** Popup does **not** appear. Main window receives focus and `ide()` runs (upstream behavior at `index.js:525287-525290`). This is intentional upstream UX — assumes the user wants to interact with the existing fullscreen Claude rather than overlay a popup on it.
|
||||
|
||||
**Diagnostics on failure:** Screenshot, launcher log, confirm fullscreen state via `wmctrl -l -G` / Wayland equivalent.
|
||||
|
||||
**References:** upstream `index.js:525287-525290`
|
||||
**Code anchors:** build-reference/app-extracted/.vite/build/index.js:525287-525290 (Quick Entry callback: `ut && !ut.isDestroyed() && ut.isFullScreen() ? (ut.focus(), ide()) : Yri()`), 515234-515241 (`ide()` — `show()` + `focus()` + `webContents.send(TEe.cmdK)` for the cmd-K dispatch).
|
||||
|
||||
## S35 — Quick Entry popup position is persisted across invocations and across app restarts
|
||||
|
||||
**Severity:** Should
|
||||
**Surface:** Popup placement memory
|
||||
**Applies to:** All rows
|
||||
**Issues:** —
|
||||
|
||||
**Steps:**
|
||||
1. Launch app. Invoke Quick Entry. Note the popup position (record monitor + coordinates if possible — e.g. `xdotool getactivewindow getwindowgeometry` on X11).
|
||||
2. Dismiss (Esc). Re-invoke. Position should be unchanged across this dismiss/re-invoke cycle.
|
||||
3. Quit Claude Desktop fully (`pkill -f app.asar`). Re-launch. Invoke Quick Entry.
|
||||
4. Confirm position matches the pre-restart capture.
|
||||
|
||||
**Expected:** Popup reappears at the same monitor + position before and after a full app restart. Upstream persists position via `an.get("quickWindowPosition")` (`index.js:515491-515526`), keyed on monitor label + resolution.
|
||||
|
||||
**Diagnostics on failure:** Captured coordinates pre/post-restart, content of any persisted settings file (project's settings storage location varies by OS).
|
||||
|
||||
**References:** upstream `index.js:515491-515526`
|
||||
**Code anchors:** build-reference/app-extracted/.vite/build/index.js:515444-515461 (`Ko.on("hide", …)` persists `quickWindowPosition` via `an.set(...)`), 515491-515521 (`aHn()` resolves saved monitor by `label + bounds.width + bounds.height`, falling back to label-only or proportional placement), 515489 (`Ko.setPosition(...)` after show).
|
||||
|
||||
## S36 — Quick Entry popup falls back to primary display when saved monitor is gone
|
||||
|
||||
**Severity:** Smoke
|
||||
**Surface:** Multi-monitor placement
|
||||
**Applies to:** All rows with a multi-monitor capable host
|
||||
**Issues:** —
|
||||
|
||||
**Steps:**
|
||||
1. **Multi-monitor required.** With an external monitor connected, invoke Quick Entry on the external monitor. Trigger position persistence (per [S35](#s35--quick-entry-popup-position-is-persisted-across-invocations-and-across-app-restarts)).
|
||||
2. Disconnect the external monitor (libvirt: detach the second display device; bare metal: unplug).
|
||||
3. Invoke Quick Entry.
|
||||
|
||||
**Expected:** Popup appears on the primary display, not at off-screen coordinates. Upstream falls back to `cHn()` when the saved monitor is no longer present (`index.js:515502`).
|
||||
|
||||
**Diagnostics on failure:** `xrandr` (X11) / `wlr-randr` (wlroots) output before and after disconnect, captured popup coordinates, screenshot.
|
||||
|
||||
**Skip when:** Single-monitor VM or host. Skip with `-` in the dashboard.
|
||||
|
||||
**References:** upstream `index.js:515502`
|
||||
**Code anchors:** build-reference/app-extracted/.vite/build/index.js:515502 (`return cHn();` early-return when no saved position), 515523-515527 (`cHn()` centres popup on `screen.getPrimaryDisplay()` workArea), 515514-515515 (`label`-only match fallback before primary-display fallback).
|
||||
|
||||
## S37 — Quick Entry popup remains functional after main window destroy
|
||||
|
||||
**Severity:** Should
|
||||
**Surface:** Popup lifecycle independence from main window
|
||||
**Applies to:** All rows (where reachable)
|
||||
**Issues:** —
|
||||
|
||||
**Steps:**
|
||||
1. Launch app, focus main window.
|
||||
2. **Trigger main window destroy without quitting the app.** On this project, the X-button hide-to-tray override means the standard close path does **not** destroy `ut`. Reach the destroy path via one of:
|
||||
- DevTools console on the main window: `require('electron').remote.getCurrentWindow().destroy()` (if `remote` is exposed; not guaranteed).
|
||||
- A debug build with the hide-to-tray override removed.
|
||||
- Skip and mark `-` if unreachable.
|
||||
3. After destroy: invoke Quick Entry, type `hello`, submit.
|
||||
|
||||
**Expected:** Popup appears and accepts input. Upstream's `!ut || ut.isDestroyed()` guard at `index.js:515595` skips the show/focus block without crashing. The new chat is created in the data layer; whether it has a window to surface in is a separate question (upstream contract is "popup itself does not crash").
|
||||
|
||||
**Diagnostics on failure:** Crash dump, `~/.config/Claude/logs/`, sequence of actions taken to reach the destroy path.
|
||||
|
||||
**Currently:** Likely unreachable on Linux without a debug build, due to project's hide-to-tray override of the X button. Mark `-` (N/A) on rows where the destroy path can't be triggered.
|
||||
|
||||
**References:** upstream `index.js:515595`
|
||||
**Code anchors:** build-reference/app-extracted/.vite/build/index.js:515595-515602 (`setTimeout(() => { !ut || ut.isDestroyed() || (h1() || ut.show(), ut.focus(), Qe == null || Qe.webContents.focus(), iri()); }, 0)` — guard skips show/focus block on destroy without throwing); 515547 (companion guard in `nde()` chat-id submit path: `else if (ut && !ut.isDestroyed())`).
|
||||
@@ -0,0 +1,123 @@
|
||||
# Tray & Window Chrome
|
||||
|
||||
Tests covering the tray icon, OS-native window decorations, the hybrid in-app topbar (PR #538), and hide-to-tray on close. See [`../matrix.md`](../matrix.md) for status.
|
||||
|
||||
## T03 — Tray icon present
|
||||
|
||||
**Severity:** Smoke
|
||||
**Surface:** System tray / SNI
|
||||
**Applies to:** All rows
|
||||
**Issues:** —
|
||||
**Runner:** [`tools/test-harness/src/runners/T03_tray_icon_present.spec.ts`](../../../tools/test-harness/src/runners/T03_tray_icon_present.spec.ts) — registration only (left-click toggle + theme-switch in-place rebuild are v2)
|
||||
|
||||
**Steps:**
|
||||
1. Launch the app. Wait a few seconds.
|
||||
2. Locate the tray icon in the system tray / status area.
|
||||
3. Right-click → confirm standard menu (Show, Quit, etc.). Left-click → confirm window toggles.
|
||||
4. Switch the system theme between light and dark; observe the tray icon update.
|
||||
|
||||
**Expected:** Tray icon appears within a few seconds of app launch. Right-click exposes the standard menu. Left-click toggles main window visibility. Theme changes update the icon in place without spawning a duplicate.
|
||||
|
||||
**Diagnostics on failure:** `RegisteredStatusNotifierItems` from the SNI watcher (see [runbook](../runbook.md#tray--dbus-state-kde)), the tray daemon process for the DE (Plasma's `plasmashell`, GNOME's `gnome-shell` + AppIndicator extension state, etc.), launcher log.
|
||||
|
||||
**References:** [`docs/learnings/tray-rebuild-race.md`](../../learnings/tray-rebuild-race.md)
|
||||
**Code anchors:** `build-reference/app-extracted/.vite/build/index.js:525627` (`vy.on("menuBarEnabled", () => { Sde() })` — re-entry), `index.js:525631-525673` (`function Sde()` — tray construction), `index.js:525645` (`new hA.Tray(hA.nativeImage.createFromPath(t))`), `index.js:525646` (`qh.on("click", () => void Yri())` — left-click handler), `index.js:525653` (`qh.setContextMenu(mnt())` — Linux right-click via context menu), `index.js:515150-515169` (`function mnt()` — Show App + Quit menu items), `index.js:525623` (`hA.nativeTheme.on("updated", ...)` — theme-change re-entry).
|
||||
|
||||
## T04 — Window decorations draw
|
||||
|
||||
**Severity:** Smoke
|
||||
**Surface:** Window chrome
|
||||
**Applies to:** All rows
|
||||
**Issues:** [PR #127](https://github.com/aaddrick/claude-desktop-debian/pull/127), [PR #538](https://github.com/aaddrick/claude-desktop-debian/pull/538)
|
||||
**Runner:** [`tools/test-harness/src/runners/T04_window_decorations.spec.ts`](../../../tools/test-harness/src/runners/T04_window_decorations.spec.ts) — X11 / XWayland only (checks `_NET_FRAME_EXTENTS`); native-Wayland window-state queries are deferred
|
||||
|
||||
**Steps:**
|
||||
1. Launch the app.
|
||||
2. Confirm window has a working OS-native frame: close, minimize, maximize render and respond.
|
||||
3. Resize via window edges.
|
||||
|
||||
**Expected:** Frame is drawn by the DE/compositor (not the app). All controls render and respond. Resize works.
|
||||
|
||||
**Diagnostics on failure:** `xprop _NET_WM_WINDOW_TYPE` (X11) / `swaymsg -t get_tree` or compositor-equivalent (Wayland), launcher log line for `frame:` setting, screenshot.
|
||||
|
||||
**References:** [PR #127](https://github.com/aaddrick/claude-desktop-debian/pull/127), [PR #538](https://github.com/aaddrick/claude-desktop-debian/pull/538) (hybrid mode keeps native frame), [`docs/learnings/linux-topbar-shim.md`](../../learnings/linux-topbar-shim.md)
|
||||
**Code anchors:** Upstream factory passes `titleBarStyle: "hidden"` and `titleBarOverlay: ys` (Windows-only flag) to `BrowserWindow` at `build-reference/app-extracted/.vite/build/index.js:524892-524909` (`Ori()`). On Linux the wrapper at `scripts/frame-fix-wrapper.js:122` overrides to `options.frame = true` and at `scripts/frame-fix-wrapper.js:129-130` deletes the macOS-only `titleBarStyle` / `titleBarOverlay` so the DE draws the frame. (Hybrid-mode plumbing — `CLAUDE_TITLEBAR_STYLE` resolution and the `native`/`hybrid`/`hidden` branches — lives on `main` per PR #538; the docs/compat-matrix branch's `frame-fix-wrapper.js` carries only the unconditional `frame:true` patch, which is sufficient for T04's "frame draws" assertion.)
|
||||
|
||||
## T07 — In-app topbar renders + clickable
|
||||
|
||||
**Severity:** Smoke
|
||||
**Surface:** In-app topbar (hybrid mode)
|
||||
**Applies to:** All rows on PR #538 builds
|
||||
**Issues:** [PR #538](https://github.com/aaddrick/claude-desktop-debian/pull/538), [PR #127](https://github.com/aaddrick/claude-desktop-debian/pull/127)
|
||||
|
||||
**Steps:**
|
||||
1. Launch a PR #538 build.
|
||||
2. Observe the in-app topbar below the OS frame.
|
||||
3. Click each of: hamburger menu, sidebar toggle, search, back, forward, Cowork ghost.
|
||||
|
||||
**Expected:** All five topbar buttons render below the native frame. Each responds to mouse clicks (no implicit drag region capturing the events). If any single button fails to render or click, the test is `✗` — note which one in the linked issue.
|
||||
|
||||
**Diagnostics on failure:** Screenshot, env (`OZONE_PLATFORM`, `ELECTRON_OZONE_PLATFORM_HINT`, `GDK_BACKEND`, `QT_QPA_PLATFORM`, `MOZ_ENABLE_WAYLAND`, `SDL_VIDEODRIVER`), launcher log, DevTools `document.querySelector('.topbar')` HTML if accessible.
|
||||
|
||||
**References:** [PR #538](https://github.com/aaddrick/claude-desktop-debian/pull/538), [PR #127](https://github.com/aaddrick/claude-desktop-debian/pull/127), [`docs/learnings/linux-topbar-shim.md`](../../learnings/linux-topbar-shim.md)
|
||||
**Code anchors:** UA-spoof shim source `scripts/wco-shim.js` (lines 1-30 module guard / `CLAUDE_TITLEBAR_STYLE != 'native'` gate, lines 184-191 `navigator.userAgent` redefinition matching `/(win32|win64|windows|wince)/i`, lines 52-53 `CONTROLS_WIDTH=140` / `TITLEBAR_HEIGHT=40`); injection orchestrator `scripts/patches/wco-shim.sh` (`patch_wco_shim()` prepends shim source to `mainView.js`); hybrid-mode wrapper branch `scripts/frame-fix-wrapper.js:62-70` (`VALID_TITLEBAR_STYLES`, default `hybrid`) and `:152-240` (per-mode `frame` / `titleBarStyle` handling).
|
||||
|
||||
## T08 — Hide-to-tray on close
|
||||
|
||||
**Severity:** Smoke
|
||||
**Surface:** Window lifecycle
|
||||
**Applies to:** All rows
|
||||
**Issues:** [PR #451](https://github.com/aaddrick/claude-desktop-debian/pull/451)
|
||||
|
||||
**Steps:**
|
||||
1. Launch the app. Click the window close (X) button.
|
||||
2. Confirm app process is still running (`pgrep -af claude-desktop`).
|
||||
3. Click the tray icon (or invoke Quick Entry) → window restores.
|
||||
4. Quit explicitly via tray menu or `Ctrl+Q`.
|
||||
|
||||
**Expected:** Close button hides main window to tray, doesn't quit. App keeps running. Tray-click restores. Explicit Quit ends the process.
|
||||
|
||||
**Diagnostics on failure:** `pgrep -af claude-desktop` after close, launcher log, screenshot of any dialog.
|
||||
|
||||
**References:** [PR #451](https://github.com/aaddrick/claude-desktop-debian/pull/451)
|
||||
**Code anchors:** Upstream Linux quit-on-last-close at `build-reference/app-extracted/.vite/build/index.js:525550-525552` (`hA.app.on("window-all-closed", () => { Zr || Ap() })` — `Zr` is darwin). Wrapper interception at `scripts/frame-fix-wrapper.js:178-185` (`this.on('close', e => { if (!result.app._quittingIntentionally && !this.isDestroyed()) { e.preventDefault(); this.hide() } })`) and `scripts/frame-fix-wrapper.js:370-374` (`app.on('before-quit', () => { app._quittingIntentionally = true })` — arms the bypass for tray-Quit / `Ctrl+Q` / SIGTERM). `CLOSE_TO_TRAY` gate (Linux + `CLAUDE_QUIT_ON_CLOSE !== '1'`) at `scripts/frame-fix-wrapper.js:49-51`. Tray Quit menu item `mnt()` `click: rde` at `index.js:515166`; `function rde()` at `index.js:515306-515308` calls `Ap(!1)`.
|
||||
|
||||
## S08 — Tray icon doesn't duplicate after `nativeTheme` update
|
||||
|
||||
**Severity:** Should
|
||||
**Surface:** Tray (KDE)
|
||||
**Applies to:** KDE-W, KDE-X
|
||||
**Issues:** [`docs/learnings/tray-rebuild-race.md`](../../learnings/tray-rebuild-race.md)
|
||||
|
||||
**Steps:**
|
||||
1. Launch the app on KDE.
|
||||
2. Toggle system theme (light ↔ dark).
|
||||
3. Observe the tray for ~10 seconds.
|
||||
|
||||
**Expected:** Tray icon updates in place via `setImage` + `setContextMenu`. SNI service stays registered — no de-register / re-register churn that would leave a duplicate icon visible until KDE garbage-collects.
|
||||
|
||||
**Diagnostics on failure:** SNI watcher state before/after theme switch (see [runbook](../runbook.md#tray--dbus-state-kde)), launcher log, `journalctl --user -u plasma-plasmashell -n 50`.
|
||||
|
||||
**References:** [`docs/learnings/tray-rebuild-race.md`](../../learnings/tray-rebuild-race.md). Mitigated upstream — the in-place fast-path is the current behavior.
|
||||
**Code anchors:** Upstream destroy+recreate slow-path at `build-reference/app-extracted/.vite/build/index.js:525643` (`qh && (qh.destroy(), (qh = null))`) followed immediately by `new hA.Tray(...)` at `:525645` and `setContextMenu(mnt())` at `:525653` — the SNI re-register that races on KDE. Fast-path injection in `scripts/patches/tray.sh` `patch_tray_inplace_update()` (lines 95-231): extracts `tray_var` / `menu_func` / `path_var` / `enabled_var` dynamically, then injects `if (TRAY && ENABLED !== false) { TRAY.setImage(EL.nativeImage.createFromPath(PATH)); process.platform !== "darwin" && TRAY.setContextMenu(MENU()); return }` before the destroy block. Idempotency marker at `tray.sh:174-180` keys on the post-rename `setImage(...nativeImage.createFromPath(PATH_VAR))` literal. Mutex + 250 ms DBus settle delay (the prior mitigation, kept for the legitimate slow-path entries) at `tray.sh:48-60`.
|
||||
|
||||
## S13 — Hybrid topbar shim survives Omarchy's Ozone-Wayland env exports
|
||||
|
||||
**Severity:** Critical (for Omarchy users)
|
||||
**Surface:** In-app topbar (hybrid mode) under Omarchy env
|
||||
**Applies to:** Hypr-O
|
||||
**Issues:** [PR #538](https://github.com/aaddrick/claude-desktop-debian/pull/538)
|
||||
|
||||
**Steps:**
|
||||
1. On OmarchyOS, export Omarchy's session-wide env (`ELECTRON_OZONE_PLATFORM_HINT=wayland`, `OZONE_PLATFORM=wayland`, `GDK_BACKEND=wayland,x11,*`, `QT_QPA_PLATFORM=wayland;xcb`, `MOZ_ENABLE_WAYLAND=1`, `SDL_VIDEODRIVER=wayland,x11`).
|
||||
2. Launch a PR #538 build.
|
||||
3. Click each of the five topbar buttons.
|
||||
|
||||
**Expected:** The hybrid-mode topbar shim (`scripts/wco-shim.js`) loads in time to spoof the UA before claude.ai's `isWindows()` check fires. All five topbar buttons render and click.
|
||||
|
||||
**Diagnostics on failure:** Full session env, launcher log, `--doctor`, screenshot, video (per @lukedev45's bug report on PR #538), DevTools console for shim-load errors.
|
||||
|
||||
**Currently:** Reproduces partial render on OmarchyOS Hyprland per [@lukedev45](https://github.com/lukedev45)'s video on [PR #538](https://github.com/aaddrick/claude-desktop-debian/pull/538). @aaddrick attempted local repro on KDE Plasma + Wayland with the same env vars and could not reproduce; root cause TBD pending diagnostic capture from a broken run.
|
||||
|
||||
**References:** [PR #538](https://github.com/aaddrick/claude-desktop-debian/pull/538), [`docs/learnings/linux-topbar-shim.md`](../../learnings/linux-topbar-shim.md)
|
||||
**Code anchors:** Shim is inlined at the top of `mainView.js` (the BrowserView preload), not loaded via `require` — see the rationale at `scripts/patches/wco-shim.sh:23-40` ("Sandboxed preloads can only require a fixed allowlist of modules…"). The injection prepends `scripts/wco-shim.js` source at the start of `app.asar.contents/.vite/build/mainView.js` so the UA override fires before the bundle's `isWindows()` regex (`/(win32|win64|windows|wince)/i`) ever runs in the page main world (`scripts/wco-shim.js:184-191`). The shim's IIFE no-ops on non-Linux at `wco-shim.js:29` and on `CLAUDE_TITLEBAR_STYLE === 'native'` at `wco-shim.js:30-32`, so the only env-export interaction with `OZONE_PLATFORM` etc. is via Chromium's own platform plumbing — none of those exports are read by the shim itself, which makes the partial-render repro on Omarchy mysterious to static analysis.
|
||||
Reference in New Issue
Block a user