vibe-coding-master 0.6.23 → 0.7.1

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

@@ -1,6 +1,6 @@
 import { isGateReviewerRoleName, isHarnessEngineerToolRoleName, isTranslatorToolRoleName, isUserFacingRole, isVcmRoleName } from "../../shared/constants.js";
 import { VcmError } from "../errors.js";
-import { readLatestRoleTurnReply } from "./claude-transcript-reply.js";
+import { readLatestRoleTurnReply, readTranscriptTurnEvidence } from "./claude-transcript-reply.js";
 import { submitTerminalInput } from "../runtime/terminal-submit.js";
 import { getTaskRuntimeRepoRoot } from "./task-service.js";
 const MAX_ROLE_RETRY_ATTEMPTS = 20;
@@ -11,7 +11,9 @@ const NON_RETRYABLE_STOP_FAILURE_ERRORS = new Set([
     "billing_error",
     "invalid_request",
     "model_not_found",
-    "max_output_tokens"
+    "max_output_tokens",
+    "terminal_session_exited",
+    "terminal_session_missing"
 ]);
 const DIAGNOSTIC_SNIPPET_MAX_LENGTH = 2000;
 export function createClaudeHookService(deps) {
@@ -220,6 +222,9 @@ export function createClaudeHookService(deps) {
             throwUnsupportedEvent(eventName);
         }
         const context = await getHookContext(input);
+        if (await isDuplicateCompletedStop(context, input)) {
+            return completedHookResult(input, eventName);
+        }
         const memoryResult = await processAutoMemoryRoleHook(input, context, eventName);
         if (memoryResult) {
             return memoryResult;
@@ -252,6 +257,31 @@ export function createClaudeHookService(deps) {
             settleGuard: true
         });
     }
+    async function isDuplicateCompletedStop(context, input) {
+        const session = await deps.sessionService.getRoleSession(context.project.repoRoot, context.taskSlug, input.role);
+        if (!session || session.activityStatus === "running" || !session.lastTurnEndedAt) {
+            return false;
+        }
+        const evidence = await readTranscriptTurnEvidence(session);
+        if (!evidence.completion) {
+            return false;
+        }
+        const completionAt = Date.parse(evidence.completion.timestamp);
+        const recordedEndAt = Date.parse(session.lastTurnEndedAt);
+        return Number.isFinite(completionAt)
+            && Number.isFinite(recordedEndAt)
+            && completionAt <= recordedEndAt + 1_000;
+    }
+    function completedHookResult(input, eventName) {
+        return {
+            ok: true,
+            eventName,
+            taskSlug: input.taskSlug,
+            role: input.role,
+            sessionUpdated: false,
+            dispatchedCount: 0
+        };
+    }
     async function processStopFailureHook(input) {
         const eventName = parseHookEvent(input.event.hook_event_name);
         if (eventName !== "StopFailure") {
@@ -699,6 +729,16 @@ export function createClaudeHookService(deps) {
             }
             return processStopHook(input, { allowBlock: true });
         },
+        handleReconciledTurnEnd(input) {
+            const eventName = parseHookEvent(input.event.hook_event_name);
+            if (eventName === "Stop") {
+                return processStopHook(input, { allowBlock: false });
+            }
+            if (eventName === "StopFailure") {
+                return processStopFailureHook(input);
+            }
+            throwUnsupportedEvent(eventName);
+        },
         handlePermissionRequestHook
     };
 }

package/dist/backend/services/claude-transcript-reply.js

@@ -1,9 +1,10 @@
-import { readFile } from "node:fs/promises";
+import { open, readFile } from "node:fs/promises";
 import { parseAssistantContent, resolveExistingClaudeTranscriptPath } from "./claude-transcript-service.js";
 /** Default maximum captured-reply length (characters). */
 export const MAX_TURN_REPLY_CHARS = 8_000;
 /** Tolerance applied when matching transcript events to the role's last-turn window. */
 const TURN_WINDOW_TOLERANCE_MS = 1_000;
+const TRANSCRIPT_EVIDENCE_TAIL_BYTES = 2 * 1024 * 1024;
 /**
  * Best-effort read of a role's latest user-facing turn reply.
  *
@@ -48,6 +49,80 @@ export async function readTranscriptTextEvents(transcriptPath) {
     }
     return events;
 }
+/** Read transcript activity and a completed assistant turn after this turn began. */
+export async function readTranscriptTurnEvidence(session) {
+    const transcriptPath = resolveExistingClaudeTranscriptPath(session);
+    if (!transcriptPath) {
+        return {};
+    }
+    let raw;
+    let modifiedAt;
+    let handle;
+    try {
+        handle = await open(transcriptPath, "r");
+        const metadata = await handle.stat();
+        modifiedAt = metadata.mtime.toISOString();
+        const readLength = Math.min(metadata.size, TRANSCRIPT_EVIDENCE_TAIL_BYTES);
+        const readOffset = Math.max(0, metadata.size - readLength);
+        const buffer = Buffer.alloc(readLength);
+        await handle.read(buffer, 0, readLength, readOffset);
+        raw = buffer.toString("utf8");
+        if (readOffset > 0) {
+            const firstNewline = raw.indexOf("\n");
+            raw = firstNewline >= 0 ? raw.slice(firstNewline + 1) : "";
+        }
+    }
+    catch {
+        return {};
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+    }
+    const turnStartedAtMs = timestampMs(session.lastTurnStartedAt);
+    let lastActivityAt;
+    let completion;
+    for (const line of raw.split("\n")) {
+        if (!line.trim()) {
+            continue;
+        }
+        let record;
+        try {
+            record = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        const timestamp = typeof record.timestamp === "string" ? record.timestamp : undefined;
+        if (timestamp && isLaterTimestamp(timestamp, lastActivityAt)) {
+            lastActivityAt = timestamp;
+        }
+        if (record.type !== "assistant" || !timestamp) {
+            continue;
+        }
+        const message = record.message;
+        if (message?.model === "<synthetic>" || message?.stop_reason !== "end_turn") {
+            continue;
+        }
+        const completionAtMs = timestampMs(timestamp);
+        if (completionAtMs === undefined
+            || (turnStartedAtMs !== undefined && completionAtMs < turnStartedAtMs - TURN_WINDOW_TOLERANCE_MS)) {
+            continue;
+        }
+        if (!completion || isLaterTimestamp(timestamp, completion.timestamp)) {
+            completion = {
+                id: typeof record.uuid === "string" ? record.uuid : null,
+                timestamp
+            };
+        }
+    }
+    if (isLaterTimestamp(modifiedAt, lastActivityAt)) {
+        lastActivityAt = modifiedAt;
+    }
+    return {
+        ...(lastActivityAt ? { lastActivityAt } : {}),
+        ...(completion ? { completion } : {})
+    };
+}
 /** True for a text event that completed a turn (assistant stopped of its own accord). */
 export function isFinalTurnTextEvent(event) {
     return event.stopReason === "end_turn";
@@ -105,3 +180,8 @@ function timestampMs(value) {
     const parsed = Date.parse(value);
     return Number.isFinite(parsed) ? parsed : undefined;
 }
+function isLaterTimestamp(candidate, current) {
+    const candidateMs = timestampMs(candidate);
+    const currentMs = timestampMs(current);
+    return candidateMs !== undefined && (currentMs === undefined || candidateMs > currentMs);
+}

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

@@ -17,6 +17,7 @@ import { renderTesterHarnessRules } from "../templates/harness/tester-agent.js";
 import { renderVcmFinalAcceptanceSkillRules } from "../templates/harness/vcm-final-acceptance-skill.js";
 import { renderVcmHarnessBootstrapSkillRules } from "../templates/harness/vcm-harness-bootstrap-skill.js";
 import { renderVcmLongRunningValidationSkillRules } from "../templates/harness/vcm-long-running-validation-skill.js";
+import { renderVcmProposeMemorySkillRules } from "../templates/harness/vcm-propose-memory-skill.js";
 import { renderVcmReportHarnessIssueSkillRules } from "../templates/harness/vcm-report-harness-issue-skill.js";
 import { renderVcmRouteMessageSkillRules } from "../templates/harness/vcm-route-message-skill.js";
 import { submitTerminalInput } from "../runtime/terminal-submit.js";
@@ -37,7 +38,7 @@ 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,event}));});'"'"' | curl -fsS --max-time 2 -X POST "\${VCM_API_URL}/api/hooks/claude-code" -H "content-type: application/json" --data-binary @- >/dev/null || true'`;
-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,event}));});'"'"' | curl -fsS --max-time 5 -X POST "\${VCM_API_URL}/api/hooks/claude-code/stop" -H "content-type: application/json" --data-binary @- || true'`;
+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,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,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; python3 "$guard" || exit 0'`;
 const VCM_BASH_DEFAULT_TIMEOUT_MS = "600000";
@@ -142,6 +143,14 @@ const HARNESS_FILES = [
         ownership: "whole-file",
         renderRules: renderVcmReportHarnessIssueSkillRules
     },
+    {
+        kind: "skill-vcm-propose-memory",
+        path: ".claude/skills/vcm-propose-memory/SKILL.md",
+        title: "VCM Propose Memory Skill",
+        frontmatter: renderSkillFrontmatter("vcm-propose-memory", "Use only when VCM requests a role memory proposal during Task Harness Review."),
+        ownership: "whole-file",
+        renderRules: renderVcmProposeMemorySkillRules
+    },
     {
         kind: "agent-gate-reviewer",
         path: ".claude/agents/gate-reviewer.md",

package/dist/backend/services/runtime-coordinator-service.js

@@ -1,6 +1,7 @@
 import { isVcmRoleName } from "../../shared/constants.js";
 import { VcmError } from "../errors.js";
 import { getTaskRuntimeRepoRoot } from "./task-service.js";
+const RUNTIME_RECONCILE_INTERVAL_MS = 10_000;
 const EXPECTED_AUTO_RETROSPECTIVE_SKIP_CODES = new Set([
     "HARNESS_FEEDBACK_ACTIVE",
     "TASK_HARNESS_RETROSPECTIVE_EXISTS",
@@ -11,6 +12,9 @@ const EXPECTED_AUTO_RETROSPECTIVE_SKIP_CODES = new Set([
 ]);
 export function createRuntimeCoordinatorService(deps) {
     const locks = new Map();
+    const setTimer = deps.setInterval ?? ((callback, delayMs) => globalThis.setInterval(callback, delayMs));
+    const clearTimer = deps.clearInterval ?? ((timer) => globalThis.clearInterval(timer));
+    let reconcileTimer;
     async function withRepoLock(repoRoot, run) {
         const previous = locks.get(repoRoot) ?? Promise.resolve({
             activeTask: null,
@@ -31,6 +35,22 @@ export function createRuntimeCoordinatorService(deps) {
         }
     }
     return {
+        start() {
+            if (reconcileTimer !== undefined) {
+                return;
+            }
+            reconcileTimer = setTimer(() => {
+                void reconcileCurrentProject().catch(() => undefined);
+            }, RUNTIME_RECONCILE_INTERVAL_MS);
+            void reconcileCurrentProject().catch(() => undefined);
+        },
+        stop() {
+            if (reconcileTimer === undefined) {
+                return;
+            }
+            clearTimer(reconcileTimer);
+            reconcileTimer = undefined;
+        },
         reconcileProject(repoRoot, input = {}) {
             return withRepoLock(repoRoot, async () => {
                 const [activeTask, gatewayStatus] = await Promise.all([
@@ -42,6 +62,8 @@ export function createRuntimeCoordinatorService(deps) {
                     return { activeTask: null, gatewayStatus };
                 }
                 const taskRepoRoot = getTaskRuntimeRepoRoot(activeTask);
+                const stateRoot = await deps.getStateRoot(repoRoot);
+                await deps.turnReconciler.reconcileTask(repoRoot, activeTask, stateRoot);
                 const harnessInitialized = await deps.harnessService.getHarnessStatus(taskRepoRoot)
                     .then((status) => status.initialized)
                     .catch(() => false);
@@ -55,17 +77,28 @@ export function createRuntimeCoordinatorService(deps) {
                 else {
                     await deps.translationService.stopTask(taskRepoRoot, activeTask.taskSlug).catch(() => undefined);
                 }
-                await reconcileAutoMemory(repoRoot, activeTask);
-                if (preferences.autoTaskHarnessReviewEnabled) {
-                    const memoryReadiness = await getTaskRetrospectiveMemoryReadiness(repoRoot, activeTask);
-                    if (memoryReadiness.ready) {
-                        await maybeStartTaskHarnessRetrospective(repoRoot, activeTask);
-                    }
+                await reconcileAutoMemory(repoRoot, activeTask, preferences.autoTaskHarnessReviewEnabled ? "auto" : undefined);
+                const memoryReadiness = await getTaskRetrospectiveMemoryReadiness(repoRoot, activeTask);
+                if ((preferences.autoTaskHarnessReviewEnabled || memoryReadiness.trigger) && memoryReadiness.ready) {
+                    await maybeStartTaskHarnessRetrospective(repoRoot, activeTask, memoryReadiness.trigger ?? "auto");
                 }
                 return { activeTask, gatewayStatus };
             });
         }
     };
+    async function reconcileCurrentProject() {
+        const project = await deps.projectService.getCurrentProject();
+        if (!project) {
+            return;
+        }
+        await withRepoLock(project.repoRoot, async () => {
+            const activeTask = await resolveActiveTask(project.repoRoot);
+            if (activeTask) {
+                await deps.turnReconciler.reconcileTask(project.repoRoot, activeTask, await deps.getStateRoot(project.repoRoot));
+            }
+            return { activeTask, gatewayStatus: null };
+        });
+    }
     async function resolveActiveTask(repoRoot, requestedTaskSlug) {
         const tasks = await deps.taskService.listTasks(repoRoot);
         const activeTasks = tasks.filter((task) => task.cleanupStatus !== "cleaned");
@@ -134,7 +167,7 @@ export function createRuntimeCoordinatorService(deps) {
             throw error;
         }
     }
-    async function maybeStartTaskHarnessRetrospective(repoRoot, task) {
+    async function maybeStartTaskHarnessRetrospective(repoRoot, task, trigger) {
         const stateRoot = await deps.getStateRoot(repoRoot);
         const taskRepoRoot = getTaskRuntimeRepoRoot(task);
         const roundState = await deps.roundService.getSessionRoundState({
@@ -153,7 +186,7 @@ export function createRuntimeCoordinatorService(deps) {
                 taskSlug: task.taskSlug,
                 taskRepoRoot,
                 handoffDir: task.handoffDir,
-                trigger: "auto"
+                trigger
             });
         }
         catch (error) {
@@ -163,7 +196,7 @@ export function createRuntimeCoordinatorService(deps) {
             throw error;
         }
     }
-    async function reconcileAutoMemory(repoRoot, task) {
+    async function reconcileAutoMemory(repoRoot, task, requestTrigger) {
         const stateRoot = await deps.getStateRoot(repoRoot);
         const taskRepoRoot = getTaskRuntimeRepoRoot(task);
         const roundState = await deps.roundService.getSessionRoundState({
@@ -177,6 +210,7 @@ export function createRuntimeCoordinatorService(deps) {
             taskRepoRoot,
             taskSlug: task.taskSlug,
             handoffDir: task.handoffDir,
+            requestTrigger,
             roundReady: roundState.status === "stopped"
                 && Boolean(roundState.roundId)
                 && roundState.roleRecovery?.status !== "failed"

package/dist/backend/services/runtime-recovery-service.js

@@ -22,6 +22,12 @@ export function createRuntimeRecoveryService(deps) {
             await runStep(context, "recover harness bootstrap", () => recoverHarnessBootstrap(repoRoot, recoveredAt, context));
             await runStep(context, "recover harness feedback", () => recoverHarnessFeedback(repoRoot, recoveredAt, context));
             const tasks = await deps.taskService.listTasks(repoRoot);
+            for (const task of tasks.filter((candidate) => candidate.cleanupStatus === "cleaned")) {
+                await runStep(context, `retry cleaned task ${task.taskSlug}`, async () => {
+                    const result = await deps.taskService.cleanupTask(repoRoot, task.taskSlug);
+                    context.warnings.push(...(result.warnings ?? []).map((warning) => `${task.taskSlug}: ${warning}`));
+                });
+            }
             for (const task of tasks.filter((candidate) => candidate.cleanupStatus !== "cleaned")) {
                 const taskRepoRoot = getTaskRuntimeRepoRoot(task);
                 await runStep(context, `recover task ${task.taskSlug}`, async () => {

package/dist/backend/services/task-close-service.js

@@ -0,0 +1,88 @@
+import { VCM_ROLE_NAMES } from "../../shared/constants.js";
+import { VcmError } from "../errors.js";
+import { getTaskRuntimeRepoRoot } from "./task-service.js";
+export function createTaskCloseService(deps) {
+    return {
+        async closeTask(repoRoot, taskSlug) {
+            const task = await deps.taskService.markTaskCleaned(repoRoot, taskSlug);
+            const warnings = [];
+            await stopTaskRoleSessions(repoRoot, taskSlug, warnings);
+            await moveOrStopProjectToolSession("Translator", () => deps.sessionService.moveProjectTranslatorSessionToSafeCwd(repoRoot), () => deps.sessionService.stopProjectTranslatorSession(repoRoot), warnings);
+            await moveOrStopProjectToolSession("Harness Engineer", () => deps.sessionService.moveProjectHarnessEngineerSessionToSafeCwd(repoRoot), () => deps.sessionService.stopProjectHarnessEngineerSession(repoRoot), warnings);
+            await bestEffort("Unable to stop task translation runtime", () => deps.translationService.stopTask(getTaskRuntimeRepoRoot(task), taskSlug, { clearCache: true }), warnings);
+            await bestEffort("Unable to clear task round runtime", () => deps.roundService.stopTask(taskSlug), warnings);
+            try {
+                const result = await deps.taskService.cleanupTask(repoRoot, taskSlug);
+                const combinedWarnings = [...warnings, ...(result.warnings ?? [])];
+                return {
+                    ...result,
+                    warnings: combinedWarnings.length > 0 ? combinedWarnings : undefined
+                };
+            }
+            catch (error) {
+                warnings.push(`Task was closed, but resource cleanup did not finish: ${describeError(error)}`);
+                return {
+                    taskSlug,
+                    taskClosed: true,
+                    worktreeRemoved: false,
+                    branchDeleted: false,
+                    stateRemoved: false,
+                    removedWorktreePath: null,
+                    removedStatePaths: [],
+                    deletedBranch: null,
+                    cleanedAt: task.cleanedAt ?? task.updatedAt,
+                    warnings
+                };
+            }
+        }
+    };
+    async function stopTaskRoleSessions(repoRoot, taskSlug, warnings) {
+        let sessions;
+        try {
+            sessions = await deps.sessionService.listRoleSessions(repoRoot, taskSlug);
+        }
+        catch (error) {
+            warnings.push(`Unable to list task role sessions during close: ${describeError(error)}`);
+            return;
+        }
+        for (const session of sessions) {
+            if (session.status !== "running" || !VCM_ROLE_NAMES.some((role) => role === session.role)) {
+                continue;
+            }
+            await bestEffort(`Unable to stop ${session.role} session`, () => deps.sessionService.stopRoleSession(repoRoot, taskSlug, session.role), warnings);
+        }
+    }
+}
+async function moveOrStopProjectToolSession(label, move, stop, warnings) {
+    try {
+        await move();
+    }
+    catch (error) {
+        if (isMissingSession(error)) {
+            return;
+        }
+        warnings.push(`Unable to move ${label} session to the base repository: ${describeError(error)}`);
+        try {
+            await stop();
+        }
+        catch (stopError) {
+            if (!isMissingSession(stopError)) {
+                warnings.push(`Unable to stop ${label} session after cwd migration failed: ${describeError(stopError)}`);
+            }
+        }
+    }
+}
+async function bestEffort(message, operation, warnings) {
+    try {
+        await operation();
+    }
+    catch (error) {
+        warnings.push(`${message}: ${describeError(error)}`);
+    }
+}
+function isMissingSession(error) {
+    return error instanceof VcmError && error.code === "SESSION_MISSING";
+}
+function describeError(error) {
+    return error instanceof Error ? error.message : String(error);
+}

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

@@ -118,61 +118,130 @@ export function createTaskService(deps) {
             await this.saveTask(repoRoot, updated);
             return updated;
         },
-        async cleanupTask(repoRoot, taskSlug, options = {}) {
-            assertValidTaskSlug(taskSlug);
-            if (!deps.fs.removePath) {
-                throw new VcmError({
-                    code: "FILESYSTEM_REMOVE_UNAVAILABLE",
-                    message: "This VCM runtime cannot remove task files.",
-                    statusCode: 500
-                });
-            }
-            const config = await deps.projectService.loadConfig(repoRoot);
+        async markTaskCleaned(repoRoot, taskSlug) {
             const task = await this.loadTask(repoRoot, taskSlug);
+            if (task.cleanupStatus === "cleaned" && task.cleanedAt) {
+                return task;
+            }
+            const timestamp = now();
+            const updated = {
+                ...task,
+                status: "stopped",
+                cleanupStatus: "cleaned",
+                cleanedAt: timestamp,
+                updatedAt: timestamp
+            };
+            await this.saveTask(repoRoot, updated);
+            return updated;
+        },
+        async cleanupTask(repoRoot, taskSlug) {
+            assertValidTaskSlug(taskSlug);
+            const task = await this.markTaskCleaned(repoRoot, taskSlug);
             const taskRepoRoot = getTaskRuntimeRepoRoot(task);
             const taskStoreRoot = deps.projectService.getProjectDataRoot(repoRoot);
             const taskPath = getTaskPath(taskStoreRoot, taskSlug);
-            const statePaths = getTaskStatePaths(taskStoreRoot, taskRepoRoot, config.stateRoot, config.handoffRoot, taskSlug);
-            const removedStatePaths = [];
             const warnings = [];
-            const cleanedAt = now();
-            assertTaskWorktreePath(repoRoot, task.worktreePath);
-            await removeTaskWorktreeIdempotent(deps.fs, deps.git, repoRoot, task.worktreePath, options.force ?? true, warnings);
-            await deleteTaskBranchIdempotent(deps.git, repoRoot, task.branch, options.forceDeleteBranch ?? true);
+            if (!deps.fs.removePath) {
+                warnings.push("This VCM runtime cannot remove task files; the task remains logically closed.");
+            }
+            let stateRoot = ".ai/vcm";
+            let handoffRoot = task.handoffDir;
+            try {
+                const config = await deps.projectService.loadConfig(repoRoot);
+                stateRoot = config.stateRoot;
+                handoffRoot = config.handoffRoot;
+            }
+            catch (error) {
+                warnings.push(`Unable to load project cleanup paths; using task defaults: ${describeError(error)}`);
+            }
+            const statePaths = getTaskStatePaths(taskStoreRoot, taskRepoRoot, stateRoot, handoffRoot, taskSlug);
+            const removedStatePaths = [];
+            let worktreeRemoved = false;
+            try {
+                assertTaskWorktreePath(repoRoot, task.worktreePath);
+                worktreeRemoved = await removeTaskWorktreeBestEffort(deps.fs, deps.git, repoRoot, task.worktreePath, warnings);
+            }
+            catch (error) {
+                warnings.push(`Skipped unsafe task worktree path ${task.worktreePath}: ${describeError(error)}`);
+            }
+            const branchCleanup = await deleteTaskBranchBestEffort(deps.git, repoRoot, task.branch, warnings);
             for (const statePath of statePaths.filter((candidate) => candidate !== taskPath)) {
                 await removeWorktreeStatePathBestEffort(deps.fs, statePath, removedStatePaths, warnings);
             }
-            await deps.fs.removePath(taskPath, { recursive: true, force: true });
-            removedStatePaths.push(taskPath);
+            let stateRemoved = false;
+            if (worktreeRemoved && branchCleanup.resolved) {
+                try {
+                    await deps.fs.removePath?.(taskPath, { recursive: true, force: true });
+                    stateRemoved = !(await deps.fs.pathExists(taskPath));
+                    if (stateRemoved) {
+                        removedStatePaths.push(taskPath);
+                    }
+                    else {
+                        warnings.push(`Task state remained after cleanup: ${taskPath}`);
+                    }
+                }
+                catch (error) {
+                    warnings.push(`Unable to remove cleaned task state ${taskPath}: ${describeError(error)}`);
+                }
+            }
+            else {
+                warnings.push("Retained cleaned task state so unresolved resource cleanup can be retried later.");
+            }
             return {
                 taskSlug,
-                removedWorktreePath: task.worktreePath,
+                taskClosed: true,
+                worktreeRemoved,
+                branchDeleted: branchCleanup.resolved,
+                stateRemoved,
+                removedWorktreePath: worktreeRemoved ? task.worktreePath : null,
                 removedStatePaths,
-                deletedBranch: task.branch,
-                cleanedAt,
+                deletedBranch: branchCleanup.deleted ? task.branch : null,
+                cleanedAt: task.cleanedAt ?? now(),
                 warnings: warnings.length > 0 ? warnings : undefined
             };
         }
     };
 }
-async function removeTaskWorktreeIdempotent(fs, git, repoRoot, worktreePath, force, warnings) {
-    const wasRegistered = await git.isWorktreeRegistered(repoRoot, worktreePath);
-    if (wasRegistered) {
+async function removeTaskWorktreeBestEffort(fs, git, repoRoot, worktreePath, warnings) {
+    let wasRegistered;
+    try {
+        wasRegistered = await git.isWorktreeRegistered(repoRoot, worktreePath);
+    }
+    catch (error) {
+        warnings.push(`Unable to inspect task worktree registration for ${worktreePath}: ${describeError(error)}`);
+    }
+    if (wasRegistered !== false) {
         try {
-            await git.removeWorktree(repoRoot, worktreePath, { force });
+            await git.removeWorktree(repoRoot, worktreePath, { force: true });
         }
         catch (error) {
             await pruneWorktreesBestEffort(git, repoRoot, warnings);
-            if (await git.isWorktreeRegistered(repoRoot, worktreePath)) {
-                throw error;
+            let stillRegistered = true;
+            try {
+                stillRegistered = await git.isWorktreeRegistered(repoRoot, worktreePath);
+            }
+            catch (inspectionError) {
+                warnings.push(`Unable to verify task worktree registration after forced removal: ${describeError(inspectionError)}`);
+            }
+            if (stillRegistered) {
+                warnings.push(`Unable to force-remove Git worktree ${worktreePath}: ${describeError(error)}`);
+            }
+            else {
+                warnings.push(`Git worktree metadata was already cleared for ${worktreePath}; continuing cleanup.`);
             }
-            warnings.push(`Git worktree metadata was already cleared for ${worktreePath}; continuing cleanup.`);
         }
     }
     else {
         await pruneWorktreesBestEffort(git, repoRoot, warnings);
     }
-    if (await fs.pathExists(worktreePath)) {
+    let staleDirectoryExists = true;
+    try {
+        staleDirectoryExists = await fs.pathExists(worktreePath);
+    }
+    catch (error) {
+        warnings.push(`Unable to inspect stale task worktree directory ${worktreePath}: ${describeError(error)}`);
+    }
+    if (staleDirectoryExists) {
         try {
             await fs.removePath?.(worktreePath, { recursive: true, force: true });
         }
@@ -180,19 +249,67 @@ async function removeTaskWorktreeIdempotent(fs, git, repoRoot, worktreePath, for
             warnings.push(`Unable to remove stale task worktree directory ${worktreePath}: ${describeError(error)}`);
         }
     }
+    let pathExists = true;
+    let registered = true;
+    try {
+        pathExists = await fs.pathExists(worktreePath);
+    }
+    catch (error) {
+        warnings.push(`Unable to verify task worktree directory cleanup: ${describeError(error)}`);
+    }
+    try {
+        registered = await git.isWorktreeRegistered(repoRoot, worktreePath);
+    }
+    catch (error) {
+        warnings.push(`Unable to verify task worktree metadata cleanup: ${describeError(error)}`);
+    }
+    return !pathExists && !registered;
 }
-async function deleteTaskBranchIdempotent(git, repoRoot, branch, force) {
-    if (!(await git.branchExists(repoRoot, branch))) {
-        return;
+async function deleteTaskBranchBestEffort(git, repoRoot, branch, warnings) {
+    let branchExists;
+    try {
+        branchExists = await git.branchExists(repoRoot, branch);
+    }
+    catch (error) {
+        warnings.push(`Unable to inspect task branch ${branch}: ${describeError(error)}`);
     }
+    if (branchExists === false) {
+        return { resolved: true, deleted: false };
+    }
+    await warnAboutDiscardedCommits(git, repoRoot, branch, warnings);
     try {
-        await git.deleteBranch(repoRoot, branch, { force });
+        await git.deleteBranch(repoRoot, branch, { force: true });
+        return { resolved: true, deleted: true };
     }
     catch (error) {
-        if (!(await git.branchExists(repoRoot, branch))) {
+        try {
+            if (!(await git.branchExists(repoRoot, branch))) {
+                return { resolved: true, deleted: true };
+            }
+        }
+        catch (inspectionError) {
+            warnings.push(`Unable to verify task branch cleanup for ${branch}: ${describeError(inspectionError)}`);
+        }
+        warnings.push(`Unable to force-delete task branch ${branch}: ${describeError(error)}`);
+        return { resolved: false, deleted: false };
+    }
+}
+async function warnAboutDiscardedCommits(git, repoRoot, branch, warnings) {
+    try {
+        const baseBranch = await git.getCurrentBranch(repoRoot);
+        const commits = await git.getCommitList(repoRoot, `${baseBranch}..${branch}`);
+        if (commits.length === 0) {
             return;
         }
-        throw error;
+        const summary = commits
+            .slice(0, 5)
+            .map((commit) => `${commit.sha.slice(0, 8)} ${commit.subject}`)
+            .join("; ");
+        const remainder = commits.length > 5 ? `; and ${commits.length - 5} more` : "";
+        warnings.push(`${branch} has ${commits.length} commit(s) not contained in ${baseBranch}; close force-deletes the branch: ${summary}${remainder}`);
+    }
+    catch (error) {
+        warnings.push(`Unable to inspect commits before force-deleting ${branch}: ${describeError(error)}`);
     }
 }
 async function pruneWorktreesBestEffort(git, repoRoot, warnings) {