The local main sync exposed a flaky WsBridge integration test during coverage: the client-side open event could resolve before the test's server-side connection array observed the connection. The test now waits for the server connection event before sending messages through the captured socket, preserving the FIFO behavior assertion without changing production bridge logic.
Constraint: Worktree validation must cover the latest local main commit before merging back
Rejected: Retry the full quality gate without a code change | the same timing race can recur and hide real merge readiness
Confidence: high
Scope-risk: narrow
Directive: Keep WsBridge integration tests synchronized on server-side connection readiness before using captured sockets
Tested: bun test adapters/common/__tests__/ws-bridge.test.ts
Tested: bun test --coverage --coverage-reporter=lcov --coverage-reporter=text --coverage-dir /tmp/cc-haha-adapters-coverage adapters
Bulk tab actions reused a direct disconnect path instead of the single-tab running-session confirmation path. The tab bar now collects running sessions before closing any selected tab set, prompts when active work would be affected, and applies the user's stop-or-keep choice consistently across close all, close others, close left, and close right.
Constraint: Desktop users can run multiple sessions concurrently and must not lose running work through a bulk tab action without confirmation
Rejected: Patch only Close All | the neighboring bulk actions had the same direct disconnect bypass
Confidence: high
Scope-risk: narrow
Directive: Keep bulk tab closing routed through the same running-session policy as single tab closing
Tested: cd desktop && bun run test src/components/layout/TabBar.test.tsx --pool forks --poolOptions.forks.singleFork=true
Tested: cd desktop && bun run lint
Tested: bun run check:desktop
Tested: git diff --check
Not-tested: Manual desktop UI click-through
Bring the desktop Feishu onboarding prompt from the worktree onto local main while preserving the existing local Web UI startup commit.
Constraint: Local main already had an independent commit after the worktree base, so fast-forward merge was not possible.
Confidence: high
Scope-risk: narrow
Directive: Keep future Feishu setup help concise in the settings page and leave detailed platform instructions in docs.
Tested: merge completed without conflicts
Tested: cd desktop && bunx vitest run src/pages/AdapterSettings.test.tsx src/i18n/index.test.tsx
Not-tested: Full post-merge check:desktop was not rerun; it had passed in the source worktree before merge.
Developers currently start the API server and Vite frontend by hand with fixed ports. This script keeps that workflow fast while avoiding bind failures when a previous run or another service already owns one of the defaults.
Constraint: Web UI must receive the actual backend URL whenever the backend port changes
Rejected: Reuse Vite auto-port behavior alone | it would not check or report the backend port and could leave the browser pointed at 3456
Confidence: high
Scope-risk: narrow
Directive: Keep this script dependency-light so it remains usable on a default macOS developer machine
Tested: bash -n scripts/start-web-ui.sh
Tested: ./scripts/start-web-ui.sh --help
Tested: occupied preferred ports 45678 and 45679, script switched to 45680 and 45681 and reached Web UI ready
Not-tested: full bun run verify, script-only developer workflow change
Feishu onboarding previously expected users to find the template bot flow in docs before the desktop form made sense. Surface the documented OpenClaw creation link and the two required setup steps directly in the unconfigured Feishu settings state, while hiding the prompt once saved credentials exist.
Constraint: The documented one-click template URL is the source of truth for bot creation.
Rejected: Add a full wizard | this flow only needs a short external creation link plus credential fields.
Confidence: high
Scope-risk: narrow
Directive: Keep this prompt short; detailed Feishu menu setup belongs in docs, not the settings form.
Tested: cd desktop && bunx vitest run src/pages/AdapterSettings.test.tsx src/i18n/index.test.tsx
Tested: cd desktop && bun run lint
Tested: git diff --check
Tested: bun run check:desktop
Not-tested: Live Feishu developer console account flow.
Desktop receives task lifecycle events for local subagents in addition to the visible Agent tool call. Rendering those events as standalone transcript cards exposed internal task types such as local_agent and duplicated the Agent surface. The store now keeps agent lifecycle state for Agent tool notifications without inserting separate transcript background cards, while non-agent background work remains visible with user-facing labels.
The long workspace preview test now has a wider timeout so coverage mode does not fail a behaviorally passing case.
Constraint: CLI task events use internal task_type values such as local_agent and local_bash.
Rejected: Rename local_agent in the standalone card | still leaves duplicate Agent and task cards for one subagent.
Confidence: high
Scope-risk: moderate
Directive: Do not render local_agent or remote_agent as standalone transcript cards unless the Agent tool card no longer exists.
Tested: bun run verify passed=8 failed=0 skipped=2
Not-tested: Live provider-backed desktop session smoke.
The desktop status store retained the last non-default server verb until idle, so a one-time worktree startup label could leak into later thinking or execution bubbles. The fix treats default Thinking and verb-less status updates as a reset for transient status text while preserving explicit non-default labels.
Constraint: Server-side duplicate worktree startup guards are still valid and should remain the source of launch truth.
Rejected: Suppress the label in StreamingIndicator | stale state would still leak to any future consumer of statusVerb.
Confidence: high
Scope-risk: narrow
Directive: Keep statusVerb transient; default Thinking or missing verbs must not preserve prior special labels.
Tested: cd desktop && bun run test -- src/stores/chatStore.test.ts --run
Tested: cd desktop && bun run lint
Tested: bun test src/server/__tests__/conversations.test.ts -t worktree --timeout 30000
Tested: git diff --check
The notification plugin can return an object whose unregister method
expects its original listener object as this. Calling the extracted
method directly drops that context and produces an unhandled rejection
when the browser shell cleans up listeners.
Constraint: The desktop frontend also runs in browser-like dev shells where Tauri plugin APIs may be partially present
Rejected: Ignore cleanup errors | it leaves noisy unhandled rejections during local UI smoke tests
Confidence: high
Scope-risk: narrow
Tested: cd desktop && bun run test -- desktopNotifications
Not-tested: Native notification click behavior on every desktop platform
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
The goal command now uses a session Stop hook as the durable completion mechanism and removes the separate evaluator path. Completion output is persisted as local command output so CLI streams, transcripts, and desktop history all see the same completed state.
Desktop keeps active goals in a compact header strip and lets completed goals render in the conversation flow, which avoids the old duplicate pinned card behavior while preserving visibility for running goals.
Constraint: /goal state has to survive transcript replay and desktop session restore.
Rejected: Keep the legacy evaluator alongside Stop hooks | duplicate completion paths made desktop state drift and hid the final card.
Confidence: high
Scope-risk: moderate
Directive: Keep goal completion events on the local_command transcript path unless desktop history restore is changed at the same time.
Tested: bun test src/goals/goalState.test.ts src/query/stopHooks.test.ts src/commands/goal/goal.test.tsx src/commands/headless.test.ts src/server/__tests__/ws-memory-events.test.ts src/server/__tests__/sessions.test.ts
Tested: bun run check:server
Tested: bun run check:desktop
Tested: real /tmp /goal CLI run 98fb4bb2-52da-4850-bc8e-e5e1cc0e4c51 with deepseek-v4-pro and WebUI screenshot verification
Not-tested: Remote release workflow
Bring back the narrow, previously validated sidebar recovery and Windows x64 sidecar compatibility fixes that were present on worktree branches but absent from the canonical local main checkout. The broader worktree branch is intentionally not merged because it would replay unrelated history and risk dropping current main work.
Constraint: The local main worktree already contains unrelated Settings and portable storage edits, so only the recovery hunks are staged.
Rejected: Merge 1506086927/main wholesale | its history includes broad rollback/replay commits that would remove current main changes.
Confidence: high
Scope-risk: narrow
Directive: Recover future worktree fixes by cherry-picking or staging narrow hunks; do not merge drifted worktree branches wholesale.
Tested: cd desktop && bun run test -- --run src/components/layout/Sidebar.test.tsx scripts/build-sidecars.test.ts
Not-tested: Full bun run verify due unrelated dirty Settings/portable-storage worktree changes.
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
The worktree fix diverged from local main because main already contains local desktop update proxy work. Merge the completed worktree commit into main so the terminal-like environment behavior lands without rewriting either line of local history.
Constraint: Local main is not an ancestor of the worktree commit, so fast-forward merge is unavailable
Rejected: Rebase or cherry-pick the worktree commit | user requested a worktree-to-main merge
Confidence: high
Scope-risk: moderate
Directive: Preserve the terminal shell env merge order when touching desktop subprocess startup
Tested: bun run verify
Not-tested: Push or remote PR validation
This brings the detached worktree fix for desktop background-task visibility into the local main branch while preserving the main branch updates that landed after the worktree base.
Constraint: The source worktree was detached from an older main ancestor
Rejected: Fast-forward merge | local main has newer commits and cannot fast-forward to the detached worktree commit
Confidence: high
Scope-risk: narrow
Tested: bun run verify
Not-tested: No live provider baseline was run because this was a desktop UI state fix and the PR gate used non-live checks
Desktop launches can inherit a sparse GUI environment, while user runtimes such as nvm and Homebrew are often initialized from shell startup files. Capture a bounded login+interactive shell environment once and reuse it for desktop CLI sessions, scheduled tasks, and MCP stdio startup while keeping explicit MCP PATH and provider-managed env overrides authoritative.
Constraint: macOS app launches may omit user shell PATH and exported runtime variables
Rejected: Patch only MCP stdio | leaves normal desktop sessions and scheduled tasks inconsistent
Confidence: high
Scope-risk: moderate
Directive: Keep provider/OAuth scrubbing after shell env merging when changing child env builders
Tested: bun test src/utils/terminalShellEnvironment.test.ts src/utils/mcpStdioEnvironment.test.ts src/server/services/mcpHostPreflight.test.ts src/server/__tests__/conversation-service.test.ts src/server/__tests__/cron-scheduler-launcher.test.ts src/server/__tests__/mcp.test.ts
Tested: bun run check:server
Tested: bun run check:coverage
Tested: bun run verify
Not-tested: Real desktop UI live-model smoke on an installed .app
The CLI can emit a completed assistant turn while local background bash or task work continues. The desktop transcript and header now keep that background activity visible without converting the composer into a global stop state.
Constraint: Preserve CLI turn semantics where message_complete means the current assistant turn is done, not every background task is finished
Rejected: Treat background tasks as composer-active generation | this blocks follow-up input even though the CLI keeps the session responsive
Confidence: high
Scope-risk: narrow
Tested: cd desktop && bun run test -- --run src/components/chat/MessageList.test.tsx src/components/chat/ChatInput.test.tsx src/pages/ActiveSession.test.tsx
Tested: bun run check:desktop
Tested: bun run verify
The updater proxy fix was developed in a detached worktree based on an older local main commit. Merge it into the canonical local main while preserving the feature commit and the main branch's intervening desktop work.
Constraint: Local main contains four commits after the worktree base, so a fast-forward is not available
Rejected: Rebase detached worktree onto main | unnecessary history rewriting for a single verified feature commit
Confidence: high
Scope-risk: moderate
Directive: Do not push this local integration unless explicitly requested
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
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 add-to-chat popover was keyed off the mouse-up location, so broad selections could cover the selected text and stale popovers could remain visible. Shared placement and dismissal logic now anchors the action to the selected range, prefers the space above the selection like Codex App, and clears stale selections on outside clicks.
Constraint: Desktop chat and workspace previews share the same selection affordance and must keep their existing add-reference behavior.
Rejected: Keep cursor-based placement | it can hide selected text and makes multi-line selections unpredictable.
Confidence: high
Scope-risk: moderate
Directive: Keep future selection actions range-anchored and outside-click dismissible across chat and workspace surfaces.
Tested: bun run check:desktop
Tested: Browser verification on http://127.0.0.1:5174 showed the popover above selection, no overlap, and outside click clearing it.
Not-tested: Native packaged Tauri window.
Related: https://github.com/NanmiCoder/cc-haha/issues/484
Desktop non-session tabs unmount the active chat composer, so component-local draft refs disappeared before users returned to the session. Move the draft into per-session chat state and save it at session-switch and unmount boundaries, then clear it after submit.
Constraint: Settings and terminal tabs replace ActiveSession in ContentRouter.
Rejected: Persist drafts in localStorage | would add unnecessary persistence migration surface for a runtime-only draft.
Confidence: high
Scope-risk: narrow
Directive: Keep composer draft state scoped per session; do not move it back into component-only refs without covering unmount and remount.
Tested: bun run test src/components/chat/ChatInput.test.tsx --run
Tested: bun run check:desktop
Tested: bun run verify
Bring the detached worktree fix into local main so desktop sessions keep legacy custom slash commands visible across live CLI updates.
Constraint: Local main contains an additional local commit, so this is a real merge rather than a fast-forward.
Confidence: high
Scope-risk: moderate
Directive: Preserve both skill and legacy command fallback behavior when changing slash command session state.
Tested: bun test src/server/__tests__/sessions.test.ts -t "slash-commands"
Tested: cd desktop && bun run test -- --run src/stores/chatStore.test.ts
Tested: bun run check:desktop
Tested: bun run check:server
Tested: bun run check:native
Not-tested: Full verify remains blocked by unrelated/flaky coverage lane failures observed before merge.
Related: 010a4bf9
The desktop command list could be replaced by a partial live CLI update after a turn, and the server fallback only knew about skills. Keep the client list stable while refreshing from the authoritative session endpoint, and include legacy .claude/commands entries in that endpoint.
Constraint: Claude Code custom slash commands still use .claude/commands/*.md alongside newer skill commands.
Rejected: Only union client-side updates | would still miss custom commands before CLI init and lose argument hints from the authoritative API.
Confidence: high
Scope-risk: moderate
Directive: Keep session slash command fallback aware of both skills and legacy command directories.
Tested: bun test src/server/__tests__/sessions.test.ts -t "slash-commands"
Tested: cd desktop && bun run test -- --run src/stores/chatStore.test.ts
Tested: bun run check:desktop
Tested: bun run check:server
Tested: bun run check:native
Not-tested: bun run verify remains red due unrelated/flaky coverage lane failures outside this change.
Related: https://github.com/NanmiCoder/cc-haha/issues/495
AskUserQuestion used one free-text value for every tab, so typing a custom response on one question leaked into the next and option selection could erase another question's answer. Store free-text answers per question index and submit the per-question answer map so mixed custom and option replies stay intact.
Constraint: Multiple questions share one AskUserQuestion component instance
Rejected: Keep a single free-text fallback | it cannot distinguish which question owns the custom reply
Confidence: high
Scope-risk: narrow
Directive: Keep custom text and option state scoped to a question index when changing this component
Tested: Reproduced in Web UI on 127.0.0.1:1420 with server 127.0.0.1:4678 and deepseek-v4-pro in /private/tmp
Tested: cd desktop && bun run test -- AskUserQuestion.test.tsx --run
Tested: bun run verify
Not-tested: none
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 goal workflow remains in code but is intentionally hidden for this release, so the public release note should not market or validate it as a shipped feature.
This keeps the release body aligned with the enabled entry points and shifts the highlight back to Project Memory, project sessions, plugin refresh, chat input, and desktop stability.
Constraint: /goal is not being published in v0.2.7 because defects remain
Rejected: Leave /goal in the release note | would ask reviewers and users to validate a hidden feature
Confidence: high
Scope-risk: narrow
Tested: rg -n 'goal|/goal|目标' release-notes/v0.2.7.md
Tested: git diff --check
Tested: bun run scripts/release.ts 0.2.7 --dry
The goal implementation is being kept in the tree for later redesign, but the CLI and desktop slash-command surfaces should not advertise or route new users into it while the long-running goal experience is incomplete. Existing transcript parsing and goal event rendering remain intact so historical sessions still load.
Constraint: Keep the implementation code available for future iteration while removing discoverable entrypoints.
Confidence: high
Scope-risk: narrow
Directive: Do not re-expose /goal until the persistent goal/runtime design is revisited.
Tested: bun test src/commands/headless.test.ts
Tested: cd desktop && bun run test -- composerUtils.test.ts pages.test.tsx
Tested: NODE_ENV=test ANTHROPIC_API_KEY=dummy bun -e getCommands assertion for hidden goal command
The e3b851a8 session showed the final assistant turn had completed all tracked tasks, but the transcript never received Goal marked complete. The remaining CLI process was consistent with the post-turn goal completion side query blocking, leaving desktop without any completion event to render.
This makes the goal evaluator complete locally when every tracked task is completed and the latest assistant message contains a clear completion summary. It also bounds the model-backed evaluator with a timeout so uncertain cases continue instead of hanging the session indefinitely.
Constraint: Desktop can only render a completed goal card after the CLI writes a completion event into the transcript.
Rejected: Broaden desktop history parsing only | the failing session had no completion event to parse, so UI parsing alone could not fix new sessions.
Confidence: high
Scope-risk: narrow
Directive: Keep goal completion checks bounded; never let an auxiliary evaluator block the main turn from finishing.
Tested: bun test src/goals/goalEvaluator.test.ts
Tested: bun run check:server
Goal sessions were showing stopped background-agent cards because the parent model used TaskStop after reading enough partial review output. That writes a killed task notification, which the desktop then rendered like a failure.
TaskStop and async agent launch guidance now make cancellation an exceptional action rather than a normal cleanup step. Stopped background-agent transcript cards also render as neutral interrupted events instead of error-styled failures.
Constraint: Background agent task notifications must remain truthful; killed tasks still surface as stopped instead of being hidden.
Rejected: Hide stopped notifications in /goal sessions | this would mask real user cancellations and runaway-task stops.
Confidence: medium
Scope-risk: narrow
Directive: Do not encourage parent turns to kill background agents only because partial output was read.
Tested: cd desktop && bun run test src/components/chat/MessageList.test.tsx -t "renders stopped background agents as neutral transcript events"
Tested: cd desktop && bun run lint
Tested: bun run check:server
The goal evaluator now treats TaskCreate/TaskUpdate transcript state as a hard liveness gate, so a goal cannot complete while task entries remain pending or in_progress.
Background agent completion now notifies the parent before classifier or worktree cleanup, which keeps the main session from waiting forever when post-completion cleanup hangs. The desktop store also marks tabs idle on message_complete so completed transcripts do not leave stale running chrome.
Constraint: Desktop /goal relies on transcript task notifications to resume after background agents.
Rejected: Let optional cleanup run before notification | cleanup can hang and leaves the parent loop stuck.
Confidence: high
Scope-risk: moderate
Directive: Do not gate task-notification delivery on classifier or worktree cleanup without a timeout-backed liveness test.
Tested: bun test src/goals/goalEvaluator.test.ts src/tools/AgentTool/agentToolUtils.test.ts
Tested: bun run check:server
Tested: cd desktop && bun run test src/stores/chatStore.test.ts -t "marks the tab idle when a message completes"
Goal runs spawn visible background work while the conversation is active, so the desktop should show those events at their actual transcript position instead of pinning a separate panel above the chat. The UI now renders background task records as inline message events, repairs restored task state from transcript notifications, and keeps later task updates on the original event card.
Constraint: Existing transcripts only persist terminal task notifications, so the server now preserves their timestamps for deterministic restore ordering.
Rejected: Keep the page-level background-agent panel | it occluded the session content and duplicated message-flow information.
Confidence: high
Scope-risk: moderate
Directive: Background task message timestamps intentionally stay fixed after insertion; update the task content without moving the card in the transcript.
Tested: cd desktop && bun run test -- src/stores/chatStore.test.ts src/pages/ActiveSession.test.tsx src/components/chat/MessageList.test.tsx
Tested: cd desktop && bun run lint
Tested: bun test src/server/__tests__/sessions.test.ts
Daily pushes should catch policy and path-aware local failures without making every contributor wait for full coverage. The hook now runs a new quality:push entrypoint that reuses the PR quality gate while skipping coverage; verify, quality:pr, and CI still retain the full coverage gate for PR readiness.
Constraint: Forks and local contributors need a faster default push path
Rejected: Remove coverage from quality:pr | PR readiness and CI still need the ratcheted coverage signal
Confidence: high
Scope-risk: narrow
Directive: Keep pre-push on quality:push; use verify or quality:pr when coverage evidence is required
Tested: bun test scripts/pr/quality-contract.test.ts scripts/git-hooks/install.test.ts
Tested: bun run check:policy
Tested: bun run quality:push
Not-tested: Live provider smoke; intentionally remains opt-in
The pre-push hook already treats live model smoke as optional at runtime, but an existing local config can keep it enabled after reinstalling the hook. Default hook installation now writes the fast local setting explicitly unless a provider selector is supplied, so fresh forks and repeated installs stay on the PR gate path by default while release maintainers can still opt into live smoke.
Constraint: Daily contributor pushes should not depend on real provider access or long desktop smoke runs
Rejected: Remove live smoke lanes entirely | release and provider changes still need an explicit high-confidence validation path
Confidence: high
Scope-risk: narrow
Directive: Keep live provider and desktop smoke opt-in for push hooks; use quality:smoke or baseline gates for release validation
Tested: bun test scripts/git-hooks/install.test.ts
Tested: bun run check:policy
Not-tested: Full bun run verify before commit; push hook will run the non-live PR gate
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.
Desktop sessions previously only showed the final local-agent output, so long verification phases looked stalled even while the CLI was still working. The websocket bridge now forwards task start/progress events, and the desktop session state renders them as a compact background-agent panel below the active goal.
Constraint: CLI already emits task lifecycle events; desktop needed to consume the existing stream instead of polling transcript files.
Rejected: Wait for final task notifications only | that keeps the long-running phase invisible.
Confidence: high
Scope-risk: moderate
Directive: Keep task_started/task_progress available as structured desktop notifications when changing CLI event translation.
Tested: bun run verify (passed=8 failed=0 skipped=2)
Tested: bun run check:desktop
Tested: bun run check:server
Tested: bun run check:native
Tested: bun run check:coverage
Not-tested: Post-formatting check:server rerun was intentionally stopped at user request.
Formula-heavy conversations were still expensive after removing the fixed-height virtual chat window because every render repeated KaTeX expansion and HTML post-processing. Keep readable math, but reduce the DOM and CPU cost by rendering KaTeX without the hidden MathML copy, caching repeated formula output, and memoizing enhanced HTML parts outside the JSX render path.
Constraint: H5 streaming scroll follow behavior must remain unchanged
Rejected: Restore fixed-height virtualization | it caused blank gaps for variable-height math and code messages
Rejected: Disable LaTeX rendering | formula readability is a user-facing feature
Confidence: medium
Scope-risk: narrow
Directive: Do not reintroduce estimated-height chat virtualization without measured row heights for math-heavy messages
Tested: cd desktop && bun run test -- MarkdownRenderer.test.tsx MessageList.test.tsx
Tested: cd desktop && bun run lint
Tested: cd desktop && bun run build
Tested: git diff --check
Not-tested: Manual desktop scroll trace on the user's formula-heavy production conversation
The fixed-height virtual window introduced after v0.2.6 assumed every rendered chat item was 96px tall. Real desktop messages include markdown, math, code blocks, tool groups, and agent cards with highly variable heights, so scrolling history could replace real content with incorrectly sized blank spacer regions and make tab restoration janky.
Remove that unsafe virtualization layer and keep the existing direct scroll restoration behavior. The regression tests now keep long mixed-height transcripts and tool-call histories mounted so variable-height rows cannot disappear behind fake spacer math again.
Constraint: Desktop chat rows have unbounded variable height from markdown, KaTeX, code, tool, and agent output.
Rejected: Tune the 96px estimate | any constant row height still fails for mixed markdown and tool output.
Rejected: Add measured virtualization now | larger change surface than needed for the production white-gap regression.
Confidence: high
Scope-risk: narrow
Directive: Do not reintroduce chat virtualization without real row-height measurement and scroll restore coverage.
Tested: cd desktop && bun run test -- MessageList.test.tsx
Tested: cd desktop && bun run lint
Tested: cd desktop && bun run build
Tested: git diff --check
The simplified /goal surface only supports setting a condition and clearing it. Removed subcommand names such as status were still valid free-form objectives, so a user trying the old query flow could overwrite the real goal with a goal named status and make the desktop state look stuck in progress.
Constraint: /goal should stay as /goal <condition> and /goal clear for the prelaunch simplified UX
Rejected: Reintroduce /goal status | it expands the command surface the product direction intentionally removed
Confidence: high
Scope-risk: narrow
Directive: Do not add pseudo subcommands back to the desktop picker unless the CLI command surface is deliberately expanded again
Tested: bun test src/commands/goal/goal.test.tsx src/goals/goalState.test.ts src/goals/goalEvaluator.test.ts src/server/__tests__/ws-memory-events.test.ts
Tested: cd desktop && bun run test -- --run src/components/chat/composerUtils.test.ts src/__tests__/pages.test.tsx src/stores/chatStore.test.ts src/components/chat/MessageList.test.tsx
Drag-drop support made the composer panel clip overflow so the
stateful slash and file popovers still opened but were hidden above
the panel. Restore visible overflow on the drop target while keeping
the drop overlay and attachment flow intact, then lock both active
and empty composer surfaces with regression coverage.
Constraint: Drag-drop attachments must continue using the existing path-only composer pipeline
Rejected: Move slash and file menus outside the composer tree | broader portal refactor not needed for this regression
Confidence: high
Scope-risk: narrow
Directive: Do not reintroduce overflow clipping on composer panels without proving bottom-full popovers still render
Tested: cd desktop && bun run test -- --run src/components/chat/ChatInput.test.tsx src/pages/EmptySession.test.tsx
Tested: cd desktop && bun run lint
Tested: Browser smoke at http://127.0.0.1:1421/?serverUrl=http%3A%2F%2F127.0.0.1%3A3456 for / and @src popovers
Tested: bun run check:desktop
Bring the desktop markdown LaTeX renderer back into the local main line
without folding unrelated local release edits into the merge commit.
Constraint: Local main had uncommitted release changes, so they were preserved outside the merge and restored afterward
Confidence: high
Scope-risk: narrow
Directive: Keep future markdown rendering changes covered by focused renderer tests before broad desktop gates
Tested: bun run test --run src/components/markdown/MarkdownRenderer.test.tsx
Tested: bun run lint
Tested: bun run build
Tested: WebUI complex formula screenshot and 390px viewport overflow check
Not-tested: Full desktop gate still has unrelated /goal command hint expectation drift
Desktop assistant responses previously showed LaTeX source for common
model outputs. The markdown renderer now extracts math outside code spans
and fences, renders it through KaTeX, and applies chat-safe layout rules
for inline, block, multiline, matrix, and long-form formulas.
Constraint: Desktop chat already forces long markdown text to wrap, so KaTeX internals must opt out of that wrapping while display blocks handle overflow locally
Rejected: Render all dollar-delimited text blindly | currency and escaped dollar text would become false-positive formulas
Confidence: high
Scope-risk: narrow
Directive: Keep math extraction before marked parsing and preserve code fence protection when extending markdown rendering
Tested: bun run test --run src/components/markdown/MarkdownRenderer.test.tsx
Tested: bun run lint
Tested: bun run build
Tested: WebUI complex formula screenshot and 390px viewport overflow check
Not-tested: Full desktop gate still has unrelated /goal command hint expectation drift
