feat(terminal): real PTY backend, typed errors, and offline help

[oNddleo]

Features

Terminal — real PTY over Tauri IPC. The old terminal faked a TTY with script(1) and moved bytes over HTTP: one POST per keystroke, plus a 100 ms poll for output. That worked for ls and broke for anything interactive. Replaced with portable-pty, streamed over a Tauri Channel<String>:

• vim, htop, k9s and other cursor-addressed programs now render, and resize correctly — the pty gets a real SIGWINCH.
• Ctrl+C / Ctrl+D / Ctrl+Z reach the child instead of printing ^C.
• Idle terminals cost nothing; output is pushed, not polled.
• Bounded 1 MiB output ring buffer (drop-oldest) so yes cannot OOM the app.
• Session cap of 16 plus a 30-minute idle reaper; reconnects are exempt from the cap so a user at the ceiling can still reattach to existing tabs.
• Kubernetes pod shells open an in-app tab instead of shelling out to Terminal.app via osascript. "Open in Terminal.app" survives as a secondary action.
• Per-profile shell history (HISTFILE=~/.colima-ui/history-<profile>) with PROMPT_COMMAND='history -a', so several tabs on one profile do not lose each other's history to bash's append-on-exit.

Typed error taxonomy. error.rs now returns a structured ColimaError carrying a category and a doc_id, and both entry points (Tauri IPC and HTTP) serialize the same shape. The frontend half lives in lib/errors.ts; errorReporter.ts turns a failed operation into a localized toast plus a hint, so call sites no longer decide presentation. Failures are recorded in an error log with a detail panel.

Secret redaction. redact.rs / lib/redact.ts strip credentials from any string that can reach the user, a log, or a bug report. The motivating leak: reqwest puts the full request URL in its Display output, so an error from a provider that authenticates by query parameter would print the API key. Redaction works by position (credential-shaped parameters) and by pattern.

System capability detection. check_system, check_tool and get_platform each returned a different shape and SetupWizard.svelte stitched them together, so every other page had to re-derive "is Colima installed and usable". Now one source of truth.

Colima config editor — read, validate and write ~/.colima/<profile>/colima.yaml from Settings.

Live engine resources. The dashboard derived CPU/memory/disk from colima.yaml, which is the allocated VM config and only exists when Colima manages the engine. Docker Desktop, OrbStack and Rancher now report real figures.

Menu bar / tray — see instance state and start or stop instances without opening the main window.

Offline Help — 6 articles (install Colima / Docker CLI / kubectl, start Colima, common errors, performance tuning) in English, Japanese, Vietnamese and Chinese. These are the destination for the doc_id slugs errors attach: the error says what broke, the article says what to do about it.

Compose grouping — containers are grouped by
com.docker.compose.project; hand-started containers stay ungrouped.

Fixes

• Terminal rendered garbage (a run of repeated characters and an oversized block cursor) because @xterm/xterm/css/xterm.css was never imported. xterm.js positions its row divs, hides its character-measuring element and sizes the cursor entirely from that stylesheet; without it the measure element renders on screen.
• Terminal session id embedded Date.now(), so every remount opened a new pty and abandoned the old one. Keyed to the tab, a remount now reattaches.
• Terminal rewrote \n as \r\n to compensate for the script(1) wrapper, corrupting any program that positions the cursor itself. Removed with the wrapper.
• terminal.* translation keys were absent from all four locale files, so terminal errors always displayed in English. Added to en/ja/vi/zh.
• Terminal printed a "Connecting to …" banner with a doubled space and a stray blank line, pushing the shell prompt down two rows. Removed on the happy path; failures still announce themselves.
• Client-side ids were Date.now().toString() and collided when two items were created in the same millisecond.
• validation.rs gained path-traversal and argument-injection guards for values that reach a command line (profile names, k8s namespace/pod/ container), covered by unit tests.

Security

routes/ws.rs is deleted. Despite the filename it contained no WebSocket — only five HTTP handlers (api_terminal_create/write/read/close/resize) that exposed an interactive shell on a local port, which is remote code execution. The terminal is desktop-only, so these were removed rather than ported: over Tauri IPC there is no port to reach and no handshake to authenticate. Terminal I/O is never logged.

Tests

9 frontend test modules (errors, redaction, ids, compose grouping, markdown) and 12 Rust tests over the terminal session — argv construction, hostile-name rejection, UTF-8 carry across read boundaries, zero-size resize refusal, and per-profile history.

[ecc-tools]

Analyzing 200 commits...

[ecc-tools]

Analysis Complete

Generated ECC bundle from 1 commits | Confidence: 75%

View Pull Request #31

Repository Profile

Attribute	Value
Language	Rust
Framework	Not detected
Commit Convention	conventional
Test Directory	colocated

Changed Files (138)

Metric	Value
Files changed	138
Additions	14203
Deletions	3151

Top hotspots

Path	Status	+/-
src/index.css	modified	+17 / -1795
pnpm-lock.yaml	added	+1512 / -0
src-tauri/src/commands/colima_config.rs	added	+1068 / -0
src/components/AiChatPanel.svelte	modified	+732 / -85
src-tauri/src/terminal_session.rs	modified	+672 / -135

Top directories

Directory	Files	Total changes
src-tauri/src/commands	15	2919
src-tauri/src	13	2571
.	9	1939
src	3	1910
src/components	7	1697

Analysis Depth Readiness (commit-history, 21%)

ECC Tools uses this to decide whether recommendations should stay at commit-history/setup guidance or expand into CI, security, harness, reference-set, AI-routing, and team backlog work.

Area	Status	Evidence / Next Step
Commit history	Partial	1 commits sampled
CI/CD signals	Missing	Add workflow files or CI troubleshooting evidence so ECC Tools can reason about pipeline setup.
Security evidence	Missing	Add AgentShield, audit, SARIF, SBOM, or security review evidence so recommendations can cover security posture.
Harness configuration	Missing	Add Claude, Codex, OpenCode, Zed, dmux, MCP, plugin, or cross-harness config evidence for harness-agnostic recommendations.
Reference/eval evidence	Missing	Add fixtures, golden traces, reference sets, or evaluator benchmarks so deeper recommendations have regression evidence.
AI routing and cost controls	Ready	src/styles/tokens.css
Team handoff and project tracking	Missing	Add roadmap, runbook, project, Linear, or follow-up tracking docs so generated work can land in a team queue.

Reference Set Readiness (0/7, 0%)

Area	Status	Evidence / Next Step
Deep analyzer corpus	Missing	Add analyzer fixture, golden, benchmark, or reference-set files that can catch analyzer regressions.
RAG/evaluator comparison	Missing	Add retrieval or evaluator reference-set comparison fixtures with expected ranking behavior.
PR salvage/review corpus	Missing	Add stale-PR, review-thread, reopen-flow, or salvage reference cases for queue cleanup automation.
Discussion triage corpus	Missing	Add public discussion triage fixtures, golden cases, or reference sets for informational, answered, and no-response classifications.
Harness compatibility	Missing	Add cross-harness, adapter-compliance, or harness-audit evidence for Claude, Codex, OpenCode, Zed, dmux, and agent surfaces.
Security evidence	Missing	Attach security evidence such as SBOMs, SARIF, audit reports, or AgentShield evidence packs.
CI failure-mode evidence	Missing	Add captured CI failure logs, dry-run fixtures, or troubleshooting docs for common workflow failure modes.

Likely Future Issues (8)

Severity	Signal	Why it may show up
HIGH	API contract changes may ship without integration coverage	14 API surface paths changed; 0 integration or e2e tests changed
MEDIUM	API implementation changes may ship without contract artifact updates	14 API implementation paths changed; 0 API contract/spec files changed
MEDIUM	Runtime config changes may ship without example or template updates	1 runtime config paths changed; 0 example or template config files changed
HIGH	Auth or permission changes may ship without security regression coverage	1 auth/permission paths changed; 0 auth-focused integration or e2e tests changed
MEDIUM	User-facing UI changes may ship without browser coverage	30 user-facing UI paths changed; 0 browser or e2e coverage files changed
MEDIUM	CLI changes may ship without shell or end-to-end coverage	15 CLI surface paths changed; 0 CLI-focused integration or e2e tests changed
HIGH	Security-sensitive changes may ship without scanner evidence	1 security-sensitive paths changed; 0 security scanner or security-focused validation artifacts changed
MEDIUM	Cost or token-risk changes may ship without budget evidence	1 cost/token-risk paths changed; 0 budget, usage, or cost validation artifacts changed

• API contract changes may ship without integration coverage: The PR changes API or route-facing files but does not touch any obvious integration or end-to-end tests.
• API implementation changes may ship without contract artifact updates: The PR changes API implementation files but does not touch any obvious OpenAPI, GraphQL, or contract/spec artifact.
• Runtime config changes may ship without example or template updates: The PR changes runtime config or deployment settings but does not update any obvious example env file or config template.
• Auth or permission changes may ship without security regression coverage: The PR changes auth, session, middleware, or permission-sensitive files without touching any obvious auth-focused integration or end-to-end tests.
• User-facing UI changes may ship without browser coverage: The PR changes components, pages, or other user-facing UI files without touching any obvious browser or end-to-end coverage.
• CLI changes may ship without shell or end-to-end coverage: The PR changes CLI, bin, or command-entry files without touching any obvious CLI-focused integration or end-to-end tests.
• Security-sensitive changes may ship without scanner evidence: The PR touches billing, secrets, auth, webhooks, agent, or CI-sensitive surfaces without adding obvious security scanner, code scanning, or security-focused validation evidence.
• Cost or token-risk changes may ship without budget evidence: The PR changes AI routing, usage, token budget, or model-call surfaces without touching obvious budget, usage-limit, or cost regression evidence.

Suggested Follow-up Work (8)

Type	Suggested title	Targets
PR	test: add integration coverage for src-tauri/src/routes/ai.rs + src-tauri/src/routes/colima_config.rs	src-tauri/src/routes/ai.rs, src-tauri/src/routes/colima_config.rs
PR	docs: sync API contract for src-tauri/src/routes/ai.rs + src-tauri/src/routes/colima_config.rs	src-tauri/src/routes/ai.rs, src-tauri/src/routes/colima_config.rs
PR	chore: sync config templates for src-tauri/tauri.conf.json	src-tauri/tauri.conf.json
PR	test: add auth coverage for src-tauri/src/auth.rs	src-tauri/src/auth.rs
PR	test: add browser coverage for src/components/AiChatPanel.svelte + src/components/DiffView.svelte	src/components/AiChatPanel.svelte, src/components/DiffView.svelte
PR	test: add CLI coverage for src-tauri/src/commands/ai_chat.rs + src-tauri/src/commands/colima.rs	src-tauri/src/commands/ai_chat.rs, src-tauri/src/commands/colima.rs
PR	security: add scanner evidence for src-tauri/src/auth.rs	src-tauri/src/auth.rs
PR	test: add budget evidence for src/styles/tokens.css	src/styles/tokens.css

• test: add integration coverage for src-tauri/src/routes/ai.rs + src-tauri/src/routes/colima_config.rs: Backfill integration or end-to-end coverage for the changed API surface before more contract changes land.
• docs: sync API contract for src-tauri/src/routes/ai.rs + src-tauri/src/routes/colima_config.rs: Backfill the missing API contract or spec update before another implementation change lands on top of the same surface.
• chore: sync config templates for src-tauri/tauri.conf.json: Backfill example env files or config templates before a fresh setup drifts from the shipped runtime surface.
• test: add auth coverage for src-tauri/src/auth.rs: Backfill auth or permission regression coverage before another access-control change lands on the touched surface.
• test: add browser coverage for src/components/AiChatPanel.svelte + src/components/DiffView.svelte: Backfill browser coverage before another user-facing UI change lands on the touched surface.
• test: add CLI coverage for src-tauri/src/commands/ai_chat.rs + src-tauri/src/commands/colima.rs: Backfill CLI coverage before another command-surface change lands on the touched paths.
• security: add scanner evidence for src-tauri/src/auth.rs: Backfill explicit scanner or code-scanning evidence before another security-sensitive change lands on the touched surface.
• test: add budget evidence for src/styles/tokens.css: Backfill cost, token, or usage-limit validation before another model-routing change lands on the touched surface.

Copy-ready bodies

test: add integration coverage for src-tauri/src/routes/ai.rs + src-tauri/src/routes/colima_config.rs

## Summary
- Add integration or end-to-end coverage for the recently changed API surface.

## Why
- Backfill integration or end-to-end coverage for the changed API surface before more contract changes land.

## Touched paths
- `src-tauri/src/routes/ai.rs`
- `src-tauri/src/routes/colima_config.rs`

## Validation
- Add or extend integration / e2e coverage for the changed API, route, or contract surface.
- Exercise the touched endpoints or route handlers against realistic request / response flows.

docs: sync API contract for src-tauri/src/routes/ai.rs + src-tauri/src/routes/colima_config.rs

## Summary
- Update the API contract artifact that should reflect the recently changed implementation surface.

## Why
- Backfill the missing API contract or spec update before another implementation change lands on top of the same surface.

## Touched paths
- `src-tauri/src/routes/ai.rs`
- `src-tauri/src/routes/colima_config.rs`

## Validation
- Update the relevant OpenAPI, GraphQL, or contract/spec artifact used by this repo.
- Run the contract validation, docs generation, or API verification flow that depends on that artifact.

chore: sync config templates for src-tauri/tauri.conf.json

## Summary
- Update the example env files, sample configs, or deployment templates that should mirror the changed runtime configuration surface.

## Why
- Backfill example env files or config templates before a fresh setup drifts from the shipped runtime surface.

## Touched paths
- `src-tauri/tauri.conf.json`

## Validation
- Update the repo example env file or config template that should reflect the new runtime settings.
- Run the setup, boot, or deployment validation flow that depends on the changed config surface.

test: add auth coverage for src-tauri/src/auth.rs

## Summary
- Add auth, session, or permission regression coverage for the recently changed security-sensitive surface.

## Why
- Backfill auth or permission regression coverage before another access-control change lands on the touched surface.

## Touched paths
- `src-tauri/src/auth.rs`

## Validation
- Add or extend integration / e2e coverage for the changed auth, session, middleware, or permission surface.
- Exercise allowed and denied flows, invalid or expired credentials, or equivalent access-control boundary cases.

test: add browser coverage for src/components/AiChatPanel.svelte + src/components/DiffView.svelte

## Summary
- Add browser or end-to-end coverage for the recently changed user-facing surface.

## Why
- Backfill browser coverage before another user-facing UI change lands on the touched surface.

## Touched paths
- `src/components/AiChatPanel.svelte`
- `src/components/DiffView.svelte`

## Validation
- Add or extend browser / e2e coverage for the changed component, page, or flow.
- Exercise the visible user journey that depends on the touched UI surface.

test: add CLI coverage for src-tauri/src/commands/ai_chat.rs + src-tauri/src/commands/colima.rs

## Summary
- Add shell, CLI, or end-to-end coverage for the recently changed command surface.

## Why
- Backfill CLI coverage before another command-surface change lands on the touched paths.

## Touched paths
- `src-tauri/src/commands/ai_chat.rs`
- `src-tauri/src/commands/colima.rs`

## Validation
- Add or extend shell, CLI, or end-to-end coverage for the changed command surface.
- Exercise the user-facing command invocation and expected exit/output behavior.

security: add scanner evidence for src-tauri/src/auth.rs

## Summary
- Add security scanner or code-scanning evidence for the recently changed security-sensitive surface.

## Why
- Backfill explicit scanner or code-scanning evidence before another security-sensitive change lands on the touched surface.

## Touched paths
- `src-tauri/src/auth.rs`

## Validation
- Run or add the relevant security scanner, code scanning, secret scanning, or dependency/security review check for the touched surface.
- Attach the scanner output, SARIF/code-scanning result, or focused security regression test to the follow-up PR.
- Confirm the changed auth, billing, webhook, secret-handling, agent, or CI surface has an explicit pass/fail gate.

test: add budget evidence for src/styles/tokens.css

## Summary
- Add budget or usage-limit validation for the recently changed AI routing or model-call surface.

## Why
- Backfill cost, token, or usage-limit validation before another model-routing change lands on the touched surface.

## Touched paths
- `src/styles/tokens.css`

## Validation
- Add or extend budget, token, usage-limit, or model-routing regression coverage for the changed path.
- Verify the route still enforces plan limits, retry caps, fallback behavior, or explicit cost controls.

Generated Instincts (10)

Domain	Count
git	2
code-style	3
architecture	1
testing	4

After merging, import with:

/instinct-import .claude/homunculus/instincts/inherited/colima-ui-instincts.yaml

Files

• .claude/ecc-tools.json
• .claude/skills/colima-ui/SKILL.md
• .agents/skills/colima-ui/SKILL.md
• .agents/skills/colima-ui/agents/openai.yaml
• .claude/identity.json
• .codex/config.toml
• .codex/AGENTS.md
• .codex/agents/explorer.toml
• .codex/agents/reviewer.toml
• .codex/agents/docs-researcher.toml
• .claude/homunculus/instincts/inherited/colima-ui-instincts.yaml

---

_{ECC Tools | Everything Claude Code}