Porting Notes

Running log of deliberate deviations from the pristine reference_projects/clawcodex/ui-tui sources. Everything not listed here is a verbatim copy.

Stage 3 — app source copy

• src/ and scripts/{build,build-dev,profile-tui}.mjs copied byte-identical from ui-tui (verified with diff -r).
• vitest.config.ts: testTimeout raised to 120s. The upstream cursor-drift regression test walks every typing prefix through a real Ink render and needs >5s on this hardware (WSL2); it passes given time.
• 7 tests marked it.skip with a KNOWN-SKEW(upstream) comment. All 7 fail identically in the pristine ui-tui checkout with its own lockfile (verified 2026-08-18), i.e. the upstream tests drifted from the upstream sources before the snapshot was taken; the sources are the authority for look/feel, so the stale expectations are skipped rather than "fixed":
  • createGatewayEventHandler.test.ts — expects Patch("foo.ts")-style quoted tool-trail labels and an Args: verbose block that buildToolTrailLine no longer emits.
  • statusRule.test.ts (2) — expects a cost segment that statusBarSegments no longer returns.
  • useConfigSync.test.ts (2) — expects the default indicator style to be kaomoji; the source default is star.
  • virtualHeights.test.ts (1) — expects a different wrap estimate for compound user prompts.
• slashParity.test.ts shells out to the Python clawcodex_cli package to compare slash catalogs and self-skips ("best effort") when the module is missing, as it is here.

Revisit: when a stage touches one of these areas, reconcile the skipped expectation with the observed behavior instead of leaving it skipped.

• Local flake class: the interactive .tsx suites (modelPicker, questionPromptMount, ...) drive fake stdin with fixed 20ms delays and can fail under full-suite parallel load on slow machines while passing consistently in isolation. Mitigated with retry: 1 in vitest.config.ts — a real regression still fails twice.

Stage 4 — harness gateway

• src/gatewayClient.ts: single-token diff — const SLASHES became export const SLASHES so the harness client can serve commands.catalog/complete.slash from the same table.
• New src/harness/ (the only directory allowed to import @deepseek-ai/*, gated by npm run verify:boundary): index.ts (cordis plugin surface), plugin.ts (entry.tsx- equivalent boot wiring), client.ts (HarnessGatewayClient extends GatewayClient — overrides start/request/kill; start() creates an in-process harness agent instead of spawning Python, and session/event records are translated onto the GatewayEvent union).
• dist/plugin.js is an esbuild bundle with ONLY @deepseek-ai/* external: React, the ink fork, and the app ship inside the plugin file, so a dsh profile needs no additional node_modules and there is never a second React copy.
• e2e (npm run e2e): boots the real dsh CLI from this repo's node_modules (one copy of every harness package in the process), dsh-base bundle + a scripted mock LLM adapter (test/e2e/mock-llm.mjs, provider route mock), inside a Python PTY driver that answers DA1/CPR/OSC-11 terminal queries. Asserts banner+composer render, a streamed MOCK-REPLY: <prompt> turn, and clean /quit.
• The mock adapter must pick the last message with source.kind === 'user' — the harness injects context (time, instructions) as user-role messages and a naive "last user message" echoes those instead of the human prompt.

Stage 5 — interaction gates

• Approvals: the client is the approval/request waterfall answerer for its own agent (delegates other agents via next()). The gated command shown in the box is recovered from the tool/call arguments by callId. allow_permanent is false — the harness has no persistent grant store, so the "don't ask again" option is hidden and always maps to allowed-once if it ever arrives. In the stock dsh-base composition, approvals fire on sandbox escalations (sandbox_permissions on bash) rather than on every tool call.
• Questions: the client registers as the ctx.userQuestions provider (DUPLICATE_PROVIDER-tolerant). QuestionSpec has no id, so answers are re-paired by question text; multi-select answers arrive as ', '-joined labels and are split back into selected labels + custom leftovers.
• Plan review: a single question carrying intent {kind:'plan-review', approve} renders as the clawcodex PlanApprovalPrompt; approve choices answer with the intent's approve label, accept-edits maps to default (no per-category harness equivalent), bypass additionally sets approval policy 'never'; deny answers with the feedback as custom text.
• Permission modes: Shift+Tab cycles default → plan → bypassPermissions (acceptEdits is omitted — no harness analog). plan drives ctx.planMode.set, bypass drives ctx.approval.setPolicy('never'); 'plan/mode' session events (e.g. the model exiting plan mode) flow back as permission.mode updates.

Stage 6 — sessions

• The client keeps a live-agent registry (Map<sid, AgentHandle>); the UI binds to one (attach() = swap subscriptions + rebuild info + recount the turn odometer from the log). session.close disposes; kill() disposes all.
• session.resume/activate: live handles switch in place; persisted ids go through ctx.agents.resume, then the transcript is rehydrated from agent.session.events (user/message with source.kind user → user rows; assistant/message → assistant rows; tool/call → tool trail rows with prettyArgs context).
• session.list serves sessionPersistence.list() newest-first with titles from sessionProjectionCache.cachedSnapshot when warm; session.active_list reflects the live map with agent.status. session.title get/rename via ctx.sessionTitle.
• e2e is now two-phase: phase 2 boots fresh and /sessions <fixed-id> replays phase 1's persisted conversation.

Stage 7 — slash commands, model picker, usage

• commands.catalog / complete.slash now merge ctx.commands.list(agent) behind the static SLASHES table (locals win on collisions — a harness command never shadows a built-in).
• slash.exec: effort and context are handled in the client (selection.reasoningEffort / tokenMeter snapshot); everything else bridges to ctx.commands.execute — note the dsh-commands parseCommand contract requires the LEADING SLASH on the line.
• config.set model → applyModelSwitch: accepts model, provider:model, and model --provider slug; updates the live selection (installModelSelection ref), persists via agentDefaultModel.saveSelection, refreshes the context window, republishes session.info.
• model.options / model.effort_options from the ctx.llm advisory catalog + resolveModelInfo.
• session.usage + message.complete usage now carry context_used/max/percent from tokenMeter.measure + the resolved model context window (drives the context bar).
• e2e lesson: a bare slash word leaves the completion menu open and Enter ACCEPTS instead of submitting — the PTY driver sends Esc first; and flattened-transcript needles must avoid digits (some glyphs render via absolute cursor positioning and vanish in the flattener).

Stage 8 — rich rendering & telemetry

• tool/result now routes through the owning tool's presentResult view: diff views convert to StructuredDiffPayload via jsdiff structuredPatch (create → content + firstLine; multi- file diffs render the first + a "+N more" note), terminal views render output + exit code, search path views join paths; everything else falls back to the raw text blocks.
• todo/write snapshots stash and ride the next tool.complete's todos (the todo_write tool completes immediately after, which is where the clawcodex TodoPanel reads them).
• tool-call-delta chunks announce tool.generating once per call id.
• session.stats {session_turns} publishes after resume/activate so the odometer is right before the next turn.
• e2e mock lesson: "has a tool result" must be scoped to messages AFTER the last human prompt — the derived history keeps earlier turns' tool results forever.

Stage 9 — packaging & install

• Distribution is checkout-based: ./install.sh builds locally then dsh plugin --profile dsh-cctui add <checkout> (a pnpm link install). The bundle's cordis.patch.yml supplies the cctui row; module resolution from the linked checkout finds the repo's own node_modules, so the plugin externals resolve without touching the profile.
• bin/dsh-cctui.js is a thin launcher (probe dsh, verify the profile, exec dsh --profile dsh-cctui with NODE_ENV=production).
• The installed path has its own e2e (npm run e2e:install, in CI): scratch DSH_HOME, real dsh plugin add, boot with only a mock-LLM overlay patch, one streamed turn.
• Not ported (backend never fires them, UI degrades silently): billing/credits, voice, pets gallery (pet RPCs resolve empty), browser progress, worktree exit flow, rollback, memory targets, sudo/secret prompts.

Stage 10 — DeepSeek rebrand (v0.2.0)

• Wordmark: DSH-CCTUI in the same ANSI-shadow style (69 cols, hand-assembled, uniform width).
• Mascot: the lobster became a blue whale; it now always paints from the active /logo gradient (default: the new whale palette, anchored on DeepSeek blue #4D6BFE). sunset remains selectable; /logo grammar gained whale.
• brand: name dsh-ccTUI, icon 🐳; tagline "Claude Code style TUI for Deepseek-Harness" (mid tier: "Claude Code style TUI"; tiny tier: "dsh-ccTUI").
• Every user-visible "clawcodex" string was renamed; functional identifiers stay (CLAWCODEX_* env vars, ~/.clawcodex data dir, @dsh-cctui/ink package name).
• Identifier rename: every cc-tui token became cctui (package dsh-cctui, row id cctui, bin dsh-cctui, env prefix DSH_CCTUI_*); the default profile is dsh-cctui.
• SessionInfo.version now carries the real plugin version (package.json, resolved from dist/ or src/), so the panel reads "dsh-ccTUI v0.2.0".
• e2e determinism fix: the write-tool scenario deletes its probe file first — a leftover file turned the create into an update and hit the read-before-write observation policy.

Stage 11 — ocean-blue brand, own data directory (v0.2.1)

• The banner shipped GREEN despite the v0.2.0 rebrand: readLogoColorSync read ~/.clawcodex/config.json, so a clawcodex /logo forest preference overrode the new default. Two fixes: the app now owns ~/.dsh-cctui (src/lib/appHome.ts, env override DSH_CCTUI_HOME) for the logo pref, prompt history, lifecycle logs, perf log, heapdumps and the memory-file home; and config.set logoColor persists there (previously it fell through to {}, so /logo silently failed to stick). No migration from ~/.clawcodex — inheriting another product's UI prefs is the bug.
• Brand palette is the existing ocean ramp (now DEFAULT_LOGO_PALETTE), not a bespoke one; LOGO_BRAND pins the same six stops as literals and a test asserts they match.
• Theme brand hue moved off Claude terracotta to DeepSeek blue: dark #4D6BFE, light #3A57E8 (deeper for contrast on white), shimmer band recolored to match. This is what makes the whole header/chrome read blue, not just the ASCII art.
• Testing lesson that caused this: the v0.2.0 e2e asserted banner glyphs but never the SGR colors, so a stale palette passed. The e2e now asserts every brand-colored run in the banner region is blue-dominant, and a unit test pins the default ramp to ocean.

Stage 12 — fork and identifier rename (v0.3.0)

• packages/clawcodex-ink → packages/dsh-cctui-ink, package @clawcodex/ink → @dsh-cctui/ink (143 files, ~29k LOC; 96 import sites, three esbuild aliases, the ambient .d.ts module declaration, tsconfig paths and the vitest excludes). It is a vendored fork of Ink that this repo ships and bundles, so carrying another product's brand in its package identity was wrong; MIT permits the rename and NOTICE.md keeps the attribution (renaming never removes credit).
• Environment knobs CLAWCODEX_* / CLAWCODEX_TUI_* → DSH_CCTUI_* (49 names; the redundant TUI_ infix was dropped, e.g. CLAWCODEX_TUI_INLINE → DSH_CCTUI_INLINE). CLAUDE_CODE_SCROLL_SPEED is deliberately KEPT as a migration fallback — it is another product's knob read for interop, not our branding.
• Remaining "clawcodex" mentions in the tree are provenance comments ("ported from …") and the dead Python-gateway test fixtures; those describe history and stay.
• The inert /memory feature's file name became DSH-CCTUI.md under ~/.dsh-cctui.