vibe-coding-master 0.3.28 → 0.3.29

package/README.md

@@ -11,7 +11,7 @@ VCM is designed for long-running coding work where one Claude Code conversation
 
 Each role runs as a real Claude Code process inside an embedded terminal. The GUI lets the user start, stop, resume, restart, switch, observe, and manually intervene in those sessions without juggling separate terminal windows.
 
-When Gate Review Gates are enabled for a task, or when a Gate Reviewer session already exists, the workspace can also show a fifth `Gate Reviewer` terminal role. It runs Claude Code as a project-scoped long-lived review session, receives short gate prompts that include the current task and worktree path, writes reports under the task worktree, and stays outside normal PM role routing.
+When Gate Review Gates are enabled for a task, or when a Gate Reviewer session already exists, the workspace can also show a fifth `Gate Reviewer` terminal role. It is an optional VCM flow role powered by Claude Code. Its session is project-scoped and reusable across tasks, but each gate turn is bound to the current task/worktree, writes reports under the task worktree, and stays outside normal PM route-file dispatch.
 
 ## Current Capabilities
 
@@ -21,7 +21,7 @@ When Gate Review Gates are enabled for a task, or when a Gate Reviewer session a
 - Connected repository status for the base repo, including branch, upstream status, commit hash, dirty state, and fast-forward-only pull.
 - Embedded Claude Code terminals powered by `node-pty` and `xterm.js`.
 - One Claude Code session per role, with role tabs in the task header.
-- Optional Gate Reviewer terminal role when any Gate Review Gate is enabled.
+- Optional Gate Reviewer VCM flow role when any Gate Review Gate is enabled.
 - Role session recovery through persisted Claude session ids and `claude --resume`.
 - Permission mode selection before start, resume, or restart:
   - `default`
@@ -350,14 +350,14 @@ Typical mobile flow:
 - `/pull-current`: runs the same fast-forward-only connected repository pull as the desktop `Pull` button.
 - `/tasks`: lists tasks for the selected project.
 - `/use-task <index-or-task-slug>`: selects the Gateway's current task context.
-- `/create-task <task-slug> [title]`: creates a worktree-backed task and starts the four role sessions using the saved launch template.
+- `/create-task <task-slug> [title]`: creates a worktree-backed task and starts the four core role sessions using the saved launch template. If any Gate Review Gate is enabled, Gateway also resumes or starts Gate Reviewer from the saved template.
 - `/close-task`: starts a destructive close confirmation for the current task.
 - `/close-task confirm <task-slug>`: closes the task through VCM cleanup after exact slug confirmation.
 - `/translate on` and `/translate off`: changes Gateway translation for mobile messages.
 
 `/pull-current` only pulls the connected base repository. It does not pull task worktrees, stash local changes, merge divergent branches, or run arbitrary shell commands.
 
-`/create-task` uses the saved launch template from the desktop settings. The template controls permission mode, model, effort, and auto orchestration for the four core role sessions. Gateway translation uses the global Gateway translation setting, not the launch template.
+`/create-task` uses the saved launch template from the desktop settings. The template controls permission mode, model, effort, and auto orchestration for the four core role sessions plus the optional Gate Reviewer. Gateway translation uses the global Gateway translation setting, not the launch template.
 
 `/close-task` is destructive. It stops VCM-managed role sessions and removes task-owned worktree/branch state according to the same cleanup behavior as the desktop `Close Task` action.
 
@@ -574,7 +574,7 @@ When it is on, VCM is in auto mode:
 - When the target role later reaches `Stop`, VCM scans again and may deliver the next pending route file.
 - If auto orchestration gets stuck after a manual copy/paste recovery, `Mark All Done` clears pending route files. It does not mutate message history.
 
-VCM Harness injects Claude Code `UserPromptSubmit` and `Stop` hooks into `.claude/settings.json`. Role tabs become `running` when Claude Code accepts a prompt and `idle` after `Stop`; VCM also marks a role `running` immediately after it writes a message to that embedded terminal. Gate Reviewer is a Claude Code role, but VCM triggers and settles gate turns directly around the gate prompt and report callback. The terminal process status is still tracked separately. Claude role rules require a role to end its turn after writing or updating a message route file, rather than polling, looping, or waiting for another role inside the same Claude Code turn.
+VCM Harness injects Claude Code `UserPromptSubmit` and `Stop` hooks into `.claude/settings.json`. Role tabs become `running` when Claude Code accepts a prompt and `idle` after `Stop`; VCM also marks a role `running` immediately after it writes a message to that embedded terminal. Gate Reviewer uses the same Claude hook/Round/translation path as other VCM flow roles, while VCM still owns gate report polling and the PM callback. The terminal process status is tracked separately. Claude role rules require a role to end its turn after writing or updating a message route file, rather than polling, looping, or waiting for another role inside the same Claude Code turn.
 
 The implementation keeps only the active manual/auto orchestration mode. It does not expose pause/resume, stage/approve/reject, or a separate agent-facing message CLI.
 

package/dist/backend/api/task-routes.js

@@ -1,4 +1,4 @@
-import { DISPATCHABLE_ROLES, isVcmRoleName } from "../../shared/constants.js";
+import { CORE_VCM_ROLE_NAMES, DISPATCHABLE_ROLES } from "../../shared/constants.js";
 import { isOpenFileLimitError, VcmError } from "../errors.js";
 import { getTaskRuntimeRepoRoot } from "../services/task-service.js";
 export function registerTaskRoutes(app, deps) {
@@ -40,7 +40,7 @@ export function registerTaskRoutes(app, deps) {
 async function stopRunningRoleSessions(deps, repoRoot, taskSlug) {
     const sessions = await deps.sessionService.listRoleSessions(repoRoot, taskSlug);
     for (const session of sessions) {
-        if (session.status === "running" && isVcmRoleName(session.role)) {
+        if (session.status === "running" && CORE_VCM_ROLE_NAMES.some((role) => role === session.role)) {
             await deps.sessionService.stopRoleSession(repoRoot, taskSlug, session.role);
         }
     }

package/dist/backend/gateway/gateway-service.js

@@ -1,5 +1,5 @@
 import { readFile } from "node:fs/promises";
-import { VCM_ROLE_DEFINITIONS } from "../../shared/constants.js";
+import { CORE_VCM_ROLE_DEFINITIONS, CORE_VCM_ROLE_NAMES, GATE_REVIEWER_ROLE_DEFINITION } from "../../shared/constants.js";
 import { VcmError } from "../errors.js";
 import { submitTerminalInput } from "../runtime/terminal-submit.js";
 import { getTaskRuntimeRepoRoot } from "../services/task-service.js";
@@ -407,17 +407,36 @@ export function createGatewayService(deps) {
             taskSlug: task.taskSlug,
             mode: template.autoOrchestration ? "auto" : "manual"
         });
+        const gateReviewSettings = await deps.appSettings.getGateReviewSettings(project.repoRoot, task.taskSlug);
+        const roleDefinitions = [
+            ...CORE_VCM_ROLE_DEFINITIONS,
+            ...(gateReviewSettings.enabled ? [GATE_REVIEWER_ROLE_DEFINITION] : [])
+        ];
         const startedRoles = [];
-        for (const definition of VCM_ROLE_DEFINITIONS) {
+        for (const definition of roleDefinitions) {
             const roleTemplate = template.roles[definition.name];
             try {
-                await deps.sessionService.startRoleSession(project.repoRoot, task.taskSlug, definition.name, {
+                const sessionInput = {
                     cols: 100,
                     rows: 28,
                     permissionMode: roleTemplate.permissionMode,
                     model: roleTemplate.model,
                     effort: roleTemplate.effort
-                });
+                };
+                const existing = await deps.sessionService.getRoleSession(project.repoRoot, task.taskSlug, definition.name);
+                if (existing?.status === "running") {
+                    if (definition.name === "gate-reviewer") {
+                        await deps.sessionService.resumeRoleSession(project.repoRoot, task.taskSlug, definition.name, sessionInput);
+                    }
+                    startedRoles.push(definition.name);
+                    continue;
+                }
+                if (existing?.claudeSessionId) {
+                    await deps.sessionService.resumeRoleSession(project.repoRoot, task.taskSlug, definition.name, sessionInput);
+                }
+                else {
+                    await deps.sessionService.startRoleSession(project.repoRoot, task.taskSlug, definition.name, sessionInput);
+                }
                 startedRoles.push(definition.name);
             }
             catch (error) {
@@ -536,7 +555,7 @@ export function createGatewayService(deps) {
     async function stopRunningRoleSessions(repoRoot, taskSlug) {
         const sessions = await deps.sessionService.listRoleSessions(repoRoot, taskSlug);
         for (const session of sessions) {
-            if (session.status === "running") {
+            if (session.status === "running" && CORE_VCM_ROLE_NAMES.some((role) => role === session.role)) {
                 await deps.sessionService.stopRoleSession(repoRoot, taskSlug, session.role);
             }
         }

package/dist/backend/services/claude-hook-service.js

@@ -1,4 +1,4 @@
-import { isVcmRoleName } from "../../shared/constants.js";
+import { isGateReviewerRoleName, isVcmRoleName } from "../../shared/constants.js";
 import { VcmError } from "../errors.js";
 import { submitTerminalInput } from "../runtime/terminal-submit.js";
 import { getTaskRuntimeRepoRoot } from "./task-service.js";
@@ -22,15 +22,32 @@ export function createClaudeHookService(deps) {
             });
         }
         const config = await deps.projectService.loadConfig(project.repoRoot);
-        const task = await deps.taskService.loadTask(project.repoRoot, input.taskSlug);
+        const taskSlug = await resolveHookTaskSlug(project.repoRoot, input);
+        const task = await deps.taskService.loadTask(project.repoRoot, taskSlug);
         const taskRepoRoot = getTaskRuntimeRepoRoot(task);
         return {
             project,
             config,
             task,
+            taskSlug,
             taskRepoRoot
         };
     }
+    async function resolveHookTaskSlug(repoRoot, input) {
+        if (!isGateReviewerRoleName(input.role)) {
+            return input.taskSlug;
+        }
+        const session = await deps.sessionService.getProjectGateReviewerSession(repoRoot);
+        if (session?.activeTaskSlug) {
+            return session.activeTaskSlug;
+        }
+        throw new VcmError({
+            code: "GATE_REVIEWER_TASK_UNBOUND",
+            message: "Gate Reviewer hook arrived without an active task binding.",
+            statusCode: 409,
+            hint: "Start or resume Gate Reviewer from the current task before submitting work."
+        });
+    }
     async function handleUserPromptSubmitHook(input) {
         const eventName = parseHookEvent(input.event.hook_event_name);
         if (eventName !== "UserPromptSubmit") {
@@ -39,11 +56,11 @@ export function createClaudeHookService(deps) {
         const context = await getHookContext(input);
         deps.jobGuard?.notePromptSubmitted({
             repoRoot: context.project.repoRoot,
-            taskSlug: input.taskSlug,
+            taskSlug: context.taskSlug,
             role: input.role
         });
         const session = await deps.sessionService.recordClaudeHookEvent(context.project.repoRoot, {
-            taskSlug: input.taskSlug,
+            taskSlug: context.taskSlug,
             role: input.role,
             eventName,
             claudeSessionId: stringOrUndefined(input.event.session_id),
@@ -54,7 +71,7 @@ export function createClaudeHookService(deps) {
             repoRoot: context.project.repoRoot,
             stateRepoRoot: context.taskRepoRoot,
             stateRoot: context.config.stateRoot,
-            taskSlug: input.taskSlug,
+            taskSlug: context.taskSlug,
             role: input.role,
             eventName
         });
@@ -62,7 +79,7 @@ export function createClaudeHookService(deps) {
             await deps.translationService.recordConversationBoundary({
                 repoRoot: context.project.repoRoot,
                 taskRepoRoot: context.taskRepoRoot,
-                taskSlug: input.taskSlug,
+                taskSlug: context.taskSlug,
                 role: input.role,
                 sessionId: session.id,
                 boundaryKind: "start",
@@ -75,14 +92,14 @@ export function createClaudeHookService(deps) {
             stateRepoRoot: context.taskRepoRoot,
             stateRoot: context.config.stateRoot,
             handoffDir: context.task.handoffDir,
-            taskSlug: input.taskSlug,
+            taskSlug: context.taskSlug,
             role: input.role,
             prompt: stringOrUndefined(input.event.prompt)
         });
         return {
             ok: true,
             eventName,
-            taskSlug: input.taskSlug,
+            taskSlug: context.taskSlug,
             role: input.role,
             sessionUpdated: Boolean(session),
             dispatchedCount: 0,
@@ -95,11 +112,11 @@ export function createClaudeHookService(deps) {
             throwUnsupportedEvent(eventName);
         }
         const context = await getHookContext(input);
-        clearStopFailureRecovery(context.project.repoRoot, input.taskSlug, input.role);
+        clearStopFailureRecovery(context.project.repoRoot, context.taskSlug, input.role);
         if (options.allowBlock && deps.jobGuard) {
             const verdict = await deps.jobGuard.evaluateStop({
                 repoRoot: context.project.repoRoot,
-                taskSlug: input.taskSlug,
+                taskSlug: context.taskSlug,
                 role: input.role,
                 taskRepoRoot: context.taskRepoRoot
             });
@@ -109,7 +126,7 @@ export function createClaudeHookService(deps) {
                 return {
                     ok: true,
                     eventName,
-                    taskSlug: input.taskSlug,
+                    taskSlug: context.taskSlug,
                     role: input.role,
                     sessionUpdated: false,
                     dispatchedCount: 0,
@@ -118,7 +135,7 @@ export function createClaudeHookService(deps) {
             }
         }
         return recordTurnEnd(input, context, eventName, {
-            dispatchRouteFiles: true,
+            dispatchRouteFiles: !isGateReviewerRoleName(input.role),
             notifyGateway: true,
             settleGuard: true
         });
@@ -133,9 +150,9 @@ export function createClaudeHookService(deps) {
         const pending = await deps.messageService.listPendingRouteFiles(routeDispatchInput);
         const hasCompletionEvidence = pending.some((routeFile) => routeFile.fromRole === input.role);
         if (hasCompletionEvidence) {
-            clearStopFailureRecovery(context.project.repoRoot, input.taskSlug, input.role);
+            clearStopFailureRecovery(context.project.repoRoot, context.taskSlug, input.role);
             return recordTurnEnd(input, context, eventName, {
-                dispatchRouteFiles: true,
+                dispatchRouteFiles: !isGateReviewerRoleName(input.role),
                 notifyGateway: false,
                 settleGuard: true
             });
@@ -145,7 +162,7 @@ export function createClaudeHookService(deps) {
             return {
                 ok: true,
                 eventName,
-                taskSlug: input.taskSlug,
+                taskSlug: context.taskSlug,
                 role: input.role,
                 sessionUpdated: true,
                 dispatchedCount: 0
@@ -164,7 +181,7 @@ export function createClaudeHookService(deps) {
         }
         const context = await getHookContext(input);
         const session = await deps.sessionService.recordClaudeHookEvent(context.project.repoRoot, {
-            taskSlug: input.taskSlug,
+            taskSlug: context.taskSlug,
             role: input.role,
             eventName,
             claudeSessionId: stringOrUndefined(input.event.session_id),
@@ -174,7 +191,7 @@ export function createClaudeHookService(deps) {
         return {
             ok: true,
             eventName,
-            taskSlug: input.taskSlug,
+            taskSlug: context.taskSlug,
             role: input.role,
             sessionUpdated: Boolean(session),
             dispatchedCount: 0
@@ -184,7 +201,7 @@ export function createClaudeHookService(deps) {
         const scopedRouteDispatchInput = createRouteDispatchInput(input, context, input.role);
         const settleRouteDispatchInput = createRouteDispatchInput(input, context);
         const session = await deps.sessionService.recordClaudeHookEvent(context.project.repoRoot, {
-            taskSlug: input.taskSlug,
+            taskSlug: context.taskSlug,
             role: input.role,
             eventName,
             claudeSessionId: stringOrUndefined(input.event.session_id),
@@ -195,7 +212,7 @@ export function createClaudeHookService(deps) {
             repoRoot: context.project.repoRoot,
             stateRepoRoot: context.taskRepoRoot,
             stateRoot: context.config.stateRoot,
-            taskSlug: input.taskSlug,
+            taskSlug: context.taskSlug,
             role: input.role,
             eventName,
             ...(options.settleGuard
@@ -217,7 +234,7 @@ export function createClaudeHookService(deps) {
             await deps.translationService.recordConversationBoundary({
                 repoRoot: context.project.repoRoot,
                 taskRepoRoot: context.taskRepoRoot,
-                taskSlug: input.taskSlug,
+                taskSlug: context.taskSlug,
                 role: input.role,
                 sessionId: session.id,
                 boundaryKind: "end",
@@ -227,7 +244,7 @@ export function createClaudeHookService(deps) {
         if (options.notifyGateway && session && input.role === "project-manager") {
             void deps.gatewayService?.handlePmStop({
                 repoRoot: context.project.repoRoot,
-                taskSlug: input.taskSlug,
+                taskSlug: context.taskSlug,
                 session
             }).catch(() => undefined);
         }
@@ -237,7 +254,7 @@ export function createClaudeHookService(deps) {
         return {
             ok: true,
             eventName,
-            taskSlug: input.taskSlug,
+            taskSlug: context.taskSlug,
             role: input.role,
             sessionUpdated: Boolean(session),
             dispatchedCount: dispatched.filter((result) => result.delivered).length
@@ -250,7 +267,7 @@ export function createClaudeHookService(deps) {
             stateRepoRoot: context.taskRepoRoot,
             stateRoot: context.config.stateRoot,
             handoffDir: context.task.handoffDir,
-            taskSlug: input.taskSlug,
+            taskSlug: context.taskSlug,
             ...(stoppedRole ? { stoppedRole } : {})
         };
     }
@@ -258,18 +275,18 @@ export function createClaudeHookService(deps) {
         if (!deps.runtime) {
             return false;
         }
-        const key = stopFailureRecoveryKey(context.project.repoRoot, input.taskSlug, input.role);
+        const key = stopFailureRecoveryKey(context.project.repoRoot, context.taskSlug, input.role);
         const attempt = (stopFailureRecoveryAttempts.get(key) ?? 0) + 1;
         if (attempt > MAX_STOP_FAILURE_RECOVERY_ATTEMPTS) {
             return false;
         }
-        const session = await deps.sessionService.getRoleSession(context.project.repoRoot, input.taskSlug, input.role);
+        const session = await deps.sessionService.getRoleSession(context.project.repoRoot, context.taskSlug, input.role);
         if (!session || session.status !== "running") {
             return false;
         }
         stopFailureRecoveryAttempts.set(key, attempt);
         await submitTerminalInput(deps.runtime, session.id, renderStopFailureRecoveryPrompt(attempt));
-        await deps.sessionService.markRoleActivityRunning(context.project.repoRoot, input.taskSlug, input.role);
+        await deps.sessionService.markRoleActivityRunning(context.project.repoRoot, context.taskSlug, input.role);
         return true;
     }
     function clearStopFailureRecovery(repoRoot, taskSlug, role) {

package/dist/backend/services/message-service.js

@@ -1,6 +1,6 @@
 import path from "node:path";
 import { randomUUID } from "node:crypto";
-import { VCM_ROLE_NAMES, isVcmRoleName } from "../../shared/constants.js";
+import { CORE_VCM_ROLE_NAMES } from "../../shared/constants.js";
 import { VcmError } from "../errors.js";
 import { resolveRepoPath } from "../adapters/filesystem.js";
 import { submitTerminalInput } from "../runtime/terminal-submit.js";
@@ -282,8 +282,8 @@ async function listRouteFiles(fs, input) {
     return routeFiles;
 }
 function parseRouteFileName(fileName) {
-    for (const fromRole of VCM_ROLE_NAMES) {
-        for (const toRole of VCM_ROLE_NAMES) {
+    for (const fromRole of CORE_VCM_ROLE_NAMES) {
+        for (const toRole of CORE_VCM_ROLE_NAMES) {
             if (fromRole === toRole) {
                 continue;
             }
@@ -371,14 +371,14 @@ function selectDispatchCandidates(routeFiles, stoppedRole) {
     });
 }
 function validateMessagePolicy(fromRole, toRole, type) {
-    if (!VCM_ROLE_NAMES.includes(toRole)) {
+    if (!CORE_VCM_ROLE_NAMES.some((role) => role === toRole)) {
         throw new VcmError({
             code: "MESSAGE_TARGET_UNKNOWN",
             message: `Unknown target role: ${toRole}`,
             statusCode: 400
         });
     }
-    if (!isVcmRoleName(String(fromRole))) {
+    if (!CORE_VCM_ROLE_NAMES.some((role) => role === fromRole)) {
         throw new VcmError({
             code: "MESSAGE_SENDER_UNKNOWN",
             message: `Unknown sender role: ${fromRole}`,
@@ -425,7 +425,7 @@ function getMessageDeliveryTime(message) {
 }
 async function clearRouteFileIfStillMatchesMessage(fs, input, message) {
     const fromRole = message.fromRole;
-    if (!message.routePath || !isVcmRoleName(fromRole)) {
+    if (!message.routePath || !isCoreRouteRole(fromRole) || !isCoreRouteRole(message.toRole)) {
         return;
     }
     const absolutePath = resolveRepoPath(input.taskRepoRoot ?? input.repoRoot, message.routePath);
@@ -440,6 +440,9 @@ async function clearRouteFileIfStillMatchesMessage(fs, input, message) {
         await fs.writeText(absolutePath, "");
     }
 }
+function isCoreRouteRole(role) {
+    return CORE_VCM_ROLE_NAMES.some((candidate) => candidate === role);
+}
 function arraysEqual(left, right) {
     if (left.length !== right.length) {
         return false;

package/dist/backend/services/project-service.js

@@ -1,5 +1,5 @@
 import path from "node:path";
-import { VCM_ROLE_NAMES } from "../../shared/constants.js";
+import { CORE_VCM_ROLE_NAMES } from "../../shared/constants.js";
 import { VcmError } from "../errors.js";
 const DEFAULT_HANDOFF_ROOT = ".ai/vcm/handoffs";
 const DEFAULT_STATE_ROOT = ".ai/vcm";
@@ -179,7 +179,7 @@ export function buildDefaultProjectConfig(repoRoot) {
     return {
         version: 1,
         repoRoot,
-        defaultRoles: [...VCM_ROLE_NAMES],
+        defaultRoles: [...CORE_VCM_ROLE_NAMES],
         handoffRoot: DEFAULT_HANDOFF_ROOT,
         stateRoot: DEFAULT_STATE_ROOT,
         terminalBackend: "node-pty",

package/dist/backend/services/session-service.js

@@ -1,6 +1,6 @@
 import { randomUUID } from "node:crypto";
 import path from "node:path";
-import { VCM_ROLE_NAMES, isCodexRoleName, isDispatchableRole } from "../../shared/constants.js";
+import { CORE_VCM_ROLE_NAMES, isCodexRoleName, isDispatchableRole } from "../../shared/constants.js";
 import { VcmError } from "../errors.js";
 import { resolveRepoPath } from "../adapters/filesystem.js";
 import { claudeTranscriptPath } from "./claude-transcript-service.js";
@@ -101,10 +101,10 @@ export function createSessionService(deps) {
         await persistRoleSessionRecord(deps.fs, repoRoot, taskRepoRoot, config.stateRoot, record);
         return record;
     }
-    async function launchProjectGateReviewerSession(repoRoot, input, launchMode) {
+    async function launchProjectGateReviewerSession(repoRoot, input, launchMode, activeTaskSlug) {
         const live = toRoleSessionRecordView(getRegisteredProjectGateReviewerSession(deps.registry, deps.runtime), deps.runtime);
         if (live && live.status === "running") {
-            return live;
+            return bindProjectGateReviewerSession(repoRoot, live, activeTaskSlug);
         }
         const config = await deps.projectService.loadConfig(repoRoot);
         const persisted = await loadPersistedProjectGateReviewerSession(deps.fs, repoRoot);
@@ -125,6 +125,10 @@ export function createSessionService(deps) {
         const transcriptPath = launchMode === "resume" && persisted?.transcriptPath
             ? persisted.transcriptPath
             : claudeTranscriptPath(repoRoot, claudeSessionId);
+        const activeTask = activeTaskSlug
+            ? await deps.taskService.loadTask(repoRoot, activeTaskSlug)
+            : undefined;
+        const activeTaskRepoRoot = activeTask ? getTaskRuntimeRepoRoot(activeTask) : undefined;
         const startCommand = {
             ...deps.claude.buildRoleStartCommand(GATE_REVIEWER_ROLE, config.claudeCommand, permissionMode, claudeSessionId, launchMode === "resume", model, effort),
             cwd: repoRoot
@@ -137,8 +141,8 @@ export function createSessionService(deps) {
             cwd: startCommand.cwd,
             env: {
                 VCM_API_URL: deps.apiUrl,
-                VCM_TASK_REPO_ROOT: repoRoot,
-                VCM_TASK_SLUG: PROJECT_GATE_REVIEWER_SCOPE,
+                VCM_TASK_REPO_ROOT: activeTaskRepoRoot ?? repoRoot,
+                VCM_TASK_SLUG: activeTaskSlug ?? PROJECT_GATE_REVIEWER_SCOPE,
                 VCM_ROLE: GATE_REVIEWER_ROLE,
                 VCM_SESSION_ID: claudeSessionId
             },
@@ -164,12 +168,31 @@ export function createSessionService(deps) {
             startedAt: runtimeSession.startedAt,
             updatedAt: timestamp,
             lastOutputAt: runtimeSession.lastOutputAt,
+            activeTaskSlug,
+            activeTaskRepoRoot,
             exitCode: runtimeSession.exitCode
         };
         deps.registry.upsert(record);
         await persistProjectGateReviewerSession(deps.fs, repoRoot, record);
         return record;
     }
+    async function bindProjectGateReviewerSession(repoRoot, record, activeTaskSlug) {
+        if (!activeTaskSlug) {
+            return record;
+        }
+        const task = await deps.taskService.loadTask(repoRoot, activeTaskSlug);
+        const activeTaskRepoRoot = getTaskRuntimeRepoRoot(task);
+        const updated = {
+            ...record,
+            taskSlug: PROJECT_GATE_REVIEWER_SCOPE,
+            activeTaskSlug,
+            activeTaskRepoRoot,
+            updatedAt: now()
+        };
+        deps.registry.upsert(updated);
+        await persistProjectGateReviewerSession(deps.fs, repoRoot, updated);
+        return updated;
+    }
     async function launchProjectTranslatorSession(repoRoot, input, launchMode) {
         const live = toRoleSessionRecordView(getRegisteredProjectTranslatorSession(deps.registry, deps.runtime), deps.runtime);
         if (live && live.status === "running") {
@@ -377,7 +400,7 @@ export function createSessionService(deps) {
         },
         startRoleSession(repoRoot, taskSlug, role, input = {}) {
             if (role === GATE_REVIEWER_ROLE) {
-                return this.startProjectGateReviewerSession(repoRoot, input)
+                return launchProjectGateReviewerSession(repoRoot, input, "fresh", taskSlug)
                     .then((session) => scopeProjectRoleSession(session, taskSlug));
             }
             if (role === CODEX_TRANSLATOR_ROLE) {
@@ -388,7 +411,7 @@ export function createSessionService(deps) {
         },
         resumeRoleSession(repoRoot, taskSlug, role, input = {}) {
             if (role === GATE_REVIEWER_ROLE) {
-                return this.resumeProjectGateReviewerSession(repoRoot, input)
+                return launchProjectGateReviewerSession(repoRoot, input, "resume", taskSlug)
                     .then((session) => scopeProjectRoleSession(session, taskSlug));
             }
             if (role === CODEX_TRANSLATOR_ROLE) {
@@ -430,7 +453,14 @@ export function createSessionService(deps) {
         },
         async restartRoleSession(repoRoot, taskSlug, role, input = {}) {
             if (role === GATE_REVIEWER_ROLE) {
-                return scopeProjectRoleSession(await this.restartProjectGateReviewerSession(repoRoot, input), taskSlug);
+                const existing = await this.getProjectGateReviewerSession(repoRoot);
+                if (existing && deps.runtime.getSession(existing.id)) {
+                    await deps.runtime.stop(existing.id);
+                }
+                if (existing) {
+                    deps.registry.remove(existing.id);
+                }
+                return scopeProjectRoleSession(await launchProjectGateReviewerSession(repoRoot, input, "fresh", taskSlug), taskSlug);
             }
             if (role === CODEX_TRANSLATOR_ROLE) {
                 void taskSlug;
@@ -448,7 +478,11 @@ export function createSessionService(deps) {
         },
         async getRoleSession(repoRoot, taskSlug, role) {
             if (role === GATE_REVIEWER_ROLE) {
-                return scopeProjectRoleSession(await this.getProjectGateReviewerSession(repoRoot), taskSlug);
+                const session = await this.getProjectGateReviewerSession(repoRoot);
+                if (!session) {
+                    return undefined;
+                }
+                return scopeProjectRoleSession(await bindProjectGateReviewerSession(repoRoot, session, taskSlug), taskSlug);
             }
             if (role === CODEX_TRANSLATOR_ROLE) {
                 void taskSlug;
@@ -470,7 +504,7 @@ export function createSessionService(deps) {
             const task = await deps.taskService.loadTask(repoRoot, taskSlug);
             const taskRepoRoot = getTaskRuntimeRepoRoot(task);
             const persistedTaskSession = await loadPersistedTaskSessionRecord(deps.fs, taskRepoRoot, config.stateRoot, taskSlug);
-            for (const role of VCM_ROLE_NAMES) {
+            for (const role of CORE_VCM_ROLE_NAMES) {
                 const record = deps.registry.getByRole(taskSlug, role)
                     ?? normalizePersistedRoleRecord(persistedTaskSession?.roles[role]?.record);
                 const session = toRoleSessionRecordView(record, deps.runtime);

package/dist/shared/constants.js

@@ -1,6 +1,6 @@
 export const DEFAULT_BACKEND_PORT = 4173;
 export const DEFAULT_FRONTEND_PORT = 5173;
-export const VCM_ROLE_DEFINITIONS = [
+export const CORE_VCM_ROLE_DEFINITIONS = [
     {
         name: "project-manager",
         label: "Project Manager",
@@ -32,6 +32,10 @@ export const GATE_REVIEWER_ROLE_DEFINITION = {
     commandAgent: "gate-reviewer",
     dispatchable: false
 };
+export const VCM_ROLE_DEFINITIONS = [
+    ...CORE_VCM_ROLE_DEFINITIONS,
+    GATE_REVIEWER_ROLE_DEFINITION
+];
 export const CODEX_TRANSLATOR_ROLE_DEFINITION = {
     name: "codex-translator",
     label: "Codex Translator",
@@ -43,9 +47,9 @@ export const CODEX_ROLE_DEFINITIONS = [
 ];
 export const ROLE_DEFINITIONS = [
     ...VCM_ROLE_DEFINITIONS,
-    GATE_REVIEWER_ROLE_DEFINITION,
     ...CODEX_ROLE_DEFINITIONS
 ];
+export const CORE_VCM_ROLE_NAMES = CORE_VCM_ROLE_DEFINITIONS.map((role) => role.name);
 export const VCM_ROLE_NAMES = VCM_ROLE_DEFINITIONS.map((role) => role.name);
 export const CODEX_ROLE_NAMES = CODEX_ROLE_DEFINITIONS.map((role) => role.name);
 export const ROLE_NAMES = ROLE_DEFINITIONS.map((role) => role.name);