Large desktop installs can accumulate huge JSONL transcripts, and the sidebar session list previously loaded each requested transcript into memory on cache misses. The main branch cache from #651 handles repeated hot refreshes, so this change keeps that cache and replaces cache-miss list metadata extraction with a sequential streaming summary scan for paginated files only. It also makes Windows sidecar shutdown prefer taskkill /T so stale child processes are less likely to survive app stop paths.
Constraint: Must preserve main's short session-list cache from #651 while reducing cache-miss memory growth.
Rejected: Rely only on the #651 cache | cache expiry, first load, and pagination still hit full JSONL reads.
Rejected: Add a persistent summary index | larger persistence migration risk than needed for this issue.
Confidence: medium
Scope-risk: moderate
Directive: Do not replace the streaming scanner with full readJsonlFile calls without re-running large-transcript pressure tests.
Tested: bun test src/server/__tests__/sessions.test.ts
Tested: bun run check:server
Tested: bun run check:native
Tested: bun run check:desktop
Tested: synthetic pressure test with 140 sessions x 1200 JSONL entries showed lower RSS growth than main baseline.
Not-tested: Windows live taskkill /T process-tree cleanup.
Wire createPicker into the preview-agent IIFE: enter/exit picker via host messages, bind DOM mousemove/click (capture phase) to picker hover/select, and on click emit a selection event carrying ElementMetadata + annotated screenshot. Route the selection event in previewEvents.ts through buildSelectionComposerText into queueComposerPrefill with the screenshot attachment.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Tauri's desktop webview injects window.confirm through the dialog confirm command, but the default desktop capability only allowed the message dialog command. Windows release builds could therefore reject confirm at ACL time even though the browser-facing code path looked valid in local web development.
Constraint: Tauri plugin-dialog 2.7 still exposes window.confirm as plugin:dialog|confirm in the injected webview shim.
Rejected: Grant dialog:default | broader than the specific confirm compatibility gap.
Confidence: high
Scope-risk: narrow
Directive: Keep confirm permission covered while the desktop webview exposes browser confirm shims.
Tested: cd desktop && bun run test -- --run src/__tests__/tauriCapabilities.test.ts
Tested: bun run check:desktop
Tested: bun run check:native
Not-tested: Windows release package manual smoke
Prepare the desktop release metadata, concise release notes, and the final terminal help polish for the 0.3.1 release. The release note groups the post-0.3.0 work by user-facing area instead of listing every commit, and the desktop version metadata is aligned for the tag-triggered packaging workflow.
Constraint: GitHub Release body is sourced from release-notes/v0.3.1.md in the tagged commit
Rejected: List every post-0.3.0 commit in the release note | too noisy for this patch release
Confidence: high
Scope-risk: narrow
Tested: cd desktop && bun run test -- src/pages/TerminalSettings.test.tsx --run
Tested: bun run check:desktop
Tested: bun run check:native
Tested: bun run verify (passed=8 failed=0 skipped=2)
Not-tested: Live provider release gate
Desktop portable mode depends on CLI-driven installs using the same filesystem root as the app. The installed terminal launcher now carries CLAUDE_CONFIG_DIR into macOS/Linux shell invocations and uses a Windows cmd wrapper so plugin, skill, and MCP operations do not fall back to the native home config. Moved portable bundles also rebase cached plugin install paths when the cache exists under the current config root.
Constraint: Desktop portable bundles are file-system based and must survive zip/unzip relocation.
Rejected: Copy the sidecar binary directly into user bin | it cannot inject the selected portable config directory for future CLI installs.
Rejected: Rewrite plugin install paths unconditionally | missing cache directories should remain visible as broken state instead of being silently retargeted.
Confidence: high
Scope-risk: moderate
Directive: Keep desktop launcher wrappers as env-carrying sh/cmd files; do not revert to raw sidecar copies without portable install verification.
Tested: bun test src/server/__tests__/desktop-cli-launcher.test.ts src/utils/plugins/installedPluginsManager.test.ts
Tested: cargo test portable --manifest-path desktop/src-tauri/Cargo.toml
Tested: bun run check:server
Tested: bun run check:native
Tested: macOS launcher fixture plus Computer Use Finder verification of portable marker output.
Not-tested: Windows physical desktop execution; Windows wrapper behavior is covered by unit test only.
Bump version from 0.2.9 to 0.3.0 across desktop/package.json,
tauri.conf.json, and Cargo.toml. Add v0.3.0 release notes covering
desktop long-session performance, streaming tool previews,
AskUserQuestion reliability, multi-client streaming, and H5 network
fixes.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This records the v0.2.9 release notes and aligns desktop package,
Tauri, and Cargo metadata so the release script can create the final
annotated tag after manual validation.
Constraint: Release tag creation is intentionally deferred for manual smoke validation.
Rejected: Run scripts/release.ts now | it would create the release commit and annotated tag before manual review.
Confidence: high
Scope-risk: narrow
Directive: Do not create v0.2.9 tag until the manual release check is complete.
Tested: bun run scripts/release.ts 0.2.9 --dry
Tested: bun run check:native
Not-tested: Full bun run verify and live ChatGPT Official OAuth smoke
The desktop release workflow expects app version files, Cargo.lock, and release-notes/vX.Y.Z.md to agree with the tag. Bump the desktop package and Tauri metadata to 0.2.8 and add the release note that will be used as the GitHub Release body.
Constraint: The release pipeline reads release-notes/v0.2.8.md from the tagged commit.
Confidence: high
Scope-risk: narrow
Directive: Keep desktop/package.json, Cargo.toml, tauri.conf.json, Cargo.lock, and release-notes/vX.Y.Z.md aligned before tagging.
Tested: Not rerun for this metadata-only release prep commit; previous push gate passed for the workflow fix immediately before this commit.
Not-tested: Full release workflow and packaged artifact smoke after tagging.
The previous portable-mode settings were hard to discover and mostly
explained through environment variables. Users could not pick a target
folder from the desktop UI or clearly understand which config directory
would become active after switching modes.
This moves the control to a lower-priority storage section, makes the
active directory source explicit, supports choosing a portable data
folder, and prepares the desktop app for a controlled restart so the
new storage location takes effect.
Constraint: Directory picking and relaunch require the Tauri desktop runtime
Rejected: Keep environment-variable-only setup | users could not discover or validate the target path from the app
Confidence: high
Scope-risk: moderate
Tested: cd desktop && bun run test -- generalSettings settingsStore
Tested: bun run check:desktop
Tested: bun run check:native
Tested: bun run check:coverage
Tested: bun run verify
Tested: Maintainer manual desktop UI test
Not-tested: Windows relaunch path beyond existing native coverage
Remote main carries portable-mode, legacy Windows workdir recovery, and Feishu path-safety fixes while local main carries terminal shell, update proxy, slash-command, prompt-draft, AskUserQuestion, background-work, and shell-env changes. This merge keeps both lines by layering portable Bash-path defaults underneath the desktop terminal shell preference and preserving both update-proxy and app-mode settings state.
Constraint: Local main and origin/main diverged after v0.2.7 and both lines contain release-relevant desktop/runtime fixes
Rejected: Prefer either side's terminal settings wholesale | would drop either Windows portable Bash support or explicit desktop startup-shell support
Confidence: medium
Scope-risk: moderate
Directive: Keep portable Bash path as the system-default terminal fallback; explicit desktop startup-shell settings should continue to override it
Tested: cd desktop && bun run test -- --run src/pages/TerminalSettings.test.tsx src/stores/settingsStore.test.ts
Tested: cd desktop/src-tauri && cargo test terminal -- --nocapture
Tested: bun test src/server/__tests__/sessions.test.ts -t stale worktree
Tested: bun run check:desktop
Tested: bun run check:server
Tested: bun run check:native
Not-tested: Manual Windows packaged-app terminal/portable smoke
Desktop update downloads currently depend on the updater HTTP stack and can miss the proxy users already rely on for GitHub access. The change enables OS proxy discovery in the native updater client and adds a narrow manual proxy fallback scoped only to update checks and package downloads.
Constraint: Tauri updater carries the proxy from check through download, so changing proxy settings after a check must discard the pending update and re-check before install
Rejected: Reuse provider proxy settings | provider traffic and updater traffic have different scope and persistence risks
Confidence: high
Scope-risk: moderate
Directive: Keep update proxy settings scoped to app updates; do not mix them with model/provider proxy configuration without a separate migration decision
Tested: cd desktop && bun run test -- --run src/__tests__/generalSettings.test.tsx src/stores/updateStore.test.ts src/stores/settingsStore.test.ts src-tauri/tauri-config.test.ts
Tested: bun run check:desktop
Tested: bun run check:native
Not-tested: Full coverage gate intentionally skipped after maintainer said it was not needed
The desktop terminal defaulted to COMSPEC on Windows, which commonly lands on cmd.exe and makes the settings terminal feel broken for users who expect PowerShell. This change adds a desktop-only terminal startup-shell setting in Settings, keeps the existing system default untouched unless the user opts in, and resolves the selected shell inside the Tauri PTY spawn path so docked terminals, terminal tabs, and the settings terminal stay aligned.
Constraint: Existing terminal sessions and non-Windows defaults must keep their current behavior unless a Windows user explicitly changes the setting
Rejected: Reuse settings.defaultShell | that setting already controls CLI ! commands and would couple unrelated shell semantics
Rejected: Flip Windows default to pwsh automatically | too risky for users whose current COMSPEC-based terminal already works
Confidence: high
Scope-risk: moderate
Reversibility: clean
Directive: Keep desktop terminal shell selection separate from CLI shell routing unless both paths are redesigned together
Tested: cd desktop && bun run test -- src/stores/settingsStore.test.ts src/pages/TerminalSettings.test.tsx
Tested: cd desktop/src-tauri && cargo test desktop_terminal_shell_resolution -- --nocapture
Tested: bun run check:desktop
Tested: bun run check:native
Not-tested: Real interactive spawn on a physical Windows machine
The contributor PR adds useful Windows terminal and portable mode support, but it also reintroduced an older General settings zoom block and left the new native settings paths without enough regression coverage. This commit keeps the feature direction intact while removing the duplicate UI, making invalid bash paths fail at save time, and covering the portable cache and app-mode paths with focused tests.
Constraint: This commit lands directly on the contributor PR branch to avoid a long review-comment loop.
Rejected: Ask the contributor to rework the PR from scratch | the remaining issues are narrow and maintainable by us.
Confidence: high
Scope-risk: moderate
Directive: Keep future portable-mode changes covered at the native boundary and the desktop store boundary.
Tested: cd desktop && bun run test src/pages/TerminalSettings.test.tsx src/__tests__/generalSettings.test.tsx src/stores/settingsStore.test.ts
Tested: bun test src/utils/__tests__/cachePaths.test.ts
Tested: cd desktop/src-tauri && cargo test
Tested: cd desktop && bun run lint
Tested: cd desktop/src-tauri && cargo check
Tested: bun run check:server
Tested: bun run check:desktop
Not-tested: Manual Windows packaged-app portable-mode smoke; to be covered before a future release.
The release branch has moved substantially past v0.2.6, so this records the desktop version bump and the release note that will be reviewed before the tag is created. The note groups the large post-v0.2.6 range by user-facing areas instead of replaying the raw commit list.
Constraint: The user wants to push the release-prep commit for manual GitHub development testing before any tag is created.
Rejected: Run scripts/release.ts directly | it would create the release commit and annotated tag before review.
Confidence: high
Scope-risk: narrow
Directive: Do not create v0.2.7 tag until manual GitHub validation is complete.
Tested: bun run scripts/release.ts 0.2.7 --dry
Tested: git diff --check
Not-tested: Full release gate or tag-triggered release workflow.
This brings the desktop memory worktree onto local main after main advanced with opener, IM, zoom, and autonomous goal work. The conflict resolution keeps both the selected-chat reference imports and memory event settings entrypoint in MessageList, and keeps both open-targets and memory API routes in the server router.
Constraint: main and feat/desktop-memory-surface diverged across desktop chat and server routing.
Constraint: desktop Vitest runs src-tauri tests under Vitest, so the Tauri config test cannot import bun:test.
Rejected: Fast-forward merge | main carried newer local commits not present on the memory branch.
Confidence: high
Scope-risk: moderate
Directive: Keep chat selection references, memory cards, open-target routes, and memory routes together when touching these files.
Tested: bun run check:desktop
Tested: bun run check:server
Tauri WebView was allowed to call the desktop sidecar API, but the CSP still blocked image loads from that same local server, so extracted IDE icons degraded to the generic code glyph in packaged builds. macOS detection also trusted command shims before app bundles, which let stale JetBrains Toolbox scripts keep removed IDEs visible.
Constraint: Opener icons are served by the per-run desktop sidecar on localhost or 127.0.0.1
Rejected: Bundle a fixed static icon set | the product should use detected installed application icons across platforms
Rejected: Trust macOS command shims for detection | stale shims survive app removal and make the menu lie
Confidence: high
Scope-risk: narrow
Directive: Keep macOS IDE detection anchored to real app bundles before accepting command shims
Tested: bun test src/server/__tests__/open-target-service.test.ts src/server/__tests__/open-target-api.test.ts desktop/src-tauri/tauri-config.test.ts
Tested: cd desktop && bun run test -- src/api/client.test.ts src/api/openTargets.test.ts src/stores/openTargetStore.test.ts src/components/layout/OpenProjectMenu.test.tsx src/components/layout/TabBar.test.tsx
Tested: cd desktop && bun run lint
Bring the detached worktree implementation for issue #407 back into
local main while preserving a merge boundary for review and rollback.
Constraint: Local main already contains post-release-boundary desktop fixes
Confidence: high
Scope-risk: narrow
Tested: bun run verify in detached worktree before merge
Not-tested: Full gate on local main before this merge commit
The desktop shell needed predictable zoom controls across macOS,
Windows, and Linux without depending on browser defaults. This adds a
small app zoom controller that persists a bounded zoom factor, maps the
IDE-style primary-modifier shortcuts, and uses native Tauri webview zoom
when available with a browser fallback for H5/dev runs.
Constraint: Issue #407 requested IDE-style zoom shortcuts across macOS, Windows, and Linux
Rejected: Enable Tauri built-in zoom hotkeys only | it would not cover browser/H5 fallback or app-owned persistence consistently
Confidence: high
Scope-risk: narrow
Directive: Keep app zoom bounded and validated before applying persisted localStorage values
Tested: bun run verify; browser smoke on http://127.0.0.1:45679/ with Meta+= and Meta+0
Not-tested: Manual Windows/Linux desktop runtime smoke
Superpowers can trigger plan approval or browser confirm flows inside the desktop shell. Tauri's dialog plugin shims window.confirm through the message command, but the desktop capability only allowed file open/save dialogs, so Windows rejected confirm with an ACL error and left the flow blocked.
Constraint: Tauri plugin-dialog 2.7 routes alert/confirm through the message permission.
Rejected: Grant dialog:default | broader than needed for this bugfix.
Confidence: high
Scope-risk: narrow
Directive: Keep dialog message permission whenever browser confirm or alert shims are available in desktop.
Tested: cd desktop && bun run test -- --run src/__tests__/tauriCapabilities.test.ts
Tested: bun run check:native
Tested: bun run check:desktop
The release needs a curated GitHub Release body and matching desktop/Tauri version metadata before the annotated tag can trigger the remote packaging workflow. The notes summarize the post-v0.2.5 H5 access recovery, sidebar batch management, file mention search alignment, and desktop polish while keeping generated dependency versions unchanged.
Constraint: GitHub Release body is sourced from release-notes/v0.2.6.md in the tagged commit
Constraint: Desktop package, Tauri config, Cargo.toml, and Cargo.lock must agree on the release version
Rejected: Run the release script directly after manual edits | its default commit message does not capture the release decision context
Confidence: high
Scope-risk: narrow
Directive: Keep future release notes aligned with the tagged version file before pushing tags
Tested: git diff --check
Tested: bun run scripts/release.ts 0.2.6 --dry
Not-tested: Full release gate; this commit only prepares release metadata after markdown review
The generated logo asset carried both an opaque square canvas and an inner rounded tile, so the desktop empty state and sidebar rendered a visible nested background. Rebuilt the canonical app icon with transparent outside corners, one white rounded badge, and a centered mark, then regenerated the Tauri icon set and docs raster assets from that source.
Constraint: Existing desktop views consume /app-icon.png directly with no wrapper background to remove.
Rejected: Add CSS masking around each img usage | would leave native app icons and docs assets with the same nested canvas problem.
Confidence: high
Scope-risk: narrow
Directive: Keep desktop/src-tauri/app-icon.png as the canonical 1024 RGBA source before regenerating platform icons.
Tested: cd desktop && bun run build; npm run --loglevel=error docs:build; git diff --check; sips alpha and size checks; iconutil icns size ladder; Chrome DevTools light and forced-dark screenshots.
Not-tested: full bun run verify gate, per prior instruction to skip local gate for this logo pass.
The desktop app and documentation need to present the new logo consistently, so the canonical 1024px source icon now feeds the Tauri icon family, desktop public assets, README images, and VitePress brand imagery.
Constraint: Tauri bundle icons are generated assets and must be refreshed from the source icon rather than relying on README or public image replacement alone
Rejected: Rename logo paths | existing README, desktop, and docs references can keep stable paths and pick up the new files directly
Confidence: high
Scope-risk: moderate
Directive: Regenerate desktop/src-tauri/icons whenever desktop/src-tauri/app-icon.png changes
Tested: cd desktop && bun run build; npm run --loglevel=error docs:build; git diff --check; iconutil expanded icon.icns size ladder
Not-tested: full local quality gate per request
This release packages the emergency H5 token pause so upgraded users can resume desktop and browser chat without generating or carrying a token. The release notes document the temporary open-access behavior and the verification run used before tagging.
Constraint: v0.2.4 restored startup but token auth can still break chat flows for upgraded users
Rejected: Wait for a full token-auth redesign | users are actively blocked and H5 auth is not critical right now
Confidence: high
Scope-risk: narrow
Directive: Restore H5 token controls only with migration coverage and browser chat E2E
Tested: bun run scripts/release.ts 0.2.5 --dry
Tested: bun run scripts/release.ts 0.2.5
Tested: bun test src/server/__tests__/h5-access-auth.test.ts src/server/middleware/cors.test.ts
Tested: bun run check:server
Tested: bun run check:desktop
This release moves the verified desktop H5-auth regression fix into the versioned artifact pipeline so blocked v0.2.3 users can receive a GitHub-built replacement quickly.
Constraint: GitHub Release body is sourced from release-notes/v0.2.4.md in the tagged commit.
Constraint: Release workflow requires the app, Tauri, Cargo, and lockfile versions to match the tag.
Rejected: Ship only the hotfix commit without a release tag | affected desktop users need packaged artifacts from the release workflow.
Confidence: high
Scope-risk: narrow
Directive: Keep v0.2.4 scoped to the startup auth regression; broader H5 improvements belong in a later release.
Tested: bun run scripts/release.ts 0.2.4 --dry
Tested: bun run scripts/release.ts 0.2.4
Not-tested: GitHub release workflow before push; it only runs after the tag is pushed.
The post-v0.2.2 changes are now summarized in the release body with the user-facing highlights first, while process-only H5 hardening is described as part of the new feature instead of old-version bug fixes. Desktop and Tauri version files are aligned to the release note version.
Constraint: GitHub Release body is sourced from release-notes/vX.Y.Z.md in the tagged commit
Constraint: Problem fixes should describe issues users could have seen in prior releases, not internal fixups for unreleased work
Rejected: Put every fix commit under 问题修复 | mixes development cleanup with released-user regressions
Confidence: high
Scope-risk: narrow
Tested: git diff --check
Tested: git diff --cached --check
Tested: bun run scripts/release.ts 0.2.3 --dry
Tested: version consistency check for desktop package, Tauri config, Cargo.toml, and Cargo.lock
Not-tested: Full bun run verify; release note and version bump only
Packaged desktop builds started the sidecar on loopback only, so phones on the same WiFi could not connect to the H5 URL. The server now binds to LAN interfaces while keeping the desktop control URL on loopback, serves the bundled H5 frontend, and reports a LAN public URL when H5 access is enabled.
Constraint: Packaged Tauri resources place ../dist under Contents/Resources/_up_/dist.
Rejected: Bind the desktop control URL to 0.0.0.0 | desktop clients should keep using loopback for local control.
Confidence: high
Scope-risk: moderate
Directive: Keep packaged H5 resource lookup aligned with Tauri resource mapping when changing bundle resources.
Tested: bun run check:server
Tested: cd desktop/src-tauri && cargo test --lib
Tested: cd desktop && bun run test -- desktopRuntime.test.ts generalSettings.test.tsx
Tested: SKIP_INSTALL=1 ./desktop/scripts/build-macos-arm64.sh
Tested: Packaged claude-sidecar smoke served H5 HTML while listening on *:39876
Not-tested: Physical phone browser test on the local WiFi network
The Rust command now keeps the synchronous bridge wait off the invoke thread, but the Objective-C bridge still initiated UserNotifications authorization from that worker. In a packaged app that path could fail immediately and the settings UI collapsed the error into an unsupported environment.
Start notification settings reads, authorization requests, and delivery submissions on the macOS main queue while keeping the blocking wait on the worker thread. This preserves foreground-safe notification delivery without deadlocking the UI or losing the system permission prompt.
Constraint: UserNotifications APIs are UI-adjacent and should be initiated on the app main queue.
Rejected: Only change the unsupported status copy | it would keep the authorization path broken.
Confidence: high
Scope-risk: narrow
Directive: Keep UserNotifications calls main-queue initiated while the synchronous wait remains off the main thread.
Tested: cd desktop/src-tauri && cargo test
Tested: bun run check:native
Tested: SKIP_INSTALL=1 ./scripts/build-macos-arm64.sh
Tested: codesign --verify --deep --strict --verbose=2 desktop/build-artifacts/macos-arm64/Claude Code Haha.app
Tested: hdiutil verify desktop/build-artifacts/macos-arm64/Claude Code Haha_0.2.1_aarch64.dmg
Tested: Computer Use opened /Users/nanmi/workspace/myself_code/claude-code-haha/desktop/build-artifacts/macos-arm64/Claude Code Haha.app and verified Settings -> General shows notifications as authorized after disable/enable.
Not-tested: Fresh first-time system notification prompt on a machine that has never granted this bundle identifier.
The macOS notification bridge synchronously waits for UserNotifications callbacks. Running that wait on the Tauri command caller can block the callback path and make permission reads time out, which the UI reports as an unsupported environment.
Route the bridge calls through a blocking worker so permission reads, permission prompts, and delivery checks do not stall the app thread that needs to service native notification callbacks.
Constraint: UserNotifications permission and delivery APIs complete asynchronously through macOS callbacks.
Rejected: Change the settings status label only | it would hide the failed native permission read without fixing notification delivery.
Confidence: high
Scope-risk: narrow
Directive: Keep macOS notification bridge calls off the invoke caller thread unless the Objective-C bridge becomes fully async.
Tested: cd desktop/src-tauri && cargo test
Tested: bun run check:native
Tested: cd desktop && bun run test --run src/lib/desktopNotifications.test.ts src/__tests__/generalSettings.test.tsx
Tested: SKIP_INSTALL=1 ./scripts/build-macos-arm64.sh
Tested: codesign --verify --deep --strict --verbose=2 desktop/build-artifacts/macos-arm64/Claude Code Haha.app
Tested: hdiutil verify desktop/build-artifacts/macos-arm64/Claude Code Haha_0.2.1_aarch64.dmg
Not-tested: Manual click-through of the newly built .app notification settings screen.
Notification clicks and repeated launches can enter the native app through OS-level activation paths, so the desktop runtime now registers Tauri's single-instance guard before sidecars or other plugins start. A second launch restores and focuses the existing main window instead of creating another app process.
Constraint: macOS and Windows launch paths must reuse the running desktop instance.
Rejected: Handle only notification click callbacks | does not cover Dock, shortcut, installer, or Windows relaunch paths.
Confidence: high
Scope-risk: narrow
Directive: Keep the single-instance plugin before sidecar startup so duplicate launches cannot create extra runtime processes.
Tested: SKIP_INSTALL=1 ./desktop/scripts/build-macos-arm64.sh
Tested: open -n built app twice; desktop_count stayed 1 with pid 69821
Tested: bun run check:native
Tested: cargo test --manifest-path desktop/src-tauri/Cargo.toml
Tested: cd desktop && bun run test -- desktopNotifications.test.ts
Tested: cd desktop && bun run lint
Desktop users can carry provider indexes, managed settings, localStorage state, and native update state from builds that no longer match current readers. This adds startup migrations and recovery paths before server and React state are consumed, plus a persistence upgrade gate so future storage protocol changes ship with old-format fixtures.
Constraint: Existing installs may contain malformed or legacy JSON/localStorage that must not block startup.
Constraint: Local verify should evaluate the current worktree diff rather than unrelated detached-worktree history.
Rejected: Treat invalid persisted state as fatal | reproduces white-screen and startup failure behavior for existing users.
Rejected: Bypass PR policy locally | hides real gate behavior and does not fix detached-worktree false positives.
Confidence: high
Scope-risk: moderate
Directive: Any local JSON, localStorage, or app config shape change must add a migration fixture and keep `bun run check:persistence-upgrade` green.
Tested: bun run check:persistence-upgrade; bun run check:policy; bun run check:desktop; bun run check:server; bun run check:native; bun run verify (9 passed, 1 coverage baseline failure)
Not-tested: Live provider baseline; existing user configs beyond covered fixtures
Desktop notifications now carry a narrow target payload so clicking a permission, completion, or scheduled-task notification can reopen the matching tab and reconnect the session. macOS uses the native notification bridge for tap callbacks, while the shared desktop notification layer also accepts plugin action payloads where the platform exposes them.
Constraint: Notification clicks need to activate existing desktop tabs without adding a new navigation state channel.
Rejected: Store only notification ids and infer the active session later | stale notifications would point at the wrong session after tab changes.
Confidence: high
Scope-risk: moderate
Directive: Keep notification targets serializable and versioned through desktopNotifications before adding new target types.
Tested: bun run quality:pr with ALLOW_CLI_CORE_CHANGE=1; desktop unit tests; server tests; native sidecar build and cargo check; docs build.
Not-tested: Packaged Windows toast activation runtime; current fallback depends on Tauri notification action delivery.
Linux release builds use MenuBuilder for the shared tray menu, while MenuItemBuilder and SubmenuBuilder are only used in the macOS native menu bar. Gate only the macOS-only imports so Linux builds no longer warn about them and still compile the shared tray path.
Constraint: Linux builds compile the shared tray setup path and require MenuBuilder
Constraint: MenuItemBuilder and SubmenuBuilder are only referenced inside cfg(target_os = "macos")
Rejected: Gate the whole tauri::menu import on macOS | Linux still needs MenuBuilder for tray menu construction
Confidence: high
Scope-risk: narrow
Directive: Do not gate MenuBuilder by platform unless setup_system_tray is also made platform-specific
Tested: cargo fmt --check
Tested: git diff --check
Not-tested: Local Linux cargo check beyond system GTK/WebKit pkg-config setup; GitHub release Linux job is the verification surface
Release logs showed two warning classes after the packaging fixes: Linux builds warned about macOS-only menu imports, and tauri-action reported an unknown releaseAssetNamePattern input. Gate the native menu imports to macOS and use the action's supported assetNamePattern input so release logs stay clean and asset naming is actually applied.
Constraint: Linux release builds compile the shared Tauri lib without macOS-only menu usage
Constraint: tauri-action v0 accepts assetNamePattern, not releaseAssetNamePattern
Rejected: Ignore warning-only output | release candidates should not hide real signal behind avoidable warnings
Confidence: high
Scope-risk: narrow
Directive: Keep workflow input names aligned with tauri-action's published action schema
Tested: cargo fmt --check
Tested: cargo check --target aarch64-apple-darwin
Tested: git diff --check
Not-tested: Full GitHub release workflow after retag before pushing
