vibe-coding-master 0.4.19 → 0.4.21

package/dist/backend/services/harness-feedback-service.js

@@ -1,4 +1,6 @@
+import { createHash } from "node:crypto";
 import path from "node:path";
+import { checkMarkdownArtifact } from "../../shared/validation/artifact-check.js";
 import { resolveRepoPath, toRepoRelativePath } from "../adapters/filesystem.js";
 import { VcmError } from "../errors.js";
 import { submitTerminalInput } from "../runtime/terminal-submit.js";
@@ -6,6 +8,7 @@ const FEEDBACK_ROOT = ".ai/vcm/harness-feedback";
 const PENDING_DIR = `${FEEDBACK_ROOT}/pending`;
 const ACTIVE_DIR = `${FEEDBACK_ROOT}/active`;
 const COMPLETED_DIR = `${FEEDBACK_ROOT}/completed`;
+const TASK_RETROSPECTIVE_DIR = `${FEEDBACK_ROOT}/task-retrospectives`;
 const STATE_PATH = `${FEEDBACK_ROOT}/state.json`;
 export function createHarnessFeedbackService(deps) {
     const now = deps.now ?? (() => new Date().toISOString());
@@ -13,6 +16,80 @@ export function createHarnessFeedbackService(deps) {
         await maybeDispatchNext(repoRoot, activeTaskSlug);
         return buildStateReport(repoRoot);
     }
+    async function startTaskRetrospective(repoRoot, input) {
+        const taskSlug = input.taskSlug.trim();
+        if (!taskSlug) {
+            throw new VcmError({
+                code: "HARNESS_TASK_REQUIRED",
+                message: "Select an active task before reviewing task harness.",
+                statusCode: 409
+            });
+        }
+        const state = await loadStoredState(repoRoot);
+        if (state) {
+            throw new VcmError({
+                code: "HARNESS_FEEDBACK_ACTIVE",
+                message: "Harness feedback is already active.",
+                statusCode: 409,
+                hint: "Review, approve, comment, or reject the current Harness feedback before starting Task Harness Retrospective."
+            });
+        }
+        const existingMarker = await loadTaskRetrospectiveMarker(repoRoot, taskSlug);
+        if (existingMarker) {
+            throw new VcmError({
+                code: "TASK_HARNESS_RETROSPECTIVE_EXISTS",
+                message: `Task Harness Retrospective has already been triggered for task: ${taskSlug}`,
+                statusCode: 409,
+                hint: "Review the existing Harness feedback item instead of starting another retrospective for the same task."
+            });
+        }
+        const finalAcceptancePath = path.posix.join(input.handoffDir, "final-acceptance.md");
+        const finalAcceptanceAbsolutePath = resolveRepoPath(input.taskRepoRoot, finalAcceptancePath);
+        const finalAcceptanceContent = await readAbsoluteOptionalText(finalAcceptanceAbsolutePath);
+        const finalAcceptanceCheck = checkMarkdownArtifact("final-acceptance", finalAcceptancePath, finalAcceptanceContent ?? null);
+        if (finalAcceptanceCheck.status !== "ok" || !finalAcceptanceContent) {
+            throw new VcmError({
+                code: "TASK_FINAL_ACCEPTANCE_NOT_READY",
+                message: "Task final acceptance is not complete yet.",
+                statusCode: 409,
+                hint: `${finalAcceptancePath} must pass the final-acceptance artifact check before Task Harness Retrospective can start.`
+            });
+        }
+        const session = await ensureIdleHarnessEngineer(repoRoot, taskSlug);
+        const timestamp = now();
+        const finalAcceptanceHash = `sha256:${sha256(finalAcceptanceContent)}`;
+        const id = sanitizeFeedbackId(`${timestamp}-task-retrospective-${taskSlug}`);
+        const feedbackPath = `${ACTIVE_DIR}/${id}/feedback.md`;
+        const analysisPath = `${ACTIVE_DIR}/${id}/analysis.md`;
+        const applyReportPath = `${ACTIVE_DIR}/${id}/apply-report.md`;
+        const active = {
+            id,
+            title: `Task Harness Retrospective: ${taskSlug}`,
+            path: feedbackPath,
+            source: "task-retrospective",
+            taskSlug,
+            summary: "Review the completed task workflow for reusable harness problems.",
+            trigger: input.trigger,
+            finalAcceptanceHash,
+            feedbackPath,
+            analysisPath,
+            applyReportPath,
+            startedAt: timestamp,
+            updatedAt: timestamp,
+            lastPromptAt: timestamp
+        };
+        const nextState = {
+            version: 1,
+            status: "analyzing",
+            active
+        };
+        await deps.fs.ensureDir(resolveRepoPath(repoRoot, path.posix.dirname(feedbackPath)));
+        await deps.fs.writeText(resolveRepoPath(repoRoot, feedbackPath), renderTaskRetrospectiveFeedback(active, finalAcceptancePath));
+        await persistStoredState(repoRoot, nextState);
+        await persistTaskRetrospectiveMarker(repoRoot, active, "analyzing");
+        await submitTerminalInput(deps.runtime, session.id, buildTaskRetrospectivePrompt(repoRoot, active));
+        return buildStateReport(repoRoot);
+    }
     async function decide(repoRoot, input) {
         const state = await loadStoredState(repoRoot);
         if (!state || state.status !== "awaiting_user_approval") {
@@ -48,6 +125,7 @@ export function createHarnessFeedbackService(deps) {
                 }
             };
             await persistStoredState(repoRoot, nextState);
+            await persistTaskRetrospectiveMarker(repoRoot, nextState.active, "analyzing");
             await submitTerminalInput(deps.runtime, session.id, buildFeedbackCommentPrompt(repoRoot, nextState.active, input.comment ?? ""));
             return buildStateReport(repoRoot);
         }
@@ -63,6 +141,7 @@ export function createHarnessFeedbackService(deps) {
             }
         };
         await persistStoredState(repoRoot, nextState);
+        await persistTaskRetrospectiveMarker(repoRoot, nextState.active, "applying");
         await submitTerminalInput(deps.runtime, session.id, buildFeedbackApplyPrompt(repoRoot, nextState.active, input.comment ?? ""));
         return buildStateReport(repoRoot);
     }
@@ -76,14 +155,16 @@ export function createHarnessFeedbackService(deps) {
         }
         const timestamp = now();
         if (state.status === "analyzing") {
-            await persistStoredState(repoRoot, {
+            const nextState = {
                 ...state,
                 status: "awaiting_user_approval",
                 active: {
                     ...state.active,
                     updatedAt: timestamp
                 }
-            });
+            };
+            await persistStoredState(repoRoot, nextState);
+            await persistTaskRetrospectiveMarker(repoRoot, nextState.active, "awaiting_user_approval", timestamp);
             return;
         }
         if (state.status === "applying") {
@@ -132,6 +213,7 @@ export function createHarnessFeedbackService(deps) {
         const active = {
             ...next,
             feedbackPath: next.path,
+            source: next.source ?? "role-feedback",
             analysisPath,
             applyReportPath,
             startedAt: timestamp,
@@ -209,12 +291,15 @@ export function createHarnessFeedbackService(deps) {
             id: state.active.id,
             title: state.active.title,
             path: state.active.path,
+            source: state.active.source,
             reporterRole: state.active.reporterRole,
             taskSlug: state.active.taskSlug,
             summary: state.active.summary,
             status: state.status,
             startedAt: state.active.startedAt,
             updatedAt: state.active.updatedAt,
+            trigger: state.active.trigger,
+            finalAcceptanceHash: state.active.finalAcceptanceHash,
             feedbackContent,
             analysisPath: state.active.analysisPath,
             analysisContent,
@@ -249,6 +334,7 @@ export function createHarnessFeedbackService(deps) {
             id,
             title: compactLine(title),
             path: relativePath,
+            source: "role-feedback",
             reporterRole: metadata["reporter role"] ?? metadata.reporter,
             taskSlug: metadata["task slug"] ?? metadata.task,
             summary: metadata.summary
@@ -278,6 +364,16 @@ export function createHarnessFeedbackService(deps) {
             "</HARNESS_FEEDBACK>"
         ].join("\n");
     }
+    function buildTaskRetrospectivePrompt(repoRoot, active) {
+        return [
+            "[VCM Task Harness Retrospective]",
+            "",
+            "Review the completed task from the current active task worktree.",
+            "",
+            `Write the analysis to Result Path: ${resolveRepoPath(repoRoot, active.analysisPath)}`,
+            "End your turn after writing the result."
+        ].join("\n");
+    }
     function buildFeedbackCommentPrompt(repoRoot, active, comment) {
         return [
             "[VCM Harness Feedback Revision]",
@@ -345,6 +441,7 @@ export function createHarnessFeedbackService(deps) {
             comment,
             completedAt: now()
         });
+        await persistTaskRetrospectiveMarker(repoRoot, state.active, outcome === "rejected" ? "rejected" : "completed");
         await deps.fs.removePath?.(resolveRepoPath(repoRoot, state.active.feedbackPath), { force: true });
         await deps.fs.removePath?.(resolveRepoPath(repoRoot, path.posix.dirname(state.active.analysisPath)), { recursive: true, force: true });
     }
@@ -357,6 +454,7 @@ export function createHarnessFeedbackService(deps) {
         if (state?.version !== 1 || !state.active?.id || !state.status) {
             return undefined;
         }
+        state.active.source = state.active.source ?? "role-feedback";
         return state;
     }
     async function persistStoredState(repoRoot, state) {
@@ -372,8 +470,38 @@ export function createHarnessFeedbackService(deps) {
         }
         return deps.fs.readText(absolutePath);
     }
+    async function readAbsoluteOptionalText(absolutePath) {
+        if (!(await deps.fs.pathExists(absolutePath))) {
+            return undefined;
+        }
+        return deps.fs.readText(absolutePath);
+    }
+    async function loadTaskRetrospectiveMarker(repoRoot, taskSlug) {
+        const markerPath = resolveRepoPath(repoRoot, getTaskRetrospectiveMarkerPath(taskSlug));
+        if (!(await deps.fs.pathExists(markerPath))) {
+            return undefined;
+        }
+        return deps.fs.readJson(markerPath);
+    }
+    async function persistTaskRetrospectiveMarker(repoRoot, active, status, timestamp = now()) {
+        if (active.source !== "task-retrospective" || !active.taskSlug) {
+            return;
+        }
+        await deps.fs.writeJsonAtomic(resolveRepoPath(repoRoot, getTaskRetrospectiveMarkerPath(active.taskSlug)), {
+            version: 1,
+            taskSlug: active.taskSlug,
+            activeId: active.id,
+            trigger: active.trigger ?? "manual",
+            status,
+            finalAcceptanceHash: active.finalAcceptanceHash,
+            createdAt: active.startedAt,
+            updatedAt: timestamp,
+            ...(status === "completed" || status === "rejected" ? { completedAt: timestamp } : {})
+        });
+    }
     return {
         getState,
+        startTaskRetrospective,
         decide,
         recordHarnessEngineerHook,
         assertHarnessEngineerAvailable
@@ -397,10 +525,29 @@ function firstHeading(content) {
 function compactLine(value) {
     return value.replace(/\s+/g, " ").trim().slice(0, 160);
 }
+function renderTaskRetrospectiveFeedback(active, finalAcceptancePath) {
+    return [
+        `# ${active.title}`,
+        "",
+        `Source: ${active.source}`,
+        `Task slug: ${active.taskSlug ?? ""}`,
+        `Trigger: ${active.trigger ?? "manual"}`,
+        `Final acceptance: ${finalAcceptancePath}`,
+        `Final acceptance hash: ${active.finalAcceptanceHash ?? ""}`,
+        "",
+        "Summary: Review the completed task workflow for reusable harness problems."
+    ].join("\n");
+}
+function getTaskRetrospectiveMarkerPath(taskSlug) {
+    return `${TASK_RETROSPECTIVE_DIR}/${sanitizeFeedbackId(taskSlug)}.json`;
+}
 function sanitizeFeedbackId(value) {
     const sanitized = value.replace(/[^A-Za-z0-9._-]/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
     return sanitized || "feedback";
 }
+function sha256(content) {
+    return createHash("sha256").update(content).digest("hex");
+}
 export function getHarnessFeedbackRelativePath(repoRoot, absolutePath) {
     return toRepoRelativePath(repoRoot, absolutePath);
 }

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

@@ -21,6 +21,7 @@ import { bumpHarnessRevision, readHarnessRevisionState } from "./harness-revisio
 const execFileAsync = promisify(execFile);
 const BOOTSTRAP_SESSION_PATH = ".ai/vcm/bootstrap/session.json";
 const HARNESS_ENGINEER_SESSION_PATH = ".ai/vcm/harness-engineer/session.json";
+const MANIFEST_PATH = ".ai/vcm-harness-manifest.json";
 export const VCM_HARNESS_VERSION = 1;
 const MANAGED_BLOCK_PATTERN = /<!-- VCM:BEGIN(?:\s+version=(\d+))? -->[\s\S]*?<!-- VCM:END -->/m;
 const HASH_MANAGED_BLOCK_PATTERN = /# VCM:BEGIN(?:\s+version=(\d+))?\n[\s\S]*?# VCM:END/m;
@@ -173,11 +174,15 @@ const HARNESS_FILES = [
 ];
 export function createHarnessService(deps) {
     const now = deps.now ?? (() => new Date().toISOString());
+    const vcmVersion = deps.vcmVersion ?? "unknown";
     return {
         async getHarnessStatus(repoRoot) {
             const analyses = await analyzeHarnessFiles(deps.fs, repoRoot);
             const legacyChanges = await analyzeLegacyCodexHarnessPaths(deps.fs, repoRoot);
-            return renderHarnessStatus(await readHarnessRevisionValue(deps.fs, repoRoot), analyses, legacyChanges);
+            const manifestChange = deps.runFixedInstaller
+                ? await analyzeHarnessManifest(deps.fs, repoRoot, vcmVersion)
+                : undefined;
+            return renderHarnessStatus(await readHarnessRevisionValue(deps.fs, repoRoot), analyses, legacyChanges, manifestChange);
         },
         async getHarnessFileContent(repoRoot, filePath) {
             return readHarnessFileContent(deps.fs, repoRoot, filePath);
@@ -208,9 +213,12 @@ export function createHarnessService(deps) {
             const file = await readHarnessFileContent(deps.fs, repoRoot, definition.path);
             const analyses = await analyzeHarnessFiles(deps.fs, repoRoot);
             const legacyChanges = await analyzeLegacyCodexHarnessPaths(deps.fs, repoRoot);
+            const manifestChange = deps.runFixedInstaller
+                ? await analyzeHarnessManifest(deps.fs, repoRoot, vcmVersion)
+                : undefined;
             return {
                 file,
-                status: renderHarnessStatus(await readHarnessRevisionValue(deps.fs, repoRoot), analyses, legacyChanges),
+                status: renderHarnessStatus(await readHarnessRevisionValue(deps.fs, repoRoot), analyses, legacyChanges, manifestChange),
                 harnessCommit
             };
         },
@@ -258,12 +266,15 @@ export function createHarnessService(deps) {
         async getRepositoryDiff(repoRoot, input = {}) {
             return getRepositoryDiffReport(requireRepositoryDiffGit(deps.git), repoRoot, input, now());
         },
+        async mergeRepositoryDiffToCurrentBranch(baseRepoRoot, input) {
+            return mergeRepositoryDiffToCurrentBranch(requireRepositoryMergeGit(deps.git), baseRepoRoot, input, now());
+        },
         async getBootstrapStatus(repoRoot, targetRepoRoot = repoRoot) {
-            return getHarnessBootstrapStatus(deps, repoRoot, targetRepoRoot, now);
+            return getHarnessBootstrapStatus(deps, repoRoot, targetRepoRoot, now, vcmVersion);
         },
         async startHarnessBootstrap(repoRoot, targetRepoRoot = repoRoot, input = {}) {
-            const session = await ensureHarnessEngineerForBootstrap(deps, repoRoot, targetRepoRoot, now, input);
-            const nextStatus = await getHarnessBootstrapStatus(deps, repoRoot, targetRepoRoot, now);
+            const session = await ensureHarnessEngineerForBootstrap(deps, repoRoot, targetRepoRoot, now, vcmVersion, input);
+            const nextStatus = await getHarnessBootstrapStatus(deps, repoRoot, targetRepoRoot, now, vcmVersion);
             return {
                 status: {
                     ...nextStatus,
@@ -274,8 +285,8 @@ export function createHarnessService(deps) {
             };
         },
         async restartHarnessBootstrap(repoRoot, targetRepoRoot = repoRoot, input = {}) {
-            const session = await restartHarnessEngineerForBootstrap(deps, repoRoot, targetRepoRoot, now, input);
-            const nextStatus = await getHarnessBootstrapStatus(deps, repoRoot, targetRepoRoot, now);
+            const session = await restartHarnessEngineerForBootstrap(deps, repoRoot, targetRepoRoot, now, vcmVersion, input);
+            const nextStatus = await getHarnessBootstrapStatus(deps, repoRoot, targetRepoRoot, now, vcmVersion);
             return {
                 status: {
                     ...nextStatus,
@@ -296,7 +307,7 @@ export function createHarnessService(deps) {
             }
             await deps.harnessEngineerSessions?.stopProjectHarnessEngineerSession(repoRoot);
             await clearHarnessBootstrapRunState(deps.fs, repoRoot);
-            return getHarnessBootstrapStatus(deps, repoRoot, repoRoot, now);
+            return getHarnessBootstrapStatus(deps, repoRoot, repoRoot, now, vcmVersion);
         },
         async runHarnessBootstrap(repoRoot, targetRepoRoot = repoRoot) {
             if (!deps.runtime || !deps.harnessEngineerSessions) {
@@ -307,7 +318,7 @@ export function createHarnessService(deps) {
                 });
             }
             await assertHarnessWorktreeClean(deps.git, targetRepoRoot);
-            const status = await getHarnessBootstrapStatus(deps, repoRoot, targetRepoRoot, now);
+            const status = await getHarnessBootstrapStatus(deps, repoRoot, targetRepoRoot, now, vcmVersion);
             const session = status.session;
             if (!session || session.status !== "running" || !deps.runtime.getSession(session.id)) {
                 throw new VcmError({
@@ -328,7 +339,7 @@ export function createHarnessService(deps) {
                 updatedAt: timestamp
             });
             await submitTerminalInput(deps.runtime, session.id, prompt);
-            const nextStatus = await getHarnessBootstrapStatus(deps, repoRoot, targetRepoRoot, now);
+            const nextStatus = await getHarnessBootstrapStatus(deps, repoRoot, targetRepoRoot, now, vcmVersion);
             return {
                 status: {
                     ...nextStatus,
@@ -342,7 +353,7 @@ export function createHarnessService(deps) {
         async recordHarnessBootstrapHook(repoRoot, input) {
             const state = await loadPersistedHarnessBootstrapRunState(deps.fs, repoRoot);
             if (state?.status !== "running" || !matchesBootstrapRunState(state, input)) {
-                return getHarnessBootstrapStatus(deps, repoRoot, state?.targetRepoRoot ?? repoRoot, now);
+                return getHarnessBootstrapStatus(deps, repoRoot, state?.targetRepoRoot ?? repoRoot, now, vcmVersion);
             }
             const timestamp = now();
             if (input.eventName === "Stop" && state.targetRepoRoot) {
@@ -355,11 +366,11 @@ export function createHarnessService(deps) {
                 updatedAt: timestamp,
                 lastHookEvent: input.eventName
             });
-            return getHarnessBootstrapStatus(deps, repoRoot, state.targetRepoRoot ?? repoRoot, now);
+            return getHarnessBootstrapStatus(deps, repoRoot, state.targetRepoRoot ?? repoRoot, now, vcmVersion);
         }
     };
 }
-async function ensureHarnessEngineerForBootstrap(deps, repoRoot, targetRepoRoot, now, input) {
+async function ensureHarnessEngineerForBootstrap(deps, repoRoot, targetRepoRoot, now, vcmVersion, input) {
     if (!deps.harnessEngineerSessions) {
         throw new VcmError({
             code: "HARNESS_BOOTSTRAP_UNAVAILABLE",
@@ -367,7 +378,7 @@ async function ensureHarnessEngineerForBootstrap(deps, repoRoot, targetRepoRoot,
             statusCode: 501
         });
     }
-    const currentStatus = await getHarnessBootstrapStatus(deps, repoRoot, targetRepoRoot, now);
+    const currentStatus = await getHarnessBootstrapStatus(deps, repoRoot, targetRepoRoot, now, vcmVersion);
     if (currentStatus.session?.status === "running") {
         return currentStatus.session;
     }
@@ -380,7 +391,7 @@ async function ensureHarnessEngineerForBootstrap(deps, repoRoot, targetRepoRoot,
     }
     return toHarnessBootstrapSession(await deps.harnessEngineerSessions.ensureProjectHarnessEngineerSession(repoRoot, input));
 }
-async function restartHarnessEngineerForBootstrap(deps, repoRoot, targetRepoRoot, now, input) {
+async function restartHarnessEngineerForBootstrap(deps, repoRoot, targetRepoRoot, now, vcmVersion, input) {
     if (!deps.harnessEngineerSessions) {
         throw new VcmError({
             code: "HARNESS_BOOTSTRAP_UNAVAILABLE",
@@ -388,7 +399,7 @@ async function restartHarnessEngineerForBootstrap(deps, repoRoot, targetRepoRoot
             statusCode: 501
         });
     }
-    const currentStatus = await getHarnessBootstrapStatus(deps, repoRoot, targetRepoRoot, now);
+    const currentStatus = await getHarnessBootstrapStatus(deps, repoRoot, targetRepoRoot, now, vcmVersion);
     if (!currentStatus.canStart) {
         throw new VcmError({
             code: "HARNESS_BOOTSTRAP_NOT_READY",
@@ -454,6 +465,7 @@ function requireRepositoryDiffGit(git) {
     if (!git?.getCommitDiff ||
         !git.getCommitInfo ||
         !git.getCommitList ||
+        !git.getCurrentBranch ||
         !git.getHeadCommit ||
         !git.getMergeBase) {
         throw new VcmError({
@@ -464,7 +476,22 @@ function requireRepositoryDiffGit(git) {
     }
     return git;
 }
+function requireRepositoryMergeGit(git) {
+    if (!git?.branchExists ||
+        !git.getCurrentBranch ||
+        !git.getHeadCommit ||
+        !git.mergeBranchFastForward) {
+        throw new VcmError({
+            code: "HARNESS_GIT_UNAVAILABLE",
+            message: "Git-backed repository merge is not available in this VCM runtime.",
+            statusCode: 501
+        });
+    }
+    return git;
+}
 async function getRepositoryDiffReport(git, repoRoot, input, generatedAt) {
+    const sourceBranch = await git.getCurrentBranch(repoRoot);
+    const targetBranch = input.baseRepoRoot ? await git.getCurrentBranch(input.baseRepoRoot) : sourceBranch;
     const baseRef = input.baseRepoRoot
         ? await git.getHeadCommit(input.baseRepoRoot)
         : "HEAD^";
@@ -476,6 +503,8 @@ async function getRepositoryDiffReport(git, repoRoot, input, generatedAt) {
         return {
             version: 1,
             repoRoot,
+            sourceBranch,
+            targetBranch,
             generatedAt,
             commits,
             summary: createEmptyRepositoryDiffSummary(),
@@ -497,6 +526,8 @@ async function getRepositoryDiffReport(git, repoRoot, input, generatedAt) {
     return {
         version: 1,
         repoRoot,
+        sourceBranch,
+        targetBranch,
         generatedAt,
         commits,
         commit: {
@@ -522,6 +553,71 @@ async function getRepositoryDiffReport(git, repoRoot, input, generatedAt) {
         warnings
     };
 }
+async function mergeRepositoryDiffToCurrentBranch(git, baseRepoRoot, input, mergedAt) {
+    const taskBranch = input.taskBranch.trim();
+    if (!taskBranch) {
+        throw new VcmError({
+            code: "HARNESS_MERGE_SOURCE_BRANCH_MISSING",
+            message: "Task branch is missing.",
+            statusCode: 400
+        });
+    }
+    if (!(await git.branchExists(baseRepoRoot, taskBranch))) {
+        throw new VcmError({
+            code: "HARNESS_MERGE_SOURCE_BRANCH_MISSING",
+            message: `Task branch does not exist locally: ${taskBranch}`,
+            statusCode: 409,
+            hint: "Create or restore the task branch before merging it into the connected repository branch."
+        });
+    }
+    const targetBranch = await git.getCurrentBranch(baseRepoRoot);
+    if (targetBranch === "detached") {
+        throw new VcmError({
+            code: "HARNESS_MERGE_BASE_DETACHED",
+            message: "The connected repository is in detached HEAD state.",
+            statusCode: 409,
+            hint: "Checkout the intended target branch in the connected repository before merging the task branch."
+        });
+    }
+    if (taskBranch === targetBranch) {
+        throw new VcmError({
+            code: "HARNESS_MERGE_BRANCH_INVALID",
+            message: "Task branch is already the connected repository branch.",
+            statusCode: 409,
+            hint: `Source and target are both ${targetBranch}.`
+        });
+    }
+    await assertVisibleWorktreeClean(git, input.taskRepoRoot, "The active task worktree", "HARNESS_MERGE_TASK_DIRTY");
+    await assertVisibleWorktreeClean(git, baseRepoRoot, "The connected repository", "HARNESS_MERGE_BASE_DIRTY");
+    const beforeSha = await git.getHeadCommit(baseRepoRoot);
+    const mergeResult = await git.mergeBranchFastForward(baseRepoRoot, taskBranch);
+    const afterSha = await git.getHeadCommit(baseRepoRoot);
+    return {
+        version: 1,
+        baseRepoRoot,
+        taskRepoRoot: input.taskRepoRoot,
+        sourceBranch: taskBranch,
+        targetBranch,
+        beforeSha,
+        afterSha,
+        changed: beforeSha !== afterSha,
+        stdout: mergeResult.stdout,
+        stderr: mergeResult.stderr,
+        mergedAt
+    };
+}
+async function assertVisibleWorktreeClean(git, repoRoot, label, code) {
+    const entries = await getVisibleGitStatusEntries(git, repoRoot);
+    if (entries.length === 0) {
+        return;
+    }
+    throw new VcmError({
+        code,
+        message: `${label} has uncommitted Git-visible changes.`,
+        statusCode: 409,
+        hint: `Commit or revert these files before merging to main: ${entries.map((entry) => entry.path).slice(0, 12).join(", ")}`
+    });
+}
 function toRepositoryDiffCommit(commit) {
     return {
         sha: commit.sha,
@@ -987,12 +1083,13 @@ async function removeLegacyCodexHarnessPaths(fs, repoRoot) {
     }
     return changes;
 }
-function renderHarnessStatus(harnessRevision, analyses, legacyChanges = []) {
+function renderHarnessStatus(harnessRevision, analyses, legacyChanges = [], manifestChange) {
     const files = analyses.map((analysis) => analysis.status);
     const plannedChanges = analyses
         .map((analysis) => analysis.plannedChange)
         .filter((change) => Boolean(change))
-        .concat(legacyChanges);
+        .concat(legacyChanges)
+        .concat(manifestChange ? [manifestChange] : []);
     // Derive `initialized`: the VCM harness is considered installed when at least one
     // VCM-exclusive marker is present (per analysis):
     //   - status.hasManagedBlock === true (a managed block already lives in the file), OR
@@ -1165,10 +1262,40 @@ function resolveHarnessPath(repoRoot, relativePath) {
 function ensureTrailingNewline(content) {
     return content.endsWith("\n") ? content : `${content}\n`;
 }
-async function getHarnessBootstrapStatus(deps, repoRoot, targetRepoRoot, now) {
+async function analyzeHarnessManifest(fs, repoRoot, vcmVersion) {
+    if (!vcmVersion || vcmVersion === "unknown") {
+        return undefined;
+    }
+    const manifestPath = resolveHarnessPath(repoRoot, MANIFEST_PATH);
+    if (!await fs.pathExists(manifestPath)) {
+        return {
+            path: MANIFEST_PATH,
+            action: "create",
+            reason: `VCM fixed harness manifest is missing; current VCM version is ${vcmVersion}.`
+        };
+    }
+    const manifest = await readOptionalJsonObject(fs, repoRoot, MANIFEST_PATH);
+    const installedVersion = typeof manifest?.harnessVersion === "string" ? manifest.harnessVersion : undefined;
+    if (!manifest || manifest.manager !== "vcm" || manifest.schemaVersion !== 1) {
+        return {
+            path: MANIFEST_PATH,
+            action: "update",
+            reason: "VCM fixed harness manifest metadata is invalid."
+        };
+    }
+    if (installedVersion !== vcmVersion) {
+        return {
+            path: MANIFEST_PATH,
+            action: "update",
+            reason: `VCM fixed harness manifest version is ${installedVersion ?? "missing"}; current VCM version is ${vcmVersion}.`
+        };
+    }
+    return undefined;
+}
+async function getHarnessBootstrapStatus(deps, repoRoot, targetRepoRoot, now, vcmVersion) {
     const moduleIndex = await readOptionalJsonObject(deps.fs, targetRepoRoot, ".ai/generated/module-index.json");
     const checks = [
-        await checkFixedHarness(deps.fs, targetRepoRoot),
+        await checkFixedHarness(deps.fs, targetRepoRoot, vcmVersion),
         await checkProjectContext(deps.fs, targetRepoRoot),
         checkGeneratedJson(moduleIndex, ".ai/generated/module-index.json", "module-index", "Module index"),
         checkGeneratedJson(await readOptionalJsonObject(deps.fs, targetRepoRoot, ".ai/generated/public-surface.json"), ".ai/generated/public-surface.json", "public-surface", "Public surface"),
@@ -1200,10 +1327,10 @@ async function getHarnessBootstrapStatus(deps, repoRoot, targetRepoRoot, now) {
         warnings: bootstrapWarnings(status, checks, session, runState)
     };
 }
-async function checkFixedHarness(fs, repoRoot) {
+async function checkFixedHarness(fs, repoRoot, vcmVersion) {
     const requiredPaths = [
         "CLAUDE.md",
-        ".ai/vcm-harness-manifest.json",
+        MANIFEST_PATH,
         ".claude/skills/vcm-harness-bootstrap/SKILL.md",
         ".ai/tools/generate-module-index",
         ".ai/tools/generate-public-surface"
@@ -1232,6 +1359,16 @@ async function checkFixedHarness(fs, repoRoot) {
             detail: "CLAUDE.md is missing the VCM managed block."
         };
     }
+    const manifestChange = await analyzeHarnessManifest(fs, repoRoot, vcmVersion);
+    if (manifestChange) {
+        return {
+            key: "fixed-harness",
+            label: "Fixed harness",
+            status: "incomplete",
+            path: MANIFEST_PATH,
+            detail: manifestChange.reason
+        };
+    }
     return {
         key: "fixed-harness",
         label: "Fixed harness",