@voybio/ace-swarm 2.4.0 → 2.4.1

package/dist/tools-files.js

@@ -1,10 +1,12 @@
 /**
  * File operation tool registrations + new safe-edit and diff tools.
  */
-import { mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { createHash, randomUUID } from "node:crypto";
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, isAbsolute, relative, resolve } from "node:path";
 import { z } from "zod";
-import { ACE_TASKS_ROOT_REL, normalizePathForValidation, safeRead, safeWriteAsync, safeWrite, resolveStoreFallbackKeysForPath, wsPath, WORKSPACE_ROOT, } from "./helpers.js";
+import { ACE_TASKS_ROOT_REL, normalizePathForValidation, safeRead, safeWriteAsync, safeWrite, resolveWorkspaceWritePath, resolveStoreFallbackKeysForPath, wsPath, WORKSPACE_ROOT, } from "./helpers.js";
 import { isInside, looksLikeSwarmHandoffPath, normalizeRelPath } from "./shared.js";
 import { validateAgentStateHandoffPayload, validateArtifactManifestPayload, validateProvenanceLogContent, validateStatusEventsNdjsonContent, validateSwarmHandoffPayload, validateTealConfigContent, validateRuntimeExecutorSessionRegistryPayload, validateRuntimeToolSpecRegistryPayload, validateTrackerSnapshotPayload, validateVericifyBridgeSnapshotPayload, validateVericifyProcessPostLogPayload, validateWorkspaceSessionRegistryPayload, lintHandoffPayload, } from "./schemas.js";
 import { syncTodoStateSafe } from "./todo-state.js";
@@ -12,8 +14,42 @@ import { shouldAutoRefreshKanbanForPath, refreshKanbanArtifacts, } from "./kanba
 import { appendRunLedgerEntrySafe } from "./run-ledger.js";
 import { appendStatusEventSafe } from "./status-events.js";
 import { safeEditFile, diffContents, applyPatch } from "./safe-edit.js";
+import { detectAstgrepCommand, locateAstgrepMatches, runAstgrepQuery, } from "./astgrep-index.js";
 import { readRuntimeProfile, resolveEffectiveSurgicalReadBudget, validateRuntimeProfileContent, } from "./runtime-profile.js";
 import { withLocalModelRuntimeRepository } from "./store/repositories/local-model-runtime-repository.js";
+function reasonCodeFromError(error) {
+    return typeof error === "object" && error !== null && "reason_code" in error
+        ? String(error.reason_code)
+        : undefined;
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+async function appendWriteWorkspaceRejection(input) {
+    await appendRunLedgerEntrySafe({
+        tool: "write_workspace_file",
+        category: "regression",
+        message: input.message,
+        artifacts: [],
+        metadata: {
+            reason_code: input.reason_code,
+            path: input.path,
+            workspace_path: input.workspace_path,
+        },
+    }).catch(() => undefined);
+    await appendStatusEventSafe({
+        source_module: "capability-safety",
+        event_type: "WORKSPACE_WRITE_REJECTED",
+        status: "blocked",
+        summary: input.message,
+        objective_id: "workspace-write-safety",
+        payload: {
+            reason_code: input.reason_code,
+            path: input.path,
+            workspace_path: input.workspace_path,
+        },
+    }).catch(() => undefined);
+}
 export function planAstgrepRewriteTargets(files) {
     const affected = [...new Set(files.filter(Boolean))].sort((a, b) => a.localeCompare(b));
     if (affected.length > 1) {
@@ -50,6 +86,370 @@ function astgrepFileToWorkspaceRel(file) {
         return undefined;
     return normalizeRelPath(relative(WORKSPACE_ROOT, abs));
 }
+const STRUCTURAL_EDIT_ARTIFACTS_REL = "agent-state/structural-edits";
+function contentSha256(content) {
+    return `sha256:${createHash("sha256").update(content, "utf8").digest("hex")}`;
+}
+function structuralEditArtifactRelPath(prefix, id) {
+    return `${STRUCTURAL_EDIT_ARTIFACTS_REL}/${prefix}-${id}.json`;
+}
+async function writeJsonArtifact(artifact) {
+    await safeWriteAsync(artifact.artifact_path, JSON.stringify(artifact, null, 2));
+    return artifact;
+}
+function readJsonArtifact(relPath) {
+    const raw = safeRead(relPath);
+    if (raw.startsWith("[FILE NOT FOUND]") || raw.startsWith("[ACCESS DENIED]"))
+        return undefined;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+}
+function jsonResponse(payload, isError = false) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
+        ...(isError ? { isError: true } : {}),
+    };
+}
+async function storeLocateArtifact(input, result) {
+    const locatorId = randomUUID();
+    return writeJsonArtifact({
+        version: 1,
+        kind: "astgrep_locate",
+        locator_id: locatorId,
+        created_at: new Date().toISOString(),
+        artifact_path: structuralEditArtifactRelPath("locate", locatorId),
+        input,
+        astgrep_command: result.astgrep_command,
+        total_matches: result.total_matches,
+        matches: result.matches,
+    });
+}
+function listStructuralEditArtifacts(prefix) {
+    const dir = wsPath(STRUCTURAL_EDIT_ARTIFACTS_REL);
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir)
+        .filter((name) => name.startsWith(`${prefix}-`) && name.endsWith(".json"))
+        .sort((a, b) => b.localeCompare(a))
+        .map((name) => normalizeRelPath(relative(WORKSPACE_ROOT, resolve(dir, name))));
+}
+function findStoredMatch(matchId) {
+    for (const relPath of listStructuralEditArtifacts("locate")) {
+        const artifact = readJsonArtifact(relPath);
+        if (!artifact)
+            continue;
+        const match = artifact.matches.find((candidate) => candidate.match_id === matchId);
+        if (match)
+            return { artifact, match };
+    }
+    return undefined;
+}
+function loadStructuralEditPlan(planId) {
+    return readJsonArtifact(structuralEditArtifactRelPath("plan", planId));
+}
+function planScopeFromMatches(matches) {
+    return [...new Set(matches.map((match) => match.file))].sort((a, b) => a.localeCompare(b));
+}
+function rewriteCaptureRefs(rewriteTemplate) {
+    const refs = new Set();
+    const regex = /\$([A-Z][A-Z0-9_]*)/g;
+    let match;
+    while ((match = regex.exec(rewriteTemplate)) !== null) {
+        refs.add(match[1]);
+    }
+    return [...refs].sort((a, b) => a.localeCompare(b));
+}
+function missingRewriteCaptures(rewriteTemplate, captures) {
+    const available = new Set(Object.keys(captures ?? {}));
+    return rewriteCaptureRefs(rewriteTemplate).filter((ref) => !available.has(ref));
+}
+async function compileStructuralEditPlan(input) {
+    const scopedMatches = input.selectedMatch
+        ? input.locateArtifact.matches.filter((match) => match.file === input.selectedMatch?.file)
+        : input.locateArtifact.matches;
+    const targetFile = input.selectedMatch?.file ?? scopedMatches[0]?.file ?? "";
+    const selectedMatch = input.selectedMatch ?? scopedMatches.find((match) => match.file === targetFile) ?? scopedMatches[0];
+    const rewriteTemplate = input.rewriteTemplate ?? input.desiredChange;
+    const missingCaptures = missingRewriteCaptures(rewriteTemplate, selectedMatch?.captures);
+    if (missingCaptures.length > 0) {
+        throw new Error(`bad_capture: rewrite references missing capture(s): ${missingCaptures.join(", ")}`);
+    }
+    const planId = randomUUID();
+    return writeJsonArtifact({
+        version: 1,
+        kind: "astgrep_edit_plan",
+        plan_id: planId,
+        created_at: new Date().toISOString(),
+        artifact_path: structuralEditArtifactRelPath("plan", planId),
+        locator_artifact_path: input.locateArtifact.artifact_path,
+        locator: input.locator,
+        target: {
+            file: targetFile,
+            file_hash: selectedMatch?.file_hash ?? "sha256:none",
+            selected_match_id: selectedMatch?.match_id,
+            selected_range: selectedMatch?.range,
+            selected_text_preview: selectedMatch?.text_preview,
+            captures: selectedMatch?.captures,
+            node_kind: selectedMatch?.node_kind,
+            match_count_in_file: scopedMatches.length,
+            scope_match_count: input.locateArtifact.matches.length,
+            scope_affected_files: planScopeFromMatches(input.locateArtifact.matches),
+        },
+        rewrite: {
+            desired_change: input.desiredChange,
+            rewrite_template: rewriteTemplate,
+            rewrite_source: input.rewriteTemplate ? "rewrite_template" : "desired_change",
+        },
+        validation_command: input.validationCommand,
+        test_command: input.testCommand,
+    });
+}
+function previewDiffText(diffText) {
+    const lines = diffText.trimEnd().split("\n");
+    const limited = lines.slice(0, 80).join("\n");
+    const bounded = limited.slice(0, 4000);
+    return bounded.length < diffText.length ? `${bounded}\n…` : bounded;
+}
+function parseChangedRanges(diffText) {
+    const ranges = [];
+    const regex = /^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/gm;
+    let match;
+    while ((match = regex.exec(diffText)) !== null) {
+        const originalStart = Number(match[1] ?? "0");
+        const originalLength = Number(match[2] ?? "1");
+        const updatedStart = Number(match[3] ?? "0");
+        const updatedLength = Number(match[4] ?? "1");
+        ranges.push({
+            original_start_line: originalStart,
+            original_end_line: Math.max(originalStart, originalStart + Math.max(originalLength, 1) - 1),
+            updated_start_line: updatedStart,
+            updated_end_line: Math.max(updatedStart, updatedStart + Math.max(updatedLength, 1) - 1),
+        });
+    }
+    return ranges;
+}
+async function buildStructuralPreview(plan) {
+    const previewId = randomUUID();
+    const artifactPath = structuralEditArtifactRelPath("preview", previewId);
+    const finalize = (artifact) => writeJsonArtifact({
+        version: 1,
+        kind: "astgrep_preview",
+        preview_id: previewId,
+        created_at: new Date().toISOString(),
+        artifact_path: artifactPath,
+        plan_id: plan.plan_id,
+        ...artifact,
+    });
+    const currentContent = safeRead(plan.target.file);
+    if (currentContent.startsWith("[FILE NOT FOUND]") || currentContent.startsWith("[ACCESS DENIED]")) {
+        return {
+            artifact: await finalize({
+                ok: false,
+                reason_code: "target_unreadable",
+                error: `Cannot read ${plan.target.file}`,
+                target_file: plan.target.file,
+                expected_file_hash: plan.target.file_hash,
+                matched_count: 0,
+                affected_file_count: 0,
+                changed_ranges: [],
+                diff_summary: "",
+                diff_preview: "",
+                promotable: false,
+            }),
+        };
+    }
+    const currentFileHash = contentSha256(currentContent);
+    if (currentFileHash !== plan.target.file_hash) {
+        return {
+            artifact: await finalize({
+                ok: false,
+                reason_code: "stale_hash",
+                error: `Plan ${plan.plan_id} is stale for ${plan.target.file}`,
+                target_file: plan.target.file,
+                expected_file_hash: plan.target.file_hash,
+                current_file_hash: currentFileHash,
+                matched_count: 0,
+                affected_file_count: 0,
+                changed_ranges: [],
+                diff_summary: "",
+                diff_preview: "",
+                promotable: false,
+            }),
+        };
+    }
+    let locateResult;
+    try {
+        locateResult = locateAstgrepMatches(plan.locator);
+    }
+    catch (error) {
+        return {
+            artifact: await finalize({
+                ok: false,
+                reason_code: "scope_escape",
+                error: error instanceof Error ? error.message : String(error),
+                target_file: plan.target.file,
+                expected_file_hash: plan.target.file_hash,
+                current_file_hash: currentFileHash,
+                matched_count: 0,
+                affected_file_count: 0,
+                changed_ranges: [],
+                diff_summary: "",
+                diff_preview: "",
+                promotable: false,
+            }),
+        };
+    }
+    if (!locateResult.ok) {
+        return {
+            artifact: await finalize({
+                ok: false,
+                reason_code: "locate_failed",
+                error: locateResult.error ?? "Failed to locate structural matches",
+                target_file: plan.target.file,
+                expected_file_hash: plan.target.file_hash,
+                current_file_hash: currentFileHash,
+                matched_count: 0,
+                affected_file_count: 0,
+                changed_ranges: [],
+                diff_summary: "",
+                diff_preview: "",
+                promotable: false,
+            }),
+        };
+    }
+    if (locateResult.matches.length === 0) {
+        return {
+            artifact: await finalize({
+                ok: false,
+                reason_code: "no_matches",
+                error: `No matches found for plan ${plan.plan_id}`,
+                target_file: plan.target.file,
+                expected_file_hash: plan.target.file_hash,
+                current_file_hash: currentFileHash,
+                matched_count: 0,
+                affected_file_count: 0,
+                changed_ranges: [],
+                diff_summary: "",
+                diff_preview: "",
+                promotable: false,
+            }),
+        };
+    }
+    const affectedFiles = planScopeFromMatches(locateResult.matches);
+    const targetPlan = planAstgrepRewriteTargets(affectedFiles);
+    if (!targetPlan.ok) {
+        return {
+            artifact: await finalize({
+                ok: false,
+                reason_code: "ambiguous_multi_file",
+                error: targetPlan.error ?? "astgrep_rewrite refused a multi-file preview",
+                target_file: plan.target.file,
+                expected_file_hash: plan.target.file_hash,
+                current_file_hash: currentFileHash,
+                matched_count: locateResult.matches.length,
+                affected_file_count: affectedFiles.length,
+                changed_ranges: [],
+                diff_summary: "",
+                diff_preview: "",
+                promotable: false,
+            }),
+        };
+    }
+    const targetMatches = locateResult.matches.filter((match) => match.file === plan.target.file);
+    if (targetMatches.length === 0) {
+        return {
+            artifact: await finalize({
+                ok: false,
+                reason_code: "target_mismatch",
+                error: `Plan ${plan.plan_id} no longer resolves ${plan.target.file}`,
+                target_file: plan.target.file,
+                expected_file_hash: plan.target.file_hash,
+                current_file_hash: currentFileHash,
+                matched_count: locateResult.matches.length,
+                affected_file_count: affectedFiles.length,
+                changed_ranges: [],
+                diff_summary: "",
+                diff_preview: "",
+                promotable: false,
+            }),
+        };
+    }
+    const astgrepCmd = detectAstgrepCommand();
+    if (!astgrepCmd) {
+        return {
+            artifact: await finalize({
+                ok: false,
+                reason_code: "astgrep_unavailable",
+                error: "ast-grep command not available",
+                target_file: plan.target.file,
+                expected_file_hash: plan.target.file_hash,
+                current_file_hash: currentFileHash,
+                matched_count: locateResult.matches.length,
+                affected_file_count: affectedFiles.length,
+                changed_ranges: [],
+                diff_summary: "",
+                diff_preview: "",
+                promotable: false,
+            }),
+        };
+    }
+    const stagingDir = wsPath(".ace-staging", `structural-edit-${plan.plan_id}-${Date.now()}`);
+    const stagedOriginal = resolve(stagingDir, `original__${plan.target.file.replace(/\//g, "__")}`);
+    const stagedRewrite = resolve(stagingDir, `rewrite__${plan.target.file.replace(/\//g, "__")}`);
+    mkdirSync(dirname(stagedOriginal), { recursive: true });
+    writeFileSync(stagedOriginal, currentContent, "utf-8");
+    writeFileSync(stagedRewrite, currentContent, "utf-8");
+    const rewriteResult = spawnSync(astgrepCmd, ["--pattern", plan.locator.pattern, "--rewrite", plan.rewrite.rewrite_template, "--lang", plan.locator.lang, stagedRewrite, "--update-all"], { encoding: "utf8", cwd: WORKSPACE_ROOT });
+    if (rewriteResult.status !== 0) {
+        return {
+            artifact: await finalize({
+                ok: false,
+                reason_code: "rewrite_failed",
+                error: rewriteResult.stderr || rewriteResult.stdout || "ast-grep rewrite failed",
+                target_file: plan.target.file,
+                expected_file_hash: plan.target.file_hash,
+                current_file_hash: currentFileHash,
+                matched_count: locateResult.matches.length,
+                affected_file_count: affectedFiles.length,
+                changed_ranges: [],
+                diff_summary: "",
+                diff_preview: "",
+                promotable: false,
+                staging_path: stagingDir,
+            }),
+        };
+    }
+    const rewrittenContent = readFileSync(stagedRewrite, "utf-8");
+    const rewriteHash = contentSha256(rewrittenContent);
+    const diff = diffContents(currentContent, rewrittenContent);
+    const diffProcess = spawnSync("diff", ["-u", "--label", `a/${plan.target.file}`, "--label", `b/${plan.target.file}`, stagedOriginal, stagedRewrite], { encoding: "utf8", cwd: WORKSPACE_ROOT });
+    const diffText = diffProcess.status === 1
+        ? diffProcess.stdout
+        : diffProcess.status === 0
+            ? ""
+            : diff.diff_summary;
+    return {
+        artifact: await finalize({
+            ok: true,
+            target_file: plan.target.file,
+            expected_file_hash: plan.target.file_hash,
+            current_file_hash: currentFileHash,
+            rewritten_file_hash: rewriteHash,
+            matched_count: targetMatches.length,
+            affected_file_count: affectedFiles.length,
+            changed_ranges: parseChangedRanges(diffText),
+            diff_summary: diff.diff_summary,
+            diff_preview: diffText ? previewDiffText(diffText) : diff.diff_summary,
+            promotable: diff.has_diff,
+            staging_path: stagingDir,
+        }),
+        rewritten_content: rewrittenContent,
+    };
+}
 async function resolveReadFileLinesBudget() {
     let modelClass;
     const statuses = await withLocalModelRuntimeRepository(WORKSPACE_ROOT, async (repo) => repo.listRuntimeStatuses()).catch(() => undefined);
@@ -82,9 +482,62 @@ export function registerFileTools(server) {
     server.tool("write_workspace_file", "Write or update a workspace file. Prefer apply_patch for targeted edits, astgrep_rewrite for structural rewrites. Cost: heavy.", {
         path: z.string().describe("Relative path from workspace root"),
         content: z.string().describe("File content"),
-    }, async ({ path, content }) => {
+        workspace_path: z
+            .string()
+            .optional()
+            .describe("Required workspace root for model/runtime writes"),
+    }, async ({ path, content, workspace_path }) => {
+        if (!workspace_path?.trim()) {
+            const message = "write_workspace_file requires workspace_path for workspace-root write safety.";
+            await appendWriteWorkspaceRejection({
+                reason_code: "missing_workspace_path",
+                message,
+                path,
+            });
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            ok: false,
+                            reason_code: "missing_workspace_path",
+                            message,
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        const workspaceRoot = resolve(workspace_path);
         const normalizedPath = normalizePathForValidation(path);
         const validationNotes = [];
+        let targetPath;
+        try {
+            targetPath = resolveWorkspaceWritePath(path, workspaceRoot);
+        }
+        catch (error) {
+            const reasonCode = reasonCodeFromError(error) ?? "path_escape";
+            const message = errorMessage(error);
+            await appendWriteWorkspaceRejection({
+                reason_code: reasonCode,
+                message,
+                path,
+                workspace_path,
+            });
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            ok: false,
+                            reason_code: reasonCode,
+                            message,
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
         // ── Append-only guard ───────────────────────────────────────────
         if (APPEND_ONLY_PATHS.has(normalizedPath)) {
             const existing = safeRead(path);
@@ -524,9 +977,20 @@ export function registerFileTools(server) {
             todoStateSuffix = `\nTODO state synced: ${synced.path}`;
         }
         const storeFallbackKeys = resolveStoreFallbackKeysForPath(normalizedPath);
-        const useAsyncStoreAdmission = storeFallbackKeys.length > 0;
+        const useAsyncStoreAdmission = storeFallbackKeys.length > 0 && workspaceRoot === WORKSPACE_ROOT;
         // Keep the file as a materialized projection after the canonical store update.
-        const abs = useAsyncStoreAdmission ? await safeWriteAsync(path, content) : safeWrite(path, content);
+        let abs;
+        if (useAsyncStoreAdmission) {
+            abs = await safeWriteAsync(path, content);
+        }
+        else if (workspaceRoot === WORKSPACE_ROOT) {
+            abs = safeWrite(path, content);
+        }
+        else {
+            mkdirSync(dirname(targetPath), { recursive: true });
+            writeFileSync(targetPath, content, "utf-8");
+            abs = targetPath;
+        }
         let kanbanSuffix = "";
         const shouldRefreshKanban = shouldAutoRefreshKanbanForPath(normalizedPath);
         if (shouldRefreshKanban) {
@@ -814,7 +1278,6 @@ export function registerFileTools(server) {
         scope: z.string().optional().describe("Workspace-relative directory to search (default: src)"),
         max_results: z.number().int().min(1).max(200).optional().describe("Max results to return (default: 50)"),
     }, async ({ pattern, lang, scope, max_results }) => {
-        const { runAstgrepQuery } = await import("./astgrep-index.js");
         const root = wsPath(scope ?? "src");
         const matches = runAstgrepQuery(pattern, lang, [root]);
         const limited = matches.slice(0, max_results ?? 50);
@@ -831,110 +1294,349 @@ export function registerFileTools(server) {
                 }],
         };
     });
-    server.tool("astgrep_rewrite", "Apply a structural rewrite to one workspace file using ast-grep pattern + replacement. Multi-file rewrites are refused; staged through safe_edit_file. Emits transition-compatible result details. Cost: heavy.", {
+    server.tool("astgrep_locate", "Locate structural matches and persist a reusable locator artifact with match IDs, ranges, previews, captures, and file hashes. Cost: cheap.", {
         pattern: z.string().describe("ast-grep pattern to match"),
-        rewrite: z.string().describe("Replacement template (use $NAME etc. from pattern)"),
         lang: z.string().describe("Language: ts, py, rust, go, js"),
         scope: z.string().optional().describe("Workspace-relative directory (default: src)"),
-        confirm_multi_file: z.boolean().optional().describe("Deprecated; multi-file rewrites are always refused"),
-        validation_command: z.string().optional().describe("Shell command to validate the staged rewrite before promotion"),
-        test_command: z.string().optional().describe("Shell command to test the staged rewrite before promotion"),
-        session_id: z.string().optional().describe("Optional runtime session id for transition-record emission"),
-    }, async ({ pattern, rewrite, lang, scope, validation_command, test_command, session_id }) => {
-        const { runAstgrepQuery } = await import("./astgrep-index.js");
-        const root = wsPath(scope ?? "src");
-        if (!isInside(WORKSPACE_ROOT, root)) {
-            return {
-                content: [{ type: "text", text: `astgrep_rewrite failed: scope escapes workspace root (${scope})` }],
-                isError: true,
-            };
+        symbol_hint: z.string().optional().describe("Optional symbol name or text hint used to narrow or prioritize matches"),
+        max_results: z.number().int().min(1).max(200).optional().describe("Max results to persist/return (default: 50)"),
+    }, async ({ pattern, lang, scope, symbol_hint, max_results }) => {
+        const locatorInput = {
+            pattern,
+            lang,
+            scope: scope ?? "src",
+            symbol_hint,
+            max_results,
+        };
+        try {
+            const result = locateAstgrepMatches(locatorInput);
+            const artifact = await storeLocateArtifact(locatorInput, result);
+            return jsonResponse({
+                ok: result.ok,
+                locator_id: artifact.locator_id,
+                artifact_path: artifact.artifact_path,
+                pattern,
+                lang,
+                scope: locatorInput.scope,
+                symbol_hint,
+                total_matches: artifact.total_matches,
+                matches: artifact.matches.map(({ matched_text: _matchedText, ...match }) => match),
+                error: result.error,
+            }, !result.ok);
         }
-        const matches = runAstgrepQuery(pattern, lang, [root]);
-        const affectedFiles = [...new Set(matches.map(m => m.file))];
-        const plan = planAstgrepRewriteTargets(affectedFiles);
-        if (!plan.ok) {
-            await appendAstgrepRewriteTransition(session_id, "refused", plan.error ?? "astgrep_rewrite refused the requested rewrite", plan.affected_files);
-            return {
-                content: [{
-                        type: "text",
-                        text: plan.error ?? "astgrep_rewrite refused the requested rewrite",
-                    }],
-                isError: true,
+        catch (error) {
+            return jsonResponse({
+                ok: false,
+                reason_code: "scope_escape",
+                error: error instanceof Error ? error.message : String(error),
+                pattern,
+                lang,
+                scope: locatorInput.scope,
+            }, true);
+        }
+    });
+    server.tool("compile_structural_edit", "Compile a one-file structural edit plan from a selected match ID or locator input and persist the plan artifact without touching files. Cost: moderate.", {
+        match_id: z.string().optional().describe("Previously returned astgrep_locate match ID"),
+        pattern: z.string().optional().describe("ast-grep pattern to locate when no match_id is provided"),
+        lang: z.string().optional().describe("Language: ts, py, rust, go, js when using locator input"),
+        scope: z.string().optional().describe("Workspace-relative directory (default: src) when using locator input"),
+        symbol_hint: z.string().optional().describe("Optional symbol name or text hint for locator input"),
+        max_results: z.number().int().min(1).max(200).optional().describe("Max locator matches to keep (default: 50)"),
+        desired_change: z.string().describe("Plain-language edit intent; used as rewrite_template when no explicit template is provided"),
+        rewrite_template: z.string().optional().describe("Explicit ast-grep rewrite template; preferred when provided"),
+        validation_command: z.string().optional().describe("Shell command to validate before promotion"),
+        test_command: z.string().optional().describe("Shell command to run before promotion"),
+    }, async ({ match_id, pattern, lang, scope, symbol_hint, max_results, desired_change, rewrite_template, validation_command, test_command, }) => {
+        if (!match_id && (!pattern || !lang)) {
+            return jsonResponse({
+                ok: false,
+                reason_code: "locator_required",
+                error: "compile_structural_edit requires either match_id or pattern+lang locator input",
+            }, true);
+        }
+        let locateArtifact;
+        let selectedMatch;
+        let locator;
+        if (match_id) {
+            const stored = findStoredMatch(match_id);
+            if (!stored) {
+                return jsonResponse({
+                    ok: false,
+                    reason_code: "match_not_found",
+                    error: `No persisted locator match found for ${match_id}`,
+                    match_id,
+                }, true);
+            }
+            const narrowedMatches = stored.artifact.matches.filter((match) => match.file === stored.match.file);
+            locator = {
+                ...stored.artifact.input,
+                scope: stored.match.file,
             };
+            locateArtifact = {
+                ...stored.artifact,
+                input: locator,
+                matches: narrowedMatches,
+                total_matches: narrowedMatches.length,
+            };
+            selectedMatch = stored.match;
         }
-        if (matches.length === 0) {
-            return {
-                content: [{ type: "text", text: "No matches found for pattern. No files modified." }],
+        else {
+            locator = {
+                pattern: pattern,
+                lang: lang,
+                scope: scope ?? "src",
+                symbol_hint,
+                max_results,
             };
+            try {
+                const locateResult = locateAstgrepMatches(locator);
+                locateArtifact = await storeLocateArtifact(locator, locateResult);
+                if (!locateResult.ok) {
+                    return jsonResponse({
+                        ok: false,
+                        reason_code: "locate_failed",
+                        error: locateResult.error ?? "Failed to locate structural matches",
+                        locator_id: locateArtifact.locator_id,
+                        artifact_path: locateArtifact.artifact_path,
+                    }, true);
+                }
+                if (locateArtifact.matches.length === 0) {
+                    return jsonResponse({
+                        ok: false,
+                        reason_code: "no_matches",
+                        error: "No matches found for locator input",
+                        locator_id: locateArtifact.locator_id,
+                        artifact_path: locateArtifact.artifact_path,
+                    }, true);
+                }
+                selectedMatch = locateArtifact.matches[0];
+            }
+            catch (error) {
+                return jsonResponse({
+                    ok: false,
+                    reason_code: "scope_escape",
+                    error: error instanceof Error ? error.message : String(error),
+                }, true);
+            }
+        }
+        if (!locateArtifact) {
+            return jsonResponse({
+                ok: false,
+                reason_code: "locator_missing",
+                error: "Structural locator artifact was not available",
+            }, true);
+        }
+        const scopedMatches = selectedMatch
+            ? locateArtifact.matches.filter((match) => match.file === selectedMatch?.file)
+            : locateArtifact.matches;
+        const scopeFiles = planScopeFromMatches(locateArtifact.matches);
+        if (scopeFiles.length > 1) {
+            return jsonResponse({
+                ok: false,
+                reason_code: "ambiguous_multi_file",
+                error: `compile_structural_edit refuses multi-file locators (${scopeFiles.length} files)`,
+                locator_id: locateArtifact.locator_id,
+                artifact_path: locateArtifact.artifact_path,
+                affected_files: scopeFiles,
+            }, true);
         }
-        const targetRel = astgrepFileToWorkspaceRel(plan.target_file ?? "");
-        if (!targetRel) {
+        if (scopedMatches.length === 0) {
+            return jsonResponse({
+                ok: false,
+                reason_code: "no_matches",
+                error: "No matches remained in the selected file for plan compilation",
+                locator_id: locateArtifact.locator_id,
+                artifact_path: locateArtifact.artifact_path,
+            }, true);
+        }
+        const plan = await compileStructuralEditPlan({
+            locator,
+            locateArtifact,
+            selectedMatch,
+            desiredChange: desired_change,
+            rewriteTemplate: rewrite_template,
+            validationCommand: validation_command,
+            testCommand: test_command,
+        }).catch((error) => {
+            const message = error instanceof Error ? error.message : String(error);
             return {
-                content: [{ type: "text", text: `astgrep_rewrite failed: matched path escapes workspace root (${plan.target_file ?? ""})` }],
-                isError: true,
+                error: message,
+                reason_code: message.startsWith("bad_capture:") ? "bad_capture" : "plan_compile_failed",
             };
+        });
+        if ("error" in plan) {
+            return jsonResponse({
+                ok: false,
+                reason_code: plan.reason_code,
+                error: plan.error,
+                locator_id: locateArtifact.locator_id,
+                artifact_path: locateArtifact.artifact_path,
+            }, true);
         }
-        const originalContent = safeRead(targetRel);
-        if (originalContent.startsWith("[FILE NOT FOUND]") || originalContent.startsWith("[ACCESS DENIED]")) {
-            return {
-                content: [{ type: "text", text: `astgrep_rewrite failed: cannot read ${targetRel}\n${originalContent}` }],
-                isError: true,
+        return jsonResponse(plan);
+    });
+    server.tool("preview_structural_edit", "Stage a compiled structural edit plan, return bounded diff and changed ranges, and refuse stale-hash or multi-file previews. Cost: heavy.", {
+        plan_id: z.string().describe("Compiled structural edit plan id"),
+    }, async ({ plan_id }) => {
+        const plan = loadStructuralEditPlan(plan_id);
+        if (!plan) {
+            return jsonResponse({
+                ok: false,
+                reason_code: "plan_not_found",
+                error: `No structural edit plan found for ${plan_id}`,
+                plan_id,
+            }, true);
+        }
+        const preview = (await buildStructuralPreview(plan)).artifact;
+        return jsonResponse(preview, !preview.ok);
+    });
+    server.tool("astgrep_rewrite", "Apply a structural rewrite to one workspace file using a compiled plan_id or direct ast-grep pattern + replacement. Multi-file rewrites are refused; staged through safe_edit_file. Emits transition-compatible result details. Cost: heavy.", {
+        plan_id: z.string().optional().describe("Compiled structural edit plan id; preferred over direct pattern+rewrite"),
+        pattern: z.string().optional().describe("ast-grep pattern to match"),
+        rewrite: z.string().optional().describe("Replacement template (use $NAME etc. from pattern)"),
+        lang: z.string().optional().describe("Language: ts, py, rust, go, js"),
+        scope: z.string().optional().describe("Workspace-relative directory (default: src)"),
+        confirm_multi_file: z.boolean().optional().describe("Deprecated; multi-file rewrites are always refused"),
+        validation_command: z.string().optional().describe("Shell command to validate the staged rewrite before promotion"),
+        test_command: z.string().optional().describe("Shell command to test the staged rewrite before promotion"),
+        session_id: z.string().optional().describe("Optional runtime session id for transition-record emission"),
+    }, async ({ plan_id, pattern, rewrite, lang, scope, validation_command, test_command, session_id }) => {
+        let compiledPlan;
+        if (plan_id) {
+            compiledPlan = loadStructuralEditPlan(plan_id);
+            if (!compiledPlan) {
+                return {
+                    content: [{ type: "text", text: `astgrep_rewrite failed: no structural edit plan found for ${plan_id}` }],
+                    isError: true,
+                };
+            }
+        }
+        else {
+            if (!pattern || !rewrite || !lang) {
+                return {
+                    content: [{ type: "text", text: "astgrep_rewrite requires plan_id or direct pattern+rewrite+lang input." }],
+                    isError: true,
+                };
+            }
+            const locatorInput = {
+                pattern,
+                lang,
+                scope: scope ?? "src",
+                max_results: 200,
             };
+            let locateResult;
+            try {
+                locateResult = locateAstgrepMatches(locatorInput);
+            }
+            catch {
+                return {
+                    content: [{ type: "text", text: `astgrep_rewrite failed: scope escapes workspace root (${scope})` }],
+                    isError: true,
+                };
+            }
+            const locateArtifact = await storeLocateArtifact(locatorInput, locateResult);
+            if (!locateResult.ok) {
+                return {
+                    content: [{ type: "text", text: `astgrep_rewrite failed: ${locateResult.error ?? "locator failed"}` }],
+                    isError: true,
+                };
+            }
+            if (locateArtifact.matches.length === 0) {
+                return {
+                    content: [{ type: "text", text: "No matches found for pattern. No files modified." }],
+                };
+            }
+            const scopeFiles = planScopeFromMatches(locateArtifact.matches);
+            const targetPlan = planAstgrepRewriteTargets(scopeFiles);
+            if (!targetPlan.ok) {
+                await appendAstgrepRewriteTransition(session_id, "refused", targetPlan.error ?? "astgrep_rewrite refused the requested rewrite", [locateArtifact.artifact_path, ...targetPlan.affected_files]);
+                return {
+                    content: [{
+                            type: "text",
+                            text: targetPlan.error ?? "astgrep_rewrite refused the requested rewrite",
+                        }],
+                    isError: true,
+                };
+            }
+            const directPlan = await compileStructuralEditPlan({
+                locator: locatorInput,
+                locateArtifact,
+                selectedMatch: locateArtifact.matches[0],
+                desiredChange: rewrite,
+                rewriteTemplate: rewrite,
+                validationCommand: validation_command,
+                testCommand: test_command,
+            }).catch((error) => ({
+                error: error instanceof Error ? error.message : String(error),
+            }));
+            if ("error" in directPlan) {
+                return {
+                    content: [{ type: "text", text: `astgrep_rewrite failed: ${directPlan.error}` }],
+                    isError: true,
+                };
+            }
+            compiledPlan = directPlan;
         }
-        const stagingDir = wsPath(".ace-staging", `astgrep-rewrite-${Date.now()}`);
-        const stagedFile = resolve(stagingDir, targetRel);
-        mkdirSync(dirname(stagedFile), { recursive: true });
-        writeFileSync(stagedFile, originalContent, "utf-8");
-        const { spawnSync } = await import("node:child_process");
-        const result = spawnSync("ast-grep", ["--pattern", pattern, "--rewrite", rewrite, "--lang", lang, stagedFile, "--update-all"], { encoding: "utf8", cwd: WORKSPACE_ROOT });
-        if (result.status !== 0) {
-            await appendAstgrepRewriteTransition(session_id, "failed", `astgrep_rewrite failed in staging: ${result.stderr || result.stdout || "unknown error"}`, [targetRel]);
+        const preview = await buildStructuralPreview(compiledPlan);
+        if (!preview.artifact.ok || !preview.artifact.promotable || !preview.rewritten_content) {
+            await appendAstgrepRewriteTransition(session_id, "refused", preview.artifact.error ?? "astgrep_rewrite preview refused promotion", [compiledPlan.artifact_path, preview.artifact.artifact_path, compiledPlan.target.file]);
             return {
-                content: [{ type: "text", text: `astgrep rewrite failed:\n${result.stderr}` }],
+                content: [{
+                        type: "text",
+                        text: [
+                            "astgrep_rewrite failed before promotion",
+                            `Plan: ${compiledPlan.artifact_path}`,
+                            `Preview: ${preview.artifact.artifact_path}`,
+                            `Path: ${compiledPlan.target.file}`,
+                            `Reason: ${preview.artifact.error ?? "preview was not promotable"}`,
+                        ].join("\n"),
+                    }],
                 isError: true,
             };
         }
-        const rewrittenContent = readFileSync(stagedFile, "utf-8");
         const safeResult = safeEditFile({
-            path: targetRel,
-            content: rewrittenContent,
-            validation_command,
-            test_command,
+            path: compiledPlan.target.file,
+            content: preview.rewritten_content,
+            validation_command: validation_command ?? compiledPlan.validation_command,
+            test_command: test_command ?? compiledPlan.test_command,
         });
         if (!safeResult.ok) {
-            await appendAstgrepRewriteTransition(session_id, "failed", `astgrep_rewrite failed before promotion for ${targetRel}: ${safeResult.error ?? "unknown error"}`, [targetRel]);
+            await appendAstgrepRewriteTransition(session_id, "failed", `astgrep_rewrite failed before promotion for ${compiledPlan.target.file}: ${safeResult.error ?? "unknown error"}`, [compiledPlan.artifact_path, preview.artifact.artifact_path, compiledPlan.target.file]);
             return {
                 content: [{
                         type: "text",
                         text: [
                             `astgrep_rewrite failed before promotion`,
-                            `Path: ${targetRel}`,
+                            `Plan: ${compiledPlan.artifact_path}`,
+                            `Preview: ${preview.artifact.artifact_path}`,
+                            `Path: ${compiledPlan.target.file}`,
                             `Error: ${safeResult.error ?? "unknown error"}`,
                             safeResult.validation_passed !== undefined ? `Validation: ${safeResult.validation_passed ? "passed" : "FAILED"}` : "Validation: not requested",
                             safeResult.validation_output ? `Validation output:\n${safeResult.validation_output}` : "",
                             safeResult.test_passed !== undefined ? `Tests: ${safeResult.test_passed ? "passed" : "FAILED"}` : "Tests: not requested",
                             safeResult.test_output ? `Test output:\n${safeResult.test_output}` : "",
-                            `Staging: ${safeResult.staging_path || stagingDir}`,
+                            `Staging: ${safeResult.staging_path || preview.artifact.staging_path || ""}`,
                         ].filter(Boolean).join("\n"),
                     }],
                 isError: true,
             };
         }
-        await appendAstgrepRewriteTransition(session_id, "promoted", `astgrep_rewrite promoted staged rewrite for ${targetRel}`, [targetRel]);
+        await appendAstgrepRewriteTransition(session_id, "promoted", `astgrep_rewrite promoted staged rewrite for ${compiledPlan.target.file}`, [compiledPlan.artifact_path, preview.artifact.artifact_path, compiledPlan.target.file]);
         return {
             content: [{
                     type: "text",
                     text: [
                         `# astgrep_rewrite completed`,
-                        `Pattern: ${pattern}`,
-                        `Rewrite: ${rewrite}`,
-                        `Files affected: ${affectedFiles.length}`,
-                        `Path: ${targetRel}`,
+                        `Plan: ${compiledPlan.artifact_path}`,
+                        `Preview: ${preview.artifact.artifact_path}`,
+                        `Pattern: ${compiledPlan.locator.pattern}`,
+                        `Rewrite: ${compiledPlan.rewrite.rewrite_template}`,
+                        `Files affected: ${preview.artifact.affected_file_count}`,
+                        `Path: ${compiledPlan.target.file}`,
                         `Hash: ${safeResult.original_hash} → ${safeResult.new_hash}`,
                         safeResult.validation_passed !== undefined ? `Validation: ${safeResult.validation_passed ? "passed" : "failed"}` : "Validation: not requested",
                         safeResult.test_passed !== undefined ? `Tests: ${safeResult.test_passed ? "passed" : "failed"}` : "Tests: not requested",
                         `Staging: ${safeResult.staging_path}`,
-                        result.stdout ? `\nOutput:\n${result.stdout}` : "",
                     ].filter(Boolean).join("\n"),
                 }],
         };