vibe-coding-master 0.3.31 → 0.4.0

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

@@ -3,21 +3,40 @@ import path from "node:path";
 import { CORE_VCM_ROLE_NAMES, isDispatchableRole } from "../../shared/constants.js";
 import { VcmError } from "../errors.js";
 import { resolveRepoPath } from "../adapters/filesystem.js";
+import { submitTerminalInput } from "../runtime/terminal-submit.js";
 import { claudeTranscriptPath } from "./claude-transcript-service.js";
+import { readHarnessRevisionState } from "./harness-revision.js";
 import { getTaskRuntimeRepoRoot } from "./task-service.js";
 const GATE_REVIEWER_ROLE = "gate-reviewer";
 const TRANSLATOR_ROLE = "translator";
+const HARNESS_ENGINEER_ROLE = "harness-engineer";
 const TRANSLATION_DIR = ".ai/vcm/translations";
 const TRANSLATOR_SESSION_PATH = ".ai/vcm/translations/session.json";
+const HARNESS_ENGINEER_DIR = ".ai/vcm/harness-engineer";
+const HARNESS_ENGINEER_SESSION_PATH = ".ai/vcm/harness-engineer/session.json";
 const GATE_REVIEWER_SESSION_PATH = ".ai/vcm/gate-reviewer/session.json";
 const PROJECT_TRANSLATOR_SCOPE = "__project__";
+const PROJECT_HARNESS_ENGINEER_SCOPE = "__project_harness_engineer__";
 const PROJECT_GATE_REVIEWER_SCOPE = "__project_gate_reviewer__";
 export function createSessionService(deps) {
     const now = deps.now ?? (() => new Date().toISOString());
+    async function readCurrentHarnessRevision(repoRoot) {
+        return (await readHarnessRevisionState(deps.fs, repoRoot)).revision;
+    }
+    async function withHarnessRevisionView(repoRoot, record) {
+        const currentRevision = await readCurrentHarnessRevision(repoRoot);
+        const sessionRevision = normalizeHarnessRevision(record.harnessRevision);
+        return {
+            ...record,
+            harnessRevision: sessionRevision,
+            harnessCurrentRevision: currentRevision,
+            harnessOutdated: sessionRevision < currentRevision
+        };
+    }
     async function launchRoleSession(repoRoot, taskSlug, role, input, launchMode) {
         const live = toRoleSessionRecordView(getRegisteredRoleSession(deps.registry, deps.runtime, taskSlug, role), deps.runtime);
         if (live && live.status === "running") {
-            return live;
+            return withHarnessRevisionView(repoRoot, live);
         }
         const config = await deps.projectService.loadConfig(repoRoot);
         const task = await deps.taskService.loadTask(repoRoot, taskSlug);
@@ -62,6 +81,7 @@ export function createSessionService(deps) {
             rows: input.rows
         });
         const timestamp = now();
+        const harnessRevision = await readCurrentHarnessRevision(repoRoot);
         const record = {
             id: runtimeSession.id,
             claudeSessionId,
@@ -84,16 +104,17 @@ export function createSessionService(deps) {
             startedAt: runtimeSession.startedAt,
             updatedAt: timestamp,
             lastOutputAt: runtimeSession.lastOutputAt,
+            harnessRevision,
             exitCode: runtimeSession.exitCode
         };
         deps.registry.upsert(record);
         await persistRoleSessionRecord(deps.fs, repoRoot, taskRepoRoot, config.stateRoot, record);
-        return record;
+        return withHarnessRevisionView(repoRoot, record);
     }
     async function launchProjectGateReviewerSession(repoRoot, input, launchMode, activeTaskSlug) {
         const live = toRoleSessionRecordView(getRegisteredProjectGateReviewerSession(deps.registry, deps.runtime), deps.runtime);
         if (live && live.status === "running") {
-            return bindProjectGateReviewerSession(repoRoot, live, activeTaskSlug);
+            return withHarnessRevisionView(repoRoot, await bindProjectGateReviewerSession(repoRoot, live, activeTaskSlug));
         }
         const config = await deps.projectService.loadConfig(repoRoot);
         const persisted = await loadPersistedProjectGateReviewerSession(deps.fs, repoRoot);
@@ -139,6 +160,7 @@ export function createSessionService(deps) {
             rows: input.rows
         });
         const timestamp = now();
+        const harnessRevision = await readCurrentHarnessRevision(repoRoot);
         const record = {
             id: runtimeSession.id,
             claudeSessionId,
@@ -159,11 +181,12 @@ export function createSessionService(deps) {
             lastOutputAt: runtimeSession.lastOutputAt,
             activeTaskSlug,
             activeTaskRepoRoot,
+            harnessRevision,
             exitCode: runtimeSession.exitCode
         };
         deps.registry.upsert(record);
         await persistProjectGateReviewerSession(deps.fs, repoRoot, record);
-        return record;
+        return withHarnessRevisionView(repoRoot, record);
     }
     async function bindProjectGateReviewerSession(repoRoot, record, activeTaskSlug) {
         if (!activeTaskSlug) {
@@ -185,7 +208,7 @@ export function createSessionService(deps) {
     async function launchProjectTranslatorSession(repoRoot, input, launchMode) {
         const live = toRoleSessionRecordView(getRegisteredProjectTranslatorSession(deps.registry, deps.runtime), deps.runtime);
         if (live && live.status === "running") {
-            return live;
+            return withHarnessRevisionView(repoRoot, live);
         }
         const config = await deps.projectService.loadConfig(repoRoot);
         const persisted = await loadPersistedTranslatorSession(deps.fs, repoRoot);
@@ -228,6 +251,7 @@ export function createSessionService(deps) {
             rows: input.rows
         });
         const timestamp = now();
+        const harnessRevision = await readCurrentHarnessRevision(repoRoot);
         const record = {
             id: runtimeSession.id,
             claudeSessionId,
@@ -246,11 +270,135 @@ export function createSessionService(deps) {
             startedAt: runtimeSession.startedAt,
             updatedAt: timestamp,
             lastOutputAt: runtimeSession.lastOutputAt,
+            harnessRevision,
             exitCode: runtimeSession.exitCode
         };
         deps.registry.upsert(record);
         await persistTranslatorSession(deps.fs, repoRoot, record);
-        return record;
+        return withHarnessRevisionView(repoRoot, record);
+    }
+    async function launchProjectHarnessEngineerSession(repoRoot, input, launchMode) {
+        const live = toRoleSessionRecordView(getRegisteredProjectHarnessEngineerSession(deps.registry, deps.runtime), deps.runtime);
+        if (live && live.status === "running") {
+            return withHarnessRevisionView(repoRoot, live);
+        }
+        const config = await deps.projectService.loadConfig(repoRoot);
+        const persisted = await loadPersistedHarnessEngineerSession(deps.fs, repoRoot);
+        const permissionMode = normalizeClaudePermissionMode(input.permissionMode ?? persisted?.permissionMode);
+        const model = normalizeClaudeModel(input.model ?? persisted?.model);
+        const effort = normalizeClaudeEffort(input.effort ?? persisted?.effort ?? "medium");
+        const claudeSessionId = launchMode === "resume"
+            ? persisted?.claudeSessionId
+            : randomUUID();
+        if (!claudeSessionId) {
+            throw new VcmError({
+                code: "HARNESS_ENGINEER_SESSION_MISSING",
+                message: "Harness Engineer does not have a session id to resume.",
+                statusCode: 409,
+                hint: "Start Harness Engineer once before using Resume."
+            });
+        }
+        await deps.fs.ensureDir(resolveRepoPath(repoRoot, HARNESS_ENGINEER_DIR));
+        const transcriptPath = launchMode === "resume" && persisted?.transcriptPath
+            ? persisted.transcriptPath
+            : claudeTranscriptPath(repoRoot, claudeSessionId);
+        const startCommand = {
+            ...deps.claude.buildRoleStartCommand(HARNESS_ENGINEER_ROLE, config.claudeCommand, permissionMode, claudeSessionId, launchMode === "resume", model, effort),
+            cwd: repoRoot
+        };
+        const runtimeSession = await deps.runtime.createSession({
+            taskSlug: PROJECT_HARNESS_ENGINEER_SCOPE,
+            role: HARNESS_ENGINEER_ROLE,
+            command: startCommand.command,
+            args: startCommand.args,
+            cwd: startCommand.cwd,
+            env: {
+                VCM_API_URL: deps.apiUrl,
+                VCM_TASK_REPO_ROOT: repoRoot,
+                VCM_TASK_SLUG: PROJECT_HARNESS_ENGINEER_SCOPE,
+                VCM_ROLE: HARNESS_ENGINEER_ROLE,
+                VCM_SESSION_ID: claudeSessionId
+            },
+            cols: input.cols,
+            rows: input.rows
+        });
+        const timestamp = now();
+        const harnessRevision = await readCurrentHarnessRevision(repoRoot);
+        const record = {
+            id: runtimeSession.id,
+            claudeSessionId,
+            transcriptPath,
+            taskSlug: PROJECT_HARNESS_ENGINEER_SCOPE,
+            role: HARNESS_ENGINEER_ROLE,
+            status: runtimeSession.status,
+            activityStatus: "idle",
+            command: startCommand.display,
+            permissionMode,
+            model,
+            effort,
+            cwd: startCommand.cwd,
+            terminalBackend: "node-pty",
+            pid: runtimeSession.pid,
+            startedAt: runtimeSession.startedAt,
+            updatedAt: timestamp,
+            lastOutputAt: runtimeSession.lastOutputAt,
+            harnessRevision,
+            exitCode: runtimeSession.exitCode
+        };
+        deps.registry.upsert(record);
+        await persistHarnessEngineerSession(deps.fs, repoRoot, record);
+        return withHarnessRevisionView(repoRoot, record);
+    }
+    async function notifyHarnessUpdatedForSession(repoRoot, session) {
+        const runtimeSession = deps.runtime.getSession(session.id);
+        if (!runtimeSession || runtimeSession.status !== "running") {
+            throw new VcmError({
+                code: "SESSION_NOT_RUNNING",
+                message: `${session.role} must be running before VCM can notify it about harness updates.`,
+                statusCode: 409,
+                hint: "Resume or restart the role to load the latest harness settings."
+            });
+        }
+        const currentRevision = await readCurrentHarnessRevision(repoRoot);
+        const timestamp = now();
+        await submitTerminalInput(deps.runtime, session.id, buildHarnessRefreshPrompt(session.role));
+        const updated = {
+            ...session,
+            harnessRevision: currentRevision,
+            harnessCurrentRevision: currentRevision,
+            harnessOutdated: false,
+            lastHarnessNotifyAt: timestamp,
+            updatedAt: timestamp
+        };
+        deps.registry.upsert(normalizeProjectScopedRecordForPersistence(updated));
+        await persistNotifiedHarnessSession(repoRoot, updated);
+        return withHarnessRevisionView(repoRoot, updated);
+    }
+    async function persistNotifiedHarnessSession(repoRoot, session) {
+        if (session.role === GATE_REVIEWER_ROLE) {
+            await persistProjectGateReviewerSession(deps.fs, repoRoot, {
+                ...session,
+                taskSlug: PROJECT_GATE_REVIEWER_SCOPE
+            });
+            return;
+        }
+        if (session.role === TRANSLATOR_ROLE) {
+            await persistTranslatorSession(deps.fs, repoRoot, {
+                ...session,
+                taskSlug: PROJECT_TRANSLATOR_SCOPE
+            });
+            return;
+        }
+        if (session.role === HARNESS_ENGINEER_ROLE) {
+            await persistHarnessEngineerSession(deps.fs, repoRoot, {
+                ...session,
+                taskSlug: PROJECT_HARNESS_ENGINEER_SCOPE
+            });
+            return;
+        }
+        const config = await deps.projectService.loadConfig(repoRoot);
+        const task = await deps.taskService.loadTask(repoRoot, session.taskSlug);
+        await persistRoleSessionRecord(deps.fs, repoRoot, getTaskRuntimeRepoRoot(task), config.stateRoot, session);
     }
     return {
         startProjectGateReviewerSession(repoRoot, input = {}) {
@@ -296,7 +444,8 @@ export function createSessionService(deps) {
         async getProjectGateReviewerSession(repoRoot) {
             const record = getRegisteredProjectGateReviewerSession(deps.registry, deps.runtime)
                 ?? await loadPersistedProjectGateReviewerSession(deps.fs, repoRoot);
-            return toRoleSessionRecordView(record, deps.runtime);
+            const view = toRoleSessionRecordView(record, deps.runtime);
+            return view ? withHarnessRevisionView(repoRoot, view) : undefined;
         },
         async ensureProjectGateReviewerSession(repoRoot, input = {}) {
             const existing = await this.getProjectGateReviewerSession(repoRoot);
@@ -356,7 +505,8 @@ export function createSessionService(deps) {
         async getProjectTranslatorSession(repoRoot) {
             const record = getRegisteredProjectTranslatorSession(deps.registry, deps.runtime)
                 ?? await loadPersistedTranslatorSession(deps.fs, repoRoot);
-            return toRoleSessionRecordView(record, deps.runtime);
+            const view = toRoleSessionRecordView(record, deps.runtime);
+            return view ? withHarnessRevisionView(repoRoot, view) : undefined;
         },
         async ensureProjectTranslatorSession(repoRoot, input = {}) {
             const existing = await this.getProjectTranslatorSession(repoRoot);
@@ -398,6 +548,113 @@ export function createSessionService(deps) {
             await persistTranslatorSession(deps.fs, repoRoot, updated);
             return updated;
         },
+        async notifyProjectTranslatorHarnessUpdated(repoRoot) {
+            const current = await this.getProjectTranslatorSession(repoRoot);
+            if (!current) {
+                throw new VcmError({
+                    code: "SESSION_MISSING",
+                    message: "Translator session has not been started.",
+                    statusCode: 404
+                });
+            }
+            return notifyHarnessUpdatedForSession(repoRoot, current);
+        },
+        startProjectHarnessEngineerSession(repoRoot, input = {}) {
+            return launchProjectHarnessEngineerSession(repoRoot, input, "fresh");
+        },
+        resumeProjectHarnessEngineerSession(repoRoot, input = {}) {
+            return launchProjectHarnessEngineerSession(repoRoot, input, "resume");
+        },
+        async stopProjectHarnessEngineerSession(repoRoot) {
+            const existing = await this.getProjectHarnessEngineerSession(repoRoot);
+            if (!existing) {
+                throw new VcmError({
+                    code: "SESSION_MISSING",
+                    message: "Harness Engineer session has not been started.",
+                    statusCode: 404
+                });
+            }
+            if (deps.runtime.getSession(existing.id)) {
+                await deps.runtime.stop(existing.id);
+            }
+            const updated = {
+                ...existing,
+                status: "exited",
+                activityStatus: "idle",
+                updatedAt: now()
+            };
+            deps.registry.upsert(updated);
+            await persistHarnessEngineerSession(deps.fs, repoRoot, updated);
+            return updated;
+        },
+        async restartProjectHarnessEngineerSession(repoRoot, input = {}) {
+            const existing = await this.getProjectHarnessEngineerSession(repoRoot);
+            if (!existing) {
+                return launchProjectHarnessEngineerSession(repoRoot, input, "fresh");
+            }
+            if (deps.runtime.getSession(existing.id)) {
+                await deps.runtime.stop(existing.id);
+            }
+            deps.registry.remove(existing.id);
+            return launchProjectHarnessEngineerSession(repoRoot, input, "fresh");
+        },
+        async getProjectHarnessEngineerSession(repoRoot) {
+            const record = getRegisteredProjectHarnessEngineerSession(deps.registry, deps.runtime)
+                ?? await loadPersistedHarnessEngineerSession(deps.fs, repoRoot);
+            const view = toRoleSessionRecordView(record, deps.runtime);
+            return view ? withHarnessRevisionView(repoRoot, view) : undefined;
+        },
+        async ensureProjectHarnessEngineerSession(repoRoot, input = {}) {
+            const existing = await this.getProjectHarnessEngineerSession(repoRoot);
+            if (existing?.status === "running") {
+                return existing;
+            }
+            if (existing?.claudeSessionId) {
+                return this.resumeProjectHarnessEngineerSession(repoRoot, {
+                    permissionMode: input.permissionMode ?? existing.permissionMode,
+                    model: input.model ?? existing.model,
+                    effort: input.effort ?? existing.effort,
+                    cols: input.cols,
+                    rows: input.rows
+                });
+            }
+            return this.startProjectHarnessEngineerSession(repoRoot, input);
+        },
+        async recordProjectHarnessEngineerHookEvent(repoRoot, input) {
+            const current = await this.getProjectHarnessEngineerSession(repoRoot);
+            if (!current) {
+                return undefined;
+            }
+            const timestamp = now();
+            const isTurnEnd = isTurnEndHook(input.eventName);
+            const isCompact = isCompactHook(input.eventName);
+            const updated = {
+                ...current,
+                claudeSessionId: input.sessionId ?? current.claudeSessionId,
+                transcriptPath: input.transcriptPath ?? current.transcriptPath,
+                cwd: input.cwd ?? current.cwd,
+                activityStatus: isTurnEnd ? "idle" : isCompact ? current.activityStatus : "running",
+                lastHookEventAt: timestamp,
+                lastTurnEndedAt: isTurnEnd ? timestamp : current.lastTurnEndedAt,
+                lastTurnStartedAt: isTurnEnd || isCompact ? current.lastTurnStartedAt : timestamp,
+                lastCompactAt: isCompact ? timestamp : current.lastCompactAt,
+                updatedAt: timestamp
+            };
+            deps.registry.upsert(updated);
+            await persistHarnessEngineerSession(deps.fs, repoRoot, updated);
+            return updated;
+        },
+        async notifyProjectHarnessEngineerHarnessUpdated(repoRoot) {
+            const current = await this.getProjectHarnessEngineerSession(repoRoot);
+            if (!current) {
+                throw new VcmError({
+                    code: "SESSION_MISSING",
+                    message: "Harness Engineer session has not been started.",
+                    statusCode: 404
+                });
+            }
+            return notifyHarnessUpdatedForSession(repoRoot, current);
+        },
         startRoleSession(repoRoot, taskSlug, role, input = {}) {
             if (role === GATE_REVIEWER_ROLE) {
                 return launchProjectGateReviewerSession(repoRoot, input, "fresh", taskSlug)
@@ -407,6 +664,10 @@ export function createSessionService(deps) {
                 void taskSlug;
                 return this.startProjectTranslatorSession(repoRoot, input);
             }
+            if (role === HARNESS_ENGINEER_ROLE) {
+                void taskSlug;
+                return this.startProjectHarnessEngineerSession(repoRoot, input);
+            }
             return launchRoleSession(repoRoot, taskSlug, role, input, "fresh");
         },
         resumeRoleSession(repoRoot, taskSlug, role, input = {}) {
@@ -418,6 +679,10 @@ export function createSessionService(deps) {
                 void taskSlug;
                 return this.resumeProjectTranslatorSession(repoRoot, input);
             }
+            if (role === HARNESS_ENGINEER_ROLE) {
+                void taskSlug;
+                return this.resumeProjectHarnessEngineerSession(repoRoot, input);
+            }
             return launchRoleSession(repoRoot, taskSlug, role, input, "resume");
         },
         async stopRoleSession(repoRoot, taskSlug, role) {
@@ -428,6 +693,10 @@ export function createSessionService(deps) {
                 void taskSlug;
                 return this.stopProjectTranslatorSession(repoRoot);
             }
+            if (role === HARNESS_ENGINEER_ROLE) {
+                void taskSlug;
+                return this.stopProjectHarnessEngineerSession(repoRoot);
+            }
             const existing = await this.getRoleSession(repoRoot, taskSlug, role);
             if (!existing) {
                 throw new VcmError({
@@ -466,6 +735,10 @@ export function createSessionService(deps) {
                 void taskSlug;
                 return this.restartProjectTranslatorSession(repoRoot, input);
             }
+            if (role === HARNESS_ENGINEER_ROLE) {
+                void taskSlug;
+                return this.restartProjectHarnessEngineerSession(repoRoot, input);
+            }
             const existing = await this.getRoleSession(repoRoot, taskSlug, role);
             if (!existing) {
                 return launchRoleSession(repoRoot, taskSlug, role, input, "fresh");
@@ -482,12 +755,17 @@ export function createSessionService(deps) {
                 if (!session) {
                     return undefined;
                 }
-                return scopeProjectRoleSession(await bindProjectGateReviewerSession(repoRoot, session, taskSlug), taskSlug);
+                const scoped = scopeProjectRoleSession(await bindProjectGateReviewerSession(repoRoot, session, taskSlug), taskSlug);
+                return scoped ? withHarnessRevisionView(repoRoot, scoped) : undefined;
             }
             if (role === TRANSLATOR_ROLE) {
                 void taskSlug;
                 return this.getProjectTranslatorSession(repoRoot);
             }
+            if (role === HARNESS_ENGINEER_ROLE) {
+                void taskSlug;
+                return this.getProjectHarnessEngineerSession(repoRoot);
+            }
             const config = await deps.projectService.loadConfig(repoRoot);
             const task = await deps.taskService.loadTask(repoRoot, taskSlug);
             const taskRepoRoot = getTaskRuntimeRepoRoot(task);
@@ -496,7 +774,8 @@ export function createSessionService(deps) {
             if (!record) {
                 return undefined;
             }
-            return toRoleSessionRecordView(record, deps.runtime);
+            const view = toRoleSessionRecordView(record, deps.runtime);
+            return view ? withHarnessRevisionView(repoRoot, view) : undefined;
         },
         async listRoleSessions(repoRoot, taskSlug) {
             const sessions = [];
@@ -516,7 +795,18 @@ export function createSessionService(deps) {
             if (gateReviewerSession) {
                 sessions.push(gateReviewerSession);
             }
-            return sessions;
+            return Promise.all(sessions.map((session) => withHarnessRevisionView(repoRoot, session)));
+        },
+        async notifyRoleHarnessUpdated(repoRoot, taskSlug, role) {
+            const current = await this.getRoleSession(repoRoot, taskSlug, role);
+            if (!current) {
+                throw new VcmError({
+                    code: "SESSION_MISSING",
+                    message: `${role} session has not been started.`,
+                    statusCode: 404
+                });
+            }
+            return notifyHarnessUpdatedForSession(repoRoot, current);
         },
         async recordRoleHookEvent(repoRoot, input) {
             if (input.role === GATE_REVIEWER_ROLE) {
@@ -553,6 +843,15 @@ export function createSessionService(deps) {
                     cwd: input.cwd
                 });
             }
+            if (input.role === HARNESS_ENGINEER_ROLE) {
+                void input.taskSlug;
+                return this.recordProjectHarnessEngineerHookEvent(repoRoot, {
+                    eventName: input.eventName,
+                    sessionId: input.sessionId,
+                    transcriptPath: input.transcriptPath,
+                    cwd: input.cwd
+                });
+            }
             const current = await this.getRoleSession(repoRoot, input.taskSlug, input.role);
             if (!current || (!input.allowSessionMismatch && !matchesRoleHookSession(current, input))) {
                 return undefined;
@@ -704,7 +1003,7 @@ function getHandoffArtifactPath(paths, role) {
     return undefined;
 }
 function getRegisteredRoleSession(registry, runtime, taskSlug, role) {
-    if (role !== TRANSLATOR_ROLE && role !== GATE_REVIEWER_ROLE) {
+    if (role !== TRANSLATOR_ROLE && role !== GATE_REVIEWER_ROLE && role !== HARNESS_ENGINEER_ROLE) {
         return registry.getByRole(taskSlug, role);
     }
     const candidates = registry.list().filter((session) => session.role === role);
@@ -724,11 +1023,16 @@ function getRegisteredProjectTranslatorSession(registry, runtime) {
     const live = candidates.find((session) => runtime.getSession(session.id)?.status === "running");
     return live ?? candidates.sort(compareSessionUpdatedAtDesc)[0];
 }
+function getRegisteredProjectHarnessEngineerSession(registry, runtime) {
+    const candidates = registry.list().filter((session) => session.role === HARNESS_ENGINEER_ROLE);
+    const live = candidates.find((session) => runtime.getSession(session.id)?.status === "running");
+    return live ?? candidates.sort(compareSessionUpdatedAtDesc)[0];
+}
 function compareSessionUpdatedAtDesc(left, right) {
     return (right.updatedAt ?? "").localeCompare(left.updatedAt ?? "");
 }
 function scopeProjectRoleSession(record, taskSlug) {
-    if (!record || (record.role !== TRANSLATOR_ROLE && record.role !== GATE_REVIEWER_ROLE)) {
+    if (!record || (record.role !== TRANSLATOR_ROLE && record.role !== GATE_REVIEWER_ROLE && record.role !== HARNESS_ENGINEER_ROLE)) {
         return record;
     }
     return {
@@ -745,6 +1049,10 @@ async function loadPersistedRoleRecordForRole(fs, baseRepoRoot, taskRepoRoot, st
         void taskSlug;
         return loadPersistedTranslatorSession(fs, baseRepoRoot);
     }
+    if (role === HARNESS_ENGINEER_ROLE) {
+        void taskSlug;
+        return loadPersistedHarnessEngineerSession(fs, baseRepoRoot);
+    }
     return loadPersistedRoleRecord(fs, taskRepoRoot, stateRoot, taskSlug, role);
 }
 async function loadPersistedProjectGateReviewerSession(fs, repoRoot) {
@@ -777,6 +1085,21 @@ async function loadPersistedTranslatorSession(fs, repoRoot) {
         taskSlug: PROJECT_TRANSLATOR_SCOPE
     };
 }
+async function loadPersistedHarnessEngineerSession(fs, repoRoot) {
+    const sessionPath = resolveRepoPath(repoRoot, HARNESS_ENGINEER_SESSION_PATH);
+    if (!(await fs.pathExists(sessionPath))) {
+        return undefined;
+    }
+    const payload = await fs.readJson(sessionPath);
+    const record = normalizePersistedRoleRecord(isProjectRoleSessionFile(payload) ? payload.record : payload);
+    if (!record) {
+        return undefined;
+    }
+    return {
+        ...record,
+        taskSlug: PROJECT_HARNESS_ENGINEER_SCOPE
+    };
+}
 async function loadPersistedRoleRecord(fs, repoRoot, stateRoot, taskSlug, role) {
     const current = await loadPersistedTaskSessionRecord(fs, repoRoot, stateRoot, taskSlug);
     return normalizePersistedRoleRecord(current?.roles[role]?.record);
@@ -805,6 +1128,40 @@ function normalizePersistedRoleRecord(record) {
         }
         : undefined;
 }
+function normalizeProjectScopedRecordForPersistence(record) {
+    if (record.role === GATE_REVIEWER_ROLE) {
+        return {
+            ...record,
+            taskSlug: PROJECT_GATE_REVIEWER_SCOPE
+        };
+    }
+    if (record.role === TRANSLATOR_ROLE) {
+        return {
+            ...record,
+            taskSlug: PROJECT_TRANSLATOR_SCOPE
+        };
+    }
+    if (record.role === HARNESS_ENGINEER_ROLE) {
+        return {
+            ...record,
+            taskSlug: PROJECT_HARNESS_ENGINEER_SCOPE
+        };
+    }
+    return record;
+}
+function normalizeHarnessRevision(value) {
+    return typeof value === "number" && Number.isInteger(value) && value >= 0
+        ? value
+        : 0;
+}
+function buildHarnessRefreshPrompt(role) {
+    return [
+        "VCM harness was updated.",
+        "Before continuing, re-read the current project `CLAUDE.md`, your agent definition, and any relevant VCM skills from disk.",
+        `Your agent definition is \`.claude/agents/${role}.md\` when that file exists.`,
+        "Follow the latest rules from disk. Briefly acknowledge when ready."
+    ].join("\n");
+}
 async function persistTaskSession(fs, repoRoot, stateRoot, session) {
     const sessionPath = getTaskSessionPath(repoRoot, stateRoot, session.taskSlug);
     const empty = createEmptyTaskSessionRecord(session.taskSlug, session.updatedAt);
@@ -839,6 +1196,10 @@ async function persistRoleSessionRecord(fs, baseRepoRoot, taskRepoRoot, stateRoo
         await persistTranslatorSession(fs, baseRepoRoot, session);
         return;
     }
+    if (session.role === HARNESS_ENGINEER_ROLE) {
+        await persistHarnessEngineerSession(fs, baseRepoRoot, session);
+        return;
+    }
     await persistTaskSession(fs, taskRepoRoot, stateRoot, session);
 }
 async function persistProjectGateReviewerSession(fs, repoRoot, session) {
@@ -863,6 +1224,17 @@ async function persistTranslatorSession(fs, repoRoot, session) {
         }
     });
 }
+async function persistHarnessEngineerSession(fs, repoRoot, session) {
+    await fs.writeJsonAtomic(resolveRepoPath(repoRoot, HARNESS_ENGINEER_SESSION_PATH), {
+        version: 1,
+        role: session.role,
+        updatedAt: session.updatedAt,
+        record: {
+            ...session,
+            taskSlug: PROJECT_HARNESS_ENGINEER_SCOPE
+        }
+    });
+}
 function isProjectRoleSessionFile(value) {
     return "record" in value && typeof value.record === "object" && value.record !== null;
 }

package/dist/backend/templates/harness/harness-engineer-agent.js

@@ -0,0 +1,63 @@
+export function renderHarnessEngineerHarnessRules() {
+    return `## Role
+
+You are VCM \`harness-engineer\`: a project-scoped harness maintenance tool role.
+
+Maintain and improve this repository's VCM harness. Understand both VCM fixed
+harness rules and project-specific harness customization before proposing any
+change.
+
+## Scope
+
+You may inspect:
+
+- \`CLAUDE.md\`
+- \`.claude/agents/**\`
+- \`.claude/skills/**\`
+- \`.ai/tools/**\`
+- \`.ai/vcm-harness-manifest.json\`
+- \`.ai/generated/**\`
+- durable project docs such as \`docs/ARCHITECTURE.md\`, \`docs/TESTING.md\`,
+  and \`docs/known-issues.md\`
+
+Do not act as PM, Architect, Coder, Reviewer, Gate Reviewer, or Translator.
+You are not part of the task workflow round state.
+
+## Change Policy
+
+- Propose harness changes as reviewable diffs.
+- Do not silently apply edits.
+- Do not overwrite VCM fixed managed blocks.
+- Keep project-specific customization outside VCM managed blocks.
+- If a fixed managed block appears wrong, draft a VCM issue instead of editing
+  the block.
+- Include affected files, impacted roles, session restart/reminder impact, and
+  validation recommendations with every proposal.
+- Do not edit production source code as part of harness maintenance.
+
+## VCM Feedback
+
+If the issue is a VCM product, installer, UI, or fixed template problem, draft a
+GitHub issue for:
+
+\`https://github.com/CodingForMoney/VibeCodingMaster\`
+
+Issue drafts must include title, problem, reproduction, expected behavior,
+actual behavior, VCM version when known, affected harness/UI area, impact, and a
+suggested fix if known.
+
+Do not submit issues yourself. Do not include private source code, secrets,
+private logs, or unnecessary repository details. Summarize private context
+instead of copying it.
+
+## Output
+
+When asked to improve harness content, respond with:
+
+1. diagnosis
+2. proposed diff or issue draft
+3. affected roles/sessions
+4. validation steps
+5. whether the user should apply, revise, or discard
+`;
+}