npm - vibe-coding-master - Versions diffs - 0.4.41 → 0.5.0 - Mend

vibe-coding-master 0.4.41 → 0.5.0

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 (22) hide show

package/dist/backend/api/task-routes.js +7 -0
package/dist/backend/api/translation-routes.js +11 -0
package/dist/backend/errors.js +2 -0
package/dist/backend/gateway/gateway-service.js +31 -61
package/dist/backend/server.js +11 -1
package/dist/backend/services/round-service.js +34 -0
package/dist/backend/services/task-launch-service.js +91 -0
package/dist/backend/services/translation-service.js +87 -0
package/dist/backend/services/translation-worker-service.js +228 -72
package/dist-frontend/assets/index-BaDS9Ohj.js +96 -0
package/dist-frontend/index.html +1 -1
package/docs/ARCHITECTURE.md +123 -0
package/docs/TESTING.md +121 -73
package/docs/known-issues.md +155 -0
package/package.json +1 -1
package/dist-frontend/assets/index-CsxS5H0d.js +0 -96
package/docs/claude-code-translation-plan.md +0 -1268
package/docs/full-harness-baseline.md +0 -160
package/docs/gate-review-gates.md +0 -132
package/docs/gateway-design.md +0 -813
package/docs/v0.2-implementation-plan.md +0 -408
package/docs/v0.4-harness-optimization-plan.md +0 -664

package/dist-frontend/index.html CHANGED Viewed

@@ -4,7 +4,7 @@
     <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-CsxS5H0d.js"></script>
+    <script type="module" crossorigin src="/assets/index-BaDS9Ohj.js"></script>
     <link rel="stylesheet" crossorigin href="/assets/index-BM6nSKae.css">
   </head>
   <body>

package/docs/ARCHITECTURE.md CHANGED Viewed

@@ -1 +1,124 @@
 # Architecture
+Project-level architecture for VibeCodingMaster (VCM). VCM is a single npm
+package that provides a local GUI cockpit for running and orchestrating multiple
+Claude Code role sessions around one engineering task.
+This document is architect-owned. It gives the project-wide module overview,
+responsibilities, relationships, dependency direction, and constraints. The
+module-level detailed design lives in [`ARCHITECTURE.md`](../ARCHITECTURE.md) at
+the repository root (the single workspace module recorded in
+`.ai/generated/module-index.json`).
+## Module / Layer Overview
+VCM is one workspace module (`vibe-coding-master`) organized into three source
+layers plus supporting tools.
+| Layer | Path | Responsibility |
+| --- | --- | --- |
+| Backend | `src/backend` | Fastify HTTP + WebSocket server, role/session runtime over `node-pty`, services, external adapters, mobile gateway, and the downstream harness templates. |
+| Frontend | `src/frontend` | React 19 + Vite single-page GUI: task workspace, role tabs, embedded `xterm` terminals, harness/translation panels, and client state stores. |
+| Shared | `src/shared` | Cross-layer TypeScript types, constants (role definitions, ports), and zod-backed validation helpers consumed by both backend and frontend. |
+| Tools / scripts | `.ai/tools`, `scripts` | Generated-context generators, long-running validation wrappers, bash guard, and harness install/verify scripts. |
+### Backend sub-areas (`src/backend`)
+- `api/`: Fastify route modules, one per domain (project, task, session, round,
+  message, harness, gate-review, translation, gateway, diagnostics, artifacts,
+  runtime-state, app-settings, claude-hook). Routes are thin and delegate to
+  services.
+- `services/`: business logic. Key services include `task-service`,
+  `task-launch-service` (backend-owned one-click task start, shared by the GUI
+  endpoint and the gateway), `session-service`, `round-service`,
+  `runtime-coordinator-service`, `message-service`, `harness-service`,
+  `gate-review-service`, `translation-service`/`translation-worker-service`,
+  `job-guard-service`, and `command-dispatcher`.
+- `runtime/`: PTY-backed terminal runtime (`node-pty-runtime`,
+  `terminal-runtime`, `session-registry`, `terminal-submit`) that supervises one
+  Claude Code process per role.
+- `adapters/`: side-effect boundaries — `claude-adapter`, `git-adapter`,
+  `command-runner`, `filesystem`.
+- `gateway/`: mobile gateway service plus channel implementations
+  (Weixin iLink, Lark) and command parsing.
+- `templates/`: message/handoff/role-command templates and, under
+  `templates/harness/`, the source of truth for the VCM harness that VCM installs
+  into downstream repositories.
+- `ws/`: WebSocket bridge (`terminal-ws`) streaming PTY I/O to the frontend.
+- `server.ts`, `main.ts`, `app-version.ts`, `vcm-data-dir.ts`, `errors.ts`:
+  composition root, CLI entry, version, data-dir resolution, error types.
+### Frontend sub-areas (`src/frontend`)
+- `routes/`: top-level views (`project-dashboard`, `task-workspace`).
+- `components/`: GUI building blocks (app shell, session console/toolbar, role
+  session tabs, harness panel/studio, translation panel, message timeline,
+  repo connect form, diff modal, error center).
+- `state/`: client stores and helpers (`app-store`, `session-store`,
+  `api-client`, polling schedulers, translation feed, UI error handling).
+- `terminal/`: `xterm` view and terminal websocket client.
+### Shared sub-areas (`src/shared`)
+- `types/`: domain type contracts shared across layers.
+- `validation/`: pure validators (`artifact-check`, `language-detect`,
+  `slug-check`).
+- `constants.ts`: role definitions and default ports.
+## Module Relationships and Dependency Direction
+```
+frontend  --depends on-->  shared  <--depends on--  backend
+   |                                                   ^
+   +-------- HTTP /api + WS /ws (api-client) ----------+
+```
+- `shared` is the leaf layer. It must not import from `backend` or `frontend`.
+- `backend` and `frontend` both depend on `shared`, and must not depend on each
+  other at the module level.
+- The only runtime coupling between frontend and backend is the HTTP `/api`
+  surface and the `/ws` WebSocket, mediated on the client by
+  `src/frontend/state/api-client.ts` and
+  `src/frontend/terminal/terminal-client.ts`.
+- Within the backend, the intended direction is
+  `api -> services -> (runtime | adapters | gateway | templates)`. Routes should
+  not contain business logic; services should reach the outside world only
+  through adapters and the runtime.
+## Project-Wide Constraints
+- Single npm package, ESM only, TypeScript strict mode. Node `^20 || >=22`.
+- Keep the layer boundary: no `shared -> backend/frontend` imports, no direct
+  `frontend <-> backend` imports.
+- Backend and frontend compile under separate tsconfigs
+  (`tsconfig.node.json`, `tsconfig.json`); new files must fall inside the correct
+  `include` globs, and `npm run typecheck` must pass both.
+- Downstream harness behavior is defined by `src/backend/templates/harness/**`;
+  change harness output there, not in generated target-repo files.
+- Long-running and background process rules from the VCM managed block in
+  `CLAUDE.md` apply; never detach processes.
+- The npm package ships only built artifacts (`dist`, `dist-frontend`, `docs`,
+  `scripts`, `README.md`).
+## Generated Context Ownership
+Generated indexes under `.ai/generated/` are machine-maintained and regenerated
+by the tools in `.ai/tools/`:
+- `.ai/generated/module-index.json` — produced by
+  `.ai/tools/generate-module-index`. Maps the workspace to layers, modules,
+  manifests, module docs, source files, and test files. Use it to locate code and
+  confirm module boundaries.
+- `.ai/generated/public-surface.json` — produced by
+  `.ai/tools/generate-public-surface` (after `module-index.json` exists). It is the
+  authoritative machine index of module-to-module public APIs, routes, and
+  externally consumed surfaces. Treat it as the full public-surface listing;
+  module docs explain meaning and design intent rather than duplicating it.
+Regenerate both after changing module layout, public exports, or HTTP routes.
+## Module-Level Architecture Docs
+- Root module: [`ARCHITECTURE.md`](../ARCHITECTURE.md) — detailed design,
+  boundaries, behavior, public surface explanation, risks, and update triggers
+  for the `vibe-coding-master` workspace module.

package/docs/TESTING.md CHANGED Viewed

@@ -1,82 +1,130 @@
 # Testing
-Validation strategy for `vibe-coding-master` (TypeScript/Node app). Reviewer-owned.
+Reviewer-owned validation strategy for VibeCodingMaster (VCM). This document maps
+the VCM validation levels to project-native commands, where tests live, how to
+select what to run, and the current testing gaps.
-## Validation Levels & Commands
+## Validation Levels and Commands
-| Level | Scope | Command |
-| --- | --- | --- |
-| L0 | format / typecheck | `npm run typecheck` (`tsc -p tsconfig.json --noEmit && tsc -p tsconfig.node.json --noEmit`) |
-| L1/L2 | unit + module/integration tests | `npm run test` (vitest, runs `tests/unit/**` and `tests/integration/**`) |
-| L3 | smoke / E2E (browser) | `npm run e2e` (Playwright) |
-| L4 | full regression / release | `npm run prepack` (build + `verify:package`) + full `npm run test` + `npm run e2e` |
-Targeted run: `npx vitest run <path/to/test.ts>`.
-### Test environment note
-`vitest.config.ts` runs in `environment: "node"` (no jsdom). Frontend tests are
-therefore either pure-helper tests or component tests rendered with
-`react-dom/server` `renderToStaticMarkup` (static HTML assertions), not DOM/event
-tests. Component modules that load browser globals at import time (e.g. the
-xterm-backed `terminal/xterm-view`) must be stubbed with `vi.mock` before the
-component under test is imported.
-## Required prerequisite: build before full `npm run test`
-`tests/unit/backend/harness-templates-sync.test.ts` spawns the real harness
-installer (`scripts/install-vcm-harness.mjs`), which runs the compiled CLI at
-`dist/backend/cli/install-vcm-harness.js`, falling back to the TypeScript source
-only when the `tsx` binary is present. In a clean checkout with no `dist/` and no
-`node_modules/.bin/tsx`, the installer exits with
-`compiled CLI not found. Run npm run build first.` and this single test fails.
-**Run `npm run build` before a full `npm run test`** (or before final acceptance).
-All other unit tests run without a build. This is a documented prerequisite, not a
-product defect or known issue.
+All commands run from the repository root (the task worktree during a VCM task).
-## Final-validation cleanup
-`npm run build` first runs `npm run clean` (`scripts/clean-build.mjs`), removing
-`dist/` and `dist-frontend/`. Final acceptance therefore runs from a clean state via:
+| Level | Scope | Command(s) |
+| --- | --- | --- |
+| L0 fast checks | Format/lint/typecheck/boundary. Project ships typecheck across both tsconfigs. | `npm run typecheck` |
+| L1 coder unit checks | Changed behavior + direct regressions via Vitest unit tests. | `npm test` (optionally a scoped `npx vitest run <path>`) |
+| L2 module / integration checks | Module/API/runtime wiring. Vitest config reserves `tests/integration/api/**` and `tests/integration/runtime/**`. | `npm test` (runs unit + any integration tests that exist) |
+| L3 smoke E2E checks | Core GUI journeys via Playwright. | `npm run e2e` |
+| L4 full regression / release | Build + package verification before publish. | `npm run build` then `npm run verify:package` |
+Notes:
+- `npm run typecheck` runs `tsc` against both `tsconfig.json` (frontend + shared)
+  and `tsconfig.node.json` (backend), so it is the boundary/type gate for the
+  whole module.
+- `npm test` is `vitest run`. Its `include` globs already cover unit and the
+  reserved integration directories, so a single `npm test` is both L1 and L2 once
+  integration tests exist.
+- `npm run e2e` is `playwright test` against `tests/e2e`, and its `webServer`
+  starts `npm run dev` automatically (reusing an existing server if one is up).
+## Validation Selection Rules
+- Docs-only or comment-only change: L0 (`npm run typecheck`) is usually enough; no
+  code behavior to retest.
+- `src/shared/**` change: always L0 + L1, because shared types/validators are
+  cross-cutting to both backend and frontend.
+- `src/backend/**` change: L0 + the affected `tests/unit/backend/**` files; run
+  full `npm test` before handoff. Add L2 when touching runtime, routes, or
+  cross-service wiring.
+- `src/frontend/**` change: L0 + the affected `tests/unit/frontend/**` files; add
+  L3 (`npm run e2e`) when changing a core user journey (connect repo, create task,
+  start/resume a role session, send a message, translation panel).
+- `src/backend/templates/harness/**` change: L0 + `npm test` (harness template
+  sync and harness service/route tests guard these), because output ships into
+  downstream repos.
+- `.ai/tools/**` or `scripts/harness-tools/**` change: run
+  `tests/unit/backend/harness-tools.test.ts` and `vcm-bash-guard.test.ts`.
+- Pre-publish / release: L4 (`npm run build` + `npm run verify:package`).
+## Long-Running Validation
+Use the `vcm-long-running-validation` skill (`.ai/tools/run-long-check` +
+`.ai/tools/watch-job`) for any command that may exceed ~2 minutes (notably
+`npm run e2e` and full builds). Never run validation as a detached/background
+process; the job guard denies it. Honor the 60-minute per-job ceiling.
+## Test Layout
 ```
-npm run build && npm run test
+tests/
+  unit/
+    backend/   # services, routes, runtime, adapters, gateway, harness, tools
+    frontend/  # api-client, stores, components (message timeline, harness panel, translation panel)
+    shared/    # pure validators (artifact-check, language-detect, slug-check)
+  integration/ # reserved by vitest config: api/**, runtime/** (not yet present)
+  e2e/         # reserved by playwright config (not yet present)
 ```
-Do not treat any pre-cleanup test result as final acceptance evidence.
-## Harness "Fixed install" three-state UI cases
-Backend derivation — `tests/unit/backend/harness-service.test.ts`:
-| ID | Scenario | Proves |
-| --- | --- | --- |
-| B1 | fresh repo, all harness files missing | `initialized === false`, `needsApply === true` |
-| B2 | after `applyHarness` | `initialized === true`, `needsApply === false` |
-| B3 | pre-existing non-VCM `CLAUDE.md` (action `insert`) | `initialized === false` |
-| B4 | pre-existing `.claude/settings.json` without VCM hooks (action `update`) | `initialized === false` |
-| B5 | drifted managed block (version 0) | `initialized === true`, `needsApply === true` |
-Frontend render — `tests/unit/frontend/harness-panel.test.ts`
-(entry: `HarnessPanel`, rendered via `renderToStaticMarkup`, `xterm-view` mocked):
-| ID | State | Entry / input | Key assertions |
-| --- | --- | --- | --- |
-| F1 | A — not initialized | `initialized:false, needsApply:true` | subtitle "Not initialized"; only `Initialize` button; no Refresh/Update; no "Files to update" list |
-| F2 | B — has updates | `initialized:true, needsApply:true, plannedChanges:[..]` | subtitle "N pending updates"; "Files to update" list with paths; `Update` + `Refresh`; no `Initialize` |
-| F3 | C — up to date | `initialized:true, needsApply:false` | subtitle "Up to date"; `Refresh` only; no `Update`/`Initialize`; no list |
-| F4 | busy | each state with `busy:true` | every fixed-install action button rendered `disabled` |
-Run: `npx vitest run tests/unit/backend/harness-service.test.ts tests/unit/frontend/harness-panel.test.ts`.
-## Known testing gaps
-- No DOM/interaction (click) tests for the frontend: the node test environment uses
-  static-markup rendering, so button `onClick` wiring is verified by code review and
-  by the backend status-reload behavior, not by simulated events. A jsdom +
-  `@testing-library/react` setup would be needed for true interaction coverage and is
-  not currently configured.
-- No L3 Playwright smoke was run for this task (UI conditional-rendering change with
-  full backend + frontend unit coverage). Reserve E2E for release-level or
-  cross-cutting flow changes.
+- Place unit tests next to their layer under `tests/unit/<layer>/` named
+  `<subject>.test.ts`.
+- Place integration tests under `tests/integration/api/**` or
+  `tests/integration/runtime/**` so the existing Vitest `include` picks them up.
+- Place Playwright specs under `tests/e2e/`.
+## Integration / E2E Case List
+These are reserved by configuration but not yet implemented. They are the
+recommended first cases when integration/E2E coverage is added.
+### Integration (reserved: `tests/integration/api/**`, `tests/integration/runtime/**`)
+| ID | Scenario | Entry point | Proves | Key assertions | When to run | Limitation |
+| --- | --- | --- | --- | --- | --- | --- |
+| INT-API-001 | Project + task lifecycle over HTTP | Fastify app via `project-routes` / `task-routes` | Routes + services persist task state correctly | Create project, create task, read back task, status transitions | L2, on backend api/service change | Not yet implemented |
+| INT-API-002 | Message bus round trip | `message-routes` / `message-service` | Route-file dispatch and history persistence | Posted message is persisted and retrievable in order | L2, on messaging change | Not yet implemented |
+| INT-RT-001 | Session start/resume lifecycle | `runtime-coordinator-service` + `session-registry` | PTY session can start, persist id, and resume | Session id persisted; resume reuses id; stop cleans registry | L2, on runtime change | Not yet implemented; needs `claude`/pty test doubles |
+### E2E (reserved: `tests/e2e/`)
+| ID | Scenario | Entry point | Proves | Key assertions | When to run | Limitation |
+| --- | --- | --- | --- | --- | --- | --- |
+| E2E-001 | Connect repository and create a task | GUI at `http://127.0.0.1:5173` | Core onboarding journey works end to end | Repo connects, branch/status render, task appears in list | L3, before release / on shell or routing change | Not yet implemented; requires a real `claude` binary for live sessions |
+| E2E-002 | Start a role session and observe terminal output | Task workspace role tabs | Embedded terminal streams PTY output over `/ws` | Session starts, xterm receives output, status badge updates | L3, on runtime/terminal change | Not yet implemented; environment-dependent |
+| E2E-003 | Translation panel renders translated transcript | Translation panel | Translator session reads transcript JSONL and renders | Panel shows translated entries without mutating handoffs | L3, on translation change | Not yet implemented |
+| E2E-004 | Auto-orchestration journey (one-click → auto-follow → flow-pause) | GUI task workspace, auto mode | The relocated backend-owned orchestration drives the GUI end to end | One-click starts the roster via `POST /api/tasks/:slug/one-click-start`; the role tab follows `roundState.activeRole`; a stopped round with no next turn raises the `roundState.flowPause` notice | L3, on one-click/round/role-follow change | Not yet implemented; needs a Playwright harness + live `claude`/pty. Until then the three contracts are covered at integration level: task-routes inject + gateway inbound (P1), active-role-follow + app wiring (P2), round-service flowPause matrix + flow-pause-alert (P3) |
+## Generated-Context Freshness Checks
+- Regenerate `.ai/generated/module-index.json` with `.ai/tools/generate-module-index`
+  after adding/removing/moving modules, source files, or test files.
+- Regenerate `.ai/generated/public-surface.json` with
+  `.ai/tools/generate-public-surface` (after module-index exists) after changing
+  exported APIs, HTTP routes, or shared types.
+- Treat stale generated indexes as a validation failure during review: if a
+  source/route/export change is not reflected in the indexes, regenerate before
+  acceptance.
+## Final-Validation Cleanup
+- Remove temporary scripts, scratch files, and any test-only fixtures created
+  during investigation before final acceptance.
+- Do not leave `.only`/`.skip` in committed Vitest or Playwright specs.
+- Ensure no detached/background validation jobs remain running.
+- Confirm generated indexes are regenerated and committed when source/surface
+  changed.
+- Before publish, `npm run build` and `npm run verify:package` must pass.
+## Known Testing Gaps
+- No integration tests exist yet; `tests/integration/**` is configured but empty.
+- No E2E tests exist yet; `tests/e2e/**` is configured (Playwright) but empty.
+- E2E and live runtime tests depend on a real `claude` binary and `node-pty`,
+  which are environment-sensitive and not currently stubbed for CI.
+- There is no lint command in `package.json`; L0 is currently typecheck-only.
+- Coverage thresholds are not enforced by configuration.
+- `tests/unit/backend/harness-templates-sync.test.ts` shells out to
+  `scripts/install-vcm-harness.mjs`, which needs the compiled CLI (`dist/main.js`).
+  On a clean checkout with no `dist/`, those 3 cases fail with
+  "compiled CLI not found. Run npm run build first." Run `npm run build` before
+  `npm test` (or treat these specific failures as build-state, not regressions)
+  when validating from a clean tree.

package/docs/known-issues.md CHANGED Viewed

@@ -1 +1,156 @@
 # Known Issues
+Durable open issues and accepted limitations for VibeCodingMaster (VCM). This is
+a current open-issue snapshot, not a task log. Each entry is architect-owned and
+should be removed or rewritten once the underlying gap is resolved.
+Issues are grouped by category. Severity reflects architectural/correctness/
+security risk, not delivery priority.
+---
+## Security & Exposure
+### KI-001 — Unauthenticated HTTP API and `/ws` terminal surface
+- **Status**: Open (accepted limitation by design; needs explicit user/PM decision before any non-loopback use).
+- **Category**: Product / security.
+- **Affected modules / surfaces**: `src/backend/server.ts` (no auth hook, no CORS/origin policy), all `src/backend/api/*` routes, `src/backend/ws/terminal-ws.ts`, `src/main.ts` (`--host=` flag).
+- **Current gap**: The backend registers every `/api/*` route and the `/ws/terminal/:id` WebSocket with no authentication, authorization, or origin/CSRF check. These surfaces can spawn processes (`runtime.createSession`), run `git`, read/write the filesystem and `vcmDataDir`, manage gateway tokens, and write raw bytes directly into role PTYs (`runtime.write` via the terminal WebSocket). The default bind is `127.0.0.1`, but `--host=` lets a user bind to `0.0.0.0`/LAN, and the WS upgrade path performs no `Origin` validation (cross-site WebSocket hijacking is possible if a browser session is open).
+- **Impact**: Binding to any non-loopback interface exposes a powerful, fully unauthenticated remote-code-execution-equivalent surface to the local network. Even on loopback, the lack of `Origin` checks means a malicious web page in the user's browser could drive the API/terminal.
+- **Mitigation / workaround**: Keep the default `127.0.0.1` bind; do not pass `--host=` with a routable address; do not run VCM on shared/untrusted machines.
+- **Resolution condition**: Either (a) document and enforce loopback-only as a hard product constraint, or (b) add an auth/token + `Origin` allowlist before allowing non-loopback binds. Requires a product decision (route through the full code-change flow if a fix is chosen).
+- **Related**: KI-002, KI-007.
+### KI-002 — Gateway bot token and app secret stored in plaintext at rest
+- **Status**: Open (accepted limitation).
+- **Category**: Product / security.
+- **Affected modules / surfaces**: `src/backend/gateway/gateway-settings-service.ts` (`writeJsonAtomic(settingsPath, cachedSettings)`), gateway channel credentials (`binding.token`, `binding.appSecret`).
+- **Current gap**: Gateway channel credentials (Weixin iLink bot token, Lark app secret) are persisted unencrypted as JSON under `vcmDataDir`. Status responses correctly expose only `tokenConfigured`/`appSecretConfigured` booleans, so the leak is at-rest only, not over the status API.
+- **Impact**: Anyone with read access to the user's `vcmDataDir` (backups, sync tools, other local users) can recover live chat-platform bot credentials.
+- **Mitigation / workaround**: Protect `vcmDataDir` filesystem permissions; rotate tokens if the data dir is exposed.
+- **Resolution condition**: Encrypt secrets at rest or delegate to an OS keychain; or formally accept and document the plaintext-at-rest model.
+- **Related**: KI-001.
+---
+## Correctness & Robustness
+### KI-003 — Spawn failures are indistinguishable from real `git` exit code 1
+- **Status**: Open.
+- **Category**: Product / correctness.
+- **Affected modules / surfaces**: `src/backend/adapters/command-runner.ts` (catch branch returns `{ exitCode: 1, stderr: error.message }`), `src/backend/adapters/git-adapter.ts` (`isIgnored`, `branchExists` treat `exitCode === 1` as a definitive "false").
+- **Current gap**: `command-runner.run` collapses every `execa` failure — including a spawn error such as `git` not being installed/launchable (ENOENT) — into `exitCode: 1`. Several git-adapter methods (`isIgnored`, `branchExists`) interpret `exitCode === 1` as a meaningful negative result ("not ignored" / "branch does not exist"). A missing or unspawnable `git` therefore returns a confident wrong answer instead of surfacing the real failure.
+- **Impact**: Downstream logic (worktree creation, ignore checks, branch existence gating) can silently make wrong decisions when `git` is absent or the spawn fails, masking the root cause and producing confusing secondary errors.
+- **Mitigation / workaround**: Ensure `git` is installed and on `PATH` before use.
+- **Resolution condition**: Distinguish spawn/launch errors from non-zero process exits in `command-runner` (e.g., a sentinel exit code or a typed `spawnFailed` flag) and have git-adapter treat spawn failure as an error rather than a `false` result. Requires a cross-file contract change → route through the full code-change flow.
+- **Related**: none.
+### KI-010 — Translation queue stuck-head recovery is enqueue-triggered, not continuous
+- **Status**: Open (accepted limitation; the primary issue #13 case is resolved).
+- **Category**: Product / robustness (operability).
+- **Affected modules / surfaces**: `src/backend/services/translation-worker-service.ts` (`dispatchNext` / `reconcileStuckActiveItem` / `STALE_CONVERSATION_ITEM_MS`), `src/backend/services/translation-service.ts` (`waitForConversationResult` poll loop).
+- **Current gap**: Recovery of a stuck active queue item (whose Translator `Stop`/`StopFailure` hook was lost) runs only when `dispatchNext` is invoked — i.e. when a new item is enqueued or a hook arrives. The request poll loop (`waitForConversationResult` -> `getState`) does not call `dispatchNext`. The primary case (the result already written to disk, hook lost) self-heals immediately on the next enqueue: conversation output lives in a single shared, self-describing `runtime/conversations/result.json`, and the recovery association key is the in-file `batchId` validated all-or-nothing (`conversationResultAvailable` requires the file to exist, parse, have `batchId` equal to the active item's `batchId`, and contain every expected `batchIndex`). The secondary case (Translator session gone with no result written) is only released after the item passes the 90s `STALE_CONVERSATION_ITEM_MS` window *and* a subsequent enqueue occurs; if the stuck head is still younger than 90s when the next translation is requested, that request can still time out once.
+- **Impact**: Low. A narrow window can still produce a single `translation timed out` (HTTP 502) for the "session gone, no result, head <90s old, no further enqueue" case; it self-heals on the next translation attempt after the stale window. No permanent queue block remains, and a backend restart with a pre-existing stuck item recovers immediately (its `updatedAt` is already stale, or the result is on disk).
+- **Mitigation / workaround**: Retry the translation once; the retry's enqueue triggers reconciliation.
+- **Resolution condition**: Add a periodic / poll-driven reconcile (e.g. reconcile on `getState` or a timer) so stuck heads are released without depending on a new enqueue. Requires a code change → route through the full code-change flow if pursued.
+- **Related**: KI-011.
+### KI-011 — Conversation result cleanup deletes the shared dir without a batchId guard
+- **Status**: Open (accepted limitation; harm effectively unreachable today).
+- **Category**: Product / robustness (operability).
+- **Affected modules / surfaces**: `src/backend/services/translation-worker-service.ts` (`validateConversationResult` cleanup of the shared `runtime/conversations/` directory holding `result.json`).
+- **Current gap**: Because conversation translation now uses one shared `result.json` (KI-010), cleanup after a consumed result removes the shared `conversations/` directory (the `batchResultPath` dirname) rather than a per-batch directory, and it is not guarded by a `batchId` match against the file actually on disk. In principle a delete could race a newly written `result.json` for a later batch.
+- **Impact**: Negligible in practice. Cleanup fires on the ~500ms consumer poll, far ahead of when a subsequent batch's Translator (LLM latency ≫ 500ms) could write a new `result.json`; and the all-or-nothing in-file `batchId` validation means the worst case is a recoverable dropped result, never a mis-assignment — within the design's accepted "drop over mis-assign" tolerance.
+- **Mitigation / workaround**: None needed; a dropped conversation result self-recovers via re-translate / stale-release.
+- **Resolution condition**: Optional hardening — scope the cleanup to delete only when the on-disk `result.json` `batchId` matches the just-consumed batch (or delete the file, not the directory). Requires a small code change → full code-change flow if pursued.
+- **Related**: KI-010.
+### KI-004 — Claude transcript project-directory hashing does not match Claude Code's encoding
+- **Status**: Open.
+- **Category**: Product / correctness (external coupling to Claude Code's on-disk format).
+- **Affected modules / surfaces**: `src/backend/services/claude-transcript-service.ts` (`projectHash`, `projectsTranscriptDir`, `claudeTranscriptPath`, `resolveExistingClaudeTranscriptPath`), translation panel and question/todo extraction that depend on it.
+- **Current gap**: `projectHash` only replaces `[/\s]+` with `-`, which does not reproduce Claude Code's actual project-directory encoding (which also encodes `.` and other path characters). The primary path lookup can therefore miss; correctness currently leans on the fallback full scan `findClaudeTranscriptPathBySessionId`, which picks the most-recently-modified `<sessionId>.jsonl` across all project dirs.
+- **Impact**: If Claude changes its encoding, or two project directories produce a colliding hash / share a session-id filename, transcript resolution can attach to the wrong file or fail to find one, breaking translation feed and question/todo surfacing. The fallback masks the brittleness rather than fixing it.
+- **Mitigation / workaround**: Rely on the `session.transcriptPath` / `claudeSessionId` resolution path; the mtime-sorted fallback usually recovers the right file.
+- **Resolution condition**: Mirror Claude Code's real directory-encoding scheme (or resolve transcript paths via a documented Claude API/contract) instead of an approximate replace. Treat the encoding as an external-contract assumption to re-verify on Claude Code upgrades.
+- **Related**: KI-005.
+---
+## Performance & Scalability
+### KI-005 — Synchronous filesystem I/O and full-file replay on the event loop in `TranscriptTail`
+- **Status**: Open.
+- **Category**: Product / performance.
+- **Affected modules / surfaces**: `src/backend/services/claude-transcript-service.ts` (`TranscriptTail.start/flush/replayHistory/replaySince`), translation worker/feed consumers.
+- **Current gap**: Transcript tailing uses synchronous `statSync`/`openSync`/`readSync` on every flush and `readFileSync` for replay, all on the main event-loop thread, with a 1s poll timer per subscribed session. Replay (`replayHistory`/`replaySince`) reads the entire JSONL transcript into memory and parses every line synchronously.
+- **Impact**: Long-lived sessions accumulate large transcripts; with multiple concurrent role sessions each tailing + replaying, synchronous reads can stall the event loop and spike memory, degrading API/WS responsiveness.
+- **Mitigation / workaround**: Practical session/transcript sizes are usually small; impact is bounded by transcript length and session count.
+- **Resolution condition**: Move to async/streamed reads, bound replay (cap bytes/lines read), and/or offload tailing; treat as a scalability hardening item.
+- **Related**: KI-004, KI-006.
+### KI-006 — O(n)-per-chunk terminal replay buffer recomputation
+- **Status**: Open.
+- **Category**: Product / performance.
+- **Affected modules / surfaces**: `src/backend/runtime/node-pty-runtime.ts` (`appendTerminalReplay`, `tailTerminalReplay`, invoked on every `child.onData`).
+- **Current gap**: On every PTY output chunk, `appendTerminalReplay` concatenates the existing buffer with the new data and re-tails to the 2 MB cap, and `tailTerminalReplay` recomputes `Buffer.byteLength` inside a trimming loop. This is O(buffer size) per chunk regardless of chunk size.
+- **Impact**: Chatty/high-throughput Claude sessions trigger repeated multi-MB string copies and byte-length scans, a measurable CPU hotspot under sustained output.
+- **Mitigation / workaround**: Output bursts are typically short; the 2 MB cap bounds memory.
+- **Resolution condition**: Use a chunked/ring buffer or amortized trimming so per-chunk cost is proportional to the new data, not the whole buffer.
+- **Related**: KI-005.
+---
+## Maintainability
+### KI-007 — Non-matching `/ws` upgrade requests leak the socket
+- **Status**: Open.
+- **Category**: Product / robustness.
+- **Affected modules / surfaces**: `src/backend/ws/terminal-ws.ts` (`app.server.on("upgrade", ...)`).
+- **Current gap**: When an upgrade request's path does not match `/ws/terminal/:id`, the handler `return`s without calling `socket.destroy()` (or writing a `400`/`426` response). The half-upgraded socket is left hanging until a timeout. There is also no `Origin` check at the upgrade boundary (see KI-001).
+- **Impact**: Low — stray/unrelated `/ws` upgrade attempts hold a connection open instead of being cleanly rejected; minor resource pressure, no correct rejection signal to the client.
+- **Mitigation / workaround**: Only the intended `/ws/terminal/:id` path is used by the shipped frontend.
+- **Resolution condition**: Destroy (or explicitly reject) the socket on non-matching upgrade paths and add an `Origin` allowlist.
+- **Related**: KI-001.
+### KI-008 — Oversized service modules concentrate orchestration complexity
+- **Status**: Open (maintainability hazard, not a defect).
+- **Category**: Product / maintainability.
+- **Affected modules / surfaces**: `src/backend/services/harness-service.ts` (~2160 lines), `translation-worker-service.ts` (~2155), `translation-service.ts` (~1721), `session-service.ts` (~1682), `gate-review-service.ts` (~980), `claude-hook-service.ts` (~769).
+- **Current gap**: Several service files greatly exceed comfortable single-file cohesion and bundle orchestration, retry/error handling, and side-effect coordination together. This makes the intended `api -> services -> (runtime | adapters | gateway | templates)` boundary harder to reason about and raises regression risk on edits.
+- **Impact**: Higher change cost and review/regression risk in the highest-traffic backend logic; harder to localize behavior and test seams.
+- **Mitigation / workaround**: Existing unit tests cover many of these services; keep edits narrowly scoped.
+- **Resolution condition**: Incrementally extract cohesive sub-modules (with explicit cross-file contracts captured in module `ARCHITECTURE.md`) when these areas are next changed. No standalone refactor mandated.
+- **Related**: none.
+### KI-009 — Error responses surface raw subprocess stderr and runtime diagnostics to clients
+- **Status**: Open (low risk on loopback; compounds with KI-001).
+- **Category**: Product / information exposure.
+- **Affected modules / surfaces**: `src/backend/server.ts` global error handler (returns `hint` and `runtime` diagnostics), `src/backend/adapters/git-adapter.ts` (sets `hint: result.stderr`).
+- **Current gap**: API error payloads include `hint` (often raw `git` stderr) and `diagnosticsService.getErrorRuntimeInfo()`. On loopback this is acceptable developer feedback, but it leaks local paths/environment detail to any caller — which matters if combined with a non-loopback bind (KI-001).
+- **Impact**: Low in the default configuration; an information-exposure amplifier when the API is exposed beyond loopback.
+- **Mitigation / workaround**: Keep the loopback bind (KI-001).
+- **Resolution condition**: Gate verbose `hint`/`runtime` detail behind a dev flag, or sanitize before returning, if non-loopback exposure is ever supported.
+- **Related**: KI-001, KI-007.
+### KI-012 — `flowPause.role` / `flowPause.since` are emitted but unused by the GUI
+- **Status**: Open (accepted minor redundancy; not a defect).
+- **Category**: Product / maintainability (cleanup).
+- **Affected modules / surfaces**: `src/shared/types/round.ts` (`VcmFlowPauseState`), `src/backend/services/round-service.ts` (`computeFlowPause`), `src/frontend/app.tsx` (flow-pause alert mechanics).
+- **Current gap**: The authoritative `roundState.flowPause` carries `role` and `since`, but the GUI alert mechanics still read equivalent round-level fields — `roundState.activeRole` for the pause-notice label and `getFlowPauseDurationMs(roundState)` for sound severity. Both sources derive from the same `currentRound`, so the values are equivalent and the redundancy is harmless.
+- **Impact**: None functionally; mild contract over-provisioning (fields provided that no consumer reads), which can confuse future maintainers ("why does `flowPause` carry `role`/`since`?").
+- **Mitigation / workaround**: None needed.
+- **Resolution condition**: Either point the GUI label/severity at `flowPause.role`/`flowPause.since` (consume what the signal already provides), or drop the two fields from `VcmFlowPauseState`. Small, optional.
+- **Related**: none.

package/package.json CHANGED Viewed

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