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
The macOS notification bridge is compiled by build.rs outside Cargo's Rust target handling. On Apple Silicon, clang defaulted macos_notifications.o to arm64 even when Cargo was building x86_64, so the x64 release job ignored the object and missed the exported notification symbols.
Constraint: The ObjC bridge is linked manually through cargo:rustc-link-arg
Constraint: Release workflow builds both aarch64-apple-darwin and x86_64-apple-darwin from macOS runners
Rejected: Rely on clang default architecture | Apple Silicon defaults arm64 and breaks x86_64 linking
Confidence: high
Scope-risk: narrow
Directive: Keep native ObjC bridge compilation aligned with Cargo TARGET when adding platform bridge files
Tested: cargo fmt --check
Tested: git diff --check
Tested: cargo check --target aarch64-apple-darwin
Tested: cargo build --target x86_64-apple-darwin --release
Tested: file target/x86_64-apple-darwin/release/.../macos_notifications.o reports Mach-O 64-bit object x86_64
Not-tested: Full GitHub release workflow after retag before pushing
This records the user-facing 0.2.1 release notes and aligns the desktop package, Tauri config, Cargo manifest, and lockfile package version so the tag-triggered release workflow can publish the intended build.
Constraint: GitHub Release body is sourced from release-notes/v0.2.1.md in the tagged commit
Constraint: Keep provider and OpenAI login details weak in the release narrative because this release is centered on IM, notifications, context usage, and desktop stability
Rejected: Run scripts/release.ts directly | it creates a generic commit message and tag before review of the release narrative
Confidence: high
Scope-risk: narrow
Directive: Do not tag v0.2.1 from a commit that lacks release-notes/v0.2.1.md or mismatched desktop version files
Tested: bun run scripts/release.ts 0.2.1 --dry
Tested: cargo check
Tested: git diff --check
Not-tested: Live release gate with real provider credentials in this commit step
Telegram polling stopped consuming updates when all IM adapters were loaded into the same desktop sidecar process. Launch each IM platform as its own sidecar process so Telegram keeps an isolated long-polling consumer while Feishu, WeChat, and DingTalk manage their own SDK loops independently.
Constraint: Telegram Bot API long polling needs one healthy consumer per token and should not share lifecycle with other IM SDKs
Rejected: Keep one combined adapter process | reproduced pending Telegram updates until Telegram was launched alone
Confidence: high
Scope-risk: moderate
Directive: Keep IM adapter process ownership isolated unless cross-platform lifecycle tests prove a merged process is safe
Tested: cargo fmt --check
Tested: cargo check
Tested: bun run check:native
Tested: ./desktop/scripts/build-macos-arm64.sh
Tested: Computer Use launched built app and sent Telegram smoke message with pending_update_count=0
Not-tested: Automated Feishu, WeChat, or DingTalk live message delivery after process split
Telegram long polling can be consumed or disrupted by orphaned adapter sidecar processes left behind after desktop restarts or IM settings refreshes. Kill stale Unix claude-sidecar adapters processes before launching a new managed adapter sidecar so only one Telegram consumer remains active.
Constraint: Telegram Bot API long polling should have a single active consumer for a token
Rejected: Only restart the current tracked child | orphaned sidecars with PPID 1 are outside the tracked Tauri child handle
Confidence: high
Scope-risk: narrow
Directive: Keep adapter sidecar startup single-instance across platforms when adding new IM adapters
Tested: cargo fmt --check
Tested: cargo check
Tested: bun run check:native
Tested: git diff --check
Not-tested: Packaged macOS app relaunch with a real stale sidecar during automated test
Desktop notifications were enabled by default and depended on the Tauri notification plugin for both permission state and delivery. On macOS the plugin reports desktop permission as granted and can hide foreground delivery failures, so authorization prompts could appear in the app without a real system notification.
This moves macOS permission and delivery through a native UserNotifications bridge, keeps notifications opt-in by default, and sends a test notification after successful authorization.
Constraint: Tauri notification plugin desktop permission state is always granted.
Constraint: macOS foreground delivery needs explicit native presentation handling.
Rejected: Keep using the plugin with retries | it still cannot report real macOS permission or delivery failures.
Confidence: high
Scope-risk: moderate
Directive: Do not remove the macOS bridge without verifying foreground banners from an installed app bundle.
Tested: cd desktop && bun run test --run src/lib/desktopNotifications.test.ts src/stores/settingsStore.test.ts src/__tests__/generalSettings.test.tsx src/stores/chatStore.test.ts
Tested: bun run check:desktop
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.0_aarch64.dmg
Tested: Computer Use macOS Settings and Bash authorization notifications, confirmed usernoted displayed banners.
Not-tested: Windows toast delivery on a real installed Windows build.
Desktop notification permission can appear granted while macOS still suppresses a foreground banner, so blocking permission prompts now also request OS-level window attention. The notification sender keeps the native notification path, but prompt callers can ask the window manager for attention when silence would block user progress.
The desktop package also declares the existing qrcode runtime dependency used by AdapterSettings so production desktop builds can resolve that import.
Constraint: Tauri window attention requires an explicit capability grant in packaged builds.
Constraint: macOS may suppress foreground notification banners even when notification APIs report success.
Rejected: Replace native notifications with a custom in-app sound or overlay | the notification feature should stay OS-owned and already has an in-app permission card.
Confidence: high
Scope-risk: narrow
Directive: Keep requestAttention limited to blocking prompts unless another flow truly needs persistent OS attention.
Tested: bun run test -- src/lib/desktopNotifications.test.ts src/stores/chatStore.test.ts
Tested: bun run check:desktop
Tested: bun run check:native
Tested: git diff --check
Not-tested: bun run quality:pr | blocked by existing branch-wide CLI core policy requiring allow-cli-core-change approval
DingTalk uses QR registration to store client credentials, then reuses the existing IM pairing and session bridge. The merged main implementation keeps the existing WeChat QR binding path intact while adding DingTalk as a peer IM platform. The default IM workdir now falls back to the local user working directory so a newly bound chat can start immediately even when recent-project history is empty.
Constraint: Local main already carries WeChat IM, so the merge keeps WeChat config, QR binding, sidecar args, and unbind behavior intact while adding DingTalk.
Rejected: Keep empty defaultProjectDir as project-picker-only | newly bound IM users can hit a dead end with no recent projects.
Confidence: high
Scope-risk: moderate
Directive: Keep IM platform unions synchronized across config, pairing, sidecar args, desktop settings, and docs.
Tested: bun test common/ dingtalk/ wechat/; bun test src/server/__tests__/adapters.test.ts; cd adapters && bunx tsc --noEmit; bun run check:policy; bun run check:server; bun run check:desktop; bun run check:adapters; bun run check:native; bun run check:docs
Not-tested: quality:pr full gate was blocked by existing local main CLI-core diff requiring allow-cli-core-change maintainer approval; live post-fix DingTalk second-message delivery was not repeated after the merge.
WeChat needs a QR-paired path instead of bot-token setup, so the adapter layer now includes the iLink protocol calls, desktop pairing UI, server-side bind/unbind APIs, and shared IM command behavior. Empty project history falls back to the user's default work directory so mobile /new works without pre-opening a desktop project.
Constraint: Tencent iLink login returns a URL that the desktop UI must render as a QR image locally
Constraint: IM adapters should keep /new, /projects, status, permission, and default workdir behavior consistent across WeChat, Feishu, and Telegram
Rejected: Require users to paste absolute project paths for first WeChat sessions | mobile onboarding should work from the default user working directory
Confidence: high
Scope-risk: moderate
Directive: Do not change WeChat polling back to overlapping intervals; getupdates is a long-poll endpoint and must remain serialized
Tested: Real WeChat QR scan, inbound /status, outbound reply, and unbind E2E
Tested: bun run check:adapters
Tested: bun run quality:pr
Not-tested: Re-scan live WeChat after the default-workdir fallback tweak; covered by adapter config tests and PR gate
Add native system notifications as a desktop-wide attention channel for permission prompts and scheduled task completion. The implementation keeps notification presentation owned by the OS, adds a user-facing enable switch with permission handling, and lets scheduled tasks choose desktop notifications without routing that channel through IM adapters.
Constraint: Notifications must use OS-native APIs without custom sound playback.
Constraint: Desktop channel is local-only and must not be sent through IM adapter delivery.
Rejected: Browser Notification API | not reliable inside the packaged Tauri desktop runtime.
Rejected: Treat desktop as an IM channel | would leak a local-only channel into server-side adapter sending.
Confidence: high
Scope-risk: moderate
Directive: Keep notification styling at the OS layer; business code should only provide title, body, dedupe, and routing decisions.
Tested: bun run check:desktop
Tested: bun run quality:pr
Tested: Computer Use macOS debug app verification for settings toggle, permission prompt, scheduled task desktop channel, and task-run polling dedupe
Not-tested: Windows and Linux native runtime smoke tests on physical hosts
This release marks the desktop app's shift from a thin CLI wrapper toward a fuller local Coding Agent workspace. It carries the reviewed v0.2.0 release notes, bumps desktop package metadata, and refreshes Cargo.lock from the pinned Tauri stack before publishing the tag-driven GitHub Actions release.
Constraint: GitHub Release body is sourced from release-notes/v0.2.0.md in the tagged commit
Constraint: Desktop releases are built remotely from the pushed v0.2.0 tag
Rejected: Publish as v0.1.10 | the release consolidates several desktop workflow and quality-gate milestones, so v0.2.0 better communicates the scope
Confidence: high
Scope-risk: narrow
Directive: Keep the v0.2.0 tag on this commit unless the release notes or version metadata are changed together
Tested: bun run scripts/release.ts 0.2.0 --dry
Tested: bun run quality:gate --mode release --allow-live --provider-model codingplan:main:codingplan-main --provider-model minimax:main:minimax-main (18 passed, 0 failed, 0 skipped)
The release script regenerated Cargo.lock after Tauri 2.11 became available, while the desktop Bun lock still resolves @tauri-apps/api and CLI to 2.10.1. Tauri's build preflight rejects that major/minor mismatch on every platform, so the Rust Tauri release stack is now pinned to the 2.10 combination already used by the previous successful release.
Constraint: v0.1.9 must keep the existing desktop Bun lock and JS Tauri packages at 2.10.1
Constraint: scripts/release.ts runs cargo generate-lockfile during release preparation
Rejected: Upgrade JS @tauri-apps packages during the release fix | larger dependency surface and unnecessary for the failed workflow
Rejected: Pin only the tauri crate | cargo still selected tauri-runtime 2.11.0, causing Rust API type mismatches
Confidence: high
Scope-risk: narrow
Directive: Keep Rust and JS Tauri major/minor versions aligned before moving release tags
Tested: gh run view 25217609687 --log-failed
Tested: cd desktop/src-tauri && cargo generate-lockfile
Tested: cd desktop && bunx tauri build --target aarch64-apple-darwin --config src-tauri/tauri.release-ci.json --no-bundle
Tested: cd desktop/src-tauri && cargo check
Not-tested: Full GitHub Actions matrix after retag
The release collects the post-v0.1.8 desktop workspace manager work, provider compatibility fixes, WebSearch fallback support, and desktop lifecycle hardening into a tagged GitHub Actions release.
Constraint: GitHub Release body is sourced from release-notes/v0.1.9.md in the tagged commit
Constraint: The release script owns version bumps for desktop/package.json, Tauri config, Cargo.toml, and Cargo.lock
Rejected: Push the script-generated generic release commit | it would violate the repository Lore commit protocol
Confidence: high
Scope-risk: narrow
Directive: Do not move v0.1.9 without rerunning the release preflight and verifying the tag commit contains release-notes/v0.1.9.md
Tested: bun run scripts/release.ts 0.1.9 --dry
Tested: bun run scripts/release.ts 0.1.9
Tested: cd desktop/src-tauri && cargo check
Not-tested: GitHub Actions release workflow before tag push
The macOS icon rendered smaller than neighboring Dock icons because the
source artwork left a 120px margin on the 1024px canvas. Scale the macOS
source to the expected 96px margin and regenerate the Tauri icon set so
bundled app assets stay in sync.
Constraint: macOS source artwork should fit a 1024px canvas with 96px icon spacing
Rejected: Adjust only the Dock screenshot or public preview asset | packaged icon.icns would remain undersized
Confidence: high
Scope-risk: narrow
Directive: Regenerate desktop/src-tauri/icons when changing app-icon-macos.svg
Tested: cd desktop && bun run lint
Tested: icon.icns expanded 1024px image reports 96px margins on all sides
Not-tested: Full macOS app rebuild
Windows users reported that the desktop window lost its size and position after restarting, and hidden windows could behave inconsistently when restored from taskbar/tray interactions. The Tauri shell now records the main window bounds in the app config directory, restores them on startup, and skips stale off-screen states when monitor layouts change.
Constraint: Avoid new dependencies for window state persistence
Constraint: Preserve existing hide-to-tray behavior for the main window
Rejected: Add tauri-plugin-window-state | larger dependency surface for one small main-window state file
Confidence: medium
Scope-risk: moderate
Directive: Keep monitor visibility checks when changing restore behavior so external-display removal does not strand the window off-screen
Tested: cargo test
Tested: cd desktop && bun run lint
Tested: cd desktop && bun run build
Not-tested: Windows taskbar manual reproduction; current machine is macOS
Not-tested: cd desktop && bun run test fails in existing frontend locale assertions unrelated to this Tauri change
Closing the desktop window should not tear down the local server when users expect the app to keep serving background work. The Tauri layer now owns that lifecycle: close hides the main window, tray actions restore or quit, and true quit paths still stop sidecars.
Constraint: Issue #213 asks for Windows close-to-background behavior, and macOS should follow the same desktop lifecycle.
Rejected: Frontend-only close handling | native window close events and OS menu actions need one Tauri-owned path.
Confidence: high
Scope-risk: moderate
Directive: Do not remove the explicit quit marker unless all updater, tray, and app-exit paths are rechecked.
Tested: cargo fmt --manifest-path desktop/src-tauri/Cargo.toml --check
Tested: cargo check --manifest-path desktop/src-tauri/Cargo.toml
Tested: cargo test --manifest-path desktop/src-tauri/Cargo.toml
Tested: cd desktop && bun run lint
Tested: cd desktop && bun run build
Not-tested: Windows cargo check on this macOS machine; x86_64-pc-windows-msvc cross-check stopped in ring because the host lacks Windows C/MSVC headers.
Related: https://github.com/NanmiCoder/cc-haha/issues/213
The release note is now the GitHub Release source of truth, and the desktop version files have been moved together so the tag-triggered workflow can package the same version consistently.
Constraint: release-desktop.yml reads release-notes/v0.1.8.md from the tagged commit
Rejected: Push tag without a release commit | workflow requires version files and notes in the tag
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: Keep the release notes filename aligned with the tag before pushing future releases
Tested: bun run scripts/release.ts 0.1.8 --dry
Tested: bun run scripts/release.ts 0.1.8
Not-tested: Remote GitHub Actions build before pushing the tag
The desktop release workflow reads release-notes/v0.1.6.md from the tagged commit, so this commit aligns version metadata, lockfile state, and release copy before creating the v0.1.6 tag.
Constraint: GitHub Actions packaging is triggered by pushed v*.*.* tags, not by a plain main push
Constraint: The release script expects release-notes/vX.Y.Z.md to exist in the tagged commit
Rejected: Push main without a tag | that would not start the desktop release workflow
Confidence: high
Scope-risk: narrow
Directive: Keep version files, Cargo.lock, release notes, and the release tag aligned for desktop releases
Tested: bun run scripts/release.ts 0.1.6 --dry
Tested: git diff --cached --check
Not-tested: Remote GitHub Actions run before pushing the tag
Desktop sessions can switch provider and model while a CLI subprocess is already alive, so the server now serializes runtime restarts and marks provider-managed launches to prevent stale settings env from overriding the selected provider. Provider settings also write API key env consistently and clear stale managed keys before syncing.
This includes the related desktop/docs brand asset refresh and keeps the desktop locale default in Chinese, with tests updated to match the current provider semantics.
Constraint: Session-scoped model selection must win over cc-haha/settings.json and inherited ANTHROPIC_* values.
Rejected: Store the selected model as a global provider activeModel | chat runtime selection is per session.
Confidence: high
Scope-risk: moderate
Directive: Do not remove CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST without validating Desktop provider switching against stale settings env.
Tested: bun test src/server/__tests__/conversation-service.test.ts src/server/__tests__/conversations.test.ts src/server/__tests__/providers.test.ts src/server/__tests__/providers-real.test.ts
Tested: cd desktop && bun run test src/stores/settingsStore.test.ts
Tested: cd desktop && bun run lint
Tested: git diff --check
Not-tested: Full desktop production package/signing.
The detached worktree implementation adds a Settings terminal for command-based setup flows. The merge keeps the target branch's current adapter/runtime dependencies while adding the new portable-pty backend, xterm frontend, UTF-8 output handling, and host-shell environment propagation.
Constraint: Target branch had newer desktop dependency changes, including anyhow in the Tauri crate.
Constraint: Existing uncommitted work in the main worktree had to stay out of this merge commit.
Rejected: Fast-forward the checked-out branch under a dirty worktree | would risk mixing unrelated local changes into the branch state.
Confidence: high
Scope-risk: moderate
Directive: Treat the terminal as host-shell integration; keep PATH and UTF-8 locale handling together when changing startup behavior.
Tested: cargo fmt --check
Tested: cargo test --lib
Tested: cargo check
Tested: cd desktop && bun run lint
Tested: cd desktop && bun run test src/pages/TerminalSettings.test.tsx
Tested: git diff --check
Not-tested: Rebuilt macOS DMG from the target branch after merge.
Some setup flows end in a shell command instead of a natural-language install path, so Settings now exposes a host PTY terminal backed by portable-pty and xterm. The terminal inherits the user's login-shell environment, forces a UTF-8 locale when needed, and preserves split UTF-8 output so Chinese paths render correctly.
Constraint: Desktop GUI apps do not inherit the user's interactive shell PATH on macOS.
Constraint: Command output may split UTF-8 characters across PTY reads.
Rejected: Use Tauri shell commands only | users need an interactive PTY for copy-pasted install flows.
Rejected: Ask users to edit shell profiles | terminal setup should work out of the box.
Confidence: high
Scope-risk: moderate
Directive: Keep terminal startup tied to host environment checks; do not bundle runtimes to solve PATH issues.
Tested: cargo fmt --check; cargo test --lib; cargo check; cd desktop && bun run lint; cd desktop && bun run test src/pages/TerminalSettings.test.tsx; cd desktop && bun run build; cd desktop && bun run build:macos-arm64
Tested: Computer Use verified npm is available in the built macOS app terminal and Chinese output renders after UTF-8 decoding fix.
Not-tested: Native Windows/Linux package runtime validation.
The Settings terminal added a full xterm plus Tauri PTY stack for a job
that is better handled by dedicated install and configuration flows. This
change removes the Settings tab, frontend terminal wiring, Tauri terminal
commands, and the terminal-only dependencies so the desktop settings
surface stays narrower and less fragile.
Constraint: The worktree already contains unrelated desktop icon and UI changes, so this commit stages only the terminal-removal slice
Rejected: Keep a hidden or runtime-only terminal stub | it would still preserve the heavy cross-layer maintenance surface
Rejected: Remove only the Settings tab and leave the Tauri PTY backend | that would leave dead code and unused dependencies behind
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: If future install workflows need more power, prefer Settings-native actions and runtime refresh over reintroducing a general shell tab
Tested: bun x vitest run src/__tests__/generalSettings.test.tsx src/__tests__/skillsSettings.test.tsx src/__tests__/pluginsSettings.test.tsx src/__tests__/agentsSettings.test.tsx src/__tests__/mcpSettings.test.tsx src/components/settings/InstallCenter.test.tsx; bun run lint; bun run build; cargo check --manifest-path desktop/src-tauri/Cargo.toml
Not-tested: Manual packaged desktop app click-through after removing the Settings terminal tab
Settings needed a real shell for plugin, MCP, and skill setup without relying on
a globally installed Claude CLI. Add an xterm.js terminal backed by portable-pty,
wire it into the Tauri desktop runtime, and move shell restart handoff to the
new session before old PTY teardown so the UI is less likely to stall behind
child shutdown.
Constraint: The desktop app must inject the bundled CLI into the shell environment instead of requiring a separate global install
Constraint: Restart teardown cannot block the frontend-facing Tauri command path
Rejected: Keep terminal setup inside installer chat only | that flow cannot replace an interactive shell
Rejected: Wait for old PTY shutdown before adopting the new session | it keeps restart vulnerable to hung child teardown
Confidence: medium
Scope-risk: moderate
Reversibility: clean
Directive: Preserve new-session handoff before old-session cleanup when changing terminal lifecycle or restart logic
Tested: bunx vitest run src/__tests__/terminalPanel.test.tsx src/components/settings/TerminalPanel.restart.test.tsx; bun run lint; cargo check
Not-tested: Full packaged-app command echo and repeated manual restart behavior still need additional runtime verification
The previous icon fix solved the square-background issue on older macOS
versions, but it overcorrected by removing the card entirely and turning the
app mark into a bare transparent glyph. This keeps the icon light and app-like
again by using a shallow light card as the icon body while still removing the
extra outer background that made uncropped icons look wrong.
Constraint: Older macOS versions may expose the bundled icon without applying the newer rounded mask treatment
Constraint: The desktop bundle must keep app-icon.svg and generated PNG/ICNS/ICO assets aligned
Rejected: Keep the transparent-only glyph | no longer reads like the intended app icon in Finder and DMG views
Rejected: Restore the original AI-generated image wholesale | reintroduces the outer background that caused the square-icon issue
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: Treat desktop/src-tauri/app-icon.svg as the canonical source and regenerate the bundled icon assets in the same change
Tested: desktop bun run lint; desktop bun run test; extracted regenerated icon.icns for visual verification
Not-tested: Full DMG rebuild and manual Finder/Dock verification on older macOS
Older macOS versions can surface the bundled app icon without applying the
modern rounded-mask treatment, which exposed the legacy AI-generated white
background around the Claude Code Haha mark. This replaces the icon source with
a transparent-background vector mark and regenerates the bundled macOS and
cross-platform icon assets from that canonical source so packaging stays
consistent.
Constraint: Older macOS releases may display bundled icons without automatic corner masking
Constraint: The Tauri bundle references pre-rendered icon assets, so the source and generated files must stay aligned
Rejected: Patch only icon.icns | would leave PNG and ICO assets inconsistent across platforms
Rejected: Keep the AI icon and post-process the JPEG background | brittle extraction and no canonical source of truth
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: If the brand icon changes again, regenerate every file under desktop/src-tauri/icons from desktop/src-tauri/app-icon.svg in the same change
Tested: desktop bun run lint; desktop bun run test; extracted regenerated icon.icns to verify alpha transparency
Not-tested: Full packaged app launch in macOS Dock after rebuilding the desktop bundle
The desktop app was still falling back to raw text in release builds for some
fenced code blocks, which left bash snippets visually wrong and too heavy for
chat use. This change switches the Shiki path to the JavaScript regex engine,
restores tighter code-block defaults for chat, and bumps the desktop app
version to 0.1.4 for the release artifacts.
Constraint: The packaged Tauri app must render markdown code blocks consistently without relying on WebView WASM behavior
Constraint: Chat code blocks should stay compact and should not show line numbers unless a caller explicitly requests them
Rejected: Keep tuning fallback-only CSS | did not address the packaged highlighter path failing to initialize
Rejected: Leave line numbers on by default | too noisy for assistant replies and bash snippets
Confidence: high
Scope-risk: moderate
Reversibility: clean
Directive: If code blocks regress again, inspect the highlighter engine path before adjusting chat spacing CSS
Tested: cd desktop && bun run lint
Tested: cd desktop && bun run test CodeViewer.test.tsx MarkdownRenderer.test.tsx Sidebar.test.tsx
Tested: cd desktop && bun run build:macos-arm64
Not-tested: Windows packaged build after the engine switch
