vibe-coding-master 0.9.6 → 0.9.8

package/README.md

@@ -17,12 +17,30 @@ orchestration, translation, harness setup, and mobile gateway control.
 
 ## Requirements
 
-- Node.js 20 LTS or 22+
+- Node.js 20 LTS or 22+, with `node` on the `PATH` VCM starts with (role hooks
+  and `.ai/tools` scripts run with it)
 - npm
-- Git
+- Git 2.22 or newer
+- `sh` and `curl` (role hooks report Claude Code events to VCM through them)
+- Non-interactive credentials for the repository's upstream remote (an SSH key
+  in ssh-agent or a Git credential helper). Creating a task pulls the upstream
+  branch, and VCM runs Git without credential prompts.
+- Optional: GitHub CLI (`gh`). VCM never runs it, but when it is installed and
+  logged out VCM warns, because roles that use it will fail.
 - Claude Code installed and available as `claude` (verified with 2.1.310 or
   newer; VCM shows a Repository warning when an older release is detected)
 - Claude Code authenticated in the same environment where VCM runs
+- A Git commit identity (`user.name` and `user.email`) in the same environment.
+  When either is missing, VCM and its roles commit as `VCM <vcm@localhost>`
+  and the Repository panel shows a warning; VCM never changes your Git config.
+
+VCM checks these programs at startup, runs a hook self-test that sends one
+request through the installed hook pipeline, and checks access to the upstream
+remote when a repository connects. Any problem appears in the startup log and
+the Repository warnings, and the Repository header shows how many there are
+while the section is collapsed; none of them stops VCM from running. Role sessions
+add the VCM host to `NO_PROXY`, so an `http_proxy` setting does not capture
+their hook requests.
 
 For Linux containers, make sure common native build/runtime tools are available:
 

package/dist/backend/adapters/command-runner.js

@@ -10,10 +10,15 @@ export function createCommandRunner() {
                     input: options.input,
                     reject: false
                 });
+                // A command that could not start, timed out, or died from a signal has
+                // no exit code; it failed, so it must not read as a clean exit.
+                const exitCode = result.exitCode ?? (result.failed ? 1 : 0);
                 return {
                     stdout: result.stdout,
-                    stderr: result.stderr,
-                    exitCode: result.exitCode ?? 0
+                    stderr: result.exitCode === undefined && result.failed
+                        ? [result.stderr, result.shortMessage].filter(Boolean).join("\n")
+                        : result.stderr,
+                    exitCode
                 };
             }
             catch (error) {

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

@@ -1,7 +1,24 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { VcmError } from "../errors.js";
+// Network Git commands run without a terminal prompt: VCM is driven from the
+// browser, so a credential prompt would hang the request on the terminal that
+// started VCM instead of failing with an error the UI can show.
+const REMOTE_COMMAND_TIMEOUT_MS = 20 * 1000;
+const PULL_TIMEOUT_MS = 5 * 60 * 1000;
+// Commit identity used when neither Git config nor the environment provides one.
+// Without it, Git either refuses to commit or invents an identity from the OS
+// account and hostname, which silently attributes commits to a machine name.
+export const DEFAULT_GIT_IDENTITY = { name: "VCM", email: "vcm@localhost" };
+const GIT_IDENTITY_CACHE_TTL_MS = 30 * 1000;
+export function renderGitIdentityWarning(location, identity) {
+    const missing = identity.defaulted.map((part) => `user.${part}`).join(" and ");
+    return `Git ${missing} is not configured for ${location}, so VCM and role commits use ${identity.name} <${identity.email}>. `
+        + "Set your own identity in the environment that runs VCM: "
+        + "git config --global user.name \"<name>\" and git config --global user.email \"<email>\".";
+}
 export function createGitAdapter(runner) {
+    const identityCache = new Map();
     return {
         async checkRepo(repoRoot) {
             return checkGitMarker(repoRoot);
@@ -303,7 +320,7 @@ export function createGitAdapter(runner) {
             }
         },
         async commit(repoRoot, message) {
-            const result = await runGit(runner, repoRoot, ["commit", "-m", message]);
+            const result = await runGit(runner, repoRoot, ["commit", "-m", message], (await this.resolveCommitIdentity(repoRoot)).env);
             if (result.exitCode !== 0) {
                 throw new VcmError({
                     code: "GIT_COMMIT_FAILED",
@@ -318,7 +335,7 @@ export function createGitAdapter(runner) {
             if (paths.length === 0) {
                 return this.getHeadCommit(repoRoot);
             }
-            const result = await runGit(runner, repoRoot, ["commit", "--only", "-m", message, "--", ...paths]);
+            const result = await runGit(runner, repoRoot, ["commit", "--only", "-m", message, "--", ...paths], (await this.resolveCommitIdentity(repoRoot)).env);
             if (result.exitCode !== 0) {
                 throw new VcmError({
                     code: "GIT_COMMIT_FAILED",
@@ -329,6 +346,29 @@ export function createGitAdapter(runner) {
             }
             return this.getHeadCommit(repoRoot);
         },
+        async resolveCommitIdentity(repoRoot) {
+            const cached = identityCache.get(repoRoot);
+            if (cached && Date.now() - cached.checkedAt < GIT_IDENTITY_CACHE_TTL_MS) {
+                return cached.identity;
+            }
+            const identity = { name: "", email: "", defaulted: [], env: {} };
+            for (const part of ["name", "email"]) {
+                const result = await runGit(runner, repoRoot, ["config", "--get", `user.${part}`]);
+                const configured = result.exitCode === 0 ? result.stdout.trim() : "";
+                const variables = [`GIT_AUTHOR_${part.toUpperCase()}`, `GIT_COMMITTER_${part.toUpperCase()}`];
+                for (const variable of variables) {
+                    if (!configured && !process.env[variable]) {
+                        identity.env[variable] = DEFAULT_GIT_IDENTITY[part];
+                    }
+                }
+                if (variables.some((variable) => identity.env[variable])) {
+                    identity.defaulted.push(part);
+                }
+                identity[part] = process.env[variables[0]] || configured || DEFAULT_GIT_IDENTITY[part];
+            }
+            identityCache.set(repoRoot, { checkedAt: Date.now(), identity });
+            return identity;
+        },
         async createWorktree(input) {
             const result = await runGit(runner, input.repoRoot, [
                 "worktree",
@@ -375,7 +415,7 @@ export function createGitAdapter(runner) {
             }
         },
         async pullFastForward(repoRoot) {
-            const result = await runGit(runner, repoRoot, ["pull", "--ff-only"]);
+            const result = await runGit(runner, repoRoot, ["pull", "--ff-only"], await buildNonInteractiveGitEnv(runner, repoRoot), PULL_TIMEOUT_MS);
             if (result.exitCode !== 0) {
                 throw new VcmError({
                     code: "GIT_PULL_FAILED",
@@ -388,9 +428,47 @@ export function createGitAdapter(runner) {
                 stdout: result.stdout,
                 stderr: result.stderr
             };
+        },
+        async checkRemoteAccess(repoRoot) {
+            const branch = (await runGit(runner, repoRoot, ["branch", "--show-current"])).stdout.trim();
+            if (!branch) {
+                return { status: "skipped" };
+            }
+            const remoteResult = await runGit(runner, repoRoot, ["config", "--get", `branch.${branch}.remote`]);
+            const remote = remoteResult.stdout.trim();
+            if (remoteResult.exitCode !== 0 || !remote || remote === ".") {
+                return { status: "skipped" };
+            }
+            const result = await runGit(runner, repoRoot, ["ls-remote", remote, "HEAD"], await buildNonInteractiveGitEnv(runner, repoRoot), REMOTE_COMMAND_TIMEOUT_MS);
+            if (result.exitCode === 0) {
+                return { status: "ok", remote };
+            }
+            return {
+                status: "failed",
+                remote,
+                detail: firstMeaningfulLine(result.stderr) || firstMeaningfulLine(result.stdout) || `git ls-remote exited with ${result.exitCode}`
+            };
         }
     };
 }
+async function buildNonInteractiveGitEnv(runner, repoRoot) {
+    const env = {
+        GIT_TERMINAL_PROMPT: "0",
+        GCM_INTERACTIVE: "never"
+    };
+    // Keep a configured SSH command; otherwise make ssh fail instead of asking
+    // for a passphrase or host-key confirmation.
+    if (!process.env.GIT_SSH_COMMAND && !process.env.GIT_SSH) {
+        const configured = await runGit(runner, repoRoot, ["config", "--get", "core.sshCommand"]);
+        if (configured.exitCode !== 0 || !configured.stdout.trim()) {
+            env.GIT_SSH_COMMAND = "ssh -o BatchMode=yes";
+        }
+    }
+    return { ...process.env, ...env };
+}
+function firstMeaningfulLine(value) {
+    return value.split(/\r?\n/).map((line) => line.trim()).find(Boolean) ?? "";
+}
 async function checkGitMarker(repoRoot) {
     const markerPath = path.join(repoRoot, ".git");
     try {
@@ -449,8 +527,8 @@ async function pathExists(targetPath) {
         return false;
     }
 }
-async function runGit(runner, repoRoot, args) {
-    return runner.run("git", [...await buildSafeDirectoryArgs(repoRoot), ...args], { cwd: repoRoot });
+async function runGit(runner, repoRoot, args, env, timeoutMs) {
+    return runner.run("git", [...await buildSafeDirectoryArgs(repoRoot), ...args], { cwd: repoRoot, env, timeoutMs });
 }
 function parseWorktreePaths(output) {
     return output

package/dist/backend/api/claude-hook-routes.js

@@ -1,4 +1,9 @@
+import { VCM_HOOK_PROBE_PATH } from "../services/harness-service.js";
 export function registerClaudeHookRoutes(app, deps) {
+    // The hook self-test posts here through the installed hook pipeline.
+    app.post(VCM_HOOK_PROBE_PATH, async (request) => {
+        return { received: deps.environmentCheck?.receiveHookProbe(request.body?.runtimeSessionToken) ?? false };
+    });
     app.post("/api/hooks/claude-code", async (request) => {
         return deps.claudeHookService.handleHook(request.body);
     });

package/dist/backend/server.js

@@ -1,3 +1,4 @@
+import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import Fastify from "fastify";
@@ -10,7 +11,8 @@ import { createCommandRunner } from "./adapters/command-runner.js";
 import { createCommandDispatcher } from "./services/command-dispatcher.js";
 import { createClaudeHookService } from "./services/claude-hook-service.js";
 import { createClaudeVersionCheck } from "./services/claude-version-check.js";
-import { createGitAdapter } from "./adapters/git-adapter.js";
+import { createEnvironmentCheck } from "./services/environment-check.js";
+import { createGitAdapter, renderGitIdentityWarning } from "./adapters/git-adapter.js";
 import { createAppSettingsService } from "./services/app-settings-service.js";
 import { createCodexBridgeIntegrationService } from "./services/codex-bridge-integration-service.js";
 import { createAutoMemoryService } from "./services/auto-memory-service.js";
@@ -92,7 +94,7 @@ export async function createServer(deps, options = {}) {
         appSettings: deps.appSettings,
         codexBridgeIntegration: deps.codexBridgeIntegration
     });
-    registerClaudeHookRoutes(app, { claudeHookService: deps.claudeHookService });
+    registerClaudeHookRoutes(app, { claudeHookService: deps.claudeHookService, environmentCheck: deps.environmentCheck });
     registerGateReviewRoutes(app, {
         projectService: deps.projectService,
         gateReviewService: deps.gateReviewService
@@ -215,6 +217,29 @@ async function cleanupRecentTranslationRuntime(deps) {
     const repoRoots = await deps.projectService.getRecentRepositoryPaths();
     await Promise.all(repoRoots.map((repoRoot) => deps.translationWorkerService.cleanupStartupRuntime(repoRoot)));
 }
+async function warnOnEnvironmentProblems(environmentCheck) {
+    try {
+        for (const warning of await environmentCheck?.getWarnings({ refresh: true }) ?? []) {
+            console.warn(`[VCM] ${warning}`);
+        }
+    }
+    catch {
+        // Project summaries report environment problems when a repository connects.
+    }
+}
+// Projects can still configure their own identity; this only reports the
+// identity VCM falls back to outside any repository-specific Git config.
+async function warnOnDefaultGitIdentity() {
+    try {
+        const identity = await createGitAdapter(createCommandRunner()).resolveCommitIdentity(os.homedir());
+        if (identity.defaulted.length > 0) {
+            console.warn(`[VCM] ${renderGitIdentityWarning("the VCM user", identity)}`);
+        }
+    }
+    catch {
+        // Project summaries report identity problems per repository.
+    }
+}
 export async function startServer(options = {}) {
     const host = options.host ?? "127.0.0.1";
     const port = options.port ?? 4173;
@@ -223,6 +248,8 @@ export async function startServer(options = {}) {
     });
     const app = await createServer(deps, options);
     await app.listen({ host, port });
+    await warnOnEnvironmentProblems(deps.environmentCheck);
+    await warnOnDefaultGitIdentity();
     return {
         url: `http://${host}:${port}`,
         close() {
@@ -237,6 +264,7 @@ export function createDefaultServerDeps(options = {}) {
     const runner = createCommandRunner();
     const git = createGitAdapter(runner);
     const claude = createClaudeAdapter(runner);
+    const environmentCheck = createEnvironmentCheck({ runner, git, apiUrl: options.apiUrl });
     const appSettings = createAppSettingsService({ fs });
     const codexBridgeIntegration = createCodexBridgeIntegrationService({
         settings: appSettings,
@@ -252,12 +280,14 @@ export function createDefaultServerDeps(options = {}) {
     const projectService = createProjectService({
         fs,
         git,
+        environmentCheck,
         appSettings,
         claudeVersionCheck: createClaudeVersionCheck(claude)
     });
     const taskService = createTaskService({ fs, git, artifactService, projectService });
     const taskWorkflowService = createTaskWorkflowService({ fs });
     const sessionService = createSessionService({
+        gitIdentity: git,
         fs,
         runtime,
         registry,
@@ -326,6 +356,7 @@ export function createDefaultServerDeps(options = {}) {
         taskService,
         taskWorkflowService,
         workflowControlService,
+        probeHookDelivery: () => environmentCheck.probeHookDelivery(),
         onRouteDelivered: ({ repoRoot, taskSlug, message }) => architectRestartService.recordRouteDelivered(repoRoot, taskSlug, message)
     });
     const taskLaunchService = createTaskLaunchService({
@@ -509,7 +540,8 @@ export function createDefaultServerDeps(options = {}) {
         runtime,
         diagnosticsService,
         usageAnalyticsService,
-        workflowControlService
+        workflowControlService,
+        environmentCheck
     };
 }
 export function getDefaultStaticDir() {

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

@@ -22,6 +22,9 @@ const ARTIFACT_PATH_KEYS = [
     ["workflow-progress", "workflowProgressPath"],
     ["final-acceptance", "finalAcceptancePath"]
 ];
+// Gate requests whose report VCM still waits for; any other status means the
+// run already ended and a report would be ignored.
+const OPEN_GATE_REQUEST_STATUSES = new Set(["requested", "running"]);
 const ROLE_COMMAND_PLACEHOLDER_PATTERN = /(^|\n)\s*(TBD|status:\s*draft)\s*(\n|$)/i;
 const DEFAULT_MESSAGE_ROUTES = [
     ["project-manager", "architect"],
@@ -331,6 +334,11 @@ async function validateDynamicArtifact(fs, input, content, workflowControlServic
                 `Report path must match the assigned request path ${request.reportPath ?? "<missing>"}.`
             ]);
         }
+        if (request.status && !OPEN_GATE_REQUEST_STATUSES.has(request.status)) {
+            throw artifactRejected(input.kind, [
+                `Gate request ${request.requestId ?? requestId} is already ${request.status}, so VCM will not use this report. Stop this review; VCM sends a new request if the gate runs again.`
+            ]);
+        }
         assertManagedArtifactContent(input.kind, content, artifactPath, input.mode, {
             expectedGate: request.gate,
             expectedRequestId: request.requestId ?? requestId

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

@@ -1029,7 +1029,11 @@ function normalizeDiagnosticString(value, maxLength) {
 function stringOrUndefined(value) {
     return typeof value === "string" ? value : undefined;
 }
+// VCM submits its prompts as a terminal paste, and newer Claude Code versions
+// report a pasted prompt wrapped in <pasted_content id="..."> tags, so the
+// wrapper is removed before looking for VCM's marker.
+const PASTED_CONTENT_OPEN_TAG = /^<pasted_content\b[^>]*>/i;
 function isDirectUserPrompt(prompt) {
-    const normalized = prompt.trim();
+    const normalized = prompt.trim().replace(PASTED_CONTENT_OPEN_TAG, "").trim();
     return normalized.length > 0 && !/^\[VCM(?:\s|\])/i.test(normalized);
 }

package/dist/backend/services/environment-check.js

@@ -0,0 +1,245 @@
+import { randomUUID } from "node:crypto";
+import { renderVcmHookProbeCommand } from "./harness-service.js";
+import { buildVcmNoProxyEnvironment } from "./no-proxy-environment.js";
+// Oldest Git that supports every command VCM runs (`git branch --show-current`).
+export const MIN_GIT_VERSION = [2, 22, 0];
+// Matches package.json engines; harness tools run with the `node` on PATH.
+export const MIN_NODE_MAJOR = 20;
+const CHECK_CACHE_TTL_MS = 10 * 60 * 1000;
+// A failed check is retried sooner so a fixed environment clears the warning.
+const FAILED_CHECK_TTL_MS = 30 * 1000;
+const COMMAND_TIMEOUT_MS = 10 * 1000;
+// The hook pipeline retries curl twice with a 2 s limit per attempt.
+const HOOK_PROBE_TIMEOUT_MS = 15 * 1000;
+const HOOK_PROBE_SCOPE = "__vcm_hook_probe__";
+const HOOK_PROBE_ROLE = "hook-probe";
+export function createEnvironmentCheck(deps) {
+    const now = deps.now ?? Date.now;
+    const baseEnv = deps.baseEnv ?? process.env;
+    const hookProbeTimeoutMs = deps.hookProbeTimeoutMs ?? HOOK_PROBE_TIMEOUT_MS;
+    const pendingProbes = new Map();
+    let cached;
+    let inFlight;
+    const repositoryCache = new Map();
+    const repositoryInFlight = new Map();
+    return {
+        async getWarnings(options = {}) {
+            if (!cached || options.refresh) {
+                return runOnce();
+            }
+            const ttl = cached.warnings.length > 0 ? FAILED_CHECK_TTL_MS : CHECK_CACHE_TTL_MS;
+            if (now() - cached.checkedAt >= ttl) {
+                void runOnce();
+            }
+            return cached.warnings;
+        },
+        async getRepositoryWarnings(repoRoot, options = {}) {
+            const current = repositoryCache.get(repoRoot);
+            if (!current || options.refresh) {
+                return runRepositoryOnce(repoRoot);
+            }
+            const ttl = current.warnings.length > 0 ? FAILED_CHECK_TTL_MS : CHECK_CACHE_TTL_MS;
+            if (now() - current.checkedAt >= ttl) {
+                void runRepositoryOnce(repoRoot);
+            }
+            return current.warnings;
+        },
+        probeHookDelivery,
+        receiveHookProbe(probeToken) {
+            if (typeof probeToken !== "string") {
+                return false;
+            }
+            const resolve = pendingProbes.get(probeToken);
+            if (!resolve) {
+                return false;
+            }
+            pendingProbes.delete(probeToken);
+            resolve();
+            return true;
+        }
+    };
+    function runOnce() {
+        if (inFlight) {
+            return inFlight;
+        }
+        inFlight = (async () => {
+            try {
+                const warnings = await runChecks();
+                cached = { warnings, checkedAt: now() };
+                return warnings;
+            }
+            finally {
+                inFlight = undefined;
+            }
+        })();
+        return inFlight;
+    }
+    function runRepositoryOnce(repoRoot) {
+        const running = repositoryInFlight.get(repoRoot);
+        if (running) {
+            return running;
+        }
+        const check = (async () => {
+            try {
+                const warnings = await runRepositoryChecks(repoRoot);
+                repositoryCache.set(repoRoot, { warnings, checkedAt: now() });
+                return warnings;
+            }
+            finally {
+                repositoryInFlight.delete(repoRoot);
+            }
+        })();
+        repositoryInFlight.set(repoRoot, check);
+        return check;
+    }
+    async function runRepositoryChecks(repoRoot) {
+        if (!deps.git) {
+            return [];
+        }
+        const access = await deps.git.checkRemoteAccess(repoRoot);
+        if (access.status !== "failed") {
+            return [];
+        }
+        return [
+            `Git cannot reach remote "${access.remote}": ${trimPeriod(access.detail)}. Creating a task and Pull fetch the upstream branch first, so both will fail. VCM runs Git without credential prompts; check the remote URL and set up credentials for it in the environment that runs VCM, such as an SSH key loaded in ssh-agent or a Git credential helper.`
+        ];
+    }
+    async function runChecks() {
+        const [git, sh, node, curl, gh] = await Promise.all([checkGit(), checkSh(), checkNode(), checkCurl(), checkGh()]);
+        const warnings = [git, sh, node, curl, gh].filter((warning) => Boolean(warning));
+        // A missing program already explains a failed probe; only probe when the
+        // pipeline's programs are present, to catch PATH, proxy, or network faults.
+        if (!sh && !node && !curl) {
+            const hookWarning = await probeHookDelivery();
+            if (hookWarning) {
+                warnings.push(hookWarning);
+            }
+        }
+        return warnings;
+    }
+    async function checkGit() {
+        const result = await runCommand("git", ["--version"]);
+        if (result.exitCode !== 0) {
+            return `Git is not available: ${firstLine(result.stderr)}. VCM needs Git ${formatVersion(MIN_GIT_VERSION)} or newer on PATH to read repositories and create task worktrees.`;
+        }
+        const version = parseVersion(result.stdout);
+        if (!version) {
+            return `Git version could not be parsed from "${firstLine(result.stdout)}". VCM needs Git ${formatVersion(MIN_GIT_VERSION)} or newer.`;
+        }
+        if (compareVersions(version, MIN_GIT_VERSION) < 0) {
+            return `Git ${formatVersion(version)} is older than ${formatVersion(MIN_GIT_VERSION)}, the oldest version VCM supports. Upgrade Git.`;
+        }
+        return undefined;
+    }
+    async function checkSh() {
+        const result = await runCommand("sh", ["-c", "exit 0"]);
+        return result.exitCode === 0
+            ? undefined
+            : `sh is not available: ${firstLine(result.stderr)}. Claude Code runs every VCM role hook through sh.`;
+    }
+    async function checkNode() {
+        const result = await runCommand("node", ["--version"]);
+        if (result.exitCode !== 0) {
+            return `node is not available on the PATH role sessions inherit: ${firstLine(result.stderr)}. VCM role hooks, Bash and subagent guards, and .ai/tools scripts run with node; add the Node.js bin directory to PATH before starting VCM.`;
+        }
+        const version = parseVersion(result.stdout);
+        if (version && version[0] < MIN_NODE_MAJOR) {
+            return `The node on PATH is ${formatVersion(version)}, but VCM role hooks and .ai/tools scripts need Node.js ${MIN_NODE_MAJOR} or newer. Put a newer Node.js first on PATH before starting VCM.`;
+        }
+        return undefined;
+    }
+    async function checkCurl() {
+        const result = await runCommand("curl", ["--version"]);
+        return result.exitCode === 0
+            ? undefined
+            : `curl is not available: ${firstLine(result.stderr)}. VCM role hooks use curl to report Claude Code events; without it VCM cannot see role turns start or finish. Install curl.`;
+    }
+    // VCM never runs gh, so a missing gh is not a problem; an installed but
+    // logged-out gh breaks roles that use it for pull requests or issues.
+    async function checkGh() {
+        const version = await runCommand("gh", ["--version"]);
+        if (version.exitCode !== 0) {
+            return undefined;
+        }
+        const status = await deps.runner.run("gh", ["auth", "status"], {
+            env: { ...baseEnv, GH_PROMPT_DISABLED: "1", NO_COLOR: "1" },
+            timeoutMs: COMMAND_TIMEOUT_MS
+        });
+        if (status.exitCode === 0) {
+            return undefined;
+        }
+        const detail = firstLine(status.stderr) || firstLine(status.stdout) || `gh auth status exited with ${status.exitCode}`;
+        return `GitHub CLI (gh) is installed but not logged in: ${detail}. VCM does not run gh itself, but roles that use gh for pull requests or issues will fail. Run gh auth login in the environment that runs VCM.`;
+    }
+    async function probeHookDelivery() {
+        if (!deps.apiUrl) {
+            return undefined;
+        }
+        const probeToken = randomUUID();
+        let received = false;
+        const arrived = new Promise((resolve) => {
+            pendingProbes.set(probeToken, () => {
+                received = true;
+                resolve();
+            });
+        });
+        try {
+            const run = deps.runner.run("sh", ["-c", renderVcmHookProbeCommand()], {
+                env: {
+                    ...baseEnv,
+                    ...buildVcmNoProxyEnvironment(deps.apiUrl, {}, baseEnv),
+                    VCM_API_URL: deps.apiUrl,
+                    VCM_TASK_SLUG: HOOK_PROBE_SCOPE,
+                    VCM_ROLE: HOOK_PROBE_ROLE,
+                    VCM_RUNTIME_SESSION_TOKEN: probeToken
+                },
+                input: "{}",
+                timeoutMs: hookProbeTimeoutMs
+            });
+            // The endpoint records the probe before curl exits, so the command's
+            // completion bounds the wait.
+            const result = await Promise.race([run, arrived.then(() => undefined)]);
+            if (received) {
+                return undefined;
+            }
+            const detail = firstLine(result?.stderr ?? "") || "the request did not arrive";
+            return `VCM role hooks cannot reach VCM at ${deps.apiUrl}: ${detail}. Role sessions will not report turns to VCM, so dispatches stay unconfirmed. Check that sh, node, and curl are on PATH and that any HTTP proxy excludes ${readHostname(deps.apiUrl)} through NO_PROXY.`;
+        }
+        finally {
+            pendingProbes.delete(probeToken);
+        }
+    }
+    function runCommand(command, args) {
+        return deps.runner.run(command, args, { env: baseEnv, timeoutMs: COMMAND_TIMEOUT_MS });
+    }
+}
+function parseVersion(output) {
+    const match = /(\d+)\.(\d+)(?:\.(\d+))?/.exec(output);
+    return match ? [Number(match[1]), Number(match[2]), Number(match[3] ?? 0)] : undefined;
+}
+function compareVersions(left, right) {
+    for (let index = 0; index < 3; index += 1) {
+        if (left[index] !== right[index]) {
+            return left[index] - right[index];
+        }
+    }
+    return 0;
+}
+function formatVersion(version) {
+    return version.join(".");
+}
+// Error details end the sentence they are quoted in.
+function firstLine(value) {
+    return trimPeriod(value.trim().split(/\r?\n/)[0]?.trim() ?? "");
+}
+function trimPeriod(value) {
+    return value.replace(/\.+$/, "");
+}
+function readHostname(url) {
+    try {
+        return new URL(url).hostname;
+    }
+    catch {
+        return url;
+    }
+}

package/dist/backend/services/gate-review-service.js

@@ -15,6 +15,9 @@ const GATE_REVIEW_VERSION = 1;
 const HARNESS_COMMIT_PREFIX = "[VCM Harness] ";
 const REVIEWER_ROLE = "reviewer";
 const DEFAULT_REPORT_POLL_INTERVAL_MS = 1000;
+// A Reviewer that just submitted a report usually ends its turn within
+// seconds; a missed Stop hook leaves the activity stale, so the wait is capped.
+const DEFAULT_REVIEWER_IDLE_WAIT_MS = 5 * 60 * 1000;
 const activeRuns = new Map();
 const gateStateLocks = new Map();
 const SOURCE_ARTIFACTS = {
@@ -54,6 +57,7 @@ const VALID_CODE_DIFF_FINDING_SCOPES = new Set(CODE_DIFF_FINDING_SCOPES);
 export function createGateReviewService(deps) {
     const now = deps.now ?? (() => new Date().toISOString());
     const reportPollIntervalMs = deps.reportPollIntervalMs ?? DEFAULT_REPORT_POLL_INTERVAL_MS;
+    const reviewerIdleWaitMs = deps.reviewerIdleWaitMs ?? DEFAULT_REVIEWER_IDLE_WAIT_MS;
     async function getContext(repoRoot, taskSlug) {
         const projectConfig = await deps.projectService.loadConfig(repoRoot);
         const task = await deps.taskService.loadTask(repoRoot, taskSlug);
@@ -529,6 +533,7 @@ export function createGateReviewService(deps) {
                 });
             }
             const session = await ensureReviewerSession(context);
+            await waitForReviewerIdle(context, controller.signal);
             throwIfGateRunCancelled(controller.signal);
             await submitTerminalInput(deps.runtime, session.id, prompt);
             await deps.sessionService.markRoleActivityRunning(context.repoRoot, context.taskSlug, REVIEWER_ROLE, session.id);
@@ -647,6 +652,20 @@ export function createGateReviewService(deps) {
             return next.gates[gate];
         });
     }
+    // Claude Code queues a prompt typed into a running turn but sends its
+    // UserPromptSubmit hook at once, so the running turn's Stop would look like
+    // the end of this request's turn and fail it. Wait for that turn to end.
+    async function waitForReviewerIdle(context, signal) {
+        const deadline = Date.now() + reviewerIdleWaitMs;
+        while (true) {
+            throwIfGateRunCancelled(signal);
+            const session = await deps.sessionService.getRoleSession(context.repoRoot, context.taskSlug, REVIEWER_ROLE);
+            if (session?.activityStatus !== "running" || Date.now() >= deadline) {
+                return;
+            }
+            await delay(reportPollIntervalMs);
+        }
+    }
     async function ensureReviewerSession(context) {
         const existing = await deps.sessionService.getRoleSession(context.repoRoot, context.taskSlug, REVIEWER_ROLE);
         if (existing?.status === "running" && deps.runtime.getSession(existing.id)) {

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

@@ -53,6 +53,17 @@ const LEGACY_CODEX_HARNESS_PATHS = [
     ".ai/tools/request-codex-review"
 ];
 const VCM_HOOK_COMMAND = `sh -c 'if [ -z "\${VCM_TASK_SLUG:-}" ] || [ -z "\${VCM_ROLE:-}" ] || [ -z "\${VCM_API_URL:-}" ]; then exit 0; fi; node -e '"'"'let s="";process.stdin.setEncoding("utf8");process.stdin.on("data",d=>s+=d);process.stdin.on("end",()=>{let event={};try{event=s.trim()?JSON.parse(s):{};}catch{event={raw:s};}process.stdout.write(JSON.stringify({taskSlug:process.env.VCM_TASK_SLUG,role:process.env.VCM_ROLE,runtimeSessionToken:process.env.VCM_RUNTIME_SESSION_TOKEN,event}));});'"'"' | curl -fsS --retry 2 --retry-delay 1 --retry-all-errors --connect-timeout 1 --max-time 2 -X POST "\${VCM_API_URL}/api/hooks/claude-code" -H "content-type: application/json" --data-binary @- >/dev/null || true'`;
+// The hook self-test runs the installed hook pipeline unchanged except for its
+// endpoint, so a passing probe proves sh, node, curl, PATH, and proxy settings
+// let role hooks reach VCM.
+export const VCM_HOOK_PROBE_PATH = "/api/hooks/probe";
+export function renderVcmHookProbeCommand() {
+    const endpoint = '"${VCM_API_URL}/api/hooks/claude-code"';
+    if (!VCM_HOOK_COMMAND.includes(endpoint)) {
+        throw new Error("VCM hook command no longer posts to /api/hooks/claude-code.");
+    }
+    return VCM_HOOK_COMMAND.replace(endpoint, () => `"\${VCM_API_URL}${VCM_HOOK_PROBE_PATH}"`);
+}
 const VCM_STOP_HOOK_COMMAND = `sh -c 'if [ -z "\${VCM_TASK_SLUG:-}" ] || [ -z "\${VCM_ROLE:-}" ] || [ -z "\${VCM_API_URL:-}" ]; then exit 0; fi; node -e '"'"'let s="";process.stdin.setEncoding("utf8");process.stdin.on("data",d=>s+=d);process.stdin.on("end",()=>{let event={};try{event=s.trim()?JSON.parse(s):{};}catch{event={raw:s};}process.stdout.write(JSON.stringify({taskSlug:process.env.VCM_TASK_SLUG,role:process.env.VCM_ROLE,runtimeSessionToken:process.env.VCM_RUNTIME_SESSION_TOKEN,event}));});'"'"' | curl -fsS --retry 2 --retry-delay 1 --retry-all-errors --connect-timeout 1 --max-time 2 -X POST "\${VCM_API_URL}/api/hooks/claude-code/stop" -H "content-type: application/json" --data-binary @- || true'`;
 const VCM_PERMISSION_REQUEST_HOOK_COMMAND = `sh -c 'if [ -z "\${VCM_TASK_SLUG:-}" ] || [ -z "\${VCM_ROLE:-}" ] || [ -z "\${VCM_API_URL:-}" ]; then exit 0; fi; node -e '"'"'let s="";process.stdin.setEncoding("utf8");process.stdin.on("data",d=>s+=d);process.stdin.on("end",()=>{let event={};try{event=s.trim()?JSON.parse(s):{};}catch{event={raw:s};}process.stdout.write(JSON.stringify({taskSlug:process.env.VCM_TASK_SLUG,role:process.env.VCM_ROLE,runtimeSessionToken:process.env.VCM_RUNTIME_SESSION_TOKEN,event}));});'"'"' | curl -fsS --max-time 5 -X POST "\${VCM_API_URL}/api/hooks/claude-code/permission-request" -H "content-type: application/json" --data-binary @- || true'`;
 const VCM_BASH_GUARD_HOOK_COMMAND = `sh -c 'if [ -z "\${VCM_TASK_SLUG:-}" ] || [ -z "\${VCM_ROLE:-}" ]; then exit 0; fi; guard=""; repo="$(git rev-parse --show-toplevel 2>/dev/null || true)"; if [ -n "$repo" ] && [ -f "$repo/.ai/tools/vcm-bash-guard" ]; then guard="$repo/.ai/tools/vcm-bash-guard"; else cwd="$(pwd -P 2>/dev/null || pwd)"; dir="$cwd"; while [ -n "$dir" ] && [ "$dir" != "/" ]; do if [ -f "$dir/.ai/tools/vcm-bash-guard" ]; then guard="$dir/.ai/tools/vcm-bash-guard"; break; fi; dir="$(dirname "$dir")"; done; if [ -z "$guard" ] && [ -n "\${CLAUDE_PROJECT_DIR:-}" ] && [ -f "\${CLAUDE_PROJECT_DIR}/.ai/tools/vcm-bash-guard" ]; then guard="\${CLAUDE_PROJECT_DIR}/.ai/tools/vcm-bash-guard"; fi; fi; [ -n "$guard" ] || exit 0; node "$guard" || exit 0'`;