vibe-coding-master 0.7.5 → 0.7.7

package/README.md

@@ -181,6 +181,12 @@ By default:
 Roles for the same task share the same task worktree. VCM does not create one
 worktree per role.
 
+Project Manager may record an advisory task checkpoint under
+`.ai/vcm/workflow/state.json`. VCM restores and displays this context after a
+restart, but it does not infer transitions or choose the next role. Current
+artifacts, Gate Review state, Round/Turn state, and the role rules remain
+authoritative.
+
 Typical flow:
 
 ```text
@@ -253,8 +259,10 @@ Automatic mode:
 - the UI switches to the target role before dispatch
 - Claude Code hooks confirm whether the prompt was accepted
 
-If the flow stops, VCM shows a pause alert. The `Pause alert sound` setting only
-controls the sound; the stopped-flow state is still shown in the UI.
+If the flow stops, VCM always shows a blocking pause alert. `Pause alert sound`
+only controls the looping sound. Enabling Gateway turns that preference off once;
+it can be turned back on afterward. A new Gateway command closes an open pause
+alert after its instruction is successfully submitted to PM.
 
 ## Gate Review Gates
 
@@ -280,8 +288,9 @@ findings back to the responsible role.
 
 Conversation translation is controlled from the sidebar `Translation` section.
 
-VCM uses the project-scoped Translator role and Claude transcript JSONL files,
-not raw terminal text.
+VCM uses a task-scoped Translator role and Claude transcript JSONL files, not
+raw terminal text. Translation memory and completed file translations remain
+project-level durable data.
 
 Common controls:
 
@@ -385,8 +394,9 @@ Use it to:
 - merge task harness commits back to the connected repository branch when
   appropriate
 
-Harness Engineer is project-scoped and resumable. When it performs task work,
-VCM runs it from the active task worktree.
+Harness Engineer is task-scoped and runs from the active task worktree. A new
+task receives its own Harness Engineer session. Durable memory is versioned with
+the project harness files.
 
 ### Auto Memory
 
@@ -396,20 +406,28 @@ Tester, and an enabled Gate Reviewer submit proposals in sequence through
 `vcm-propose-memory`. Harness Engineer verifies and consolidates them before VCM
 applies the result. Roles cannot edit active memory directly.
 
-Canonical memory is stored under the base repository's `.ai/vcm/memory/`.
-Harness Studio shows current memory and task-local applied history. Memory is
-applied before user review; while the task worktree remains available, the user
-can edit current memory or revert a recorded change.
+Shared memory is stored in the root `CLAUDE.md` `<VCM-memory>` block. Role memory
+is stored in the matching `.claude/agents/*.md` block. VCM changes only block
+contents and creates a dedicated commit in the active task worktree. Harness
+Studio shows current memory and task-local applied history. Memory is applied
+before user review; while the task worktree remains available, the user can edit
+current memory or revert a recorded change through another commit.
 
 Post-task processing is ordered by the backend:
 
 ```text
 Final Acceptance
   -> Review Task Harness
-  -> Memory proposals and Harness Engineer review, when Auto Memory is enabled
+  -> Workflow-role memory proposals, when Auto Memory is enabled
+  -> Harness Engineer memory review, when Auto Memory is enabled
   -> Task Harness Retrospective
 ```
 
+Memory proposal prompts sent to Project Manager, Architect, Coder, Tester, and
+an enabled Gate Reviewer use their normal task sessions and participate in
+Round/Turn tracking. Harness Engineer review and retrospective work remain tool
+role activity and do not participate in Round completion.
+
 When Auto Memory is disabled, Review Task Harness does not collect proposals or
 ask Harness Engineer to update memory. When enabled, both automatic and manual
 review requests complete the memory phase before retrospective analysis. A
@@ -420,12 +438,14 @@ can continue.
 
 `Close Task` is destructive.
 
-It stops task-owned VCM role sessions and removes task-owned worktree/branch
-state. Commit or preserve anything important before closing.
+It stops every running session owned by the task, including Translator and
+Harness Engineer, then removes task-owned worktree/branch state. Commit or
+preserve anything important before closing.
 
-Project-scoped tool sessions such as Translator and Harness Engineer are not
-ordinary task deliverables. VCM may move them to a safe cwd when task context
-changes.
+Uncommitted changes, unmerged commits, and cleanup failures are reported as
+warnings; they do not block logical task closure. VCM may discard the task
+worktree and task branch even when they contain commits that are not present on
+the connected repository branch.
 
 ## Troubleshooting
 
@@ -514,7 +534,11 @@ npm start
 ## Documentation
 
 - `docs/ARCHITECTURE.md`: repository architecture
+- `docs/CODING_STANDARDS.md`: shared implementation and test standards
+- `docs/GLOSSARY.md`: allowed durable abbreviations
 - `docs/TESTING.md`: validation strategy
+- `docs/known-issues.md`: current unresolved durable issues
+- `src/backend/gateway/ARCHITECTURE.md`: mobile gateway sub-area architecture
 - `docs/vcm-cc-best-practices.md`: current VCM Claude Code harness practice
 - `docs/v0.5-custom-workflow-plan.md`: deferred custom workflow proposal
 - `docs/cc-best-practices.md`: archived generic Claude Code harness notes

package/dist/backend/adapters/git-adapter.js

@@ -293,6 +293,21 @@ export function createGitAdapter(runner) {
             }
             return this.getHeadCommit(repoRoot);
         },
+        async commitPaths(repoRoot, message, paths) {
+            if (paths.length === 0) {
+                return this.getHeadCommit(repoRoot);
+            }
+            const result = await runGit(runner, repoRoot, ["commit", "--only", "-m", message, "--", ...paths]);
+            if (result.exitCode !== 0) {
+                throw new VcmError({
+                    code: "GIT_COMMIT_FAILED",
+                    message: "Unable to commit VCM memory changes.",
+                    statusCode: 409,
+                    hint: result.stderr || result.stdout
+                });
+            }
+            return this.getHeadCommit(repoRoot);
+        },
         async createWorktree(input) {
             const result = await runGit(runner, input.repoRoot, [
                 "worktree",

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

@@ -64,6 +64,9 @@ function parseDispatchableRole(role) {
     return role;
 }
 function artifactNameToPath(paths, artifactName) {
+    if (artifactName === "architecture-brief.md") {
+        return paths.architectureBriefPath;
+    }
     if (artifactName === "architecture-plan.md") {
         return paths.architecturePlanPath;
     }

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

@@ -55,7 +55,7 @@ export function registerHarnessRoutes(app, deps) {
     app.get("/api/projects/harness/bootstrap", async (request) => {
         const { project, task } = await requireHarnessTaskContext(deps, request.query.taskSlug);
         try {
-            return await deps.harnessService.getBootstrapStatus(project.repoRoot, task.worktreePath);
+            return await deps.harnessService.getBootstrapStatus(project.repoRoot, task.worktreePath, task.taskSlug);
         }
         catch (error) {
             if (isOpenFileLimitError(error)) {
@@ -76,61 +76,79 @@ export function registerHarnessRoutes(app, deps) {
         await deps.harnessFeedbackService.assertHarnessEngineerAvailable(project.repoRoot);
         return deps.harnessService.restartHarnessBootstrap(project.repoRoot, task.worktreePath, request.body ?? {});
     });
-    app.post("/api/projects/harness/bootstrap/stop", async () => {
-        const project = await requireCurrentProject(deps.projectService);
-        return deps.harnessService.stopHarnessBootstrap(project.repoRoot);
+    app.post("/api/projects/harness/bootstrap/stop", async (request) => {
+        const { project, task } = await requireHarnessTaskContext(deps, request.body?.taskSlug);
+        return deps.harnessService.stopHarnessBootstrap(project.repoRoot, task.worktreePath, task.taskSlug);
     });
     app.post("/api/projects/harness/bootstrap/run", async (request) => {
         const { project, task } = await requireHarnessTaskContext(deps, request.body?.taskSlug);
         await deps.autoMemoryService.assertHarnessEngineerAvailable(task.worktreePath);
         await deps.harnessFeedbackService.assertHarnessEngineerAvailable(project.repoRoot);
-        return deps.harnessService.runHarnessBootstrap(project.repoRoot, task.worktreePath);
+        return deps.harnessService.runHarnessBootstrap(project.repoRoot, task.worktreePath, task.taskSlug);
     });
-    app.get("/api/projects/harness/engineer/session", async () => {
+    app.get("/api/projects/harness/engineer/session", async (request) => {
         const project = await requireCurrentProject(deps.projectService);
-        return (await deps.sessionService.getProjectHarnessEngineerSession(project.repoRoot)) ?? null;
+        const taskSlug = request.query.taskSlug?.trim();
+        if (!taskSlug) {
+            return null;
+        }
+        return (await deps.sessionService.getRoleSession(project.repoRoot, taskSlug, "harness-engineer")) ?? null;
     });
     app.post("/api/projects/harness/engineer/session/ensure", async (request) => {
         const project = await requireCurrentProject(deps.projectService);
-        return deps.sessionService.ensureProjectHarnessEngineerSession(project.repoRoot, request.body);
+        const taskSlug = requireTaskSlug(request.body?.taskSlug, "Harness Engineer");
+        const existing = await deps.sessionService.getRoleSession(project.repoRoot, taskSlug, "harness-engineer");
+        if (existing?.status === "running") {
+            return existing;
+        }
+        if (existing?.claudeSessionId) {
+            return deps.sessionService.resumeRoleSession(project.repoRoot, taskSlug, "harness-engineer", request.body);
+        }
+        return deps.sessionService.startRoleSession(project.repoRoot, taskSlug, "harness-engineer", request.body);
     });
     app.post("/api/projects/harness/engineer/session/start", async (request) => {
         const project = await requireCurrentProject(deps.projectService);
-        if (request.body?.taskSlug) {
-            const task = await deps.taskService.loadTask(project.repoRoot, request.body.taskSlug);
-            await deps.autoMemoryService.assertHarnessEngineerAvailable(task.worktreePath);
-        }
-        return deps.sessionService.startProjectHarnessEngineerSession(project.repoRoot, request.body);
+        const taskSlug = requireTaskSlug(request.body?.taskSlug, "Harness Engineer");
+        const task = await deps.taskService.loadTask(project.repoRoot, taskSlug);
+        await deps.autoMemoryService.assertHarnessEngineerAvailable(task.worktreePath);
+        return deps.sessionService.startRoleSession(project.repoRoot, taskSlug, "harness-engineer", request.body);
     });
     app.post("/api/projects/harness/engineer/session/resume", async (request) => {
         const project = await requireCurrentProject(deps.projectService);
-        if (request.body?.taskSlug) {
-            const task = await deps.taskService.loadTask(project.repoRoot, request.body.taskSlug);
-            await deps.autoMemoryService.assertHarnessEngineerAvailable(task.worktreePath);
-        }
-        return deps.sessionService.resumeProjectHarnessEngineerSession(project.repoRoot, request.body);
+        const taskSlug = requireTaskSlug(request.body?.taskSlug, "Harness Engineer");
+        const task = await deps.taskService.loadTask(project.repoRoot, taskSlug);
+        await deps.autoMemoryService.assertHarnessEngineerAvailable(task.worktreePath);
+        return deps.sessionService.resumeRoleSession(project.repoRoot, taskSlug, "harness-engineer", request.body);
     });
     app.post("/api/projects/harness/engineer/session/restart", async (request) => {
         const project = await requireCurrentProject(deps.projectService);
-        if (request.body?.taskSlug) {
-            const task = await deps.taskService.loadTask(project.repoRoot, request.body.taskSlug);
-            await deps.autoMemoryService.assertHarnessEngineerAvailable(task.worktreePath);
-        }
-        return deps.sessionService.restartProjectHarnessEngineerSession(project.repoRoot, request.body);
+        const taskSlug = requireTaskSlug(request.body?.taskSlug, "Harness Engineer");
+        const task = await deps.taskService.loadTask(project.repoRoot, taskSlug);
+        await deps.autoMemoryService.assertHarnessEngineerAvailable(task.worktreePath);
+        return deps.sessionService.restartRoleSession(project.repoRoot, taskSlug, "harness-engineer", request.body);
     });
-    app.post("/api/projects/harness/engineer/session/stop", async () => {
+    app.post("/api/projects/harness/engineer/session/stop", async (request) => {
         const project = await requireCurrentProject(deps.projectService);
-        return deps.sessionService.stopProjectHarnessEngineerSession(project.repoRoot);
+        const taskSlug = requireTaskSlug(request.body?.taskSlug, "Harness Engineer");
+        return deps.sessionService.stopRoleSession(project.repoRoot, taskSlug, "harness-engineer");
     });
-    app.post("/api/projects/harness/engineer/session/notify-harness", async () => {
+    app.post("/api/projects/harness/engineer/session/notify-harness", async (request) => {
         const project = await requireCurrentProject(deps.projectService);
-        return deps.sessionService.notifyProjectHarnessEngineerHarnessUpdated(project.repoRoot);
+        const taskSlug = requireTaskSlug(request.body?.taskSlug, "Harness Engineer");
+        return deps.sessionService.notifyRoleHarnessUpdated(project.repoRoot, taskSlug, "harness-engineer");
     });
     app.get("/api/projects/harness/feedback", async (request) => {
         const project = await requireCurrentProject(deps.projectService);
         const taskSlug = await normalizeOptionalTaskSlug(deps, project.repoRoot, request.query.taskSlug);
         return deps.harnessFeedbackService.getState(project.repoRoot, taskSlug);
     });
+    app.post("/api/projects/harness/feedback/send", async (request) => {
+        const { project, task } = await requireHarnessTaskContext(deps, request.body?.taskSlug);
+        return deps.harnessFeedbackService.sendPendingFeedback(project.repoRoot, {
+            taskSlug: task.taskSlug,
+            feedbackPath: request.body?.feedbackPath ?? ""
+        });
+    });
     app.post("/api/projects/harness/task-retrospective", async (request) => {
         const { project, task } = await requireHarnessTaskContext(deps, request.body?.taskSlug);
         const trigger = request.body?.trigger === "auto" ? "auto" : "manual";
@@ -183,6 +201,18 @@ export function registerHarnessRoutes(app, deps) {
         return deps.autoMemoryService.retryFailedReview(project.repoRoot, task.worktreePath);
     });
 }
+function requireTaskSlug(value, roleLabel) {
+    const taskSlug = value?.trim();
+    if (!taskSlug) {
+        throw new VcmError({
+            code: "TOOL_SESSION_TASK_REQUIRED",
+            message: `${roleLabel} requires an active task.`,
+            statusCode: 409,
+            hint: "Create or select a task before using this session."
+        });
+    }
+    return taskSlug;
+}
 function degradedHarnessStatus(error) {
     return {
         version: 1,

package/dist/backend/api/runtime-state-routes.js

@@ -5,9 +5,13 @@ export function registerRuntimeStateRoutes(app, deps) {
         const taskSlug = request.query.taskSlug?.trim();
         const coordinated = await deps.runtimeCoordinator.reconcileProject(project.repoRoot, { taskSlug });
         const [translatorSession, translationState, harnessEngineerSession, harnessFeedbackState] = await Promise.all([
-            deps.sessionService.getProjectTranslatorSession(project.repoRoot).then((session) => session ?? null),
+            taskSlug
+                ? deps.sessionService.getRoleSession(project.repoRoot, taskSlug, "translator").then((session) => session ?? null)
+                : Promise.resolve(null),
             deps.translationWorkerService.getState(project.repoRoot, { visibility: "public" }),
-            deps.sessionService.getProjectHarnessEngineerSession(project.repoRoot).then((session) => session ?? null),
+            taskSlug
+                ? deps.sessionService.getRoleSession(project.repoRoot, taskSlug, "harness-engineer").then((session) => session ?? null)
+                : Promise.resolve(null),
             deps.harnessFeedbackService.getState(project.repoRoot, taskSlug || undefined)
         ]);
         if (!taskSlug) {
@@ -26,7 +30,7 @@ export function registerRuntimeStateRoutes(app, deps) {
             const task = await deps.taskService.loadTask(project.repoRoot, taskSlug);
             const [harnessStatus, harnessBootstrapStatus, autoMemoryState] = await Promise.all([
                 withOpenFileLimitFallback(() => deps.harnessService.getHarnessStatus(task.worktreePath), (error) => degradedHarnessStatus(error)),
-                withOpenFileLimitFallback(() => deps.harnessService.getBootstrapStatus(project.repoRoot, task.worktreePath), (error) => degradedBootstrapStatus(error)),
+                withOpenFileLimitFallback(() => deps.harnessService.getBootstrapStatus(project.repoRoot, task.worktreePath, task.taskSlug), (error) => degradedBootstrapStatus(error)),
                 deps.autoMemoryService.getState(project.repoRoot, task.worktreePath)
             ]);
             return {

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

@@ -45,7 +45,7 @@ export function registerTaskRoutes(app, deps) {
                 handoffDir: task.handoffDir,
                 taskSlug
             };
-            const [taskStatus, messages, orchestration, roundState] = await Promise.all([
+            const [taskStatus, messages, orchestration, roundState, workflowState] = await Promise.all([
                 withOpenFileLimitFallback(() => deps.statusService.getTaskStatus(project.repoRoot, taskSlug), (error) => degradedTaskStatus(project.repoRoot, taskSlug, error)),
                 withOpenFileLimitFallback(() => deps.messageService.listMessages(context), () => []),
                 withOpenFileLimitFallback(() => deps.messageService.getOrchestrationState(context), () => ({
@@ -58,13 +58,19 @@ export function registerTaskRoutes(app, deps) {
                     stateRepoRoot: taskRepoRoot,
                     stateRoot: config.stateRoot,
                     taskSlug
-                }), () => degradedRoundState(taskSlug))
+                }), () => degradedRoundState(taskSlug)),
+                deps.taskWorkflowService?.getState({
+                    taskRepoRoot,
+                    stateRoot: config.stateRoot,
+                    taskSlug
+                }) ?? Promise.resolve(degradedWorkflowState(taskSlug))
             ]);
             return {
                 taskStatus,
                 messages,
                 orchestration,
-                roundState
+                roundState,
+                workflowState
             };
         }
         catch (error) {
@@ -77,12 +83,26 @@ export function registerTaskRoutes(app, deps) {
                         mode: "auto",
                         updatedAt: new Date().toISOString()
                     },
-                    roundState: degradedRoundState(taskSlug)
+                    roundState: degradedRoundState(taskSlug),
+                    workflowState: degradedWorkflowState(taskSlug)
                 };
             }
             throw error;
         }
     });
+    app.post("/api/tasks/:taskSlug/workflow-state", async (request) => {
+        const project = await requireCurrentProject(deps.projectService);
+        const config = await deps.projectService.loadConfig(project.repoRoot);
+        const task = await deps.taskService.loadTask(project.repoRoot, request.params.taskSlug);
+        if (!deps.taskWorkflowService) {
+            return degradedWorkflowState(task.taskSlug);
+        }
+        return deps.taskWorkflowService.declare({
+            taskRepoRoot: getTaskRuntimeRepoRoot(task),
+            stateRoot: config.stateRoot,
+            taskSlug: task.taskSlug
+        }, request.body ?? {});
+    });
     app.post("/api/tasks/:taskSlug/one-click-start", async (request) => {
         const project = await requireCurrentProject(deps.projectService);
         return deps.taskLaunchService.startTaskRoleSessions(project.repoRoot, {
@@ -143,6 +163,17 @@ function degradedRoundState(taskSlug) {
         updatedAt: new Date().toISOString()
     };
 }
+function degradedWorkflowState(taskSlug) {
+    return {
+        version: 1,
+        taskSlug,
+        revision: 0,
+        declared: null,
+        lastDispatch: null,
+        warnings: ["Task workflow state is temporarily unavailable."],
+        updatedAt: new Date().toISOString()
+    };
+}
 async function withOpenFileLimitFallback(run, fallback) {
     try {
         return await run();
@@ -164,6 +195,7 @@ function degradedArtifactSummary(handoffDir) {
             messagesDir,
             roleCommandPaths: Object.fromEntries(DISPATCHABLE_ROLES.map((role) => [role, `${roleCommandsDir}/${role}.md`])),
             messageRoutePaths: {},
+            architectureBriefPath: `${handoffDir}/architecture-brief.md`,
             architecturePlanPath: `${handoffDir}/architecture-plan.md`,
             knownIssuesPath: `${handoffDir}/known-issues.md`,
             testReportPath: `${handoffDir}/test-report.md`,

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

@@ -86,9 +86,18 @@ export function registerTranslationRoutes(app, deps) {
         await deps.translationService.stopSession(request.params.sessionId);
         return { ok: true };
     });
-    app.post("/api/projects/translation/session/notify-harness", async () => {
+    app.post("/api/projects/translation/session/notify-harness", async (request) => {
         const project = await requireCurrentProject(deps.projectService);
-        return deps.sessionService.notifyProjectTranslatorHarnessUpdated(project.repoRoot);
+        const taskSlug = request.body?.taskSlug?.trim();
+        if (!taskSlug) {
+            throw new VcmError({
+                code: "TOOL_SESSION_TASK_REQUIRED",
+                message: "Translator requires an active task.",
+                statusCode: 409,
+                hint: "Create or select a task before notifying Translator."
+            });
+        }
+        return deps.sessionService.notifyRoleHarnessUpdated(project.repoRoot, taskSlug, "translator");
     });
     app.post("/api/translation/sessions/:sessionId/retry/:translationId", async (request) => {
         await requireCurrentProject(deps.projectService);

package/dist/backend/api/translation-worker-routes.js

@@ -6,33 +6,49 @@ export function registerTranslationWorkerRoutes(app, deps) {
             visibility: "public"
         });
     });
-    app.get("/api/translation/session", async () => {
+    app.get("/api/translation/session", async (request) => {
         const project = await requireCurrentProject(deps.projectService);
-        return (await deps.sessionService.getProjectTranslatorSession(project.repoRoot)) ?? null;
+        const taskSlug = request.query.taskSlug?.trim();
+        if (!taskSlug) {
+            return null;
+        }
+        return (await deps.sessionService.getRoleSession(project.repoRoot, taskSlug, "translator")) ?? null;
     });
     app.post("/api/translation/session/ensure", async (request) => {
         const project = await requireCurrentProject(deps.projectService);
-        return deps.sessionService.ensureProjectTranslatorSession(project.repoRoot, request.body);
+        const taskSlug = requireTaskSlug(request.body?.taskSlug, "Translator");
+        const existing = await deps.sessionService.getRoleSession(project.repoRoot, taskSlug, "translator");
+        if (existing?.status === "running") {
+            return existing;
+        }
+        if (existing?.claudeSessionId) {
+            return deps.sessionService.resumeRoleSession(project.repoRoot, taskSlug, "translator", request.body);
+        }
+        return deps.sessionService.startRoleSession(project.repoRoot, taskSlug, "translator", request.body);
     });
     app.post("/api/translation/session/start", async (request) => {
         const project = await requireCurrentProject(deps.projectService);
-        return deps.sessionService.startProjectTranslatorSession(project.repoRoot, request.body);
+        const taskSlug = requireTaskSlug(request.body?.taskSlug, "Translator");
+        return deps.sessionService.startRoleSession(project.repoRoot, taskSlug, "translator", request.body);
     });
     app.post("/api/translation/session/resume", async (request) => {
         const project = await requireCurrentProject(deps.projectService);
-        return deps.sessionService.resumeProjectTranslatorSession(project.repoRoot, request.body);
+        const taskSlug = requireTaskSlug(request.body?.taskSlug, "Translator");
+        return deps.sessionService.resumeRoleSession(project.repoRoot, taskSlug, "translator", request.body);
     });
     app.post("/api/translation/session/restart", async (request) => {
         const project = await requireCurrentProject(deps.projectService);
-        const existing = await deps.sessionService.getProjectTranslatorSession(project.repoRoot);
+        const taskSlug = requireTaskSlug(request.body?.taskSlug, "Translator");
+        const existing = await deps.sessionService.getRoleSession(project.repoRoot, taskSlug, "translator");
         if (existing) {
             await deps.translationService.stopSession(existing.id, { clearCache: true });
         }
-        return deps.sessionService.restartProjectTranslatorSession(project.repoRoot, request.body);
+        return deps.sessionService.restartRoleSession(project.repoRoot, taskSlug, "translator", request.body);
     });
-    app.post("/api/translation/session/stop", async () => {
+    app.post("/api/translation/session/stop", async (request) => {
         const project = await requireCurrentProject(deps.projectService);
-        const session = await deps.sessionService.stopProjectTranslatorSession(project.repoRoot);
+        const taskSlug = requireTaskSlug(request.body?.taskSlug, "Translator");
+        const session = await deps.sessionService.stopRoleSession(project.repoRoot, taskSlug, "translator");
         await deps.translationService.stopSession(session.id);
         return session;
     });
@@ -73,6 +89,18 @@ export function registerTranslationWorkerRoutes(app, deps) {
         return deps.translationWorkerService.promoteFileJob(project.repoRoot, request.params.jobId, targetPath);
     });
 }
+function requireTaskSlug(value, roleLabel) {
+    const taskSlug = value?.trim();
+    if (!taskSlug) {
+        throw new VcmError({
+            code: "TOOL_SESSION_TASK_REQUIRED",
+            message: `${roleLabel} requires an active task.`,
+            statusCode: 409,
+            hint: "Create or select a task before using this session."
+        });
+    }
+    return taskSlug;
+}
 async function requireCurrentProject(projectService) {
     const project = await projectService.getCurrentProject();
     if (!project) {