npm - vibe-coding-master - Versions diffs - 0.0.9 → 0.0.11 - Mend

vibe-coding-master 0.0.9 → 0.0.11

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (28) hide show

package/README.md +38 -25
package/dist/backend/api/app-settings-routes.js +8 -0
package/dist/backend/api/message-routes.js +3 -1
package/dist/backend/api/session-routes.js +7 -1
package/dist/backend/api/task-routes.js +12 -10
package/dist/backend/api/translation-routes.js +21 -3
package/dist/backend/runtime/terminal-submit.js +20 -0
package/dist/backend/server.js +9 -4
package/dist/backend/services/app-settings-service.js +28 -0
package/dist/backend/services/claude-transcript-service.js +12 -8
package/dist/backend/services/command-dispatcher.js +2 -1
package/dist/backend/services/message-service.js +10 -6
package/dist/backend/services/project-service.js +0 -3
package/dist/backend/services/session-service.js +7 -4
package/dist/backend/services/task-service.js +65 -56
package/dist/backend/services/translation-service.js +264 -77
package/dist/shared/types/app-settings.js +1 -0
package/dist-frontend/assets/index-Bi4X3GSR.css +32 -0
package/dist-frontend/assets/index-DaHXq14j.js +88 -0
package/dist-frontend/index.html +2 -2
package/docs/cc-best-practices.md +4 -4
package/docs/product-design.md +71 -33
package/docs/v1-architecture-design.md +92 -60
package/docs/v1-implementation-plan.md +101 -61
package/package.json +3 -1
package/dist/backend/ws/translation-ws.js +0 -35
package/dist-frontend/assets/index-CuiNNOzj.css +0 -32
package/dist-frontend/assets/index-D59GuHCR.js +0 -58

package/dist-frontend/index.html CHANGED Viewed

@@ -4,8 +4,8 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>VibeCodingMaster</title>
-    <script type="module" crossorigin src="/assets/index-D59GuHCR.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-CuiNNOzj.css">
+    <script type="module" crossorigin src="/assets/index-DaHXq14j.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-Bi4X3GSR.css">
   </head>
   <body>
     <div id="root"></div>

package/docs/cc-best-practices.md CHANGED Viewed

@@ -1486,11 +1486,11 @@ Branch rules:
 - large work should use phase commits on the same task branch unless phases are independently releasable
 - if a task becomes too large, split it into child tasks with explicit branch and PR ownership
-Cleanup rules:
+Close Task rules:
-- after task completion, remove the task worktree only after role sessions are stopped and uncommitted work is handled
-- remove VCM task/session/message/orchestration metadata with the worktree cleanup
-- keep the task branch by default until PR merge; delete it only with explicit confirmation
+- after task completion, use VCM `Close Task` only when the user is ready to delete task-local state
+- for worktree-backed tasks, `Close Task` deletes the task worktree, deletes the task branch by default, and removes VCM task/session/message/orchestration metadata
+- `Close Task` does not check running role sessions or uncommitted changes; finish, commit, or preserve anything important before using it
 Small commits:

package/docs/product-design.md CHANGED Viewed

@@ -66,7 +66,7 @@ The workflow is a soft guide in V1. VCM computes readiness from handoff artifact
 ### 4.1 Task Worktree Model
-Task-level worktree management is the current model for multi-task parallelism:
+Task-level worktree management is the recommended default model for multi-task parallelism:
 ```text
 one task
@@ -78,7 +78,9 @@ one task
 VCM must not create worktrees per role. `project-manager`, `architect`, `coder`, and `reviewer` for the same task all run in the same task worktree and hand off sequentially.
-When the user creates a task, VCM creates the branch and worktree immediately. There is no separate later button named `Create task worktree`, and a task cannot be switched to another worktree after creation.
+When the user creates a task, `Create worktree and branch` is selected by default. With that option selected, VCM creates the branch and worktree immediately. If the user clears the option, VCM creates the task in the currently connected repository path and records the current branch.
+There is no separate later button named `Create task worktree`, and a task cannot be switched between worktree and non-worktree mode after creation.
 Branch naming:
@@ -108,27 +110,34 @@ Task creation flow:
 ```text
 New Task submit
   -> validate task name
-  -> derive branch feature/<task-name>
-  -> derive worktree path .ai/vcm/worktrees/<task-name>
-  -> verify .ai/vcm/ is ignored and the base repo is clean
-  -> git worktree add -b feature/<task-name> .ai/vcm/worktrees/<task-name> <base-ref>
+  -> verify .ai/vcm/ is ignored
+  -> if Create worktree and branch is selected:
+       -> derive branch feature/<task-name>
+       -> derive worktree path .ai/vcm/worktrees/<task-name>
+       -> verify the base repo is clean
+       -> git worktree add -b feature/<task-name> .ai/vcm/worktrees/<task-name> <base-ref>
+  -> otherwise:
+       -> use the connected repo path and current branch
   -> create task metadata
-  -> create handoff structure inside the task worktree
-  -> open the task workspace with role session cwd = task worktree
+  -> create handoff structure inside the task runtime repo
+  -> open the task workspace with role session cwd = task runtime repo
 ```
-Task cleanup flow:
+Task close flow:
 ```text
-task complete
-  -> stop running role sessions
-  -> verify task worktree is safe to remove
-  -> remove git worktree
-  -> remove VCM task/session/message/orchestration metadata
-  -> keep or delete branch according to guarded branch cleanup policy
+user clicks red Close Task
+  -> show destructive confirmation
+  -> stop VCM-managed running role sessions for the task
+  -> explain that VCM deletes the task worktree and task branch
+  -> explain that VCM does not check running sessions or uncommitted changes
+  -> remove git worktree when the task owns one
+  -> delete the task branch by default when the task owns one
+  -> remove VCM task metadata from the base repo
+  -> remove task runtime metadata from the task runtime repo
 ```
-Branch deletion should be a separate guarded confirmation, ideally only after the branch is merged or the user explicitly confirms deletion. Worktree cleanup itself removes the local working directory and task metadata.
+Tasks created without a worktree do not own a separate branch/worktree, so Close Task stops VCM-managed running role sessions and removes only VCM metadata for those tasks.
 ## 5. Roles
@@ -242,10 +251,13 @@ The old `Dirty: yes/no` label is not used. The UI uses `Working tree: clean` or
 `Settings` contains:
+- `Theme` button, cycling through `System`, `Light`, and `Dark`.
 - `Messages` button, opening a modal list of role messages.
 - `Events` button, opening a modal list of runtime UI events for the current task.
 - `Auto orchestration` on/off toggle.
+The default theme mode is `System`, which follows the OS/browser color-scheme preference. The entire application chrome, sidebar, forms, modals, status badges, and workspace panels must support both light and dark rendering. Embedded terminals keep their terminal-native dark styling.
 There is no separate `Pause orchestration` or `Resume orchestration` control in the GUI. The current product model is one on/off toggle.
 `VCM Harness` shows whether VCM managed blocks are installed/up to date in the project rules files and `.gitignore`.
@@ -253,13 +265,14 @@ There is no separate `Pause orchestration` or `Resume orchestration` control in
 `New Task` contains:
 - `task name`
-- a checked, non-optional `Create worktree and branch` indicator
-- generated branch preview: `feature/<task-name>`
-- generated worktree preview: `.ai/vcm/worktrees/<task-name>`
+- a `Create worktree and branch` checkbox, selected by default
+- generated branch preview when selected: `feature/<task-name>`
+- generated worktree preview when selected: `.ai/vcm/worktrees/<task-name>`
+- current repository/current branch note when cleared
 There is no optional title input in the current UI.
-The worktree/branch path is the normal VCM task model, not a separate mode users toggle later. The checked indicator is shown so the user understands what will happen; VCM should not require a separate worktree creation action later.
+The worktree/branch path is the recommended VCM task model, but the user may clear the checkbox for an inline task. VCM should not require a separate worktree creation action later.
 ### Task Workspace
@@ -367,7 +380,7 @@ For `.gitignore`, VCM uses hash comments:
 # VCM:END
 ```
-`.ai/vcm/` is the active VCM local control area for task state, session state, orchestration state, and task worktrees.
+`.ai/vcm/` is the active VCM local control area. The base repo keeps the task index and nested worktrees; each task runtime repo keeps its own session, message, orchestration, and translation state.
 VCM must preserve all user-authored content outside the managed block.
@@ -426,9 +439,9 @@ Manual mode:
 - message status becomes `pending_approval` when the target role is running
 - user opens `Messages`
-- user clicks `Stage`
-- VCM writes a short prompt into the target terminal
-- VCM does not submit Enter
+- message rows show sequence, timestamp, status, body preview, path, and `Copy`
+- user decides whether to copy or manually act on the message
+- VCM does not write to the target terminal or submit Enter
 Auto mode:
@@ -436,7 +449,7 @@ Auto mode:
 - PM remains the routing hub
 - non-PM roles reply to PM
-The backend still has a `paused` state field and pause/resume API routes for compatibility. The current GUI exposes only manual/auto.
+The backend still has `stage`, `approve`, `reject`, `paused`, and pause/resume API compatibility paths. The current GUI exposes only message copy plus manual/auto orchestration.
 ## 12. Translation
@@ -468,7 +481,7 @@ Prompt slots:
 - `zh-to-en-with-context`
 - `en-to-zh`
-The settings modal shows the default prompt for each slot and allows a user override. Empty override means use the default prompt.
+The settings modal shows all three prompt slots as direct editors. `Reset prompts` restores every prompt to its built-in default. The modal does not include separate enable/output/input-mode switches; opening the role toolbar `Translate` panel is the translation on/off control, and the panel-level `Auto-send` toggle controls whether translated user input is submitted automatically.
 ### Claude Output Translation
@@ -482,6 +495,16 @@ VCM tails Claude Code transcript JSONL files under:
 The transcript path is persisted in the role session record. If that path is missing, VCM falls back to resolving by current working directory and then scanning `~/.claude/projects` for the newest file with the session id.
+VCM owns transcript listening in the backend. Opening the translation panel starts or confirms the backend tailer for the active role session. Closing the panel does not stop that tailer; it keeps collecting Claude output until the role session is stopped/restarted or the task is closed. This keeps translation capture independent from frontend rendering.
+Backend translation cache lives under:
+```text
+<taskRepoRoot>/.ai/vcm/translation/<task>/<role>/<session-id>.jsonl
+```
+The frontend does not subscribe through WebSocket. It polls the backend with a cursor and receives new cached events. The cursor means "next expected seq": `after=18` confirms that seq `1..17` have already been displayed, so the backend can remove those cached events and return seq `18` and later. If the cursor is older than the retained cache, VCM still returns whatever newer events remain; it does not use a snapshot error mode.
 Transcript event handling:
 - assistant text -> `prose` -> translated
@@ -496,9 +519,12 @@ Display behavior:
 - `prose` starts by showing the English source.
 - while translating, panel status shows `translating <elapsed>`.
 - when translation succeeds, the English source is replaced by Chinese translated text.
+- `prose` content is rendered as Markdown, including headings, lists, code fences, tables, and links.
 - when translation fails, panel status shows `error` and the entry keeps the visible source plus an error.
 - `tool-output` is dim, one-line, truncated by CSS, and not translated.
+Long translations do not block capture. Prose entries are pushed to the panel before provider translation starts. `tool_use` and `tool_result` entries are never added to the translation queue; they are displayed immediately.
 There is no keyword classifier that drops assistant text. A previous design skipped permission-looking or log-looking text; that is removed.
 ### User Input Translation
@@ -512,7 +538,9 @@ Keyboard behavior:
 After translation succeeds, the English draft replaces the original Chinese text in the same textarea.
-`Send English` writes the current English text to the active role terminal and submits Enter.
+The translated user input is also shown in the translation panel as a conversation boundary. User-input entries have a thick divider and larger top spacing so the next Claude output reads as the answer to that prompt.
+`Send English` pastes the current English text into the active role terminal, then sends Enter as a separate terminal input event.
 Translation panel `Auto-send` is separate from task `Auto orchestration`:
@@ -527,13 +555,16 @@ App-level settings:
 ~/.vcm/settings.json
 ```
+Stored app-level settings include:
+- UI theme mode: `system`, `light`, or `dark`
+- translation provider settings and API key
+- recent repository paths
 Repository-level VCM state:
 ```text
 .ai/vcm/tasks/<task>.json
-.ai/vcm/sessions/<task>.json
-.ai/vcm/messages/<task>.jsonl
-.ai/vcm/orchestration/<task>.json
 .ai/vcm/worktrees/<task>/
 ```
@@ -544,14 +575,20 @@ Project config:
 ~/.vcm/projects/index.json
 ```
-The base repository's `.ai/vcm/` directory is the repository-local runtime control area. Long-lived project config is stored under `~/.vcm` so it survives outside Git-ignored repo state. Task source changes and handoff artifacts live inside the task worktree at `.ai/vcm/worktrees/<task>/`.
+The base repository's `.ai/vcm/` directory stores the task index and nested task worktrees. Long-lived project config is stored under `~/.vcm` so it survives outside Git-ignored repo state.
 Task worktree local files:
 ```text
+.ai/vcm/worktrees/<task>/.ai/vcm/sessions/<task>.json
+.ai/vcm/worktrees/<task>/.ai/vcm/messages/<task>.jsonl
+.ai/vcm/worktrees/<task>/.ai/vcm/orchestration/<task>.json
+.ai/vcm/worktrees/<task>/.ai/vcm/translation/<task>/
 .ai/vcm/worktrees/<task>/.ai/handoffs/<task>/
 ```
+For tasks created without a worktree, the task runtime repo is the connected base repo, so the runtime state resolves under the base repo's `.ai/vcm/`.
 External Claude transcripts:
 ```text
@@ -583,8 +620,9 @@ This protects against publishing raw TypeScript bin files or missing frontend as
 VCM V1 is successful when:
 - A user can connect a repo without global Git safe-directory setup.
-- A user can create a task, which creates `feature/<task>` and `.ai/vcm/worktrees/<task>`.
-- A user can start all four role sessions in that task worktree.
+- A user can create a default task, which creates `feature/<task>` and `.ai/vcm/worktrees/<task>`.
+- A user can clear `Create worktree and branch` and create a task in the connected repo/current branch.
+- A user can start all four role sessions in the task runtime repo.
 - Switching roles never loses the embedded terminal.
 - Restart creates a fresh Claude session; Resume reconnects to the persisted one.
 - Permission modes are reflected in the Claude command.

package/docs/v1-architecture-design.md CHANGED Viewed

@@ -21,7 +21,7 @@ Runtime shape:
 ```text
 browser
   -> React GUI
-  -> HTTP API + WebSocket
+  -> HTTP API + terminal WebSocket
   -> Fastify backend
   -> services
   -> node-pty
@@ -94,9 +94,9 @@ Responsibilities:
 - Render repository connect form.
 - Render repository summary.
 - Render workflow panel.
-- Render settings section with Messages, Events, Auto orchestration.
+- Render settings section with Theme, Messages, Events, Auto orchestration.
 - Render harness status/actions.
-- Render task creation form with one task-name field, a checked non-optional worktree/branch indicator, and generated branch/path previews.
+- Render task creation form with one task-name field, a `Create worktree and branch` checkbox selected by default, and generated branch/path previews when selected.
 - Render task list.
 - Render Messages and Events modals.
@@ -112,7 +112,7 @@ Responsibilities:
 - Fetch task status, messages, and orchestration state.
 - Poll those every three seconds.
-- Render compact header with task title, branch, immutable worktree path, role tabs, and Refresh.
+- Render compact header with task title, branch, immutable worktree path, role tabs, Refresh, and red `Close Task`.
 - Hold per-role permission mode selection.
 - Render one `SessionConsole` per role but only show the active role.
 - Emit workflow/messages/orchestration/events back to `App` so sidebar stays synchronized.
@@ -140,11 +140,12 @@ File:
 Responsibilities:
 - Load translation settings and prompt previews.
-- Open translation WebSocket for the current terminal runtime session id.
+- Start backend transcript listening for the current terminal runtime session id.
+- Poll backend translation events with a cursor.
 - Render dark translation output panel.
 - Render translation status: `ready`, `translating <elapsed>`, or `error`.
 - Render preserved tool output as dim one-line rows.
-- Render prose source while translating, then translated text after completion.
+- Render prose source while translating, then translated text after completion, using Markdown rendering for prose.
 - Render user composer.
 - Translate on `Enter`; newline on `Shift+Enter`.
 - Replace Chinese input with English draft after translation.
@@ -178,6 +179,7 @@ Entry:
 Fastify registers:
+- app settings routes
 - project routes
 - harness routes
 - task routes
@@ -186,7 +188,6 @@ Fastify registers:
 - message routes
 - translation routes
 - terminal WebSocket
-- translation WebSocket
 ## 5. Repository Connection
@@ -224,12 +225,12 @@ VCM does not require global `safe.directory` configuration.
 ## 6. Task Worktree Architecture
-Task-level worktree management is the current architecture for multi-task parallelism.
+Task-level worktree management is the default architecture for multi-task parallelism.
 Rule:
 ```text
-one VCM task = one branch + one git worktree + one handoff directory + one role-session set
+default VCM task = one branch + one git worktree + one handoff directory + one role-session set
 ```
 Branch name:
@@ -244,7 +245,15 @@ Worktree path:
 <baseRepoRoot>/.ai/vcm/worktrees/<taskSlug>
 ```
-VCM does not support switching a task to another branch or worktree after creation. If the user needs a different branch/worktree, they should create a new task.
+VCM does not support switching a task to another branch or worktree mode after creation. If the user needs a different branch/worktree choice, they should create a new task.
+When `Create worktree and branch` is cleared, the task uses:
+```text
+branch: current connected-repo branch
+runtime repo root: <baseRepoRoot>
+worktreePath: undefined
+```
 VCM does not create worktrees by role. All four role sessions for a task share the same task worktree:
@@ -265,13 +274,10 @@ VCM distinguishes:
 - `branch`: `feature/<taskSlug>`.
 - `worktreePath`: same as `taskRepoRoot`.
-Project-level VCM control state stays under the base repo:
+Base repo state is only the task index and the container for nested task worktrees:
 ```text
 <baseRepoRoot>/.ai/vcm/tasks/<task>.json
-<baseRepoRoot>/.ai/vcm/sessions/<task>.json
-<baseRepoRoot>/.ai/vcm/messages/<task>.jsonl
-<baseRepoRoot>/.ai/vcm/orchestration/<task>.json
 <baseRepoRoot>/.ai/vcm/worktrees/<task>/
 ```
@@ -282,13 +288,19 @@ Project configuration is app-local and stored outside the repository:
 ~/.vcm/projects/index.json
 ```
-Task source changes and handoff artifacts live in the task worktree:
+Task runtime state, source changes, and handoff artifacts live in the task runtime repo. For worktree-backed tasks this is the nested task worktree:
 ```text
+<baseRepoRoot>/.ai/vcm/worktrees/<task>/.ai/vcm/sessions/<task>.json
+<baseRepoRoot>/.ai/vcm/worktrees/<task>/.ai/vcm/messages/<task>.jsonl
+<baseRepoRoot>/.ai/vcm/worktrees/<task>/.ai/vcm/orchestration/<task>.json
+<baseRepoRoot>/.ai/vcm/worktrees/<task>/.ai/vcm/translation/<task>/
 <baseRepoRoot>/.ai/vcm/worktrees/<task>/.ai/handoffs/<task>/
 ```
-This central base-state model lets VCM list and manage multiple tasks while each task's code changes happen in a separate worktree.
+For inline tasks, `taskRepoRoot` is the connected base repo, so these same runtime paths resolve under the connected repo's `.ai/vcm/`.
+This split lets VCM list tasks from the base repo after worktrees are created, while each task's runtime state follows the same root as the role sessions.
 ### 6.2 Git Ignore Requirement
@@ -307,37 +319,39 @@ The VCM harness manages a `.gitignore` block that ignores `.ai/vcm/` before task
 ```text
 POST /api/tasks
   -> validate taskSlug
-  -> compute branch feature/<taskSlug>
-  -> compute worktreePath <baseRepoRoot>/.ai/vcm/worktrees/<taskSlug>
-  -> assert branch does not already exist
-  -> assert worktreePath does not already exist
   -> assert .ai/vcm/ is ignored by Git
-  -> assert base repo has no uncommitted changes
-  -> git worktree add -b feature/<taskSlug> <worktreePath> <baseRef>
+  -> if createWorktree is not false:
+       -> compute branch feature/<taskSlug>
+       -> compute worktreePath <baseRepoRoot>/.ai/vcm/worktrees/<taskSlug>
+       -> assert branch does not already exist
+       -> assert worktreePath does not already exist
+       -> assert base repo has no uncommitted changes
+       -> git worktree add -b feature/<taskSlug> <worktreePath> <baseRef>
+  -> otherwise:
+       -> read current base repo branch
+       -> leave worktreePath undefined
   -> create handoff structure in taskRepoRoot
   -> write central task metadata under baseRepoRoot/.ai/vcm/tasks/<task>.json
 ```
 The default `baseRef` is the connected repo's current `HEAD`.
-### 6.4 Task Cleanup Flow
+### 6.4 Task Close Flow
 ```text
 POST /api/tasks/:taskSlug/cleanup
-  -> require no running role sessions
   -> load task metadata
-  -> verify worktree path belongs under <baseRepoRoot>/.ai/vcm/worktrees/
-  -> check worktree status
-  -> refuse cleanup when uncommitted work exists unless force is explicitly requested
-  -> git worktree remove <worktreePath>
-  -> delete central task/session/message/orchestration metadata
+  -> list role sessions for the task
+  -> stop each VCM-managed role session whose runtime status is running
+  -> stop translation tailers and clear task translation cache
+  -> when worktreePath exists, verify it belongs under <baseRepoRoot>/.ai/vcm/worktrees/
+  -> when worktreePath exists, git worktree remove --force <worktreePath>
+  -> when worktreePath exists, delete the task branch by default
+  -> delete base task metadata
+  -> delete task runtime session/message/orchestration/translation metadata
 ```
-Branch deletion is intentionally separate:
-- Keep `feature/<taskSlug>` by default.
-- Allow branch deletion only with explicit confirmation.
-- Prefer allowing deletion only when the branch has been merged, or when the user force-confirms.
+Close Task is intentionally destructive after user confirmation. It actively stops VCM-managed running role sessions, but it does not preflight running sessions or uncommitted worktree changes. Tasks created without a worktree remove VCM metadata only because there is no VCM-owned branch/worktree to delete.
 ## 7. Task And Artifact Model
@@ -359,9 +373,8 @@ Each task stores:
 - `taskSlug`
 - optional `title`
 - timestamps
-- `baseRepoRoot`
-- `worktreePath`
-- `repoRoot` / `taskRepoRoot`
+- `repoRoot`, which is the connected base repository
+- optional `worktreePath`, which is the task runtime repo when present
 - branch, always `feature/<taskSlug>` for VCM-created tasks
 - handoff directory
 - status
@@ -378,6 +391,8 @@ POST /api/tasks
   -> write base .ai/vcm/tasks/<task>.json
 ```
+Task cleanup is orchestrated by `src/backend/api/task-routes.ts` because it coordinates session stopping, translation tailer stopping, and `TaskService.cleanupTask`.
 Handoff directory:
 ```text
@@ -480,7 +495,7 @@ Permission flags:
 Session persistence:
 ```text
-<baseRepoRoot>/.ai/vcm/sessions/<task>.json
+<taskRepoRoot>/.ai/vcm/sessions/<task>.json
 ```
 The persisted record includes:
@@ -545,9 +560,9 @@ Files:
 State:
 ```text
-.ai/vcm/messages/<task>.jsonl
-.ai/vcm/orchestration/<task>.json
-.ai/handoffs/<task>/messages/<message-id>.md
+<taskRepoRoot>/.ai/vcm/messages/<task>.jsonl
+<taskRepoRoot>/.ai/vcm/orchestration/<task>.json
+<taskRepoRoot>/.ai/handoffs/<task>/messages/<message-id>.md
 ```
 Policy:
@@ -559,16 +574,10 @@ Policy:
 Manual mode:
 ```text
-send -> pending_approval -> Stage -> staged
+send -> pending_approval or queued -> Messages modal -> Copy/manual action
 ```
-`Stage` writes:
-```text
-Read and handle VCM message <id> at <bodyPath>
-```
-It does not append Enter.
+The current GUI shows sequence, timestamp, status, body preview, path, and a `Copy` button. It does not expose Open Role, Stage, or Reject buttons. The backend still exposes stage/approve/reject routes; `Stage` writes `Read and handle VCM message <id> at <bodyPath>` without appending Enter.
 Auto mode:
@@ -576,11 +585,11 @@ Auto mode:
 send -> delivered
 ```
-The backend writes a `[VCM MESSAGE]` envelope to the target terminal and appends Enter.
+The backend pastes a `[VCM MESSAGE]` envelope into the target terminal, then sends Enter as a separate terminal input event.
 The backend still exposes pause/resume orchestration API routes and stores `paused` for compatibility. The current GUI only toggles `mode` between `manual` and `auto`.
-Messages and orchestration snapshots are central project state under `baseRepoRoot/.ai/vcm`. Message body markdown lives in the task worktree handoff directory.
+Messages and orchestration snapshots are task runtime state under `taskRepoRoot/.ai/vcm`. Message body markdown also lives in the task worktree handoff directory.
 ## 12. Role Command Compatibility
@@ -608,7 +617,7 @@ The dispatcher:
 2. Reads the role command artifact.
 3. Rejects missing, empty, or placeholder role commands.
 4. Resolves primary command path `role-commands/<role>.md`, with legacy fallback `<role>-command.md`.
-5. Writes `Please read and execute the role command at: <path>` to the target terminal and submits Enter.
+5. Pastes `Please read and execute the role command at: <path>` to the target terminal, then sends Enter as a separate terminal input event.
 This is a compatibility path. The preferred V1 coordination path is `vcmctl` message bus.
@@ -664,7 +673,6 @@ Files:
 - `src/backend/services/translation-prompts.ts`
 - `src/backend/services/claude-transcript-service.ts`
 - `src/backend/adapters/translation-provider.ts`
-- `src/backend/ws/translation-ws.ts`
 - `src/backend/api/translation-routes.ts`
 - `src/frontend/components/translation-panel.tsx`
 - `src/frontend/components/translation-settings-modal.tsx`
@@ -683,6 +691,7 @@ Storage:
 Stored data:
+- UI theme preference: `system`, `light`, or `dark`
 - translation settings
 - translation secrets
 - recent repository paths, max 5
@@ -718,8 +727,11 @@ Tailer:
 - validates file exists
 - can replay history since session start minus a grace window
 - uses `fs.watch`
-- also polls every 500ms
+- also polls every 200ms
 - parses only complete newline-delimited JSON records
+- is owned by the backend translation service, not the frontend panel
+- stays running after the panel closes
+- stops only when the role session is stopped/restarted or the task is closed
 Parsed transcript events:
@@ -736,9 +748,21 @@ Translation service behavior:
 - ignores thinking
 - translates text/question/todo/agent as prose
 - preserves tool_use/tool_result as tool-output
-- queues translation per runtime session id
-- emits WebSocket `translation-entry`
-- emits WebSocket `translation-status`
+- queues provider translation per runtime session id
+- pushes prose entries before provider translation starts
+- pushes tool_use/tool_result immediately without entering the translation queue
+- writes translation events to `<taskRepoRoot>/.ai/vcm/translation/<task>/<role>/<session-id>.jsonl`
+- exposes HTTP polling for frontend rendering
+Polling protocol:
+- `seq` starts at 1 for each translation session cache.
+- the frontend calls `GET /api/translation/sessions/:sessionId/events?after=<cursor>`.
+- `after` is the next expected seq, not the last displayed seq.
+- `after=18` lets the backend delete cached events with `seq < 18` and return events with `seq >= 18`.
+- if `after` is older than the retained cache, the backend returns whatever newer events still exist.
+- no snapshot mismatch error is used.
+- translated prose replacement is a later `entry` event with the same translation entry id and a newer `seq`.
 ### User Input Path
@@ -749,10 +773,10 @@ textarea -> POST translation/input -> provider -> English draft in the same text
 Send path:
 ```text
-POST translation/send -> runtime.write(session.id, englishText + "\r")
+POST translation/send -> bracketed paste English text -> short delay -> runtime.write(session.id, "\r")
 ```
-The backend strips trailing newlines before appending `\r`.
+The backend strips trailing newlines before pasting and sends Enter separately. This avoids Claude Code TUI cases where a single large PTY write containing both text and `\r` fills the input line but does not submit it.
 ## 15. API Surface
@@ -819,6 +843,13 @@ POST /api/tasks/:taskSlug/orchestration/pause
 POST /api/tasks/:taskSlug/orchestration/resume
 ```
+App settings:
+```text
+GET  /api/settings/preferences
+PUT  /api/settings/preferences
+```
 Translation:
 ```text
@@ -826,6 +857,8 @@ GET  /api/translation/settings
 PUT  /api/translation/settings
 GET  /api/translation/prompts
 POST /api/translation/test
+POST /api/tasks/:taskSlug/sessions/:role/translation/start
+GET  /api/translation/sessions/:sessionId/events?after=<cursor>&limit=<n>
 POST /api/tasks/:taskSlug/sessions/:role/translation/input
 POST /api/tasks/:taskSlug/sessions/:role/translation/send
 POST /api/translation/sessions/:sessionId/clear
@@ -836,7 +869,6 @@ WebSockets:
 ```text
 /ws/terminal/:sessionId
-/ws/translation/:sessionId
 ```
 ## 16. Error Handling