vibe-coding-master 0.0.11 → 0.0.13

package/docs/v1-architecture-design.md

@@ -28,7 +28,7 @@ browser
   -> claude --agent <role>
 ```
 
-The app is local-first. It writes project control state under `.ai/vcm/`, handoff artifacts under `.ai/handoffs/` inside the active task worktree, app settings under `~/.vcm/settings.json`, and reads Claude transcript files under `~/.claude/projects/`.
+The app is local-first. It writes project control state under `.ai/vcm/`, handoff artifacts under `.ai/vcm/handoffs/` inside the active task worktree, app settings under `~/.vcm/settings.json`, and reads Claude transcript files under `~/.claude/projects/`.
 
 ## 2. Processes And Ports
 
@@ -94,7 +94,7 @@ Responsibilities:
 - Render repository connect form.
 - Render repository summary.
 - Render workflow panel.
-- Render settings section with Theme, Messages, Events, Auto orchestration.
+- Render settings section with Theme, Round alert, Messages, and Events.
 - Render harness status/actions.
 - 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.
@@ -110,10 +110,13 @@ File:
 
 Responsibilities:
 
-- Fetch task status, messages, and orchestration state.
+- Fetch task status, messages, orchestration state, and round state.
 - Poll those every three seconds.
 - Render compact header with task title, branch, immutable worktree path, role tabs, Refresh, and red `Close Task`.
 - Hold per-role permission mode selection.
+- Hold task orchestration state and pass its on/off control to the active role console.
+- Detect newly delivered auto-orchestration messages and switch the active role tab to the target role.
+- Emit task round state to `App` so completion alerts can be deduplicated and displayed.
 - Render one `SessionConsole` per role but only show the active role.
 - Emit workflow/messages/orchestration/events back to `App` so sidebar stays synchronized.
 
@@ -125,6 +128,12 @@ File:
 
 Responsibilities:
 
+- Render role session controls and embedded terminal.
+- Render `Auto orchestration` immediately to the left of `Translate`, using the same compact toggle styling.
+- Render the translation split panel when `Translate` is enabled.
+
+Responsibilities:
+
 - Render role toolbar.
 - Render embedded terminal for running sessions.
 - Render empty/resume state for stopped sessions.
@@ -242,7 +251,7 @@ feature/<taskSlug>
 Worktree path:
 
 ```text
-<baseRepoRoot>/.ai/vcm/worktrees/<taskSlug>
+<baseRepoRoot>/.claude/worktrees/<taskSlug>
 ```
 
 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.
@@ -258,7 +267,7 @@ worktreePath: undefined
 VCM does not create worktrees by role. All four role sessions for a task share the same task worktree:
 
 ```text
-.ai/vcm/worktrees/<taskSlug>/
+.claude/worktrees/<taskSlug>/
   project-manager session cwd
   architect session cwd
   coder session cwd
@@ -274,11 +283,11 @@ VCM distinguishes:
 - `branch`: `feature/<taskSlug>`.
 - `worktreePath`: same as `taskRepoRoot`.
 
-Base repo state is only the task index and the container for nested task worktrees:
+Base repo state is the task index plus the Claude-compatible container for nested task worktrees:
 
 ```text
 <baseRepoRoot>/.ai/vcm/tasks/<task>.json
-<baseRepoRoot>/.ai/vcm/worktrees/<task>/
+<baseRepoRoot>/.claude/worktrees/<task>/
 ```
 
 Project configuration is app-local and stored outside the repository:
@@ -291,28 +300,30 @@ Project configuration is app-local and stored outside the repository:
 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>/
+<baseRepoRoot>/.claude/worktrees/<task>/.ai/vcm/sessions/<task>.json
+<baseRepoRoot>/.claude/worktrees/<task>/.ai/vcm/messages/<task>.jsonl
+<baseRepoRoot>/.claude/worktrees/<task>/.ai/vcm/orchestration/<task>.json
+<baseRepoRoot>/.claude/worktrees/<task>/.ai/vcm/translation/<task>/
+<baseRepoRoot>/.claude/worktrees/<task>/.ai/vcm/handoffs/
 ```
 
 For inline tasks, `taskRepoRoot` is the connected base repo, so these same runtime paths resolve under the connected repo's `.ai/vcm/`.
 
+Because the handoff directory is `<taskRepoRoot>/.ai/vcm/handoffs/` without a task slug segment, VCM rejects creating a second active inline task in the same connected repository. Parallel tasks should use the default worktree mode.
+
 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
 
-The base repository must ignore `.ai/vcm/`.
+The base repository must ignore `.ai/vcm/` and `.claude/worktrees/`.
 
 Reason:
 
-- `.ai/vcm/worktrees/<task>` is a nested git worktree.
-- Without `.ai/vcm/` in `.gitignore`, the base repo sees worktree files as untracked noise.
+- `.claude/worktrees/<task>` is a nested git worktree.
+- Without `.claude/worktrees/` in `.gitignore`, the base repo sees worktree files as untracked noise.
 - `.ai/vcm` also contains local task/session/message metadata that should not be committed by default.
 
-The VCM harness manages a `.gitignore` block that ignores `.ai/vcm/` before task worktree creation.
+The VCM harness manages a `.gitignore` block that ignores `.ai/vcm/` and `.claude/worktrees/` before task worktree creation.
 
 ### 6.3 Task Creation Flow
 
@@ -321,15 +332,17 @@ POST /api/tasks
   -> validate taskSlug
   -> assert .ai/vcm/ is ignored by Git
   -> if createWorktree is not false:
+       -> assert .claude/worktrees/ is ignored by Git
        -> compute branch feature/<taskSlug>
-       -> compute worktreePath <baseRepoRoot>/.ai/vcm/worktrees/<taskSlug>
+       -> compute worktreePath <baseRepoRoot>/.claude/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
+	  -> otherwise:
+	       -> read current base repo branch
+	       -> leave worktreePath undefined
+	       -> reject when another inline task is already active
   -> create handoff structure in taskRepoRoot
   -> write central task metadata under baseRepoRoot/.ai/vcm/tasks/<task>.json
 ```
@@ -344,11 +357,12 @@ POST /api/tasks/:taskSlug/cleanup
   -> 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, verify it belongs under <baseRepoRoot>/.claude/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
+  -> delete task runtime handoff directory
 ```
 
 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.
@@ -396,7 +410,7 @@ Task cleanup is orchestrated by `src/backend/api/task-routes.ts` because it coor
 Handoff directory:
 
 ```text
-<taskRepoRoot>/.ai/handoffs/<task>/
+<taskRepoRoot>/.ai/vcm/handoffs/
   role-commands/
     architect.md
     coder.md
@@ -528,7 +542,7 @@ The runtime:
 - spawns `node-pty`
 - sets `TERM=xterm-256color`
 - sets color-friendly env vars
-- appends raw PTY output to `<taskRepoRoot>/.ai/handoffs/<task>/logs/<role>.log`
+- appends raw PTY output to `<taskRepoRoot>/.ai/vcm/handoffs/logs/<role>.log`
 - emits terminal output/input/exit events to WebSocket subscribers
 - replays the log on terminal WebSocket subscribe
 
@@ -562,7 +576,7 @@ State:
 ```text
 <taskRepoRoot>/.ai/vcm/messages/<task>.jsonl
 <taskRepoRoot>/.ai/vcm/orchestration/<task>.json
-<taskRepoRoot>/.ai/handoffs/<task>/messages/<message-id>.md
+<taskRepoRoot>/.ai/vcm/handoffs/messages/<message-id>.md
 ```
 
 Policy:
@@ -582,16 +596,58 @@ The current GUI shows sequence, timestamp, status, body preview, path, and a `Co
 Auto mode:
 
 ```text
-send -> delivered
+send -> delivered when target has no active message
+send -> queued when target is already handling a delivered message
+target role reply/result -> acknowledge active message -> deliver next queued message for that role
 ```
 
-The backend pastes a `[VCM MESSAGE]` envelope into the target terminal, then sends Enter as a separate terminal input event.
+The backend pastes a `[VCM MESSAGE]` envelope into the target terminal, then sends Enter as a separate terminal input event. Delivery is serialized per target role. VCM does not infer Claude Code readiness from PTY silence; it treats `vcmctl reply` and `vcmctl result` from that role as the turn-complete signal.
+
+The message service also serializes message mutations per task inside the VCM process so concurrent API calls cannot bypass the per-role in-flight check.
 
 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 task runtime state under `taskRepoRoot/.ai/vcm`. Message body markdown also lives in the task worktree handoff directory.
 
-## 12. Role Command Compatibility
+## 12. Round Completion Architecture
+
+Files:
+
+- `src/backend/services/round-service.ts`
+- `src/backend/api/round-routes.ts`
+- `src/shared/types/round.ts`
+
+API:
+
+```text
+GET /api/tasks/:taskSlug/round
+```
+
+The round service subscribes to the same backend Claude transcript tailer used by translation. It tracks one lightweight state record per running role session:
+
+- `unknown`
+- `answering`
+- `using_tools`
+- `waiting_user`
+- `abnormal`
+- `idle`
+
+`stop_reason === "end_turn"` is treated only as a candidate answer end. The service waits until pending tool uses are cleared and a short debounce passes before marking that role `idle`.
+
+Task-level completion:
+
+- If a message is currently `delivered` or `staged`, the latest such message defines the round target.
+- In a PM -> role -> PM chain, completion follows the newest delivered message, so the round completes after PM finishes the final response.
+- Queued or pending messages prevent completion.
+- If no VCM message is in the round, the latest direct role answer can still produce a completion state.
+
+Frontend behavior:
+
+- `TaskWorkspace` polls the round endpoint with the other task state.
+- `App` stores the sidebar `Round alert` preference in `~/.vcm/settings.json`.
+- `App` deduplicates `completionId`, then shows a small `Round complete` prompt and plays a short Web Audio tone when alerts are enabled.
+
+## 13. Role Command Compatibility
 
 Files:
 
@@ -621,7 +677,7 @@ The dispatcher:
 
 This is a compatibility path. The preferred V1 coordination path is `vcmctl` message bus.
 
-## 13. Harness Service
+## 14. Harness Service
 
 File:
 
@@ -651,6 +707,7 @@ Managed block:
 ```gitignore
 # VCM:BEGIN version=1
 .ai/vcm/
+.claude/worktrees/
 # VCM:END
 ```
 
@@ -664,7 +721,7 @@ The service:
 
 It must not overwrite user content outside the VCM block.
 
-## 14. Translation Architecture
+## 15. Translation Architecture
 
 Files:
 
@@ -778,7 +835,7 @@ POST translation/send -> bracketed paste English text -> short delay -> runtime.
 
 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
+## 16. API Surface
 
 Project:
 
@@ -843,6 +900,12 @@ POST /api/tasks/:taskSlug/orchestration/pause
 POST /api/tasks/:taskSlug/orchestration/resume
 ```
 
+Round:
+
+```text
+GET  /api/tasks/:taskSlug/round
+```
+
 App settings:
 
 ```text
@@ -871,7 +934,7 @@ WebSockets:
 /ws/terminal/:sessionId
 ```
 
-## 16. Error Handling
+## 17. Error Handling
 
 File:
 
@@ -896,7 +959,7 @@ Fastify error handler returns:
 }
 ```
 
-## 17. Packaging Architecture
+## 18. Packaging Architecture
 
 `package.json` publishes built artifacts:
 
@@ -918,7 +981,7 @@ Important scripts:
 - `prepack`: build and package verification
 - `postinstall`: fixes `node-pty` spawn helper when needed
 
-## 18. Security And Safety Boundaries
+## 19. Security And Safety Boundaries
 
 Current boundaries:
 
@@ -928,11 +991,11 @@ Current boundaries:
 - Translation API key is local in `~/.vcm/settings.json`.
 - Translation output is UI/runtime state only unless a user or role copies it into a file.
 - `.ai/vcm` is local project control state and must be ignored by Git.
-- Task handoff artifacts live in the task worktree and users should decide whether those artifacts belong in task commits.
+- Task handoff artifacts live under `.ai/vcm/handoffs/` as task-local runtime state and are removed by Close Task. Durable conclusions belong in normal project docs, code comments, commit messages, or PR text.
 - Task worktrees are created only during task creation; VCM does not expose branch/worktree switching APIs.
 - Sandbox isolation should come from a devContainer, Docker container, VM, or other user-controlled environment.
 
-## 19. Known Implementation Boundaries
+## 20. Known Implementation Boundaries
 
 - No tmux backend.
 - No per-role worktree manager.

package/docs/v1-implementation-plan.md

@@ -17,7 +17,7 @@ V1 is implemented as a local GUI app with:
 - API-driven message bus.
 - Translation panel based on Claude transcript JSONL tailing.
 - npm packaging with built `dist` and `dist-frontend` output.
-- Task creation creates one `feature/<task>` branch and one `.ai/vcm/worktrees/<task>` git worktree by default; users may clear `Create worktree and branch` to create an inline task in the connected repository/current branch.
+- Task creation creates one `feature/<task>` branch and one `.claude/worktrees/<task>` git worktree by default; users may clear `Create worktree and branch` to create an inline task in the connected repository/current branch. Because handoffs are scoped as `.ai/vcm/handoffs/` under the task runtime repo, only one active inline task is allowed per connected repository.
 
 ## 2. Package And Build
 
@@ -193,6 +193,11 @@ Theme modes:
 - `light`
 - `dark`
 
+Preferences:
+
+- `themeMode`
+- `roundCompletionAlerts`, default `true`
+
 ### `src/shared/types/task.ts`
 
 Defines:
@@ -210,7 +215,7 @@ Worktree fields:
 - `cleanupStatus?: "active" | "cleaned"`
 - `cleanedAt?: string`
 
-`CreateTaskRequest` supports `createWorktree?: boolean`. It creates a worktree and branch by default, and skips both when `createWorktree === false`.
+`CreateTaskRequest` supports `createWorktree?: boolean`. It creates a worktree and branch by default, and skips both when `createWorktree === false`. Inline creation rejects a second active inline task in the same connected repository.
 
 ### `src/shared/types/session.ts`
 
@@ -239,6 +244,17 @@ Defines:
 
 The state type includes `paused` for backend/API compatibility. The current GUI only exposes manual/auto.
 
+### `src/shared/types/round.ts`
+
+Defines:
+
+- `VcmRoleTurnStatus`
+- `VcmTaskRoundStatus`
+- `VcmRoleTurnState`
+- `VcmTaskRoundState`
+
+Round state is task-level. It reports the latest active/completed role, queued and pending message counts, and a stable `completionId` for frontend notification dedupe.
+
 ### `src/shared/types/translation.ts`
 
 Defines:
@@ -413,7 +429,7 @@ Worktree methods:
 Required safety:
 
 - all Git commands keep command-scoped `safe.directory`
-- `TaskService` verifies Close Task worktree paths are under `<baseRepoRoot>/.ai/vcm/worktrees/`
+- `TaskService` verifies Close Task worktree paths are under `<baseRepoRoot>/.claude/worktrees/`
 - VCM-created task branches are derived from validated task slugs as `feature/<taskSlug>`
 
 ### `src/backend/adapters/claude-adapter.ts`
@@ -503,7 +519,7 @@ Responsibilities:
 - record recent repo paths in app settings
 - create `~/.vcm/projects/<project-id>/config.json`
 - ensure base state directories
-- ensure `.ai/vcm/` is ignored by Git before task-worktree creation
+- ensure `.ai/vcm/` and `.claude/worktrees/` are ignored by Git before task-worktree creation
 - expose base repo as the project control root
 
 Repository connect should keep connecting to the base repo. Task worktrees are managed under that base repo and should not be treated as separate projects in the normal task list.
@@ -539,17 +555,19 @@ createTask(baseRepoRoot, { taskSlug })
   -> assertValidTaskSlug(taskSlug)
   -> assert .ai/vcm/ is ignored
   -> if createWorktree is not false:
+       -> assert .claude/worktrees/ is ignored
        -> branch = feature/<taskSlug>
-       -> worktreePath = <baseRepoRoot>/.ai/vcm/worktrees/<taskSlug>
+       -> worktreePath = <baseRepoRoot>/.claude/worktrees/<taskSlug>
        -> assert base repo has no uncommitted changes
        -> assert branch does not exist
        -> assert worktree path does not exist
        -> git.createWorktree({ baseRepoRoot, branch, worktreePath, baseRef: HEAD })
        -> taskRepoRoot = worktreePath
-  -> otherwise:
-       -> branch = current base repo branch
-       -> worktreePath = undefined
-       -> taskRepoRoot = baseRepoRoot
+	  -> otherwise:
+	       -> branch = current base repo branch
+	       -> worktreePath = undefined
+	       -> taskRepoRoot = baseRepoRoot
+	       -> reject if another inline task is already active
   -> artifactService.ensureHandoffStructure({ repoRoot: taskRepoRoot, handoffDir })
   -> artifactService.createArtifactTemplates({ repoRoot: taskRepoRoot, handoffDir })
   -> ensure task runtime state dirs under <taskRepoRoot>/.ai/vcm/
@@ -564,10 +582,11 @@ cleanupTask(baseRepoRoot, taskSlug, options)
   -> route layer lists role sessions
   -> route layer stops each VCM-managed role session with status running
   -> route layer stops translation tailers and clears task translation cache
-  -> if worktreePath exists, verify it is under <baseRepoRoot>/.ai/vcm/worktrees/
+  -> if worktreePath exists, verify it is under <baseRepoRoot>/.claude/worktrees/
   -> if worktreePath exists, git.removeWorktree(baseRepoRoot, worktreePath, force=true)
   -> if worktreePath exists, git.deleteBranch(baseRepoRoot, task.branch, force=true) by default
-  -> delete <baseRepoRoot>/.ai/vcm/tasks/<task>.json
+	  -> delete <baseRepoRoot>/.ai/vcm/tasks/<task>.json
+	  -> delete <taskRepoRoot>/.ai/vcm/handoffs/
   -> delete <taskRepoRoot>/.ai/vcm/sessions/<task>.json
   -> delete <taskRepoRoot>/.ai/vcm/messages/<task>.jsonl
   -> delete <taskRepoRoot>/.ai/vcm/orchestration/<task>.json
@@ -599,13 +618,13 @@ In task-worktree mode, artifact paths are still repo-relative, but `repoRoot` mu
 Primary role command path:
 
 ```text
-.ai/handoffs/<task>/role-commands/<role>.md
+.ai/vcm/handoffs/role-commands/<role>.md
 ```
 
 Legacy fallback:
 
 ```text
-.ai/handoffs/<task>/role-commands/<role>-command.md
+.ai/vcm/handoffs/role-commands/<role>-command.md
 ```
 
 ### `src/backend/services/status-service.ts`
@@ -674,6 +693,10 @@ Responsibilities:
 - stage/approve/reject messages
 - get/update orchestration state
 - enforce message policy
+- enforce per-target-role in-flight delivery
+- queue extra messages for a busy target role
+- acknowledge a role's active message when that role sends `vcmctl reply` or `vcmctl result`
+- deliver the next queued message for that role after acknowledgement
 - persist message snapshots
 - write message body markdown
 - write staged or delivered messages to target terminal
@@ -682,8 +705,9 @@ In task-worktree mode:
 
 - message snapshots live under `task.worktreePath/.ai/vcm/messages`
 - orchestration state lives under `task.worktreePath/.ai/vcm/orchestration`
-- message body files live under `task.worktreePath/.ai/handoffs/<task>/messages`
+- message body files live under `task.worktreePath/.ai/vcm/handoffs/messages`
 - terminal delivery uses the runtime session for the role, whose cwd is the task worktree
+- message mutations are serialized per task inside the VCM process to avoid concurrent API calls bypassing the in-flight check
 
 ### `src/backend/services/command-dispatcher.ts`
 
@@ -810,6 +834,26 @@ Responsibilities:
 
 Terminal submission is delegated to `src/backend/runtime/terminal-submit.ts`, which bracket-pastes text, waits briefly, then sends Enter separately.
 
+### `src/backend/services/round-service.ts`
+
+Exports:
+
+- `RoundService`
+- `TaskRoundInput`
+- `RoundServiceDeps`
+- `createRoundService(deps)`
+- `evaluateTaskRoundState(input)`
+
+Responsibilities:
+
+- subscribe to Claude transcript events for running role sessions
+- track per-role turn state, pending tool use ids, and debounced `end_turn`
+- mark a role idle only after `stop_reason === "end_turn"`, no pending tools, and debounce
+- evaluate task-level round completion from messages plus role states
+- wait for the latest delivered/staged target role in PM -> role -> PM chains
+- ignore completion while queued or pending messages exist
+- stop trackers on session stop/restart and task close
+
 ## 9. Backend API
 
 ### `src/backend/server.ts`
@@ -835,6 +879,7 @@ Registers HTTP routes and the terminal WebSocket.
 - `src/backend/api/session-routes.ts`: session lifecycle and dispatch compatibility endpoint
 - `src/backend/api/artifact-routes.ts`: artifact, role command, and log reads/writes
 - `src/backend/api/message-routes.ts`: messages and orchestration
+- `src/backend/api/round-routes.ts`: task round completion state
 - `src/backend/api/translation-routes.ts`: settings, prompt previews, provider test, start/poll, input/send, clear/retry
 
 Worktree task API:
@@ -853,6 +898,8 @@ Terminal WebSocket forwards PTY output/input/resize.
 
 Translation does not use WebSocket. The backend writes cached translation events under `<taskRepoRoot>/.ai/vcm/translation/<task>/<role>/<session-id>.jsonl`; the frontend polls `GET /api/translation/sessions/:sessionId/events?after=<cursor>`. The cursor is the next expected seq, so `after=18` means seq `1..17` can be removed and seq `18+` should be returned.
 
+Round completion is HTTP-polled too. `GET /api/tasks/:taskSlug/round` returns `VcmTaskRoundState` from backend transcript trackers and message state; it is not a WebSocket stream.
+
 ## 10. Backend Templates
 
 ### `src/backend/templates/handoff.ts`
@@ -908,6 +955,7 @@ It calls:
 - artifact endpoints
 - message endpoints
 - orchestration endpoints
+- round completion endpoint
 - translation endpoints
 
 Implemented task cleanup method:
@@ -941,10 +989,12 @@ Responsibilities:
 
 - own top-level app state
 - load current project and recent paths on startup
+- load app preferences, including `themeMode` and `roundCompletionAlerts`
 - load tasks and harness status after connect
 - pass sidebar props to `ProjectDashboard`
 - pass task props to `TaskWorkspace`
 - keep active workflow/messages/orchestration/events synchronized by task
+- dedupe task round `completionId` values and show/play completion alerts when enabled
 
 ### `src/frontend/routes/project-dashboard.tsx`
 
@@ -960,6 +1010,7 @@ Responsibilities:
 - repository summary
 - workflow panel
 - settings section
+- round completion alert toggle
 - messages modal
 - events modal
 - harness panel
@@ -979,6 +1030,7 @@ Responsibilities:
 - red `Close Task` action with destructive confirmation
 - show branch and immutable worktree path for the active task
 - status/message/orchestration refresh
+- round state refresh
 - periodic polling
 - session lifecycle actions
 - per-role permission state
@@ -1071,7 +1123,7 @@ Exports:
 - `SessionConsoleProps`
 - `SessionConsole(props)`
 
-Role console and translation split.
+Role console, `Auto orchestration` toggle, and translation split.
 
 ### `src/frontend/components/session-toolbar.tsx`
 
@@ -1145,8 +1197,9 @@ Sidebar:
 
 - all groups default collapsed
 - `Repository Path` default open only when no task is selected
-- `Settings` includes `Theme`, `Messages`, `Events`, and `Auto orchestration`
+- `Settings` includes `Theme`, `Round alert`, `Messages`, and `Events`
 - `Theme` cycles through `System`, `Light`, and `Dark`; `System` follows the browser/OS color-scheme preference
+- `Round alert` is on by default and controls the in-app completion prompt plus short sound
 
 Task workspace:
 
@@ -1154,6 +1207,15 @@ Task workspace:
 - workflow is not in main workspace
 - messages/events are not in main workspace
 - active role console fills available space
+- `Auto orchestration` appears immediately to the left of `Translate` and uses the same compact toggle style
+
+Round completion:
+
+- backend transcript trackers use `stop_reason === "end_turn"` only after pending tools clear and debounce
+- task state follows the latest delivered/staged message target role
+- PM -> role -> PM chains complete after PM's final `end_turn`, not after the intermediate role's `end_turn`
+- queued or pending messages keep the round active
+- frontend dedupes `completionId` before showing a prompt or playing sound
 
 Translation:
 
@@ -1171,7 +1233,7 @@ App settings:
 ~/.vcm/settings.json
 ```
 
-Contains UI theme preference, translation settings/secrets, and recent repository paths.
+Contains UI theme preference, round-completion alert preference, translation settings/secrets, and recent repository paths.
 
 Project config:
 
@@ -1196,7 +1258,7 @@ Messages:
 
 ```text
 <taskRepoRoot>/.ai/vcm/messages/<task>.jsonl
-<taskRepoRoot>/.ai/handoffs/<task>/messages/<message-id>.md
+<taskRepoRoot>/.ai/vcm/handoffs/messages/<message-id>.md
 ```
 
 Orchestration:
@@ -1214,13 +1276,13 @@ Translation cache:
 Task worktrees:
 
 ```text
-.ai/vcm/worktrees/<task>/
+.claude/worktrees/<task>/
 ```
 
 Handoff artifacts:
 
 ```text
-.ai/handoffs/<task>/
+.ai/vcm/handoffs/
 ```
 
 Claude transcripts:
@@ -1243,9 +1305,9 @@ npm run verify:package
 For frontend layout changes, also verify manually:
 
 - connect repository
-- confirm `.ai/vcm/` is ignored before creating a task worktree
+- confirm `.ai/vcm/` and `.claude/worktrees/` are ignored before creating a task worktree
 - create task and verify branch `feature/<task>` is created
-- verify worktree path is `<baseRepoRoot>/.ai/vcm/worktrees/<task>`
+- verify worktree path is `<baseRepoRoot>/.claude/worktrees/<task>`
 - open task
 - verify role sessions start with cwd set to the task worktree
 - role tabs stay in header
@@ -1254,7 +1316,9 @@ For frontend layout changes, also verify manually:
 - translation split is 50/50
 - Messages modal opens from sidebar Settings
 - Events modal opens from sidebar Settings
-- Auto orchestration toggles on/off
+- Auto orchestration toggles on/off from the role toolbar
+- Auto orchestration switches to the target role tab when a new message is delivered
+- Round alert can be toggled from sidebar Settings and fires once after a chained round truly completes
 - `Enter` in translation composer translates/sends
 - `Shift+Enter` inserts newline
 - close a worktree-backed task and verify it stops running role sessions, removes the worktree, deletes the task branch, and removes central task metadata

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vibe-coding-master",
-  "version": "0.0.11",
+  "version": "0.0.13",
   "description": "Local GUI session cockpit for Claude Code role sessions.",
   "type": "module",
   "files": [