vibe-coding-master 0.7.41 → 0.7.43

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

@@ -76,6 +76,7 @@ export function createHarnessFeedbackService(deps) {
             });
         }
         const session = await ensureIdleHarnessEngineer(repoRoot, taskSlug);
+        const pendingFeedback = await listPendingFeedback(repoRoot);
         const timestamp = now();
         const analysisPath = `${TASK_RETROSPECTIVE_DIR}/${sanitizeFeedbackId(taskSlug)}.md`;
         const analysisAbsolutePath = resolveRepoPath(repoRoot, analysisPath);
@@ -87,11 +88,11 @@ export function createHarnessFeedbackService(deps) {
             status: "running",
             analysisPath,
             finalAcceptanceHash: `sha256:${sha256(finalAcceptanceContent)}`,
+            pendingFeedbackPaths: pendingFeedback.map((item) => item.path),
             ...(memoryReview ? { memoryRunId: memoryReview.runId } : {}),
             createdAt: timestamp,
             updatedAt: timestamp
         };
-        const pendingFeedback = await listPendingFeedback(repoRoot);
         try {
             await persistTaskRetrospectiveMarker(repoRoot, marker);
             await submitTerminalInput(deps.runtime, session.id, buildTaskRetrospectivePrompt(repoRoot, analysisPath, pendingFeedback.map((item) => item.path), memoryReview));
@@ -135,7 +136,12 @@ export function createHarnessFeedbackService(deps) {
         const reportContent = await deps.fs.pathExists(reportPath)
             ? await deps.fs.readText(reportPath)
             : "";
-        const reportErrors = reportContent.trim() ? getRetrospectiveReportErrors(reportContent) : ["Report is empty."];
+        const reportErrors = reportContent.trim()
+            ? [
+                ...getRetrospectiveReportErrors(reportContent),
+                ...getFeedbackDispositionErrors(repoRoot, marker.pendingFeedbackPaths ?? [], reportContent)
+            ]
+            : ["Report is empty."];
         const reportReady = reportErrors.length === 0;
         if (!reportReady || (marker.memoryRunId && !input.memoryReviewSucceeded)) {
             await persistTaskRetrospectiveMarker(repoRoot, {
@@ -149,6 +155,19 @@ export function createHarnessFeedbackService(deps) {
             });
             return true;
         }
+        try {
+            await removeProcessedFeedback(repoRoot, marker.pendingFeedbackPaths ?? []);
+        }
+        catch (error) {
+            await persistTaskRetrospectiveMarker(repoRoot, {
+                ...marker,
+                status: "failed",
+                failedAt: timestamp,
+                updatedAt: timestamp,
+                error: `VCM could not remove processed Harness Feedback: ${errorMessage(error)}`
+            });
+            return true;
+        }
         await persistTaskRetrospectiveMarker(repoRoot, {
             ...marker,
             status: "completed",
@@ -245,7 +264,15 @@ export function createHarnessFeedbackService(deps) {
             ...(pendingFeedbackPaths.length > 0
                 ? [
                     "",
-                    "Process every listed feedback inside this retrospective. Record every disposition in the retrospective report, then delete the processed feedback files before ending the turn."
+                    "Process every listed feedback inside this retrospective. Record every disposition in the retrospective report using this exact block for each assigned path:",
+                    "",
+                    "### Feedback: <exact assigned absolute path>",
+                    "Decision: confirmed|rejected|duplicate|already-covered",
+                    "Evidence: <concise evidence>",
+                    "Impact: <impact>",
+                    "Required action: <action or none>",
+                    "",
+                    "Do not edit or delete pending feedback files. VCM removes the assigned files after validating every disposition in the accepted report."
                 ]
                 : []),
             "",
@@ -375,6 +402,20 @@ export function createHarnessFeedbackService(deps) {
             await deps.fs.removePath?.(statePath, { force: true });
         }
     }
+    async function removeProcessedFeedback(repoRoot, feedbackPaths) {
+        if (feedbackPaths.length === 0) {
+            return;
+        }
+        if (!deps.fs.removePath) {
+            throw new Error("The filesystem adapter does not support feedback removal.");
+        }
+        for (const feedbackPath of feedbackPaths) {
+            assertPendingFeedbackPath(feedbackPath);
+        }
+        for (const feedbackPath of feedbackPaths) {
+            await deps.fs.removePath(resolveRepoPath(repoRoot, feedbackPath), { force: true });
+        }
+    }
     async function readOptionalText(repoRoot, relativePath) {
         const absolutePath = resolveRepoPath(repoRoot, relativePath);
         return readAbsoluteOptionalText(absolutePath);
@@ -393,6 +434,67 @@ export function createHarnessFeedbackService(deps) {
         assertHarnessEngineerAvailable
     };
 }
+function getFeedbackDispositionErrors(repoRoot, feedbackPaths, reportContent) {
+    if (feedbackPaths.length === 0) {
+        return [];
+    }
+    const section = readLevelTwoSection(reportContent, "Feedback Dispositions");
+    if (!section) {
+        return ["Feedback Dispositions is empty."];
+    }
+    const errors = [];
+    const lines = section.split(/\r?\n/);
+    for (const feedbackPath of feedbackPaths) {
+        try {
+            assertPendingFeedbackPath(feedbackPath);
+        }
+        catch (error) {
+            errors.push(errorMessage(error));
+            continue;
+        }
+        const absolutePath = resolveRepoPath(repoRoot, feedbackPath);
+        const heading = `### Feedback: ${absolutePath}`;
+        const start = lines.findIndex((line) => line.trim() === heading);
+        if (start < 0) {
+            errors.push(`Missing disposition for assigned feedback: ${absolutePath}.`);
+            continue;
+        }
+        const endOffset = lines.slice(start + 1).findIndex((line) => /^###\s+/.test(line.trim()));
+        const end = endOffset < 0 ? lines.length : start + 1 + endOffset;
+        const block = lines.slice(start + 1, end);
+        const decision = readDispositionField(block, "Decision");
+        if (!decision || !["confirmed", "rejected", "duplicate", "already-covered"].includes(decision)) {
+            errors.push(`Feedback disposition Decision for ${absolutePath} must be confirmed|rejected|duplicate|already-covered.`);
+        }
+        for (const field of ["Evidence", "Impact", "Required action"]) {
+            if (!readDispositionField(block, field)) {
+                errors.push(`Feedback disposition ${field} is required for ${absolutePath}.`);
+            }
+        }
+    }
+    return errors;
+}
+function readLevelTwoSection(content, heading) {
+    const escapedHeading = heading.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const match = new RegExp(`^##\\s+${escapedHeading}\\s*$`, "im").exec(content);
+    if (!match || match.index === undefined) {
+        return undefined;
+    }
+    const afterHeading = content.slice(match.index + match[0].length);
+    const nextHeading = /\n##\s+\S/.exec(afterHeading);
+    return (nextHeading ? afterHeading.slice(0, nextHeading.index) : afterHeading).trim();
+}
+function readDispositionField(lines, field) {
+    const escapedField = field.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    return lines
+        .map((line) => new RegExp(`^${escapedField}:\\s*(.+)$`, "i").exec(line.trim())?.[1]?.trim())
+        .find((value) => Boolean(value));
+}
+function assertPendingFeedbackPath(feedbackPath) {
+    if (!/^\.ai\/vcm\/harness-feedback\/pending\/[A-Za-z0-9._-]+\.md$/.test(feedbackPath)) {
+        throw new Error(`Invalid assigned Harness Feedback path: ${feedbackPath}.`);
+    }
+}
 function parseSimpleMetadata(content) {
     const result = {};
     for (const line of content.split(/\r?\n/).slice(0, 80)) {

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

@@ -57,8 +57,15 @@ const VCM_HOOK_DEFINITIONS = [
     { eventName: "PreToolUse", matcher: "Bash", command: VCM_BASH_GUARD_HOOK_COMMAND, timeout: 10 },
     { eventName: "PreToolUse", matcher: "Write|Edit", command: VCM_BASH_GUARD_HOOK_COMMAND, timeout: 10 },
     { eventName: "UserPromptSubmit", command: VCM_HOOK_COMMAND, timeout: 5 },
+    { eventName: "PreToolUse", command: VCM_HOOK_COMMAND, timeout: 5 },
+    { eventName: "PostToolUse", command: VCM_HOOK_COMMAND, timeout: 5 },
+    { eventName: "PostToolUseFailure", command: VCM_HOOK_COMMAND, timeout: 5 },
+    { eventName: "PostToolBatch", command: VCM_HOOK_COMMAND, timeout: 5 },
+    { eventName: "SubagentStart", command: VCM_HOOK_COMMAND, timeout: 5 },
+    { eventName: "SubagentStop", command: VCM_HOOK_COMMAND, timeout: 5 },
     { eventName: "Stop", command: VCM_STOP_HOOK_COMMAND, timeout: 10 },
     { eventName: "StopFailure", command: VCM_HOOK_COMMAND, timeout: 5 },
+    { eventName: "PreCompact", command: VCM_HOOK_COMMAND, timeout: 5 },
     { eventName: "PostCompact", command: VCM_HOOK_COMMAND, timeout: 5 },
     { eventName: "PermissionRequest", command: VCM_PERMISSION_REQUEST_HOOK_COMMAND, timeout: 5 }
 ];
@@ -119,7 +126,7 @@ const HARNESS_FILES = [
         kind: "skill-vcm-code-navigation",
         path: ".claude/skills/vcm-code-navigation/SKILL.md",
         title: "VCM Code Navigation Skill",
-        frontmatter: renderSkillFrontmatter("vcm-code-navigation", "Use when Architect, Coder, or Reviewer must resolve code symbols, references, implementations, call hierarchies, or bounded dependency paths."),
+        frontmatter: renderSkillFrontmatter("vcm-code-navigation", "Use when Architect must resolve code symbols, references, implementations, call hierarchies, or bounded dependency paths."),
         ownership: "whole-file",
         renderRules: renderVcmCodeNavigationSkillRules
     },
@@ -209,8 +216,8 @@ const HARNESS_FILES = [
         title: "Reviewer Agent",
         memoryBlock: true,
         requiredDisallowedTools: REVIEWER_DISALLOWED_TOOLS,
-        requiredSkills: ["vcm-code-navigation"],
-        frontmatter: renderAgentFrontmatter("reviewer", "VCM independent gate review role for architecture plans, validation adequacy, and code diffs.", { disallowedTools: REVIEWER_DISALLOWED_TOOLS.join(", "), skills: ["vcm-code-navigation"] }),
+        removedSkills: ["vcm-code-navigation"],
+        frontmatter: renderAgentFrontmatter("reviewer", "VCM independent gate review role for architecture plans, validation adequacy, and code diffs.", { disallowedTools: REVIEWER_DISALLOWED_TOOLS.join(", ") }),
         renderRules: renderReviewerAgentRules
     },
     {
@@ -225,7 +232,8 @@ const HARNESS_FILES = [
         path: ".claude/agents/harness-engineer.md",
         title: "Harness Engineer Agent",
         memoryBlock: true,
-        frontmatter: renderAgentFrontmatter("harness-engineer", "VCM task-scoped harness maintenance role for harness diagnosis, diff proposals, and VCM issue drafts."),
+        requiredTools: ["Skill"],
+        frontmatter: renderAgentFrontmatter("harness-engineer", "VCM task-scoped harness maintenance role for harness diagnosis, diff proposals, and VCM issue drafts.", { tools: "Read, Grep, Glob, Bash, Edit, Write, Skill" }),
         renderRules: renderHarnessEngineerHarnessRules
     },
     {
@@ -275,7 +283,8 @@ const HARNESS_FILES = [
         path: ".claude/agents/project-manager.md",
         title: "Project Manager Agent",
         memoryBlock: true,
-        frontmatter: renderAgentFrontmatter("project-manager", "User-facing VCM orchestration role for task clarification, role routing, handoffs, acceptance, and PR preparation."),
+        requiredTools: ["Skill"],
+        frontmatter: renderAgentFrontmatter("project-manager", "User-facing VCM orchestration role for task clarification, role routing, handoffs, acceptance, and PR preparation.", { tools: "Read, Grep, Glob, Bash, Edit, Write, Skill" }),
         renderRules: renderProjectManagerHarnessRules
     },
     {
@@ -295,8 +304,8 @@ const HARNESS_FILES = [
         title: "Coder Agent",
         memoryBlock: true,
         requiredDisallowedTools: CODE_ROLE_DISALLOWED_TOOLS,
-        requiredSkills: ["vcm-code-navigation"],
-        frontmatter: renderAgentFrontmatter("coder", "VCM implementation role for scoped code changes and focused tests.", { disallowedTools: CODE_ROLE_DISALLOWED_TOOLS.join(", "), skills: ["vcm-code-navigation"] }),
+        removedSkills: ["vcm-code-navigation"],
+        frontmatter: renderAgentFrontmatter("coder", "VCM implementation role for scoped code changes and focused tests.", { disallowedTools: CODE_ROLE_DISALLOWED_TOOLS.join(", ") }),
         renderRules: renderCoderHarnessRules
     },
     {
@@ -304,7 +313,8 @@ const HARNESS_FILES = [
         path: ".claude/agents/tester.md",
         title: "Tester Agent",
         memoryBlock: true,
-        frontmatter: renderAgentFrontmatter("tester", "VCM testing role for validation, test adequacy, approved-scope validation, and risk findings."),
+        requiredTools: ["Skill"],
+        frontmatter: renderAgentFrontmatter("tester", "VCM testing role for validation, test adequacy, approved-scope validation, and risk findings.", { tools: "Read, Grep, Glob, Bash, Edit, Write, Skill" }),
         renderRules: renderTesterHarnessRules
     }
 ];
@@ -1407,9 +1417,42 @@ function ensureAgentDisallowedTools(content, requiredTools) {
         : withoutAllowedTools.replace(/\r?\n---$/, `\ndisallowedTools: ${disallowedTools}\n---`);
     return content.replace(frontmatterMatch[0], nextFrontmatter);
 }
+function ensureAgentAllowedTool(content, requiredTool) {
+    const frontmatterMatch = content.match(/^---\r?\n[\s\S]*?\r?\n---/);
+    if (!frontmatterMatch) {
+        return content;
+    }
+    const frontmatter = frontmatterMatch[0];
+    const toolsMatch = frontmatter.match(/^tools:\s*(.*)$/m);
+    if (toolsMatch) {
+        const existing = toolsMatch[1]
+            .split(",")
+            .map((tool) => tool.trim())
+            .filter(Boolean);
+        if (existing.includes(requiredTool)) {
+            return content;
+        }
+        const tools = [...existing, requiredTool].join(", ");
+        return content.replace(frontmatter, frontmatter.replace(toolsMatch[0], `tools: ${tools}`));
+    }
+    const disallowedMatch = frontmatter.match(/^disallowedTools:\s*(.*)$/m);
+    if (!disallowedMatch) {
+        return content;
+    }
+    const disallowedTools = disallowedMatch[1]
+        .split(",")
+        .map((tool) => tool.trim())
+        .filter((tool) => tool && tool !== requiredTool);
+    const nextFrontmatter = disallowedTools.length > 0
+        ? frontmatter.replace(disallowedMatch[0], `disallowedTools: ${disallowedTools.join(", ")}`)
+        : frontmatter.replace(/^disallowedTools:\s*.*\r?\n?/m, "");
+    return content.replace(frontmatter, nextFrontmatter);
+}
 function normalizeAgentFrontmatter(content, definition) {
-    const toolsUpdated = ensureAgentDisallowedTools(content, definition.requiredDisallowedTools);
-    return (definition.requiredSkills ?? []).reduce(ensureAgentSkill, toolsUpdated);
+    const allowedToolsUpdated = (definition.requiredTools ?? []).reduce(ensureAgentAllowedTool, content);
+    const disallowedToolsUpdated = ensureAgentDisallowedTools(allowedToolsUpdated, definition.requiredDisallowedTools);
+    const skillsUpdated = (definition.requiredSkills ?? []).reduce(ensureAgentSkill, disallowedToolsUpdated);
+    return (definition.removedSkills ?? []).reduce(removeAgentSkill, skillsUpdated);
 }
 function ensureAgentSkill(content, requiredSkill) {
     const frontmatterMatch = content.match(/^---\r?\n[\s\S]*?\r?\n---/);
@@ -1431,6 +1474,30 @@ function ensureAgentSkill(content, requiredSkill) {
     const nextSkills = `${skillsMatch[0].trimEnd()}\n  - ${requiredSkill}`;
     return content.replace(frontmatter, frontmatter.replace(skillsMatch[0], nextSkills));
 }
+function removeAgentSkill(content, removedSkill) {
+    const frontmatterMatch = content.match(/^---\r?\n[\s\S]*?\r?\n---/);
+    if (!frontmatterMatch) {
+        return content;
+    }
+    const frontmatter = frontmatterMatch[0];
+    const skillsMatch = frontmatter.match(/^skills:[ \t]*(?:\r?\n((?:\s+-\s+[^\r\n]+\r?\n?)*))?/m);
+    if (!skillsMatch) {
+        return content;
+    }
+    const listedSkills = (skillsMatch[1] ?? "")
+        .split(/\r?\n/)
+        .map((line) => line.match(/^\s+-\s+(.+)$/)?.[1]?.trim())
+        .filter((skill) => Boolean(skill));
+    const remainingSkills = listedSkills.filter((skill) => skill !== removedSkill);
+    if (remainingSkills.length === listedSkills.length) {
+        return content;
+    }
+    const lineEnding = skillsMatch[0].includes("\r\n") ? "\r\n" : "\n";
+    const replacement = remainingSkills.length > 0
+        ? `skills:${lineEnding}${remainingSkills.map((skill) => `  - ${skill}`).join(lineEnding)}${lineEnding}`
+        : "";
+    return content.replace(frontmatter, frontmatter.replace(skillsMatch[0], replacement));
+}
 function migrateLegacyHarnessFile(definition, currentContent, block) {
     const legacyContent = definition.legacyWholeFile?.trimEnd();
     if (!legacyContent) {

package/dist/backend/services/memory-review-paths.js

@@ -2,6 +2,19 @@ export const MEMORY_REVIEW_ROOT = ".ai/vcm/memory-review";
 export const MEMORY_REVIEW_RUNS_ROOT = `${MEMORY_REVIEW_ROOT}/runs`;
 export const MEMORY_REVIEW_STATE_PATH = `${MEMORY_REVIEW_ROOT}/state.json`;
 export const ARCHITECT_PLANNING_MEMORY_CANDIDATE_PATH = `${MEMORY_REVIEW_ROOT}/candidates/architect/planning.md`;
+const MEMORY_REVIEW_ROLE_DRAFT_PATTERN = new RegExp(`^${escapeRegExp(MEMORY_REVIEW_RUNS_ROOT)}/[A-Za-z0-9._-]+/drafts/([A-Za-z0-9._-]+)\\.md$`);
+export function memoryReviewRoleDraftPath(runId, role) {
+    return `${MEMORY_REVIEW_RUNS_ROOT}/${runId}/drafts/${role}.md`;
+}
+export function isMemoryProposalSubmissionPath(artifactPath, role) {
+    if (artifactPath === ARCHITECT_PLANNING_MEMORY_CANDIDATE_PATH) {
+        return role === "architect";
+    }
+    return MEMORY_REVIEW_ROLE_DRAFT_PATTERN.exec(artifactPath)?.[1] === role;
+}
 export function architectPlanningCandidateSnapshotPath(runId) {
     return `${MEMORY_REVIEW_RUNS_ROOT}/${runId}/sources/architect-planning.md`;
 }
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/dist/backend/services/role-stall-detector-service.js

@@ -0,0 +1,322 @@
+import { isVcmRoleName } from "../../shared/constants.js";
+import { VcmError } from "../errors.js";
+export const ROLE_MODEL_STALL_TIMEOUT_MS = 10 * 60 * 1000;
+export const ROLE_TOOL_STALL_TIMEOUT_MS = 10 * 60 * 1000;
+export const ROLE_SUBAGENT_STALL_TIMEOUT_MS = 30 * 60 * 1000;
+const TOOL_TIMEOUT_GRACE_MS = 30_000;
+export function createRoleStallDetectorService(deps) {
+    const modelTimeoutMs = deps.modelTimeoutMs ?? ROLE_MODEL_STALL_TIMEOUT_MS;
+    const toolTimeoutMs = deps.toolTimeoutMs ?? ROLE_TOOL_STALL_TIMEOUT_MS;
+    const subagentTimeoutMs = deps.subagentTimeoutMs ?? ROLE_SUBAGENT_STALL_TIMEOUT_MS;
+    const now = deps.now ?? (() => new Date().toISOString());
+    const setTimer = deps.setTimeout ?? ((callback, delayMs) => globalThis.setTimeout(callback, delayMs));
+    const clearTimer = deps.clearTimeout ?? ((timer) => globalThis.clearTimeout(timer));
+    const monitors = new Map();
+    return {
+        async recordHook(input) {
+            if (!isVcmRoleName(input.role)) {
+                return;
+            }
+            const key = monitorKey(input.repoRoot, input.taskSlug);
+            if (input.eventName === "Stop" || input.eventName === "StopFailure") {
+                clearMonitor(key);
+                return;
+            }
+            const [session, round] = await Promise.all([
+                deps.sessionService.getRoleSession(input.repoRoot, input.taskSlug, input.role),
+                deps.roundService.getSessionRoundState(roundInput(input))
+            ]);
+            if (!session
+                || session.status !== "running"
+                || session.activityStatus !== "running"
+                || round.status !== "running"
+                || round.activeRole !== input.role
+                || !round.roundId) {
+                clearMonitor(key);
+                return;
+            }
+            let monitor = monitors.get(key);
+            if (!monitor
+                || monitor.sessionId !== session.id
+                || monitor.runtimeSessionToken !== session.runtimeSessionToken
+                || monitor.roundId !== round.roundId
+                || monitor.role !== input.role) {
+                clearMonitor(key);
+                monitor = {
+                    context: taskInput(input),
+                    role: input.role,
+                    sessionId: session.id,
+                    runtimeSessionToken: session.runtimeSessionToken,
+                    roundId: round.roundId,
+                    phase: "awaiting-model",
+                    phaseStartedAt: now(),
+                    generation: 0,
+                    activeTools: new Map()
+                };
+                monitors.set(key, monitor);
+            }
+            advanceMonitor(key, monitor, input.eventName, input.event);
+        },
+        async reconcileTask(input) {
+            const key = monitorKey(input.repoRoot, input.taskSlug);
+            for (const [candidateKey, monitor] of monitors) {
+                if (monitor.context.repoRoot === input.repoRoot && candidateKey !== key) {
+                    clearMonitor(candidateKey);
+                }
+            }
+            const monitor = monitors.get(key);
+            if (!monitor) {
+                return;
+            }
+            const [session, round] = await Promise.all([
+                deps.sessionService.getRoleSession(input.repoRoot, input.taskSlug, monitor.role),
+                deps.roundService.getSessionRoundState(roundInput(input))
+            ]);
+            if (!session
+                || session.id !== monitor.sessionId
+                || session.runtimeSessionToken !== monitor.runtimeSessionToken
+                || session.status !== "running"
+                || session.activityStatus !== "running"
+                || round.status !== "running"
+                || round.activeRole !== monitor.role
+                || round.roundId !== monitor.roundId) {
+                clearMonitor(key);
+            }
+        },
+        getWarning(repoRoot, taskSlug) {
+            const warning = monitors.get(monitorKey(repoRoot, taskSlug))?.warning;
+            return warning ? { ...warning } : null;
+        },
+        ignoreWarning(repoRoot, taskSlug, warningId) {
+            const monitor = requireWarning(repoRoot, taskSlug, warningId);
+            monitor.ignoredGeneration = monitor.generation;
+            monitor.warning = undefined;
+            cancelTimer(monitor);
+            return { ok: true, warning: null };
+        },
+        async recoverWarning(input) {
+            const key = monitorKey(input.repoRoot, input.taskSlug);
+            const monitor = requireWarning(input.repoRoot, input.taskSlug, input.warningId);
+            const [session, round] = await Promise.all([
+                deps.sessionService.getRoleSession(input.repoRoot, input.taskSlug, monitor.role),
+                deps.roundService.getSessionRoundState(roundInput(input))
+            ]);
+            if (!session
+                || session.id !== monitor.sessionId
+                || session.runtimeSessionToken !== monitor.runtimeSessionToken
+                || session.status !== "running"
+                || session.activityStatus !== "running"
+                || round.status !== "running"
+                || round.activeRole !== monitor.role
+                || round.roundId !== monitor.roundId) {
+                clearMonitor(key);
+                return { ok: true, warning: null };
+            }
+            await deps.sessionService.recoverRoleSession(input.repoRoot, input.taskSlug, {
+                role: monitor.role,
+                expectedSessionId: monitor.sessionId,
+                expectedRuntimeSessionToken: monitor.runtimeSessionToken,
+                recoveryPrompt: renderRecoveryPrompt(monitor)
+            });
+            clearMonitor(key);
+            return { ok: true, warning: null };
+        },
+        clearProject(repoRoot) {
+            for (const [key, monitor] of monitors) {
+                if (monitor.context.repoRoot === repoRoot) {
+                    clearMonitor(key);
+                }
+            }
+        },
+        stop() {
+            for (const key of [...monitors.keys()]) {
+                clearMonitor(key);
+            }
+        }
+    };
+    function advanceMonitor(key, monitor, eventName, event) {
+        monitor.generation += 1;
+        monitor.warning = undefined;
+        monitor.ignoredGeneration = undefined;
+        cancelTimer(monitor);
+        switch (eventName) {
+            case "UserPromptSubmit":
+            case "PostCompact":
+            case "PostToolBatch":
+                monitor.activeTools.clear();
+                monitor.currentTool = undefined;
+                setPhase(key, monitor, "awaiting-model", modelTimeoutMs);
+                return;
+            case "PreToolUse": {
+                const tool = readTool(event, toolTimeoutMs, subagentTimeoutMs);
+                const toolKey = tool.toolUseId ?? `anonymous-${monitor.generation}`;
+                monitor.activeTools.set(toolKey, tool);
+                monitor.currentTool = tool;
+                setPhase(key, monitor, tool.toolName === "Agent" ? "subagent-running" : "tool-running", tool.timeoutMs);
+                return;
+            }
+            case "SubagentStart":
+                setPhase(key, monitor, "subagent-running", subagentTimeoutMs);
+                return;
+            case "PostToolUse":
+            case "PostToolUseFailure": {
+                const toolUseId = stringValue(event.tool_use_id);
+                if (toolUseId) {
+                    monitor.activeTools.delete(toolUseId);
+                }
+                monitor.currentTool = firstTool(monitor.activeTools);
+                if (monitor.currentTool) {
+                    setPhase(key, monitor, monitor.currentTool.toolName === "Agent" ? "subagent-running" : "tool-running", monitor.currentTool.timeoutMs);
+                }
+                return;
+            }
+            case "SubagentStop":
+                monitor.currentTool = firstTool(monitor.activeTools);
+                if (monitor.currentTool) {
+                    setPhase(key, monitor, monitor.currentTool.toolName === "Agent" ? "subagent-running" : "tool-running", monitor.currentTool.timeoutMs);
+                }
+                return;
+            case "PreCompact":
+                monitor.activeTools.clear();
+                monitor.currentTool = undefined;
+                setPhase(key, monitor, "compacting", modelTimeoutMs);
+                return;
+            case "PermissionRequest":
+                setPhase(key, monitor, "awaiting-permission");
+                return;
+            default:
+                return;
+        }
+    }
+    function setPhase(key, monitor, phase, timeoutMs) {
+        monitor.phase = phase;
+        monitor.phaseStartedAt = now();
+        if (timeoutMs === undefined) {
+            return;
+        }
+        const generation = monitor.generation;
+        monitor.timer = setTimer(() => {
+            void detectStall(key, generation).catch(() => undefined);
+        }, timeoutMs);
+    }
+    async function detectStall(key, generation) {
+        const monitor = monitors.get(key);
+        if (!monitor || monitor.generation !== generation || monitor.ignoredGeneration === generation) {
+            return;
+        }
+        const [session, round] = await Promise.all([
+            deps.sessionService.getRoleSession(monitor.context.repoRoot, monitor.context.taskSlug, monitor.role),
+            deps.roundService.getSessionRoundState(roundInput(monitor.context))
+        ]);
+        if (!session
+            || session.id !== monitor.sessionId
+            || session.runtimeSessionToken !== monitor.runtimeSessionToken
+            || session.status !== "running"
+            || session.activityStatus !== "running"
+            || round.status !== "running"
+            || round.activeRole !== monitor.role
+            || round.roundId !== monitor.roundId) {
+            clearMonitor(key);
+            return;
+        }
+        const detectedAt = now();
+        monitor.timer = undefined;
+        monitor.warning = {
+            id: `${monitor.sessionId}:${monitor.roundId}:${generation}:${detectedAt}`,
+            taskSlug: monitor.context.taskSlug,
+            role: monitor.role,
+            sessionId: monitor.sessionId,
+            runtimeSessionToken: monitor.runtimeSessionToken,
+            roundId: monitor.roundId,
+            phase: monitor.phase,
+            phaseStartedAt: monitor.phaseStartedAt,
+            detectedAt,
+            toolUseId: monitor.currentTool?.toolUseId,
+            toolName: monitor.currentTool?.toolName
+        };
+    }
+    function requireWarning(repoRoot, taskSlug, warningId) {
+        const monitor = monitors.get(monitorKey(repoRoot, taskSlug));
+        if (!monitor?.warning || monitor.warning.id !== warningId) {
+            throw new VcmError({
+                code: "ROLE_STALL_WARNING_STALE",
+                message: "The role stall warning is no longer active.",
+                statusCode: 409,
+                hint: "Refresh the task workspace before retrying the action."
+            });
+        }
+        return monitor;
+    }
+    function cancelTimer(monitor) {
+        if (monitor.timer === undefined) {
+            return;
+        }
+        clearTimer(monitor.timer);
+        monitor.timer = undefined;
+    }
+    function clearMonitor(key) {
+        const monitor = monitors.get(key);
+        if (!monitor) {
+            return;
+        }
+        cancelTimer(monitor);
+        monitors.delete(key);
+    }
+}
+function monitorKey(repoRoot, taskSlug) {
+    return `${repoRoot}:${taskSlug}`;
+}
+function taskInput(input) {
+    return {
+        repoRoot: input.repoRoot,
+        taskRepoRoot: input.taskRepoRoot,
+        stateRoot: input.stateRoot,
+        taskSlug: input.taskSlug
+    };
+}
+function roundInput(input) {
+    return {
+        repoRoot: input.repoRoot,
+        stateRepoRoot: input.taskRepoRoot,
+        stateRoot: input.stateRoot,
+        taskSlug: input.taskSlug
+    };
+}
+function readTool(event, defaultTimeoutMs, subagentTimeoutMs) {
+    const toolName = stringValue(event.tool_name);
+    const toolUseId = stringValue(event.tool_use_id);
+    const input = objectValue(event.tool_input);
+    const requestedTimeout = numberValue(input?.timeout);
+    return {
+        toolName,
+        toolUseId,
+        timeoutMs: toolName === "Agent"
+            ? subagentTimeoutMs
+            : Math.max(defaultTimeoutMs, requestedTimeout ? requestedTimeout + TOOL_TIMEOUT_GRACE_MS : 0)
+    };
+}
+function firstTool(tools) {
+    return tools.values().next().value;
+}
+function renderRecoveryPrompt(monitor) {
+    const phase = monitor.currentTool?.toolName
+        ? `${monitor.phase} (${monitor.currentTool.toolName})`
+        : monitor.phase;
+    return [
+        "[VCM Session Recovery]",
+        `The previous ${monitor.role} turn may have stalled during ${phase}.`,
+        "Continue the current assigned work from the existing Claude session context.",
+        "Do not repeat completed work unless it is needed to verify the current state."
+    ].join("\n");
+}
+function objectValue(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function stringValue(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+function numberValue(value) {
+    return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : undefined;
+}