vibe-coding-master 0.0.6 → 0.0.8

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

@@ -0,0 +1,196 @@
+import path from "node:path";
+import { renderArchitectHarnessRules } from "../templates/harness/architect-agent.js";
+import { renderCoderHarnessRules } from "../templates/harness/coder-agent.js";
+import { renderRootClaudeHarnessRules } from "../templates/harness/claude-root.js";
+import { renderGitignoreHarnessRules } from "../templates/harness/gitignore.js";
+import { renderProjectManagerHarnessRules } from "../templates/harness/project-manager-agent.js";
+import { renderReviewerHarnessRules } from "../templates/harness/reviewer-agent.js";
+export const VCM_HARNESS_VERSION = 1;
+const MANAGED_BLOCK_PATTERN = /<!-- VCM:BEGIN(?:\s+version=(\d+))? -->[\s\S]*?<!-- VCM:END -->/m;
+const HASH_MANAGED_BLOCK_PATTERN = /# VCM:BEGIN(?:\s+version=(\d+))?\n[\s\S]*?# VCM:END/m;
+const HARNESS_FILES = [
+    {
+        kind: "root-claude",
+        path: "CLAUDE.md",
+        title: "CLAUDE.md",
+        renderRules: renderRootClaudeHarnessRules
+    },
+    {
+        kind: "gitignore",
+        path: ".gitignore",
+        title: ".gitignore",
+        commentStyle: "hash",
+        renderRules: renderGitignoreHarnessRules
+    },
+    {
+        kind: "agent-project-manager",
+        path: ".claude/agents/project-manager.md",
+        title: "Project Manager Agent",
+        frontmatter: renderAgentFrontmatter("project-manager", "User-facing VCM orchestration role for task clarification, role routing, handoffs, acceptance, and PR preparation."),
+        renderRules: renderProjectManagerHarnessRules
+    },
+    {
+        kind: "agent-architect",
+        path: ".claude/agents/architect.md",
+        title: "Architect Agent",
+        frontmatter: renderAgentFrontmatter("architect", "VCM architecture role for plans, module boundaries, public contracts, test contracts, and post-review docs sync."),
+        renderRules: renderArchitectHarnessRules
+    },
+    {
+        kind: "agent-coder",
+        path: ".claude/agents/coder.md",
+        title: "Coder Agent",
+        frontmatter: renderAgentFrontmatter("coder", "VCM implementation role for scoped code changes, focused tests, implementation logs, and validation evidence."),
+        renderRules: renderCoderHarnessRules
+    },
+    {
+        kind: "agent-reviewer",
+        path: ".claude/agents/reviewer.md",
+        title: "Reviewer Agent",
+        frontmatter: renderAgentFrontmatter("reviewer", "VCM independent review role for acceptance, test adequacy, scope checks, docs gaps, and risk findings."),
+        renderRules: renderReviewerHarnessRules
+    }
+];
+export function createHarnessService(deps) {
+    return {
+        async getHarnessStatus(repoRoot) {
+            const analyses = await analyzeHarnessFiles(deps.fs, repoRoot);
+            return renderHarnessStatus(analyses);
+        },
+        async applyHarness(repoRoot) {
+            const analyses = await analyzeHarnessFiles(deps.fs, repoRoot);
+            const changedFiles = [];
+            for (const analysis of analyses) {
+                if (analysis.status.action === "ok" || !analysis.nextContent) {
+                    continue;
+                }
+                await deps.fs.writeText(resolveHarnessPath(repoRoot, analysis.definition.path), analysis.nextContent);
+                if (analysis.plannedChange) {
+                    changedFiles.push(analysis.plannedChange);
+                }
+            }
+            return {
+                version: VCM_HARNESS_VERSION,
+                changedFiles,
+                message: changedFiles.length === 0
+                    ? "VCM Harness is already up to date."
+                    : "VCM Harness updated. Review these files and commit the harness changes before starting long-running work."
+            };
+        }
+    };
+}
+async function analyzeHarnessFiles(fs, repoRoot) {
+    const analyses = [];
+    for (const definition of HARNESS_FILES) {
+        analyses.push(await analyzeHarnessFile(fs, repoRoot, definition));
+    }
+    return analyses;
+}
+async function analyzeHarnessFile(fs, repoRoot, definition) {
+    const absolutePath = resolveHarnessPath(repoRoot, definition.path);
+    const expectedBlock = renderManagedBlock(definition, definition.renderRules());
+    const managedBlockPattern = getManagedBlockPattern(definition);
+    const exists = await fs.pathExists(absolutePath);
+    if (!exists) {
+        return {
+            definition,
+            status: {
+                kind: definition.kind,
+                path: definition.path,
+                exists: false,
+                hasManagedBlock: false,
+                action: "create"
+            },
+            plannedChange: {
+                path: definition.path,
+                action: "create",
+                reason: "File is missing; VCM will create a recommended default."
+            },
+            nextContent: renderNewHarnessFile(definition, expectedBlock)
+        };
+    }
+    const currentContent = await fs.readText(absolutePath);
+    const match = currentContent.match(managedBlockPattern);
+    if (!match) {
+        return {
+            definition,
+            status: {
+                kind: definition.kind,
+                path: definition.path,
+                exists: true,
+                hasManagedBlock: false,
+                action: "insert"
+            },
+            plannedChange: {
+                path: definition.path,
+                action: "insert",
+                reason: "File exists but does not contain VCM managed rules."
+            },
+            nextContent: `${currentContent.trimEnd()}\n\n${expectedBlock}\n`
+        };
+    }
+    const managedVersion = match[1] ? Number(match[1]) : undefined;
+    const currentBlock = match[0];
+    const action = currentBlock === expectedBlock ? "ok" : "update";
+    return {
+        definition,
+        status: {
+            kind: definition.kind,
+            path: definition.path,
+            exists: true,
+            hasManagedBlock: true,
+            managedVersion,
+            action
+        },
+        plannedChange: action === "ok"
+            ? undefined
+            : {
+                path: definition.path,
+                action,
+                reason: managedVersion === VCM_HARNESS_VERSION
+                    ? "VCM managed rules differ from the current recommended template."
+                    : `VCM managed block version is ${managedVersion ?? "missing"}; current version is ${VCM_HARNESS_VERSION}.`
+            },
+        nextContent: action === "ok"
+            ? undefined
+            : currentContent.replace(managedBlockPattern, expectedBlock)
+    };
+}
+function renderHarnessStatus(analyses) {
+    const files = analyses.map((analysis) => analysis.status);
+    const plannedChanges = analyses
+        .map((analysis) => analysis.plannedChange)
+        .filter((change) => Boolean(change));
+    return {
+        version: VCM_HARNESS_VERSION,
+        files,
+        needsApply: plannedChanges.length > 0,
+        plannedChanges,
+        warnings: plannedChanges.length > 0
+            ? ["Review and commit VCM Harness changes before starting long-running work."]
+            : []
+    };
+}
+function renderManagedBlock(definition, rules) {
+    if (definition.commentStyle === "hash") {
+        return `# VCM:BEGIN version=${VCM_HARNESS_VERSION}\n${rules.trimEnd()}\n# VCM:END`;
+    }
+    return `<!-- VCM:BEGIN version=${VCM_HARNESS_VERSION} -->\n${rules.trimEnd()}\n<!-- VCM:END -->`;
+}
+function getManagedBlockPattern(definition) {
+    return definition.commentStyle === "hash"
+        ? HASH_MANAGED_BLOCK_PATTERN
+        : MANAGED_BLOCK_PATTERN;
+}
+function renderNewHarnessFile(definition, block) {
+    const frontmatter = definition.frontmatter
+        ? `${definition.frontmatter.trimEnd()}\n\n`
+        : "";
+    return `${frontmatter}# ${definition.title}\n\n${block}\n`;
+}
+function renderAgentFrontmatter(name, description) {
+    return `---\nname: ${name}\ndescription: ${description}\ntools: Read, Grep, Glob, Bash, Edit, Write\n---`;
+}
+function resolveHarnessPath(repoRoot, relativePath) {
+    return path.join(repoRoot, relativePath);
+}

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

@@ -30,7 +30,7 @@ export function createMessageService(deps) {
                 status: "queued",
                 createdAt: timestamp
             };
-            message.bodyPath = await writeMessageBody(deps.fs, input.repoRoot, input.handoffDir, message);
+            message.bodyPath = await writeMessageBody(deps.fs, input.taskRepoRoot ?? input.repoRoot, input.handoffDir, message);
             const state = await this.getOrchestrationState(input);
             const session = await deps.sessionService.getRoleSession(input.repoRoot, input.taskSlug, input.toRole);
             if (!session || session.status !== "running") {

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

@@ -1,8 +1,22 @@
 import path from "node:path";
 import { ROLE_NAMES } from "../../shared/constants.js";
 import { VcmError } from "../errors.js";
+const DEFAULT_HANDOFF_ROOT = ".ai/handoffs";
+const DEFAULT_STATE_ROOT = ".ai/vcm";
+const LEGACY_STATE_ROOT = ".vcm";
 export function createProjectService(deps) {
     let currentProject = null;
+    async function migrateLegacyStateRoot(repoRoot) {
+        if (!deps.fs.copyDir) {
+            return;
+        }
+        const legacyStateRoot = path.join(repoRoot, LEGACY_STATE_ROOT);
+        const currentStateRoot = path.join(repoRoot, DEFAULT_STATE_ROOT);
+        if (!(await deps.fs.pathExists(legacyStateRoot)) || await deps.fs.pathExists(currentStateRoot)) {
+            return;
+        }
+        await deps.fs.copyDir(legacyStateRoot, currentStateRoot);
+    }
     return {
         async connectProject(input) {
             const requestedPath = input.repoPath.trim();
@@ -26,10 +40,13 @@ export function createProjectService(deps) {
                     statusCode: 400
                 });
             }
-            const config = buildDefaultProjectConfig(repoRoot);
+            const config = await this.loadConfig(repoRoot);
             await deps.fs.ensureDir(path.join(repoRoot, config.handoffRoot));
             await deps.fs.ensureDir(path.join(repoRoot, config.stateRoot, "tasks"));
             await deps.fs.ensureDir(path.join(repoRoot, config.stateRoot, "sessions"));
+            await deps.fs.ensureDir(path.join(repoRoot, config.stateRoot, "messages"));
+            await deps.fs.ensureDir(path.join(repoRoot, config.stateRoot, "orchestration"));
+            await deps.fs.ensureDir(path.join(repoRoot, config.stateRoot, "worktrees"));
             await this.saveConfig(config, true);
             const warnings = [];
             let branch = "unknown";
@@ -59,27 +76,39 @@ export function createProjectService(deps) {
                 config,
                 warnings
             };
+            await deps.appSettings.recordRecentRepositoryPath(repoRoot);
             return currentProject;
         },
         async getCurrentProject() {
             return currentProject;
         },
+        async getRecentRepositoryPaths() {
+            return deps.appSettings.getRecentRepositoryPaths();
+        },
         async loadConfig(repoRoot) {
             const configPath = this.getConfigPath(repoRoot);
-            if (!(await deps.fs.pathExists(configPath))) {
-                return buildDefaultProjectConfig(repoRoot);
+            if (await deps.fs.pathExists(configPath)) {
+                return normalizeProjectConfig(await deps.fs.readJson(configPath), repoRoot);
+            }
+            const legacyConfigPath = path.join(repoRoot, LEGACY_STATE_ROOT, "config.json");
+            if (await deps.fs.pathExists(legacyConfigPath)) {
+                const migratedConfig = normalizeProjectConfig(await deps.fs.readJson(legacyConfigPath), repoRoot);
+                await migrateLegacyStateRoot(repoRoot);
+                await this.saveConfig(migratedConfig, true);
+                return migratedConfig;
             }
-            return deps.fs.readJson(configPath);
+            return buildDefaultProjectConfig(repoRoot);
         },
         async saveConfig(config, force = false) {
-            const configPath = this.getConfigPath(config.repoRoot);
+            const normalizedConfig = normalizeProjectConfig(config, config.repoRoot);
+            const configPath = this.getConfigPath(normalizedConfig.repoRoot);
             if (!force && await deps.fs.pathExists(configPath)) {
                 return;
             }
-            await deps.fs.writeJsonAtomic(configPath, config);
+            await deps.fs.writeJsonAtomic(configPath, normalizedConfig);
         },
         getConfigPath(repoRoot) {
-            return path.join(repoRoot, ".vcm", "config.json");
+            return path.join(repoRoot, DEFAULT_STATE_ROOT, "config.json");
         }
     };
 }
@@ -97,9 +126,21 @@ export function buildDefaultProjectConfig(repoRoot) {
         version: 1,
         repoRoot,
         defaultRoles: [...ROLE_NAMES],
-        handoffRoot: ".ai/handoffs",
-        stateRoot: ".vcm",
+        handoffRoot: DEFAULT_HANDOFF_ROOT,
+        stateRoot: DEFAULT_STATE_ROOT,
         terminalBackend: "node-pty",
         claudeCommand: process.env.VCM_CLAUDE_COMMAND || "claude"
     };
 }
+function normalizeProjectConfig(input, repoRoot) {
+    const fallback = buildDefaultProjectConfig(repoRoot);
+    return {
+        version: 1,
+        repoRoot,
+        defaultRoles: input.defaultRoles?.length ? input.defaultRoles : fallback.defaultRoles,
+        handoffRoot: input.handoffRoot || fallback.handoffRoot,
+        stateRoot: DEFAULT_STATE_ROOT,
+        terminalBackend: "node-pty",
+        claudeCommand: input.claudeCommand || fallback.claudeCommand
+    };
+}

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

@@ -3,7 +3,8 @@ import path from "node:path";
 import { ROLE_NAMES, isDispatchableRole } from "../../shared/constants.js";
 import { VcmError } from "../errors.js";
 import { resolveRepoPath } from "../adapters/filesystem.js";
-import { renderRoleMessagingContext } from "../templates/role-messaging-context.js";
+import { claudeTranscriptPath } from "./claude-transcript-service.js";
+import { getTaskRuntimeRepoRoot } from "./task-service.js";
 export function createSessionService(deps) {
     const now = deps.now ?? (() => new Date().toISOString());
     async function launchRoleSession(repoRoot, taskSlug, role, input, launchMode) {
@@ -13,7 +14,8 @@ export function createSessionService(deps) {
         }
         const config = await deps.projectService.loadConfig(repoRoot);
         const task = await deps.taskService.loadTask(repoRoot, taskSlug);
-        const paths = deps.artifactService.getHandoffPaths(repoRoot, task.handoffDir);
+        const taskRepoRoot = getTaskRuntimeRepoRoot(task);
+        const paths = deps.artifactService.getHandoffPaths(taskRepoRoot, task.handoffDir);
         const persisted = await loadPersistedRoleRecord(deps.fs, repoRoot, config.stateRoot, taskSlug, role);
         const permissionMode = input.permissionMode ?? persisted?.permissionMode ?? "default";
         const claudeSessionId = launchMode === "resume"
@@ -27,13 +29,16 @@ export function createSessionService(deps) {
                 hint: "Start the role once before using Resume."
             });
         }
+        const transcriptPath = launchMode === "resume" && persisted?.transcriptPath
+            ? persisted.transcriptPath
+            : claudeTranscriptPath(taskRepoRoot, claudeSessionId);
         const startCommand = deps.claude.buildRoleStartCommand(role, config.claudeCommand, permissionMode, claudeSessionId, launchMode === "resume");
         const runtimeSession = await deps.runtime.createSession({
             taskSlug,
             role,
             command: startCommand.command,
             args: startCommand.args,
-            cwd: repoRoot,
+            cwd: taskRepoRoot,
             env: {
                 VCM_API_URL: deps.apiUrl,
                 VCM_CTL_COMMAND: deps.vcmctlCommand,
@@ -42,18 +47,19 @@ export function createSessionService(deps) {
             },
             cols: input.cols,
             rows: input.rows,
-            logPath: resolveRepoPath(repoRoot, paths.roleLogPaths[role])
+            logPath: resolveRepoPath(taskRepoRoot, paths.roleLogPaths[role])
         });
         const timestamp = now();
         const record = {
             id: runtimeSession.id,
             claudeSessionId,
+            transcriptPath,
             taskSlug,
             role,
             status: runtimeSession.status,
             command: startCommand.display,
             permissionMode,
-            cwd: repoRoot,
+            cwd: taskRepoRoot,
             terminalBackend: "node-pty",
             pid: runtimeSession.pid,
             logPath: paths.roleLogPaths[role],
@@ -69,7 +75,6 @@ export function createSessionService(deps) {
         deps.registry.upsert(record);
         await persistTaskSession(deps.fs, repoRoot, config.stateRoot, record);
         await deps.taskService.updateTaskStatus(repoRoot, taskSlug, "running");
-        deps.runtime.write(runtimeSession.id, `${renderRoleMessagingContext(task, paths, role, deps.vcmctlCommand)}\r`);
         return record;
     }
     return {
@@ -110,9 +115,7 @@ export function createSessionService(deps) {
                 await deps.runtime.stop(existing.id);
             }
             deps.registry.remove(existing.id);
-            return existing.claudeSessionId
-                ? launchRoleSession(repoRoot, taskSlug, role, input, "resume")
-                : launchRoleSession(repoRoot, taskSlug, role, input, "fresh");
+            return launchRoleSession(repoRoot, taskSlug, role, input, "fresh");
         },
         async getRoleSession(repoRoot, taskSlug, role) {
             const config = await deps.projectService.loadConfig(repoRoot);
@@ -197,6 +200,7 @@ async function persistTaskSession(fs, repoRoot, stateRoot, session) {
             [session.role]: {
                 id: session.id,
                 claudeSessionId: session.claudeSessionId,
+                transcriptPath: session.transcriptPath,
                 status: session.status,
                 record
             }

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

@@ -1,9 +1,11 @@
+import { getTaskRuntimeRepoRoot } from "./task-service.js";
 export function createStatusService(deps) {
     return {
         async getTaskStatus(repoRoot, taskSlug) {
             const task = await deps.taskService.loadTask(repoRoot, taskSlug);
+            const taskRepoRoot = getTaskRuntimeRepoRoot(task);
             const artifacts = await deps.artifactService.listArtifacts({
-                repoRoot,
+                repoRoot: taskRepoRoot,
                 handoffDir: task.handoffDir
             });
             const sessions = await deps.sessionService.listRoleSessions(repoRoot, taskSlug);
@@ -14,8 +16,84 @@ export function createStatusService(deps) {
                 task,
                 sessions,
                 artifacts,
+                workflow: buildWorkflowReport(artifacts, sessions),
                 warnings
             };
         }
     };
 }
+function buildWorkflowReport(artifacts, sessions) {
+    const isComplete = (kind) => artifacts.checks.find((check) => check.kind === kind)?.status === "ok";
+    const roleIsRunning = (role) => sessions.some((session) => session.role === role && session.status === "running");
+    const architectureComplete = isComplete("architecture-plan");
+    const implementationComplete = isComplete("implementation-log") && isComplete("validation-log");
+    const reviewComplete = isComplete("review-report");
+    const docsSyncComplete = isComplete("docs-sync-report");
+    const steps = [
+        {
+            id: "architecture-plan",
+            label: "Architecture",
+            role: "architect",
+            artifactPaths: [artifacts.paths.architecturePlanPath],
+            status: architectureComplete ? "complete" : "ready",
+            detail: architectureComplete
+                ? "architecture-plan.md is ready."
+                : roleIsRunning("architect")
+                    ? "Architect is running; produce architecture-plan.md before coder work."
+                    : "Start architect and produce architecture-plan.md before coder work."
+        },
+        {
+            id: "implementation",
+            label: "Implementation",
+            role: "coder",
+            artifactPaths: [artifacts.paths.implementationLogPath, artifacts.paths.validationLogPath],
+            status: implementationComplete ? "complete" : architectureComplete ? "ready" : "blocked",
+            detail: implementationComplete
+                ? "implementation-log.md and validation-log.md are ready."
+                : architectureComplete
+                    ? "Start coder, then update implementation-log.md and validation-log.md."
+                    : "Blocked until architecture-plan.md is complete."
+        },
+        {
+            id: "review",
+            label: "Review",
+            role: "reviewer",
+            artifactPaths: [artifacts.paths.reviewReportPath],
+            status: reviewComplete ? "complete" : implementationComplete ? "ready" : "blocked",
+            detail: reviewComplete
+                ? "review-report.md is ready."
+                : implementationComplete
+                    ? "Start reviewer for independent review and final test adequacy."
+                    : "Blocked until implementation-log.md and validation-log.md are complete."
+        },
+        {
+            id: "docs-sync",
+            label: "Docs Sync",
+            role: "architect",
+            artifactPaths: [artifacts.paths.docsSyncReportPath],
+            status: docsSyncComplete ? "complete" : reviewComplete ? "ready" : "blocked",
+            detail: docsSyncComplete
+                ? "docs-sync-report.md is ready."
+                : reviewComplete
+                    ? "Send architect a docs-sync / architecture drift check task."
+                    : "Blocked until review-report.md is complete."
+        },
+        {
+            id: "final-acceptance",
+            label: "PM Final",
+            role: "project-manager",
+            artifactPaths: [],
+            status: docsSyncComplete ? "ready" : "blocked",
+            detail: docsSyncComplete
+                ? "Project Manager can prepare final acceptance, commit, and PR."
+                : "Blocked until architect docs sync is complete."
+        }
+    ];
+    const current = steps.find((step) => step.status !== "complete") ?? steps[steps.length - 1];
+    return {
+        currentStepId: current.id,
+        nextAction: current.detail,
+        blocked: current.status === "blocked",
+        steps
+    };
+}

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

@@ -8,6 +8,8 @@ export function createTaskService(deps) {
             assertValidTaskSlug(input.taskSlug);
             const config = await deps.projectService.loadConfig(repoRoot);
             const taskPath = getTaskPath(repoRoot, config.stateRoot, input.taskSlug);
+            const branch = `feature/${input.taskSlug}`;
+            const worktreePath = getTaskWorktreePath(repoRoot, config.stateRoot, input.taskSlug);
             if (await deps.fs.pathExists(taskPath)) {
                 throw new VcmError({
                     code: "TASK_EXISTS",
@@ -15,6 +17,46 @@ export function createTaskService(deps) {
                     statusCode: 409
                 });
             }
+            if (await deps.git.branchExists(repoRoot, branch)) {
+                throw new VcmError({
+                    code: "TASK_BRANCH_EXISTS",
+                    message: `Task branch already exists: ${branch}`,
+                    statusCode: 409,
+                    hint: "Choose a different task name or clean up the existing branch."
+                });
+            }
+            if (await deps.fs.pathExists(worktreePath)) {
+                throw new VcmError({
+                    code: "TASK_WORKTREE_EXISTS",
+                    message: `Task worktree already exists: ${worktreePath}`,
+                    statusCode: 409,
+                    hint: "Choose a different task name or clean up the existing worktree."
+                });
+            }
+            if (!(await deps.git.isIgnored(repoRoot, `${config.stateRoot}/config.json`))) {
+                throw new VcmError({
+                    code: "VCM_STATE_NOT_IGNORED",
+                    message: `${config.stateRoot}/ is not ignored by Git.`,
+                    statusCode: 409,
+                    hint: "Apply VCM Harness first so .gitignore contains the VCM managed block."
+                });
+            }
+            const baseStatus = await deps.git.getStatusPorcelain(repoRoot);
+            if (baseStatus.trim()) {
+                throw new VcmError({
+                    code: "BASE_REPO_DIRTY",
+                    message: "The connected repository has uncommitted changes.",
+                    statusCode: 409,
+                    hint: "Commit, stash, or discard base repository changes before creating a task worktree."
+                });
+            }
+            await deps.fs.ensureDir(path.dirname(worktreePath));
+            await deps.git.createWorktree({
+                repoRoot,
+                branch,
+                worktreePath,
+                baseRef: "HEAD"
+            });
             const timestamp = now();
             const task = {
                 version: 1,
@@ -23,18 +65,20 @@ export function createTaskService(deps) {
                 createdAt: timestamp,
                 updatedAt: timestamp,
                 repoRoot,
-                branch: await deps.git.getCurrentBranch(repoRoot),
+                worktreePath,
+                branch,
                 handoffDir: path.posix.join(config.handoffRoot, input.taskSlug),
                 status: "created",
-                specPath: input.specPath
+                specPath: input.specPath,
+                cleanupStatus: "active"
             };
             await deps.artifactService.ensureHandoffStructure({
-                repoRoot,
+                repoRoot: worktreePath,
                 taskSlug: input.taskSlug,
                 handoffDir: task.handoffDir
             });
             await deps.artifactService.createArtifactTemplates({
-                repoRoot,
+                repoRoot: worktreePath,
                 taskSlug: input.taskSlug,
                 handoffDir: task.handoffDir
             });
@@ -80,9 +124,79 @@ 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);
+            const task = await this.loadTask(repoRoot, taskSlug);
+            const removedStatePaths = [];
+            const cleanedAt = now();
+            if (task.worktreePath) {
+                assertTaskWorktreePath(repoRoot, config.stateRoot, task.worktreePath);
+                const status = await deps.git.getStatusPorcelain(task.worktreePath);
+                if (status.trim() && !options.force) {
+                    throw new VcmError({
+                        code: "TASK_WORKTREE_DIRTY",
+                        message: `Task worktree has uncommitted changes: ${task.worktreePath}`,
+                        statusCode: 409,
+                        hint: "Commit, stash, or discard the task worktree changes before cleanup, or retry with force."
+                    });
+                }
+                await deps.git.removeWorktree(repoRoot, task.worktreePath, { force: options.force });
+            }
+            for (const statePath of getTaskStatePaths(repoRoot, config.stateRoot, taskSlug)) {
+                await deps.fs.removePath(statePath, { force: true });
+                removedStatePaths.push(statePath);
+            }
+            let deletedBranch;
+            if (options.deleteBranch) {
+                await deps.git.deleteBranch(repoRoot, task.branch, { force: options.forceDeleteBranch });
+                deletedBranch = task.branch;
+            }
+            return {
+                taskSlug,
+                removedWorktreePath: task.worktreePath,
+                removedStatePaths,
+                deletedBranch,
+                cleanedAt
+            };
         }
     };
 }
+export function getTaskRuntimeRepoRoot(task) {
+    return task.worktreePath ?? task.repoRoot;
+}
 function getTaskPath(repoRoot, stateRoot, taskSlug) {
     return path.join(repoRoot, stateRoot, "tasks", `${taskSlug}.json`);
 }
+function getTaskWorktreePath(repoRoot, stateRoot, taskSlug) {
+    return path.join(repoRoot, stateRoot, "worktrees", taskSlug);
+}
+function getTaskStatePaths(repoRoot, stateRoot, taskSlug) {
+    return [
+        path.join(repoRoot, stateRoot, "tasks", `${taskSlug}.json`),
+        path.join(repoRoot, stateRoot, "sessions", `${taskSlug}.json`),
+        path.join(repoRoot, stateRoot, "messages", `${taskSlug}.jsonl`),
+        path.join(repoRoot, stateRoot, "orchestration", `${taskSlug}.json`)
+    ];
+}
+function assertTaskWorktreePath(repoRoot, stateRoot, worktreePath) {
+    const worktreeRoot = path.resolve(repoRoot, stateRoot, "worktrees");
+    const resolvedWorktreePath = path.resolve(worktreePath);
+    const relative = path.relative(worktreeRoot, resolvedWorktreePath);
+    if (relative.startsWith("..") || path.isAbsolute(relative) || relative === "") {
+        throw new VcmError({
+            code: "TASK_WORKTREE_PATH_INVALID",
+            message: `Refusing to clean up worktree outside ${worktreeRoot}.`,
+            statusCode: 400,
+            hint: resolvedWorktreePath
+        });
+    }
+}