@mrclrchtr/supi-code-intelligence 1.16.1 → 2.0.0

package/src/tool/orientation/precise-target.ts

@@ -0,0 +1,257 @@
+/**
+ * Precise-target resolution and execution for code_orientation.
+ *
+ * Handles targetId expansion, coordinate-based symbol resolution, and
+ * running the use-case layer for a resolved symbol target. Shared by
+ * the main code_orientation executor.
+ */
+
+import { relative } from "node:path";
+import { executeResolveService } from "../../analysis/target/service.ts";
+import type { TargetStoreEntry } from "../../session/target-store.ts";
+import type { CodeIntelResult, CodeIntelToolExecCtx, ContextDetails } from "../../types/index.ts";
+import { orientationCoordinateRules } from "../infra/cross-field.ts";
+import { unavailableContextDetails } from "../infra/error-results.ts";
+import { prepareOrientationDeps } from "./deps.ts";
+import type { CodeOrientationToolParams } from "./execute.ts";
+import { executeOrientation } from "./orchestrate.ts";
+
+/**
+ * A resolved precise target: the store entry (with handles) plus
+ * contextual notes (e.g. "targetId took precedence over focus").
+ */
+export interface PreciseTarget {
+  entry: TargetStoreEntry;
+  notes: string[];
+}
+
+/**
+ * Outcome of precise-target resolution in code_orientation.
+ *
+ * {@link resolvePreciseTarget} returns this discriminated union instead
+ * of {@link CodeIntelResult} | null so callers can't silently fall through
+ * on a bug that produces null unintentionally.
+ */
+export type PreciseTargetOutcome =
+  | { kind: "resolved"; result: CodeIntelResult }
+  | { kind: "fallthrough" };
+
+/**
+ * Resolve a precise target ({@link CodeOrientationToolParams.targetId}
+ * wins over focus/coordinates), then run symbol-centered orientation
+ * sections. Falls through to orientation-mode when both targetId
+ * expansion and coordinate resolution produce no target.
+ */
+export async function resolvePreciseTarget(
+  params: CodeOrientationToolParams,
+  ctx: CodeIntelToolExecCtx,
+  hasCoords: boolean,
+): Promise<PreciseTargetOutcome> {
+  if (params.targetId !== undefined && params.targetId !== null) {
+    const targetIdOutcome = await resolveTargetIdTarget(params, ctx, hasCoords);
+    if (targetIdOutcome.kind === "resolved") return targetIdOutcome;
+  }
+
+  if (hasCoords) {
+    const coordOutcome = await resolveCoordinateTarget(params, ctx);
+    if (coordOutcome.kind === "resolved") return coordOutcome;
+  }
+
+  return { kind: "fallthrough" };
+}
+
+/** Resolve a targetId-supplied precise target, or fallthrough. */
+async function resolveTargetIdTarget(
+  params: CodeOrientationToolParams,
+  ctx: CodeIntelToolExecCtx,
+  hasCoords: boolean,
+): Promise<PreciseTargetOutcome> {
+  const expansion = ctx.session.expandTargetId(params);
+  if (expansion.kind === "error") {
+    return wrapOutcome({
+      content: expansion.message,
+      details: unavailableContextDetails([
+        "Verify the `targetId` is valid and from this session",
+        "Re-resolve with `code_resolve` to get a fresh targetId",
+      ]),
+    });
+  }
+  if (expansion.kind !== "ok") return { kind: "fallthrough" };
+
+  const notes: string[] = [];
+  if (params.focus || hasCoords) {
+    notes.push(
+      "_Note: `targetId` takes precedence over the supplied focus/coordinates; focus and coordinates were ignored._",
+    );
+  }
+
+  return wrapOutcome(
+    await runWithOrientationTarget(params, ctx, { entry: expansion.entry, notes }),
+  );
+}
+
+/** Resolve a focus+coordinate-supplied precise target, or fallthrough. */
+async function resolveCoordinateTarget(
+  params: CodeOrientationToolParams,
+  ctx: CodeIntelToolExecCtx,
+): Promise<PreciseTargetOutcome> {
+  const coordError = validateCoordinateParams(params, ctx.cwd);
+  if (coordError) {
+    return wrapOutcome({
+      content: coordError,
+      details: unavailableContextDetails([
+        "Provide `focus`, `line`, and `character` together for symbol orientation",
+      ]),
+    });
+  }
+
+  const resolveResult = await executeResolveService(
+    { file: params.focus, line: params.line, character: params.character },
+    ctx.session,
+  );
+
+  if (resolveResult.kind === "error") {
+    return wrapOutcome({
+      content: resolveResult.message,
+      details: unavailableContextDetails([
+        "Use `code_inspect` for point-level facts at this coordinate",
+        "Or pass the identifier coordinate of a declaration",
+      ]),
+    });
+  }
+  if (resolveResult.kind === "disambiguation") {
+    return wrapOutcome(disambiguationResult(resolveResult));
+  }
+
+  const entry = resolveResult.targets[0];
+  if (!entry) {
+    return wrapOutcome({
+      content: "**Error:** Coordinate resolution returned no target.",
+      details: unavailableContextDetails(["Use `code_inspect` for point-level facts"]),
+    });
+  }
+
+  return wrapOutcome(await runWithOrientationTarget(params, ctx, { entry, notes: [] }));
+}
+
+/** Wrap a CodeIntelResult into a resolved PreciseTargetOutcome. */
+function wrapOutcome(result: CodeIntelResult): PreciseTargetOutcome {
+  return { kind: "resolved", result };
+}
+async function runWithOrientationTarget(
+  params: CodeOrientationToolParams,
+  ctx: CodeIntelToolExecCtx,
+  precise: PreciseTarget,
+): Promise<CodeIntelResult> {
+  const entry = precise.entry;
+  params.file = entry.file;
+  params.line = entry.displayLine;
+  params.character = entry.displayCharacter;
+  params.targetName = entry.name;
+  params.targetKind = entry.kind;
+  params.targetAnchorKind = entry.anchorKind;
+
+  const deps = await prepareOrientationDeps(params, ctx);
+  if ("content" in deps) return deps;
+
+  const result = await executeOrientation(
+    {
+      target: buildOrientationTarget(params),
+      maxResults: params.maxResults ?? 10,
+      showGitContext: false,
+    },
+    { ...deps, cwd: ctx.cwd },
+  );
+
+  const content = prependNotes(result.content, precise.notes, entry, ctx.cwd);
+  const details: ContextDetails = { ...result.details, target: entry };
+  return { content, details: { type: "context", data: details } };
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────
+
+/**
+ * Cross-field rule for code_orientation coordinate mode.
+ *
+ * TypeBox already enforces line/character types and min >= 1.
+ * This covers only pairing, existence, and directory checks.
+ */
+const validateCoordinateParams = orientationCoordinateRules<CodeOrientationToolParams>();
+
+function buildOrientationTarget(params: CodeOrientationToolParams) {
+  if (!params.file || params.line == null || params.character == null) return null;
+  return {
+    file: params.file,
+    line: params.line,
+    character: params.character,
+    name: params.targetName ?? null,
+    kind: params.targetKind ?? null,
+    anchorKind: params.targetAnchorKind ?? "name",
+  };
+}
+
+/** Prepend notes + a resolved-target summary to rendered orientation content. */
+function prependNotes(
+  content: string,
+  notes: string[],
+  entry: TargetStoreEntry,
+  cwd: string,
+): string {
+  const head: string[] = [];
+  if (notes.length > 0) {
+    head.push(notes.join("\n\n"));
+    head.push("");
+  }
+  const namePart = entry.name ? ` **${entry.name}**` : "";
+  const relFile = relative(cwd, entry.file) || entry.file;
+  head.push(
+    `Resolved target${namePart}: \`${relFile}\`:${entry.displayLine}:${entry.displayCharacter} — Target ID: \`${entry.targetId}\``,
+  );
+  head.push("");
+  return `${head.join("\n")}${content}`;
+}
+
+// ── Disambiguation ────────────────────────────────────────────────────
+
+/** Build the ambiguous-coordinate result: candidate targetIds, no sections. */
+function disambiguationResult(
+  result: Extract<Awaited<ReturnType<typeof executeResolveService>>, { kind: "disambiguation" }>,
+): CodeIntelResult {
+  const lines: string[] = ["# Multiple matches found", ""];
+  lines.push(
+    "Coordinate resolution was ambiguous. Use `focus` + `line` + `character` for one of the candidates (pass the identifier coordinate):",
+  );
+  lines.push("");
+  for (const c of result.candidates) {
+    const kind = c.kind ? ` (\`${c.kind}\`)` : "";
+    const container = c.container ? ` in \`${c.container}\`` : "";
+    lines.push(
+      `${c.rank}. **${c.name}**${kind}${container} — \`${c.file}\`:${c.line}:${c.character}`,
+    );
+    lines.push(`   Target ID: \`${c.targetId}\``);
+  }
+
+  const details: ContextDetails = {
+    confidence: "semantic",
+    task: null,
+    focusTarget: null,
+    requestedSections: [],
+    renderedSections: [],
+    omittedCount: 0,
+    candidates: result.candidates.map((c) => ({
+      targetId: c.targetId,
+      name: c.name,
+      kind: c.kind,
+      container: c.container,
+      file: c.file,
+      line: c.line,
+      character: c.character,
+      rank: c.rank,
+    })),
+    nextQueries: [
+      "Use `focus` + `line` + `character` for one of the candidates above (pass the identifier coordinate)",
+    ],
+  };
+
+  return { content: lines.join("\n"), details: { type: "context", data: details } };
+}

package/src/tool/orientation/tui.ts

@@ -0,0 +1,131 @@
+import { getMarkdownTheme, type Theme } from "@earendil-works/pi-coding-agent";
+import { Container, Markdown, Spacer, Text } from "@earendil-works/pi-tui";
+import { formatEvidenceBadge } from "@mrclrchtr/supi-code-runtime/api";
+import { type ResultOptios, renderPartial, type ToolResult } from "../../ui/tui/common.ts";
+import type { CodeOrientationToolParams } from "./execute.ts";
+
+/** ── renderCall ────────────────────────────────────────────────── */
+
+export function renderOrientationCall(args: unknown, theme: Theme, _context: unknown): Text {
+  const params = (args ?? {}) as CodeOrientationToolParams;
+
+  let content = theme.fg("toolTitle", "code_orientation");
+
+  if (params.targetId) {
+    content += ` ${theme.fg("accent", "target")}`;
+  } else if (params.focus) {
+    const focus = params.focus.split("/").pop() ?? params.focus;
+    content += ` ${theme.fg("accent", focus)}`;
+    if (params.line) content += theme.fg("warning", `:${params.line}`);
+  } else {
+    content += ` ${theme.fg("muted", "project")}`;
+  }
+
+  return new Text(content, 0, 0);
+}
+
+/** ── renderResult ──────────────────────────────────────────────── */
+
+export function renderOrientationResult(
+  result: ToolResult,
+  options: ResultOptios,
+  theme: Theme,
+  _context: unknown,
+): Container | Text {
+  if (options.isPartial) {
+    return renderPartial("Orienting…", theme);
+  }
+
+  const container = new Container();
+  const data =
+    result.details?.type === "context" ? (result.details.data as Record<string, unknown>) : null;
+  const markdownText = result.content.find((c) => c.type === "text")?.text ?? "";
+
+  if (result.isError) {
+    container.addChild(new Text(theme.fg("error", "code_orientation failed"), 0, 0));
+    return container;
+  }
+
+  if (!options.expanded) {
+    container.addChild(buildCompactSummary(data, theme));
+    return container;
+  }
+
+  container.addChild(buildHeader(data, theme));
+
+  const target = data?.target as Record<string, unknown> | undefined;
+  if (target) {
+    container.addChild(new Spacer(1));
+    container.addChild(
+      new Text(
+        theme.fg(
+          "muted",
+          `${String(target.name ?? "symbol")} — ${String(target.file ?? "")}:${String(target.displayLine ?? "")}`,
+        ),
+        0,
+        0,
+      ),
+    );
+  }
+
+  const sections = (data?.renderedSections as string[] | undefined) ?? [];
+  if (sections.length > 0) {
+    container.addChild(new Spacer(1));
+    container.addChild(new Text(theme.fg("dim", `Sections: ${sections.join(", ")}`), 0, 0));
+  }
+
+  if (data?.omittedCount) {
+    const badge = formatEvidenceBadge({
+      shownCount: sections.length,
+      totalCount: sections.length + Number(data.omittedCount),
+      omittedCount: Number(data.omittedCount),
+      partialReason: null,
+      label: "sections",
+    });
+    container.addChild(new Text(theme.fg("dim", badge), 0, 0));
+  }
+
+  if (markdownText) {
+    container.addChild(new Spacer(1));
+    container.addChild(new Text(theme.fg("dim", "▸ raw markdown"), 0, 0));
+    container.addChild(new Markdown(markdownText, 0, 0, getMarkdownTheme()));
+  }
+
+  return container;
+}
+
+/** ── Helpers ───────────────────────────────────────────────────── */
+
+function buildCompactSummary(data: Record<string, unknown> | null, theme: Theme): Text {
+  if (!data) return new Text(theme.fg("dim", "No orientation"), 0, 0);
+
+  const sections = (data?.renderedSections as string[] | undefined) ?? [];
+  const confidence = (data.confidence as string) ?? "";
+  const dot = theme.fg("dim", "·");
+  const segments: string[] = [
+    `${theme.fg("dim", "sections")} ${theme.fg("success", theme.bold(`${sections.length}`))}`,
+  ];
+
+  if (confidence) {
+    segments.push(`${theme.fg("dim", "confidence")} ${theme.fg("muted", confidence)}`);
+  }
+
+  const target = data.target as Record<string, unknown> | undefined;
+  if (target?.name) segments.push(theme.fg("muted", String(target.name)));
+
+  return new Text(segments.join(` ${dot} `), 0, 0);
+}
+
+function buildHeader(data: Record<string, unknown> | null, theme: Theme): Text {
+  if (!data) return new Text("", 0, 0);
+
+  const sections = (data?.renderedSections as string[] | undefined) ?? [];
+  const confidence = (data.confidence as string) ?? "";
+  const dot = theme.fg("dim", "·");
+  const parts = [
+    `${theme.fg("dim", "sections")} ${theme.fg("accent", theme.bold(`${sections.length}`))}`,
+  ];
+  if (confidence) parts.push(`${theme.fg("dim", "confidence")} ${theme.fg("muted", confidence)}`);
+
+  return new Text(parts.join(` ${dot} `), 0, 0);
+}

package/src/{refactor/apply-workspace-edit.ts → tool/refactor-apply/apply.ts}

@@ -12,8 +12,9 @@
  */
 
 import { readFileSync, writeFileSync } from "node:fs";
+import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
 import type { FileEdit, WorkspaceEdit } from "@mrclrchtr/supi-code-runtime/api";
-import { validateEditAgainstFiles } from "./safety.ts";
+import { validateEditAgainstFiles } from "../../analysis/refactor/safety.ts";
 
 export type ApplyResult =
   | { kind: "applied"; filesChanged: number; totalEdits: number }
@@ -25,23 +26,45 @@ export type ApplyResult =
  * Precomputes every file's new content in memory first, then commits
  * all writes. If a commit fails after some files were already written,
  * the function rolls those files back to their original contents.
+ *
+ * The whole precompute-then-commit (including range/safety re-checks) runs
+ * inside pi's per-file mutation queue, acquired for every involved file in
+ * sorted path order before reading. This serializes against sibling
+ * `edit`/`write` tools on the same file and prevents lock-ordering deadlock
+ * across concurrent applies, while preserving all-or-nothing across files
+ * (ADR 0006).
  */
-export function applyWorkspaceEdit(edit: WorkspaceEdit): ApplyResult {
-  const validation = validateEditAgainstFiles(edit);
-  if (!validation.safe) {
-    return { kind: "error", reason: validation.reason };
-  }
-
+export async function applyWorkspaceEdit(edit: WorkspaceEdit): Promise<ApplyResult> {
   const grouped = groupEditsByFile(edit.edits);
-  const originalContents = readOriginalContents(grouped);
-  if (originalContents.kind === "error") return originalContents;
-
-  const transformedContents = buildTransformedContents(grouped, originalContents.contents);
-  return commitTransformedContents(
-    transformedContents,
-    originalContents.contents,
-    edit.edits.length,
-  );
+  const files = [...grouped.keys()].sort();
+  return withAllMutationQueues(files, async () => {
+    const validation = validateEditAgainstFiles(edit);
+    if (!validation.safe) {
+      return { kind: "error", reason: validation.reason };
+    }
+
+    const originalContents = readOriginalContents(grouped);
+    if (originalContents.kind === "error") return originalContents;
+
+    const transformedContents = buildTransformedContents(grouped, originalContents.contents);
+    return commitTransformedContents(
+      transformedContents,
+      originalContents.contents,
+      edit.edits.length,
+    );
+  });
+}
+
+/**
+ * Acquire pi's per-file mutation queue for every involved file in sorted path
+ * order before running `fn`, holding all locks for the duration. Sorted order
+ * prevents lock-ordering deadlock across concurrent applies; per-file queues
+ * serialize against sibling `edit`/`write` tools on the same file (ADR 0006).
+ */
+async function withAllMutationQueues<T>(files: string[], fn: () => Promise<T>): Promise<T> {
+  if (files.length === 0) return fn();
+  const [head, ...rest] = files;
+  return withFileMutationQueue(head, () => withAllMutationQueues(rest, fn));
 }
 
 function groupEditsByFile(edits: FileEdit[]): Map<string, FileEdit[]> {

package/src/tool/refactor-apply/execute.ts

@@ -0,0 +1,20 @@
+/**
+ * Tool executor for the stored-plan application path.
+ *
+ * Thin executor: delegates to the refactor apply use-case for plan lookup,
+ * freshness checking, safety validation, and workspace edit application.
+ */
+
+import type { CodeIntelResult, CodeIntelToolExecCtx } from "../../types/index.ts";
+import { executeRefactorApply } from "./orchestrate.ts";
+
+export interface CodeRefactorApplyToolParams {
+  planId: string;
+}
+
+export async function executeRefactorApplyTool(
+  params: CodeRefactorApplyToolParams,
+  _ctx: CodeIntelToolExecCtx,
+): Promise<CodeIntelResult> {
+  return executeRefactorApply({ planId: params.planId }, { session: _ctx.session });
+}

package/src/tool/refactor-apply/markdown.ts

@@ -0,0 +1,118 @@
+/**
+ * Markdown renderer for refactor results.
+ */
+
+import { createEvidenceList, renderEvidenceListDisclosure } from "../../analysis/evidence.ts";
+import { toDisplayPath } from "../../analysis/search/ripgrep.ts";
+import type { RefactorPlan } from "../../session/refactor-plans.ts";
+import type { ApplyResult } from "./apply.ts";
+
+export interface RefactorRenderInput {
+  result: ApplyResult;
+  operation: string;
+  targetDescription: string;
+}
+
+/**
+ * Render a refactor result as human-readable markdown.
+ */
+export function renderRefactorResult(input: RefactorRenderInput): string {
+  const { result, operation, targetDescription } = input;
+
+  if (result.kind === "error") {
+    return `**Refactor failed:** ${result.reason}`;
+  }
+
+  return [
+    `**Refactor applied:** ${operation} on ${targetDescription}`,
+    `- Files changed: ${result.filesChanged}`,
+    `- Total edits: ${result.totalEdits}`,
+  ].join("\n");
+}
+
+/**
+ * Render a refactor plan preview.
+ */
+export function renderRefactorPlanResult(plan: RefactorPlan, cwd: string): string {
+  const lines: string[] = [];
+  const changedFiles = collectChangedFiles(plan);
+  const fileCount = changedFiles.length;
+
+  lines.push(`# Refactor Plan: ${plan.operation}`);
+  lines.push("");
+  lines.push(`**Plan ID:** \`${plan.id}\``);
+  lines.push(`**Operation:** \`${plan.operation}\``);
+  lines.push(
+    `**Target:** \`${toDisplayPath(cwd, plan.targetFile)}\`:${plan.targetLine}:${plan.targetCharacter}`,
+  );
+  if (plan.newName) {
+    lines.push(`**New name:** \`${plan.newName}\``);
+  }
+  if (plan.destination) {
+    lines.push(`**Destination:** \`${plan.destination}\``);
+  }
+  lines.push(`**Files to change:** ${fileCount} file${fileCount !== 1 ? "s" : ""}`);
+  lines.push(`**Total edits:** ${plan.edits.edits.length}`);
+  lines.push("");
+
+  lines.push("## Files");
+  for (const [file, count] of changedFiles) {
+    lines.push(`- \`${toDisplayPath(cwd, file)}\` — ${count} edit${count !== 1 ? "s" : ""}`);
+  }
+  lines.push("");
+  lines.push("## Preview");
+  lines.push("");
+  const editEvidence = createEvidenceList({
+    key: "refactor.edits",
+    items: plan.edits.edits,
+    maxResults: 5,
+  });
+  for (const edit of editEvidence.items) {
+    const range = edit.range;
+    lines.push(
+      `- \`${toDisplayPath(cwd, edit.file)}\` L${range.start.line + 1}:${range.start.character} → L${range.end.line + 1}:${range.end.character}`,
+    );
+    lines.push("  ```");
+    lines.push(`  ${edit.newText.slice(0, 80).split("\n").join("\n  ")}`);
+    lines.push("  ```");
+  }
+  const disclosure = renderEvidenceListDisclosure(editEvidence);
+  if (disclosure) {
+    lines.push(disclosure);
+  }
+  lines.push("");
+  lines.push("**This is a preview. No files were changed.**");
+  lines.push(`Use code_refactor_apply with planId: "${plan.id}" to apply this refactor.`);
+  return lines.join("\n");
+}
+
+/**
+ * Render a refactor apply result.
+ */
+export function renderRefactorApplyResult(applyResult: ApplyResult, plan: RefactorPlan): string {
+  if (applyResult.kind === "error") {
+    return `**Refactor apply failed:** ${applyResult.reason}`;
+  }
+  const lines = [
+    `**Refactor applied successfully.** Plan: \`${plan.id}\``,
+    `- Operation: \`${plan.operation}\``,
+    `- Files changed: ${applyResult.filesChanged}`,
+    `- Total edits: ${applyResult.totalEdits}`,
+  ];
+  if (plan.newName) {
+    lines.push(`- New name: \`${plan.newName}\``);
+  }
+  if (plan.destination) {
+    lines.push(`- Destination: \`${plan.destination}\``);
+  }
+  lines.push("", "Verify the changes before continuing with other work.");
+  return lines.join("\n");
+}
+
+function collectChangedFiles(plan: RefactorPlan): Array<[file: string, count: number]> {
+  const counts = new Map<string, number>();
+  for (const edit of plan.edits.edits) {
+    counts.set(edit.file, (counts.get(edit.file) ?? 0) + 1);
+  }
+  return [...counts.entries()];
+}

package/src/tool/refactor-apply/orchestrate.ts

@@ -0,0 +1,89 @@
+/**
+ * Refactor apply orchestration use-case.
+ *
+ * Handles plan lookup, freshness checking, safety re-validation, and
+ * workspace edit application for a previously stored refactor plan.
+ * Returns a rendered CodeIntelResult.
+ *
+ * Extracted from execute-refactor-apply.ts as part of the thin-executor
+ * normalization.
+ */
+
+import { validateEdit } from "../../analysis/refactor/safety.ts";
+import { isPlanFresh } from "../../session/refactor-plans.ts";
+import type { WorkspaceCodeIntelligenceSession } from "../../session/session.ts";
+import type { CodeIntelResult } from "../../types/index.ts";
+import { unavailableSearchDetails } from "../infra/error-results.ts";
+import { renderRefactorApplyResult } from "../refactor-plan/markdown.ts";
+import { applyWorkspaceEdit } from "./apply.ts";
+
+export interface RefactorApplyInput {
+  planId: string;
+}
+
+export interface RefactorApplyDeps {
+  session: WorkspaceCodeIntelligenceSession;
+}
+
+/**
+ * Execute the refactor apply use-case.
+ *
+ * Validates plan existence, freshness, and safety, then applies the
+ * workspace edit. Removes the plan from the session store on success.
+ */
+export async function executeRefactorApply(
+  input: RefactorApplyInput,
+  deps: RefactorApplyDeps,
+): Promise<CodeIntelResult> {
+  if (!input.planId) {
+    return {
+      content: "**Error:** `planId` is required.",
+      details: unavailableSearchDetails(null, ["Provide a valid `planId` from code_refactor_plan"]),
+    };
+  }
+
+  const plan = deps.session.getPlan(input.planId);
+  if (!plan) {
+    return {
+      content: `**Error:** Plan "${input.planId}" not found. The plan may have expired or was generated in a different session. Use code_refactor_plan to generate a new plan.`,
+      details: unavailableSearchDetails(null, ["Run code_refactor_plan to generate a new plan"]),
+    };
+  }
+
+  const freshness = isPlanFresh(plan);
+  if (!freshness.fresh) {
+    return {
+      content: `**Stale plan:** ${freshness.reason}`,
+      details: unavailableSearchDetails(null, ["Regenerate the plan with code_refactor_plan"]),
+    };
+  }
+
+  const validation = validateEdit(plan.edits);
+  if (!validation.safe) {
+    return {
+      content: `**Safety check failed:** ${validation.reason}. Regenerate the plan with code_refactor_plan.`,
+      details: unavailableSearchDetails(null, ["Regenerate the plan with code_refactor_plan"]),
+    };
+  }
+
+  const applyResult = await applyWorkspaceEdit(plan.edits);
+  if (applyResult.kind === "applied") {
+    deps.session.removePlan(plan.id);
+  }
+
+  const content = renderRefactorApplyResult(applyResult, plan);
+
+  return {
+    content,
+    details: {
+      type: "search" as const,
+      data: {
+        confidence: "semantic" as const,
+        scope: null,
+        candidateCount: applyResult.kind === "applied" ? applyResult.totalEdits : 0,
+        omittedCount: 0,
+        nextQueries: ["`code_health` to check for new issues after the refactor"],
+      },
+    },
+  };
+}