* feat(agent-tool): rewrite contradictory review verdicts at the harness layer
The code-reviewer and security-reviewer subagents end with a parseable
verdict (`REVIEW: APPROVE` / `SECURITY: PASS`) and their prompts forbid
emitting the positive form alongside `[CRITICAL]` or `[HIGH]` findings.
That rule is enforced only in prose, so when the model slips, the
parent agent reads "APPROVE" and ships.
Add a pure post-processing pass over the subagent's final text in
`finalizeAgentTool`: detect the verdict line, look for severity tags
above it, rewrite to `CHANGES_NEEDED` when they conflict, and prepend
a one-line audit notice so the parent (and a human reading the
transcript) can see the harness intervened. Logs a
`tengu_agent_sentinel_mismatch` analytics event for fleet visibility.
Debugger's `ROOT CAUSE: FOUND` is intentionally out of scope — its
"evidence from a real command" rule isn't mechanically verifiable.
Tested: bun test src/tools/AgentTool/sentinelCheck.test.ts (11 cases)
Confidence: high
Scope-risk: narrow
* feat(agent-tool): show subagent_type in tool-use transcript line
Each `Agent` tool call previously rendered as just its description in
the transcript, which made it invisible whether the main agent picked
a specialist or fell back to the default. Diagnosing "why didn't it
use code-reviewer?" required reading analytics or guessing.
Append `→ <subagent_type>` to the rendered description when the type
is explicit. Omitted (general-purpose default or fork) keeps the old
format — absence of the marker is itself the signal.
Tested: visual smoke only — pure UI render change with no behaviour
Confidence: high
Scope-risk: narrow
* feat(agent-tool): nudge verification subagent after edits accumulate
Verification is the only built-in agent that's *required* by the
session-specific guidance for non-trivial implementations, but the
trigger condition ("3+ file edits / backend / infra change") is
evaluated by the main agent from its own work — a classic LLM
self-audit failure mode. The model can convince itself that 4 edits
"are mostly one core change with small adjustments" and skip
verification entirely.
Add a `verification_gate_reminder` attachment that fires once when
the main thread accumulates `editCount >= threshold` (default 3)
file-mutating tool uses (Edit / Write / NotebookEdit) without
invoking the verification subagent. The reminder renders as a
`<system-reminder>` block on the next turn telling the model to
spawn `subagent_type="verification"` before reporting completion,
along with a permission to skip if the change is genuinely trivial.
A verification subagent invocation resets the counter; a previously
fired reminder suppresses re-firing until the next reset, so the
nudge isn't spammed every turn.
Subagents don't see the reminder (it's main-thread only). The gate
also no-ops when the verification agent isn't loaded in the current
session (e.g. SDK build with built-ins disabled). Disabled by
`CLAUDE_CODE_VERIFICATION_GATE_OFF=1`; threshold tuned via
`CLAUDE_CODE_VERIFICATION_GATE_THRESHOLD=N`.
Tested: bun test src/utils/verificationGate.test.ts (10 cases)
Confidence: high
Scope-risk: moderate
* feat(agent-tool): tighten subagent routing and ship real coordinator mode
The flat 15-agent routing has three known weak spots that this commit
addresses together because they share AgentTool.tsx call-path edits:
1. **General-purpose default is a vacuum cleaner.** Omitting
`subagent_type` falls back to general-purpose, which has full tool
access and cheerfully takes on review/security/perf/migration work
that a specialist would have done better and cheaper. Add a regex
heuristic over the prompt: when it strongly signals a specialist
(e.g. "code review", "security audit", "root cause", "migrate from
X to Y") and that specialist is available, refuse the default and
throw an error pointing the model at the right type. Disabled with
`CLAUDE_CODE_GP_DEFAULT_STRICT=0`. Skipped in fork and coordinator
modes (they have their own routing).
2. **No bound on verifier-style loops.** The verification prompt says
"On FAIL: fix, resume, repeat until PASS" — if the verifier
incorrectly keeps flagging the same change, the loop only stops
when the token budget runs out. Add a per-session counter for each
built-in agent type. Cap defaults are 5 for verification (loop
target) and 8 for everything else. When exceeded, throw with a
message asking the model to consult the user. Caps tunable per
type via `CLAUDE_CODE_AGENT_LIMIT_<TYPE>=N`; off via
`CLAUDE_CODE_AGENT_LIMITER_OFF=1`. Counts main-thread invocations
only.
3. **Coordinator mode was a stub.** The `coordinator/workerAgent.ts`
that `getBuiltInAgents()` requires when `COORDINATOR_MODE` is on
was an auto-generated Proxy returning nothing useful. Replace with
a real registry: a new `WORKER_AGENT` (full-tool-access generic
delegate matching the existing coordinator prompt's
`subagent_type: "worker"` references) plus the 11 specialists
minus general-purpose, claude-code-guide, statusline-setup. Also
harden the coordinator's own prompt with a "you orchestrate, you
do not implement" rule (no direct Edit/Write/NotebookEdit) and a
specialist roster table so the coordinator picks the right
delegate. Improve the AgentTool error message when coordinator
mode receives a request without `subagent_type`.
Constraint: cannot restrict the coordinator's own tool pool at the
tool layer without invasive changes to main-thread tool assembly —
enforcement is prompt-level, consistent with the rest of the
architecture.
Rejected: a tighter heuristic that requires a domain-specific phrase
(e.g. "review THIS PR") was considered for #1 but rejected — too
narrow to catch the routing problems we actually see in fleet logs.
Tested: bun test src/tools/AgentTool/specialistRouter.test.ts
bun test src/tools/AgentTool/invocationLimiter.test.ts
bun test src/coordinator/workerAgent.test.ts
(29 cases total, all pass)
Confidence: medium
Scope-risk: moderate
Directive: if specialistRouter false-positives in production, prefer
tightening the regexes over removing the gate — the failure mode
it catches (general-purpose taking specialist work) is worse than
the failure mode of an extra retry.
* docs(desktop): add local Chrome DevTools MCP testing guide
Document the workflow for driving the desktop UI end-to-end via
Chrome DevTools MCP without going through Electron. The pure-browser
dev path normally fails — CSP blocks non-loopback origins, the
H5-disabled CORS gate blocks cross-origin browsers, and the desktop's
loopback exemption clears the H5 token so even the loopback path
401s. The stable bypass is a Vite proxy that same-origins API
traffic to the renderer.
This commit covers the docs side only:
- `docs/desktop/10-local-mcp-testing.md`: full how-to with Quick
Start, MCP control snippets, can/can't test matrix, the exact
reproduction recipes for each `feat/agent-routing-hardening`
change (sentinel, gp-strict, limiter, verification gate, routing
observability), a Windows-specific `electron:dev` workaround, and
a fault dictionary mapping the symptoms each blocker produces back
to its cause.
- `docs/desktop/index.md`: link the new section in the docs index.
- `.kiro/steering/desktop-mcp-testing.md`: concise rule file with
`inclusion: manual` so it loads via #-mention only when relevant,
not as default-included context.
The Vite proxy itself is intentionally NOT committed here. The docs
explain it as a dev-only change the developer adds locally and
either reverts or commits to a separate `feat/desktop-browser-dev-proxy`
branch — the production renderer relies on Electron IPC for the
server URL and must not see the dev proxy in main.
Tested: docs render via VitePress local preview; steering file
loads via Kiro `#desktop-mcp-testing` mention; instructions
verified against the live setup that produced
artifacts/desktop-bootstrapped.png and artifacts/desktop-agents-page.png.
Confidence: high
Scope-risk: narrow
* feat(desktop): unblock pure-browser dev MCP smoke with proxy + forceH5
The standalone-browser dev workflow (vite + Chrome DevTools MCP)
fails three ways without these escape hatches:
1. CSP `connect-src` only allows loopback origins, so the renderer
can't talk to the API server cross-origin even on a LAN.
2. With H5 access disabled the server returns 403 to all
cross-origin browser requests.
3. With H5 access enabled the desktop's loopback exemption
(`requiresH5AuthForServerUrl` returns false for `localhost:1420`)
calls `setAuthToken(null)`, so `buildSessionWebSocketUrl` omits
`?token=`, and the session WS handshake 401s into a 1006 close
reconnect loop. The UI shows "处理中..." but the message never
reaches the server — `wsManager.connections` stays `{}`, server
stdout is silent, and no `POST /api/sessions/.../message` ever
fires.
Two dev-only changes break that deadlock without affecting
production:
- `desktop/vite.config.ts`: add `server.proxy` for `/health`,
`/api`, `/ws`, `/local-file`, `/preview-fs` to `127.0.0.1:3456`.
Same-origins all backend traffic so CSP and CORS pass. Vite dev
only — Electron production path is unaffected because Electron
resolves the server URL via IPC at runtime.
- `desktop/src/lib/desktopRuntime.ts`: add a `?forceH5=1` query
param check in `initializeBrowserServerUrl`. When present, treat
the URL as needing H5 auth even if it's loopback, so the H5 token
survives bootstrap and gets attached to the session WS URL. In
production the param is never set, so behavior is identical.
Workflow with both in place:
http://localhost:1420/?serverUrl=http%3A%2F%2Flocalhost%3A1420
&forceH5=1&h5Token=<TOKEN>
Verified end-to-end via WS sniffer + server log:
- ws://localhost:1420/ws/<sid>?token=... opens
- recv {"type":"connected","sessionId":"..."}
- server logs "[WS] Client connected" + "Starting CLI for ..."
- Sending a "use Task with subagent_type=Explore" prompt produced
a `tool_use_complete` for the Agent tool with
`input.subagent_type="Explore"` exactly as routed.
Also rewrites `docs/desktop/10-local-mcp-testing.md` to record:
- both patches as required steps (was missing the forceH5 piece)
- exact PowerShell commands to mint a one-shot H5 token
- the WebSocket sniffer script and three-signal diagnosis recipe
for "is the backend actually processing"
- the Item 5 (routing observability) gap: the change in
`src/tools/AgentTool/UI.tsx` only affects CLI/Ink rendering;
the desktop's separate `ToolCallGroup.tsx` doesn't surface
`subagent_type` and would need its own follow-up patch.
Tested: ran `bun run src/server/index.ts` + `bun run dev` in the
desktop/, opened the documented URL via Chrome DevTools MCP,
sent a Task-with-explicit-subagent_type chat message, observed
the full WS frame sequence and server log lines listed above.
Confidence: high
Scope-risk: narrow
Directive: do not generalize the forceH5 escape hatch to a
permanent feature — when it's needed, the dev-mode
loopback-clears-token branch is doing the right thing for
Electron and should not be removed.
* feat(desktop): show subagent_type badge next to Agent tool header
The CLI/Ink change in src/tools/AgentTool/UI.tsx surfaces routing
in the terminal transcript as `<description> → <subagent_type>`,
but the desktop renderer is independent (`ToolCallGroup.tsx` /
`AgentCallCard`) and was dropping that signal entirely. Diagnosing
"why didn't it use code-reviewer?" required reading analytics or
guessing.
Add a small `→ <subagent_type>` chip next to the Agent header in
AgentCallCard. The badge mirrors the CLI behavior:
- Renders only when `input.subagent_type` is a non-empty string;
general-purpose / fork / omitted defaults stay quiet.
- Carries `title="subagent_type: <name>"` for hover detail.
- Uses the same border-pill treatment as other secondary
transcript chips so it doesn't compete with the description.
Verified end-to-end via the local Chrome DevTools MCP path: a
real chat with `subagent_type=Explore` renders `Agent → Explore
查找specialistRouter相关文件` in the live transcript, screenshot
saved to artifacts/desktop-routing-arrow-highlighted.png.
Tested: cd desktop && bun run test -- --run -t "subagent_type"
2 tests pass:
- renders subagent_type as → Explore badge next to Agent header
- omits subagent_type badge when input has no subagent_type
Confidence: high
Scope-risk: narrow
* feat(desktop): MCP tool visibility, per-tool toggle, marketplace install
Surface MCP capabilities so the agent never under-uses a configured server,
and add a one-click install path for new servers.
Tool visibility & control:
- GET /api/mcp/:name/tools returns the live tool catalog (handles disabled /
needs-auth / host-preflight-failed / connected states)
- POST /api/mcp/:name/tools/:tool/toggle hides a single tool from the agent,
persisted to ~/.claude.json disabledMcpTools (user scope, all projects);
fetchToolsForClient filters on it and the cache is invalidated on toggle
- Desktop MCP detail page gains an Overview/Tools tab strip (both edit and
read-only views) listing name, description, annotations, JSON schema, plus
an inline enable/disable switch with a "hidden from agent" marker
Marketplace:
- Curated builtin catalog (14 servers across 8 categories) plus opt-in remote
catalog sources cached under ~/.claude/cc-haha/mcp-marketplace.json
- Endpoints: list / refresh / add-source / remove-source
- Desktop marketplace page with category grouping, install dialog (with
required-env prompts), and source management
Plugins:
- Plugin list rows get inline enable/disable + uninstall, matching the MCP
settings UX, instead of requiring users to open the detail panel
- Extract shared ToggleSwitch component
Tested: bun test src/server/__tests__/mcp.test.ts (tools list + per-tool
toggle + marketplace), cd desktop && bun run lint, mcpSettings vitest, and a
browser smoke pass via the local Chrome DevTools MCP flow (tool toggle
persistence, marketplace render, plugin enable/disable + uninstall dialog).
Not-tested: full bun run verify gate
Scope-risk: moderate
* fix(agent-tool): rephrase gp-strict error to stop poisoning sessions
Live testing surfaced an unintended side effect of the gp-strict
redirect message. The original wording embedded attribute-style
fragments like `subagent_type="code-reviewer"`. When that error
came back to the model as a tool result, the model copied the
shape into a TEXTUAL `<tool_use name="Agent">{...}` block instead
of issuing a real tool call — and every subsequent Agent call in
that session degraded to text. Confirmed by inspecting the
session JSONL via /api/sessions: messages 4..N in the affected
session were `assistant: text(...)` carrying simulated tool_use
XML, not `tool_use` content blocks. Reproduced with two unrelated
models (claude-haiku-4.5 and mimo-v2.5-pro) on the same poisoned
session, and crucially DID NOT reproduce in a fresh session with
either model — so the failure is the message text inducing
text-form mimicry, not the model itself.
Fix:
- Extract the redirect text into `formatSpecialistRedirectMessage`
in specialistRouter.ts so it has its own test surface.
- Rephrase as prose that names the parameter and value without
any `key="value"` assignment-and-quotes form. New shape:
"This task looks like a job for the code-reviewer specialist
rather than the general-purpose default. Re-call Agent with
the subagent_type parameter set to code-reviewer. ..."
- Wire AgentTool.tsx through the helper so the throw site is one
line.
Add a regression assertion to specialistRouter.test.ts that the
formatted message contains NO `key="value"` shapes, no XML-ish
open tags, and no `"subagent_type":` JSON fragments — across all
ten specialist names. This is the property the live failure
violated; lock it.
The invocation-limiter message uses shell-style `KEY=N` syntax
(not `key="value"`), did not exhibit the same behavior in
testing, and is left untouched.
Tested: bun test src/tools/AgentTool/specialistRouter.test.ts
17 pass (13 existing + 4 new), 61 expect() calls
Confidence: high
Scope-risk: narrow
Directive: any future change to redirect/error text returned
to the model should preserve the no-key="value" property.
* feat(orchestration): require copying project tool rules into sub-agent prompts
Live test on the desktop `+` orchestration mode showed mimo-v2.5-pro fan
out three sub-agents in parallel for a multi-task PR review prompt — but
none of the dispatched prompts mentioned the project's mandated codegraph
MCP tool. The sub-agents fell back to plain Bash + git diff + grep, so the
project's preferred code-exploration tooling went unused.
Root cause: the orchestrator's `Propagate project conventions` rule was a
soft "for example, restate codegraph rules" bullet. The model read it as
optional. Built-in specialist system prompts (code-reviewer, security-
reviewer, debugger, etc.) explicitly enumerate Bash/grep/git as inspection
tools and never mention codegraph; CLAUDE.md is loaded but the system
prompt outweighs it. The orchestrator was the only place the gap could be
closed, and it skipped it.
This commit upgrades the rule from optional to REQUIRED in the
orchestration system prompt, names the concrete check ("scan CLAUDE.md,
AGENTS.md, .claude/rules"), and tells the orchestrator to copy matching
rules verbatim. Read-only research agents (Explore, Plan) are called out
explicitly because they run with omitClaudeMd:true and absolutely depend
on the orchestrator to forward project tool conventions.
A new ORCHESTRATION_PROPAGATE_RULES_MARKER export plus a regression test
in conversations.test.ts lock the imperative phrasing so it can't be
quietly downgraded back to a soft suggestion.
Wiring is unchanged: built-in code-reviewer/security-reviewer/commit-pr
already inherit CLAUDE.md and have MCP tools available. This is purely a
prompt-strength change, only active when the user enables the desktop
`+` orchestration toggle.
Tested: bun test src/server/__tests__/conversations.test.ts (new test
plus the two existing orchestration-prompt tests pass).
Confidence: high
Scope-risk: narrow
* fix(verification-gate): preserve reminder flag across verification reset
Caught by an orchestrator-mode code-reviewer dispatch on this branch.
When a verification subagent invocation reset the edit counter, the early
return in getVerificationGateState() hardcoded reminderAlreadyFired:false,
discarding any reminderFired flag we'd accumulated walking back from the
tail. Concretely: if a verification_gate_reminder fired AFTER the verify
(i.e. newer than verify in the transcript), the reverse walk would set
reminderFired=true on its way to the verify boundary, then throw it away
on the early return. The gate would then inject a fresh reminder every
turn while the post-verify edit count stayed above the threshold,
ballooning the prompt.
Fix: carry the accumulated reminderFired through the early return. The
reminder we saw is necessarily newer than this verify (we're walking
backwards from the tail and only got here after seeing it), so it's the
valid signal that the model was already nudged for the current edit batch.
Tests: extend verificationGate.test.ts with a "preserves a reminder fired
AFTER a verification reset (no spam loop)" case that fails on the old
hardcoded false and passes with the fix. The pre-existing "ignores a
reminder that fired BEFORE a verification reset" test still passes because
in that ordering the reminder is older than the verify, so reminderFired
stays false on the way back.
Tested: bun test src/utils/verificationGate.test.ts (11/11 pass).
Confidence: high
Scope-risk: narrow
* chat(i18n): rename `协调模式` to `编排模式` (zh / zh-TW)
Brings the simplified- and traditional-Chinese label for the desktop `+`
menu's orchestration toggle in line with the English (Orchestration mode),
Japanese (オーケストレーションモード), and Korean (오케스트레이션 모드)
labels — all five locales now use the same `orchestration` word family.
`协调` was accurate but vague; `编排` matches the term Chinese
developers already see in LangChain, CrewAI, AutoGen, and Anthropic docs,
and tells a user reading just the label what the toggle actually does
(plan → fan out → synthesize) rather than a generic `coordinate`.
UI-text only. No behavior, store, WS message, or i18n-key changes.
* feat(desktop): welcome-screen task cards with one-click orchestration
Adds four quick-start task cards to the new-session welcome screens — both
EmptySession (the no-session-yet entry) and ActiveSession's empty state
(when a fresh session tab has no messages yet). Each card pre-fills the
composer with a starter prompt for a common workflow:
- Pre-merge code review (auto-enables Orchestration mode)
- Investigate a failing test (auto-enables Orchestration mode)
- Write unit tests (no orchestration)
- Explain unfamiliar code (no orchestration)
Cards flagged `orchestrate: true` automatically turn on Orchestration
mode for the session that gets created (or for the live session in
ActiveSession's empty state), so a new user sees fan-out behavior on
first contact instead of having to discover the `+` menu first. This is
the intended discovery surface for the orchestration directive shipped on
this branch.
Plumbing:
- WelcomeTaskCards.tsx is a shared component used by both welcome
surfaces, so card list, copy, and styles stay in one place.
- EmptySession owns its own composer textarea, so card click flips
component state directly (setInput + draftOrchestrate flag) and the
flag is applied via setSessionCoordinatorMode after createSession()
resolves and before connectToSession() — chatStore replays the
persisted toggle on connect, so the CLI launches with the right
--append-system-prompt.
- ActiveSession's session is already live, so a card click dispatches a
`cc-haha:composer-prefill` window event that ChatInput listens for
and applies to its composer state when the sessionId matches the
active tab. Orchestration cards call setSessionCoordinatorMode
directly, which sends `set_coordinator_mode` over WS and triggers a
CLI restart with the orchestration directive — verified live: the
server logs `[WS] Restarted CLI for <id> with runtime override`
immediately after the click.
- Cards never disable an existing Orchestration toggle. Non-orchestration
cards simply leave the toggle alone, so users who pre-enabled
Orchestration via the `+` menu don't have it silently turned off.
- Hidden on phone-sized H5 viewports (composer is already dense there).
i18n: ten new keys under `empty.tasks.*` with localizations for en,
zh, zh-TW, jp, kr (the same five locales the orchestration label
already covers). The orchestration hint reads `将通过编排模式分派给
专家子代理处理` in zh — aligning with the
`协调模式`→`编排模式` rename shipped in the previous commit.
Tests: five new tests in EmptySession.test.tsx covering: cards render on
desktop, hidden on mobile, click pre-fills the composer, orchestration
cards persist coordinator mode after submit, non-orchestration cards
leave coordinator mode untouched. `bun run vitest` 22/22 pass.
`bun run lint` (tsc --noEmit) clean.
Tested live in browser: clicked the Pre-merge review card → composer
filled with the 78-char zh prompt → localStorage carries
`coordinator-modes[<sessionId>]: true` → server log shows the CLI
restarted with `--append-system-prompt`. Screenshot:
artifacts/desktop-welcome-task-cards.png.
Confidence: high
Scope-risk: narrow
* chore(scripts): one-click MCP smoke setup for Windows
Wraps the recurring 4-step setup from docs/desktop/10-local-mcp-testing.md
into a single idempotent script. Same workflow we'd otherwise type by hand
every time we want to drive the desktop UI from Chrome DevTools MCP.
scripts/dev-mcp-test.ps1 does:
1. Health-check the API server on :3456 — fail fast with the start
command if it's down.
2. Health-check Vite on :1420 — fail fast with the start command if
it's down.
3. Confirm Vite's /health proxy is wired through to the server (catches
stale vite.config.ts).
4. Ensure http://localhost:1420 is in H5 allowedOrigins (PUT only when
missing).
5. Regenerate a fresh H5 token via /api/h5-access/regenerate.
6. Build the full URL with serverUrl + forceH5=1 + h5Token, copy it to
the clipboard, and print it.
7. With -Open, also Start-Process the URL in the default browser.
8. With -Quiet, only print the URL on stdout (for piping into other
tools, e.g. un run mcp:test:open chaining).
Surfaced via two npm scripts:
bun run mcp:test # generate URL + clipboard
bun run mcp:test:open # also open in default browser
Deliberate non-goals:
- Does NOT start server / Vite. Those are persistent dev processes the
developer wants to control lifecycle for; auto-starting them from a
one-shot script makes "is it still running?" questions ambiguous and
leaves zombies on script exit. The script tells the user the exact
command to run if either is down.
- Does NOT touch Electron. This workflow is the documented browser path
for Chrome DevTools MCP smoke; the Electron path doesn't need any of
this and runs through bun run electron:dev.
- Does NOT modify vite.config.ts proxy or desktopRuntime.ts forceH5
bypass. Both are already on this branch, and validation of those two
being correctly wired is what step 3 covers.
Doc: docs/desktop/10-local-mcp-testing.md grew a new "step 0 一键脚本"
section pointing at the script and naming the two npm targets, ahead of
the original 4 manual steps so future maintainers find the script first.
Verified by running it: server + vite both up, allowedOrigins pre-existed
so no PUT needed, fresh token issued, URL copied to clipboard, browser
launched into the welcome screen with the four task cards rendering
correctly. Screenshot in artifacts/desktop-welcome-task-cards-final.png.
Confidence: high
Scope-risk: narrow
* feat(desktop): zero-token "Recent activity" panel with hand-off button
Closes the painful gap where opening a new chat in a project means
re-explaining "what was I just doing" to the model. The user explicitly
called out that they don't want the obvious fix (auto-feeding the
previous transcript or an LLM-generated summary) because that burns
tokens on every new session.
This ships a different shape: derive the activity summary on the server
from on-disk state (session JSONL + git working tree), render it as a
read-only panel on the welcome screen so the user sees it, and only
move bytes into the model when the user explicitly clicks "Continue
from here" — and even then, only a 4-5 line hand-off paragraph (~60
tokens), not the previous transcript.
Server (zero LLM, all derivation):
- GET /api/projects/recent-activity?workDir=<abs>&excludeSessionId=<id>
- projectActivityService.getRecentActivity reads:
- sessionService.listSessions to find the most recent meaningful
session (skips empty messageCount=0 sessions and any
excludeSessionId, e.g. the just-created Untitled tab in
ActiveSession's empty welcome state, so the panel surfaces the
ACTUAL previous work session).
- Streams that session's JSONL and derives:
* lastUserMessageExcerpt (160 chars max, mid-word ellipsis)
* filesEdited list — Edit/Write/NotebookEdit tool_use file_paths,
de-duplicated in first-appearance order, capped at 8.
Hard-capped at 50k JSONL lines so giant transcripts don't hang
the welcome render.
- getRepositoryContext (existing, cached) for branch + default
branch + dirty state, plus two cheap git rev-list/status calls
for ahead/behind counts and exact dirty file count.
- Strict timeouts on each git command so the panel never blocks UI.
- Wired into router.ts under case 'projects'.
Frontend:
- RecentActivityCard reads via projectsApi.recentActivity.
- Two paths into it:
1. EmptySession (sidebar "New session" → user picks workDir):
shows once a workDir is chosen. "Open this session" switches
to the previous tab; "Continue from here" prefills the
hand-off into the empty composer's textarea.
2. ActiveSession's empty welcome state (sidebar "在 X 中新建会话"
creates a session immediately): excludeSessionId={activeTabId}
skips the brand-new empty session, hideContinueSessionButton
hides "Open this session" since the user is already on an
empty tab. "Continue from here" dispatches the existing
cc-haha:composer-prefill window event so ChatInput picks it
up — same plumbing the welcome task cards use.
- Auto-refreshes every 60s — git state changes between renders
(commits in another terminal, etc.) get picked up without UI work.
- Hidden on phone-sized H5 (composer is dense enough already).
Hand-off paragraph contents (i18n'd, ~60-100 tokens):
Last session on <branch>: "<title>".
Files touched: <up-to-5-files> (+N more).
Local is ahead of upstream by N commit(s).
N file(s) have uncommitted changes.
Please continue from there. Pick up by ...(describe the next step).
Token cost summary:
- Render: 0 tokens. Pure on-disk derivation, never sent to a model.
- "Open this session": 0 tokens. Just a tab switch.
- "Continue from here": ~60-100 tokens, ONLY if the user types more
and presses send. The user sees the prefill in the textarea before
sending and can edit or delete it.
i18n: 18 new keys (empty.recentActivity.*) localized for the same five
locales as the orchestration toggle (en/zh/zh-TW/jp/kr).
Live-tested via Chrome DevTools MCP on this branch:
- Opened cc-haha welcome path.
- Server returns correct shape: branch=feat/agent-routing-hardening,
aheadCount=6, dirtyCount=13, lastSession with 10 messages and
correct title.
- excludeSessionId correctly skips the empty just-created session and
surfaces the previous "请审查我当前分支..." session.
- "Continue from here" click prefills the textarea with the 152-char
Chinese hand-off paragraph; localStorage and WS state untouched
(zero token cost confirmed).
- Screenshots: artifacts/desktop-recent-activity-card.png and
artifacts/desktop-recent-activity-handoff.png.
bun run lint passes (tsc --noEmit clean).
Confidence: high
Scope-risk: moderate (new endpoint, but read-only and isolated; new UI
panel, but additive only — empty workdir or no prior sessions just
hides the card)
Tested: live MCP smoke per above.
Not-tested: server-side unit tests for projectActivityService (planned
follow-up; live integration validated the happy path end-to-end).
* fix(desktop): compact recent-activity card so composer stays in view
Live MCP smoke caught a layout regression. Welcome screen vertical
budget on a 923px viewport is roughly:
79 tab bar
+ ~250 hero block (logo + title + subtitle)
+ ~165 task cards
+ ~222 composer (ChatInput in hero variant)
+ ~64 flex padding
≈ 780px before activity panel
The first cut of RecentActivityCard rendered a 235px column block
(title row, chips row, italic excerpt row, file-chips row, action row).
Together with the task cards that pushed total content to ~410px
beyond what fits, and ActiveSession's empty-state wrapper used
flex flex-1 + justify-center without overflow handling — so the
sibling ChatInput got pushed below viewport bottom (composer.bottom
1112 on a 923 viewport, visible:false confirmed via DOM measurement).
Two changes:
1. Compact the card to ~127px (down 108px, roughly half) by collapsing
to a single horizontal row: icon | title + chips column | action
buttons. The italic last-user-message excerpt and the file-name
chip strip both go away — they're nice-to-haves, not load-bearing.
The data they carried is preserved: filesEditedCount stays as a
chip with a tooltip showing the first 5 file basenames; the lead
excerpt is still in the hand-off paragraph the "Continue from here"
button injects, so the user gets it where it counts (in the
composer) instead of as ambient ornament on the welcome screen.
Action buttons collapse their labels under sm: breakpoints to keep
the card single-row even in narrow side panels.
2. Add min-h-0 + overflow-y-auto to ActiveSession's isEmpty wrapper.
Belt-and-suspenders: future taller content (extra cards, longer
localized strings) now scrolls inside the welcome region instead of
shoving the composer offscreen. Composer remains a flex sibling and
stays anchored at the bottom regardless of content height above it.
Verified live in MCP browser:
recentActivity height: 235 → 127px
composer.bottom: 1112 (offscreen) → 907 (visible, on a 923 viewport)
textareaVisible: false → true
Tested across two projects with very different activity profiles
(cc-haha: short title + 0 files edited; layout-editor: long title +
20 files edited + 1876 messages). Both render in single horizontal
row.
Screenshot: artifacts/desktop-recent-activity-compact.png
bun run lint passes (tsc --noEmit clean).
Confidence: high
Scope-risk: narrow (CSS / layout only, no behavioral change).
---------
Co-authored-by: 你的姓名 <you@example.com>
Add a WhatsApp adapter backed by Baileys linked-device auth, plus desktop QR binding UI, server config endpoints, sidecar startup wiring, tests, and documentation.
Constraint: Uses WhatsApp Web linked-device auth, not Meta WhatsApp Business Cloud API.
Tested:
- cd adapters && bun run check:adapters
- bun test src/server/__tests__/adapters.test.ts
- cd desktop && bun run check:desktop
- bun run check:native
- bun run check:persistence-upgrade
- bun run check:docs
Not-tested:
- Live WhatsApp QR pairing, because no WhatsApp account/device was exercised here.
- bun run check:server, because the existing src/server/__tests__/conversations.test.ts timeout still fails independently.
Confidence: medium
Scope-risk: moderate
Surface expanded error output for tool cards whose previews previously returned before rendering the result body. Keep successful Bash/Read/Edit/Write outputs hidden as before while exposing error details with wrapping and copy support.
Tested: cd desktop && bun run test -- src/components/chat/chatBlocks.test.tsx
Tested: bun test src/server/__tests__/conversations.test.ts -t "should switch from bypass permissions back to default without restarting" --timeout=20000
Tested: bun run verify
Confidence: high
Scope-risk: narrow
Tested:
- cd desktop && bun run test -- src/__tests__/pluginsSettings.test.tsx src/stores/pluginStore.test.ts --run --reporter=verbose --pool=forks --maxWorkers=1 --minWorkers=1
- bun run check:desktop
- git diff --check
Scope-risk: moderate
Confidence: high
方案3 (desktop, manual-guided): when compactions keep firing only a turn or two
apart — the same thrash the CLI circuit breaker trips on — chatStore now appends
a one-time visible system notice suggesting the user start a fresh session
(the prior summary stays in the current one). Detection lives in module-level
state (compactionThrashBySession) so PerSessionState is untouched; counts user
turns between compactions, suggests after 3 rapid ones, deduped per session and
reset on /clear. New i18n key chat.contextExhausted (en/zh/zh-TW/jp/kr).
Also includes in-progress orchestration/coordinator work on the same files
(orchestrationPrompt.ts, conversationService coordinatorMode --append-system-prompt,
ws handler/events, chatStore, ChatInput, sessionRuntimeStore, types/chat) —
committed together per request.
Tested:
- bunx vitest run desktop/src/stores/chatStore.test.ts (102 pass, incl. new
方案3 rapid-compaction suggestion + spread-out negative case)
- cd desktop && bun run lint (clean)
- get_diagnostics clean across changed server + desktop files
Not-tested: full bun run check:server / check:desktop gates; pre-existing WS
runtime-restart integration tests are flaky in this env (CLI code 143).
Confidence: medium-high
Scope-risk: moderate
- Update source: desktop/package.json publish.owner NanmiCoder -> 706412584 (electron-updater
now checks this fork's releases via app-update.yml). Also bump homepage and the legacy
Tauri updater endpoint to the fork.
- About page: GITHUB_REPO / issues / releases / changelog and the displayed repo name now
point to 706412584/cc-haha. Sidebar repo link and ActivitySettings profile subtitle too.
- Attribution: original author (NanmiCoder + Bilibili/Douyin/Xiaohongshu social links) is
preserved unchanged. Added a new "Fork maintainer" credit (706412584) with i18n keys
settings.about.forkMaintainer / forkMaintainerHint across en/zh/zh-TW/jp/kr.
Why: this is a self-maintained fork shipping its own builds; pointing the updater at upstream
risked overwriting custom builds with upstream releases and hid the fork's own releases.
Tested:
- bunx vitest run src/pages/ActivitySettings.test.tsx src/__tests__/generalSettings.test.tsx (59 pass)
- cd desktop && bun run lint (clean)
Not-tested: full verify (long-running)
Confidence: high
Scope-risk: moderate
Built-in agents:
- Add debugger, security-reviewer, refactor, migration, docs-writer, performance, commit-pr built-ins and register them in getBuiltInAgents().
Desktop:
- AskUserQuestion prompts no longer vanish silently: when an unanswered question card is cleared by turn end (message_complete / error) — e.g. a malformed question call — a visible system notice (chat.questionDropped) is appended instead. Added across en/zh/zh-TW/jp/kr.
Versioning:
- Bump desktop/package.json to 0.5.5 and add release-notes/v0.5.5.md.
Tested:
- bunx vitest run desktop/src/stores/chatStore.test.ts (99 pass, incl. dropped-question notice for message_complete + error, and no notice for non-AskUserQuestion)
- bun test src/tools/AgentTool/builtInAgents.test.ts (pass)
- cd desktop && bun run lint (clean)
- build:windows-x64 + package-smoke (PASS, Claude-Code-Haha-0.5.5-win-x64.exe)
Not-tested: full bun run verify / check:server (long-running)
Confidence: high
Scope-risk: moderate
ChatInput / SkillPickerMenu:
- + menu now has 4 entries: file, slash command, Skills, Plugins.
- Skills/Plugins open an inline picker above the composer (mirrors the file-search popover: ↑↓ navigate, Enter pick, Esc dismiss). Picking inserts a "@skill:<name>" / "@plugin:<name>" token at the cursor — visible to the user, also legible to the agent as "use this skill/plugin".
Queue "send now":
- sendQueuedMessageNow no longer aborts the running turn or promotes-and-waits — it just sends the message immediately. Removes the prior "Request was aborted" / code 143 retry loop caused by mid-turn stop_generation.
Theme follow-system persistence:
- settingsStore.loadSettings now honours a locally stored "system" theme over whatever concrete value the server last saw, since the server intentionally rejects "system". Fixes follow-system reverting to a concrete theme on every restart.
- uiStore.test.ts: updated the toggleTheme cycle test to include the system step (was a stale failure independent of these changes).
FileReadTool:
- Treat pages: "" as undefined ("read whole file") so the agent's empty-string slips don't trap the tool in a validation-error retry loop.
i18n:
- Added chat.openSkills / openPlugins / skillPicker.{title,empty} / pluginPicker.{title,empty} / sendNow across en / zh / zh-TW / jp / kr.
- Did NOT touch unrelated settings.skills.recommended.* / settings.plugins.* additions present in the working tree from another in-progress task.
Tested:
- bunx vitest run src/stores/chatStore.test.ts -t "message queue" (10 pass)
- bunx vitest run src/stores/settingsStore.test.ts src/stores/uiStore.test.ts (32 pass)
- bun run lint (desktop tsc --noEmit, clean)
- Windows package-smoke after build:windows-x64 (PASS)
Not-tested: full bun run check:desktop / check:server (long-running)
Confidence: high
Scope-risk: narrow
v0.5.3's one-shot skip only blocked a single auto-drain, but a Stop emits
multiple idle events (message_complete + status idle); the second one still
drained one queued message and flipped the button back to running. Replace
the one-shot skip with a sticky queueDrainPaused flag: Stop pauses all
auto-drains until the user sends their next message (which clears it and
fires immediately, ahead of the queue). The queue then resumes FIFO on the
next idle. Bumps desktop app to 0.5.4 with release notes.
Tested: tsc --noEmit; Vitest chatStore 94 passed (incl. multi-idle stop /
priority message / queue resume); browser end-to-end (Stop keeps button at
Run with queue intact, priority send immediate, queue resumes); Windows x64
NSIS package + package-smoke PASS.
Scope-risk: narrow
Confidence: high
Stop no longer flushes the queue: a user-initiated Stop now skips exactly the
auto-drain triggered by its resulting idle (one-shot guard). The queue stays
intact, the next message the user sends fires immediately (priority, not
queued — even with items waiting), and the queue resumes FIFO on the next idle
after that turn. Queue enqueue/drain/edit mechanics are otherwise unchanged.
Also removes the Buy-Me-a-Coffee / donation section from README (zh/en).
Bumps desktop app to 0.5.3 with release notes.
Tested: desktop tsc --noEmit; Vitest chatStore 94 + pages/ActiveSession 43
passed (incl. stop-no-flush / priority-message / queue-resume case); Windows
x64 NSIS package + package-smoke PASS.
Scope-risk: narrow
Confidence: high
Desktop chat message queue (v0.5.2):
- Queue follow-up messages (Enter) while the agent is busy; FIFO auto-drain
on true idle. Collapsible, height-capped to-do panel above the composer so
it never inflates the composer. Per-item move-to-top/edit/delete/clear.
Never drains mid-stream, during tool execution, or while a permission
prompt is pending; Stop cancels the current turn but keeps the queue.
Per-session isolation. In-memory only (no persistence schema change).
Also included in this commit:
- Settings provider form: model-id comboboxes + fetch-models + per-slot
context-window auto-fill.
- Bundled skills: defineGoal, pdf, screenshot.
- Bump desktop app to 0.5.2 with release notes.
Tested: desktop tsc --noEmit; Vitest chatStore/pages/ActiveSession 136 passed
(incl. 7 queue tests); browser end-to-end queue smoke; Windows x64 NSIS
package + package-smoke PASS.
Not-tested: full check:desktop suite has pre-existing unrelated failures
(electron packaging, theme cycling, ThinkingBlock label); check:server.
Scope-risk: moderate
Confidence: medium
In-progress generations were interrupted when a set_runtime_config
arrived mid-stream: the handler immediately stopped and restarted the
CLI subprocess. Track per-session busy state from outbound status
events and queue the restart, applying it (with the latest override,
collapsing multiple toggles) once the session returns to idle.
Bumps desktop app to 0.5.1 with matching release notes.
Tested: desktop tsc --noEmit; Windows x64 NSIS package + package-smoke.
Not-tested: check:server, desktop Vitest.
Scope-risk: narrow
Confidence: medium
Commit 449ff0b0 changed completed thinking blocks to render the
'thinking.labelDone' title ("Thought"/"已思考") instead of the static
"Thinking" label, and updated ThinkingBlock.test.tsx but not
chatBlocks.test.tsx. The three inactive/default-state cases there still
queried the toggle button by /Thinking/ and failed. Match the new
done-state label (/Thought/); the active-state case is unchanged.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Main added two TranslationKeys after this branch's base — 'thinking.labelDone'
(the "Thought" label shown after thinking completes) and
'slashCmd.agent.description' — which the jp/kr/zh-TW locale files did not yet
cover, so the Record<TranslationKey, string> contract failed tsc after merging
main. Add both keys to each new locale:
- jp: '思考完了' / '選択した Agent でプロンプトを実行'
- kr: '사고 완료' / '선택한 Agent로 프롬프트 실행'
- zh-TW: '已思考' / '使用指定 Agent 執行提示'
en/zh are unchanged. `tsc --noEmit` is now clean and the i18n + timestamp
suites pass.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The desktop notification poller fired on mount, racing the bootstrap that
resolves the dynamic server URL and confirms /health. Its first requests hit
the uninitialized default base URL and failed with "Failed to fetch", logging
spurious client_api_request_failed warnings to the diagnostics panel.
Add a whenDesktopServerReady() signal resolved once initializeDesktopServerUrl
sets the base URL and the healthcheck passes, and gate the poller on it so it
only starts once the server is reachable.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The thinking block title always rendered the static "思考中"/"Thinking"
label; isActive only toggled the animated dots. Once thinking finished
the dots disappeared but the in-progress text stayed. Switch the label
to "已思考"/"Thought" when the block is no longer active.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Indent session rows under their project group and switch project folder icons between open and closed states when collapsed.
Tested: cd desktop && bun run test --run src/components/layout/Sidebar.test.tsx -t "groups sessions by project|collapses a project group"
Tested: cd desktop && bun run test --run src/components/layout/Sidebar.test.tsx
Tested: bun run check:desktop
Tested: Browser plugin smoke on http://127.0.0.1:3456/ confirmed first project open -> closed state, icon state, and pl-6 session indentation.
Confidence: high
Scope-risk: narrow
Normalize image blocks loaded from transcript history back into renderable data URLs and keep generated image metadata out of the visible user bubble. Image source metadata is applied in order so multi-image messages retain the correct paths and names.
Tested: bun run test -- --run src/stores/chatStore.test.ts
Tested: bun run check:desktop
Confidence: high
Scope-risk: narrow
(cherry picked from commit 82381e8d647fa19e20853a96b9681fb548c17f0a)
Close the native preview WebContentsView when the Electron renderer starts a top-level navigation so refreshed session pages cannot leave the in-app browser surface behind.
Fixes#680
Tested:
- bun run verify
Confidence: high
Scope-risk: narrow
Use frameless Electron chrome only on Windows and remove the native Windows application menu so the packaged app matches the previous Tauri-style desktop surface.
Add a Windows-only manual drag fallback for desktop drag regions, while excluding tab reorder targets and preserving macOS/Linux native chrome and menu behavior.
Tested: cd desktop && bun run test --run electron/services/menu.test.ts electron/services/windows.test.ts src/hooks/useElectronWindowDragRegions.test.tsx src/components/layout/TabBar.test.tsx src/components/layout/Sidebar.test.tsx src/lib/desktopHost/electronHost.test.ts electron/ipc/capabilities.test.ts
Tested: cd desktop && SKIP_INSTALL=1 bun run build:windows-x64
Tested: Computer Use Windows packaged app smoke verified no native menu, custom controls, drag regions, tab reorder, close-to-background, and deepseek-v4-pro provider response FINAL_WINDOWS_ELECTRON_REAL_PROVIDER_OK.
Not-tested: full bun run verify.
Constraint: keep custom frameless behavior scoped to win32 so macOS and Linux native chrome paths remain intact.
Confidence: high
Scope-risk: moderate
- Rewrite release-notes/v0.4.0.md to match the historical style (no emoji,
Highlights/Fixes/Notes), keep it user-facing only (drop release-process
notes), and correct Linux (supported since the Tauri builds, not new).
- README.md / README.en.md: replace Tauri references with Electron, list
macOS / Windows / Linux, and point first-launch approval to the guide.
- Rewrite docs/desktop/04-installation.md for Electron: Electron asset
names, Linux section, and the unsigned-macOS flow (clear the DMG quarantine
before double-clicking; drop the WebView2/right-click-open leftovers).
- install-macos-unsigned.sh: keep the same-folder DMG flow, no online download.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Bump the Electron desktop package version to 0.4.0, publish a macOS unsigned install helper, and let the release workflow continue when Developer ID signing is not configured.
Tested: bash -n desktop/scripts/install-macos-unsigned.sh
Tested: bun test scripts/pr/release-workflow.test.ts
Tested: bun run scripts/release.ts 0.4.0 --dry
Tested: git diff --check
Tested: bun run check:docs
Tested: bun run check:policy
Confidence: high
Scope-risk: moderate
Ensure Electron Builder has the project URL and maintainer metadata required by Linux deb targets, and lock the fields with release workflow coverage.
Tested: bun test scripts/pr/release-workflow.test.ts
Tested: bun run check:policy
Tested: bun run check:native
Tested: bun run verify
Confidence: high
Scope-risk: narrow
Use container queries for the activity summary grid so the Token usage panel responds to its own width instead of the full desktop viewport. This prevents loose medium-width layouts and over-compressed five-column cards when the settings page is shown with sidebars.
Tested:
- cd desktop && bun run test -- src/pages/ActivitySettings.test.tsx --run --reporter=verbose --pool=forks --maxWorkers=1 --minWorkers=1
- cd desktop && bun run test -- src/theme/globals.test.ts --run --reporter=verbose --pool=forks --maxWorkers=1 --minWorkers=1
- bun run check:desktop
- Electron smoke at 1180px and 900px against the local dev server
Not-tested:
- Coverage report; this is a presentation-only desktop UI change.
Confidence: high
Scope-risk: narrow
The sidebar title area also needs to participate in Electron's CSS app-region chrome. Mark only the sidebar title/header region as draggable and keep the full sidebar body out of the drag region so session rows, search controls, and project actions remain normal interactions.
Constraint: Electron window dragging is driven by CSS app-region regions after the migration
Rejected: Keep the sidebar-wide startDragging mouse handler | Electron does not use that as the active drag path and it misses the left title gap
Confidence: high
Scope-risk: narrow
Directive: Keep sidebar body interactions outside the drag region unless a real titlebar affordance is added there
Tested: cd desktop && bun run test src/components/layout/Sidebar.test.tsx --run
Tested: bun run check:desktop
Drop the explanatory comment added earlier - notifications work as-is, so the
notification service stays byte-for-byte identical to main.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Adds a CSP meta tag that hardens default-src/object-src/base-uri while keeping
script/style 'unsafe-inline'+'unsafe-eval' (Emotion CSS-in-JS injects runtime
<style> tags, the startup watchdog is inline, shiki/mermaid/Vite use eval) and a
permissive connect-src (localhost sidecar + ws + https) so renderer fetches and
dev HMR keep working. Needs a runtime smoke on dev + packaged builds before any
tightening.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- serverRuntime injects CLAUDE_CODE_POWERSHELL_PATH from the user's chosen shell
(readDesktopTerminalConfig + resolveDesktopTerminalShell) on Windows, so the
agent PowerShellTool honors the same shell as the UI terminal. Best-effort:
never blocks startup, never overrides an explicit env var, only forwards
pwsh/powershell selections (not cmd/custom). Regression from the Tauri build.
- document that notificationPermissionState reflects OS capability, not macOS
authorization (no Electron API exists; the 'failed' lifecycle is the real
signal) instead of calling the non-existent systemPreferences.getNotificationSettings
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
killSidecar gains a sync flag (spawnSync taskkill on Windows); serverRuntime
stopAll threads it through; before-quit now shuts down synchronously so the
Windows taskkill completes before the process exits.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- applyWindowsAppUserModelId() so Windows attributes toast notifications to the
app (kept in sync with build.appId via a test); no-op on macOS/Linux
- main window: setWindowOpenHandler denies uncontrolled popups, routes http(s)
links to the system browser; intentionally no will-navigate guard so dev HMR
reloads keep working
- preview view: denies popups + blocks non-http(s) navigation (file:/custom
schemes) while allowing in-page http(s) browsing
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- mac.notarize=true + hardenedRuntime + entitlements so a signed CI release
actually notarizes (gatekeeper smoke + Squirrel.Mac auto-update need it)
- entitlements grant disable-library-validation for the Bun sidecar/node-pty
- local unsigned build passes -c.mac.notarize=false so electron:package still
works without an Apple account
- release signing-preflight now hard-requires only the Apple secrets; Windows
cert is optional (unsigned NSIS still auto-updates, just SmartScreen warning)
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Bare absolute paths like /icons/bilibili.svg failed under Electron's
file:// protocol. Route them through publicAssetPath so they resolve
against the relative base URL, matching the GitHub and app icons.
Electron handles custom draggable chrome through CSS app-region rules, not the old runtime startDragging path. Mark the tab strip and empty scroll gutter as native drag regions while keeping tab items and controls explicitly no-drag so tab reordering and close/tool buttons keep receiving pointer events.
Constraint: Electron drag regions swallow pointer events unless interactive children are marked no-drag
Rejected: Keep calling startDragging from the empty gutter | Electron desktopHost does not expose that as the active migration path
Confidence: high
Scope-risk: narrow
Directive: Do not mark tab items themselves as drag regions without revalidating tab reorder behavior
Tested: cd desktop && bun run test src/components/layout/TabBar.test.tsx --run
Tested: cd desktop && bun run lint
Tested: bun run check:desktop
The chat reference action was still tied too closely to message-local
mouseup timing, and the floating fixed-position control stayed inside
virtualized message DOM. In Electron Chromium that made multi-line ranges
race selection settlement and let transformed ancestors offset the button
away from the viewport position we calculated.
This reads settled document selections after pointerup/selectionchange,
portals the action to document.body, and prefers right-side placement for
multi-line selections.
Constraint: Electron Chromium selectionchange can settle after message-local mouse events
Rejected: Keep the popover inside the message node | transformed/virtualized ancestors offset fixed positioning in real browser layout
Confidence: high
Scope-risk: narrow
Directive: Keep chat selection actions portaled; do not reparent under virtualized message rows without browser-coordinate verification
Tested: cd desktop && bun run test -- src/components/chat/MessageList.test.tsx
Tested: bun run check:desktop
Tested: Playwright Chromium smoke for multi-line selection, single-line selection, and outside-click dismissal on local desktop harness
Add jp / kr / zh-TW translations and wire them into the i18n runtime so the
desktop app can switch among English, Simplified Chinese, Traditional Chinese,
Japanese, and Korean.
- new locale files jp.ts / kr.ts / zh-TW.ts with full TranslationKey coverage
- register the locales in the i18n index and extend the Locale union
- accept the new codes in settingsStore.getStoredLocale (default stays zh)
- add language-switcher entries (简体中文 / 繁體中文 / 日本語 / 한국어)
- localize chat message timestamps: Han 年月日 for zh/zh-TW/jp, Intl ko-KR for kr
- extend the DATE_LOCALES map in ActivitySettings (ja-JP / ko-KR / zh-TW)
- tests: formatMessageTimestamp locale branches + i18n locale resolution
Korean terminology follows the Microsoft Korean localization style guide
(새로 고침 / 사용·사용 안 함 / 이름 바꾸기, 합니다-style sentences).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Chat selection references could miss drag gestures that ended outside the
message bubble after the Electron migration. The chat transcript now tracks
selection gestures at the document pointer-up boundary and repositions the
shared selection action near the selected text with above-then-right placement.
Constraint: Electron/WebView selection ranges are not always stable during the message-local mouseup event
Rejected: Add a new selection popover system | the existing shared selection hook already covers chat and workspace dismissal behavior
Confidence: high
Scope-risk: narrow
Directive: Keep chat and workspace selection popovers on the shared positioning/dismissal hook unless their behavior intentionally diverges
Tested: bun run test -- src/components/chat/MessageList.test.tsx -t "selected-message action"
Tested: bun run test -- src/components/chat/MessageList.test.tsx
Tested: bun run check:desktop
Tested: in-app browser smoke at http://127.0.0.1:5181/ with zero console errors
Not-tested: Packaged Electron manual drag selection smoke
Related: #351
Selecting a concrete /agent entry from the composer suggestions should prepare the command and leave focus in the editor so the user can type the required prompt. The Enter send shortcut still applies after the suggestion menu is closed, and exact non-agent slash commands keep their existing direct execution path when they remain highlighted.
Constraint: The desktop composer supports configurable Enter vs Ctrl/Cmd+Enter sending.
Rejected: Special-case only /agent entries | the highlighted suggestion should consistently win while the menu is open.
Confidence: high
Scope-risk: narrow
Directive: Keep ChatInput and EmptySession slash-key handling aligned with shared send shortcut behavior.
Tested: cd desktop && bun run test -- --run src/components/chat/composerUtils.test.ts src/components/chat/ChatInput.test.tsx src/pages/EmptySession.test.tsx
Tested: bun run check:desktop
Not-tested: Live backend agent-list integration beyond mocked desktop composer coverage.
Electron was showing the main BrowserWindow before renderer load completed, so macOS could paint a blank window surface behind the menu bar. Persisted y=0 window state could also restore the titlebar under the menu-bar work area on external displays. Delay the initial show until the renderer entry is loaded, clamp restored macOS bounds into the display workArea, skip the macOS status-bar tray, and unhide the app before focusing restored windows.
Constraint: macOS external displays expose menu-bar and status-item chrome differently from Windows and Linux.
Rejected: Remove the native application menu | it would break expected macOS menu behavior without fixing the pre-load window surface.
Confidence: high
Scope-risk: narrow
Directive: Do not reintroduce pre-load main-window show without validating macOS external-display menu-bar rendering.
Tested: cd desktop && bun test electron/services/windows.test.ts electron/services/tray.test.ts electron/services/singleInstance.test.ts electron/services/menu.test.ts
Tested: bun run check:desktop
Tested: bun run check:native
Tested: git diff --check
Not-tested: Live dual-external-monitor screenshot smoke.
Complete the Electron replacement boundary before merging by removing the renderer-side Tauri host fallback, tightening H5/browser access so only desktop navigation is tokenless, and moving desktop release publication to a tag-driven GitHub Actions matrix with a single final publish job.
Constraint: H5/browser capability access must not gain tokenless access through localhost or retired Tauri origins
Constraint: Desktop release artifacts must be built by GitHub Actions from version tags, not treated as local build outputs
Rejected: Keep localhost browser origins trusted for convenience | local browser contexts can access loopback services and must use the H5 token path
Rejected: Publish from each matrix job | partial releases can be created before all platforms finish
Confidence: high
Scope-risk: broad
Directive: Do not reintroduce Tauri origins or localhost browser origins into the trusted desktop origin set without a reviewed security design
Tested: bun test src/server/__tests__/h5-access-policy.test.ts src/server/__tests__/h5-access-auth.test.ts src/server/__tests__/diagnostics-service.test.ts src/server/middleware/cors.test.ts
Tested: bun test scripts/pr/release-workflow.test.ts scripts/release-update-metadata.test.ts
Tested: bun run check:desktop
Tested: bun run check:native
Tested: git diff --check
Not-tested: bun run check:server is blocked by expired quarantine entries server:cron-scheduler, server:providers-real, server:tasks, server:e2e:business-flow, server:e2e:full-flow
Electron desktop runs network-sensitive OpenAI OAuth token exchange in the sidecar process, so the sidecar now receives system proxy env derived from Electron's cross-platform proxy resolver and the OAuth token client uses the existing proxy fetch options. General manual proxy settings also document and preserve authenticated proxy URLs.
The macOS fullscreen black-screen path is addressed by avoiding native fullscreen Spaces for app fullscreen toggles and by leaving fullscreen before hiding or closing the window.
Constraint: Electron packaged apps may not inherit shell HTTPS_PROXY env when launched from Finder.
Constraint: Manual authenticated proxies must remain standard HTTP(S) proxy URLs for Bun/undici compatibility.
Rejected: Store proxy username and password as separate fields | would require new secret-storage semantics and migration beyond this bugfix.
Rejected: Use native macOS fullscreen Spaces for the desktop app | reproduced black-screen behavior when hiding/closing from fullscreen.
Confidence: high
Scope-risk: moderate
Directive: Do not remove sidecar proxy env injection without retesting OpenAI OAuth from a packaged app launched outside a shell.
Tested: bun test src/services/openaiAuth/client.test.ts src/server/__tests__/haha-openai-oauth-service.test.ts
Tested: bun test src/server/__tests__/network-settings.test.ts
Tested: cd desktop && bun run test -- src/__tests__/generalSettings.test.tsx --run
Tested: cd desktop && bun run check:electron
Tested: git diff --check
Not-tested: bun run check:server blocked by expired quarantine entries server:cron-scheduler, server:providers-real, server:tasks, server:e2e:business-flow, server:e2e:full-flow
Not-tested: live OpenAI OAuth through a corporate authenticated proxy
Electron's sidecar runs outside app.asar, so H5 static files must be available as normal unpacked files. Point the sidecar at the unpacked renderer dist and keep a server fallback for stale app.asar-style paths.
Constraint: Packaged Bun sidecars cannot read app.asar paths with ordinary fs stat calls.
Rejected: Serve H5 from app.asar directly | the external sidecar is not Electron and does not get asar filesystem support.
Confidence: high
Scope-risk: narrow
Directive: Keep package-smoke checking app.asar.unpacked/dist/index.html before changing asarUnpack or H5 dist paths.
Tested: bun test src/server/__tests__/h5-access-auth.test.ts src/server/__tests__/h5-access-policy.test.ts
Tested: bun test desktop/electron/services/sidecarManager.test.ts scripts/quality-gate/package-smoke/index.test.ts
Tested: bun run check:server
Tested: cd desktop && bun run check:electron
Tested: git diff --check
Tested: SKIP_INSTALL=1 SIGN_BUILD=0 MAC_TARGETS=dmg desktop/scripts/build-macos-arm64.sh
Tested: packaged sidecar curl /?serverUrl=...&h5Token=... returned HTTP 200
Not-tested: Gatekeeper notarization for the local ad-hoc DMG
Introduce the Electron desktop shell alongside the existing React renderer and local Bun server boundary. The migration keeps the DesktopHost contract explicit across Tauri, Electron, and browser runtimes while adding Electron main/preload services for dialogs, shell, notifications, updates, tray/window lifecycle, terminal, preview WebContentsView, app mode, and release/package validation.
The commit also carries the latest local main desktop command updates, including agent slash entries and hidden-by-default markdown thinking details, so the packaged Electron build matches the current main UX surface.
Constraint: React renderer, local Bun server, REST/WebSocket, and sidecar boundaries must remain reusable during the migration
Constraint: macOS dev packages are ad-hoc signed and cannot prove Developer ID notarization or Gatekeeper release launch
Rejected: Browser-only smoke validation | it cannot exercise native dialogs, keychain prompts, notification behavior, or packaged app startup
Confidence: medium
Scope-risk: broad
Directive: Do not remove Tauri host support until signed Electron release artifacts pass native OS smoke on macOS, Windows, and Linux
Tested: bun run check:desktop
Tested: cd desktop && bun run check:electron
Tested: CSC_IDENTITY_AUTO_DISCOVERY=false bun run electron📦dir
Tested: bun run test:package-smoke --platform macos --package-kind dir --artifacts-dir desktop/build-artifacts/electron
Tested: Computer Use read packaged Electron app window at desktop/build-artifacts/electron/mac-arm64/Claude Code Haha.app
Not-tested: Developer ID signed/notarized Gatekeeper launch
Not-tested: Real OS notification click-to-session action
Not-tested: Windows and Linux packaged app smoke on real hosts
Project entry HTML often only mounts a dev-server app, while built output can be served statically. The desktop open-with policy now only offers the in-app browser for static HTML candidates, and preview-fs rewrites built HTML root-relative assets under the workspace preview path.
Constraint: Frontend project index.html needs a dev server instead of preview-fs static serving
Rejected: Treat every .html file as browser-previewable | project entry HTML can render blank or with missing assets
Confidence: high
Scope-risk: moderate
Tested: cd desktop && bun run check:desktop
Tested: bun run check:server
Tested: git diff --check
Not-tested: bun run verify was intentionally stopped at user request
