@phren/cli 0.0.32 → 0.0.34

package/mcp/dist/tools/finding.js

@@ -83,8 +83,389 @@ function withLifecycleMutation(phrenPath, project, writeQueue, updateIndex, hand
         return mcpResponse({ ok: true, message: mapped.message, data: mapped.data });
     });
 }
-export function register(server, ctx) {
+// ── Handlers ─────────────────────────────────────────────────────────────────
+async function handleAddFinding(ctx, { project, finding, citation, sessionId, source, findingType, scope }) {
+    const { phrenPath, withWriteQueue, updateFileInIndex } = ctx;
+    if (!isValidProjectName(project))
+        return mcpResponse({ ok: false, error: `Invalid project name: "${project}"` });
+    const addFindingDenied = permissionDeniedError(phrenPath, "add_finding", project);
+    if (addFindingDenied)
+        return mcpResponse({ ok: false, error: addFindingDenied });
+    if (Array.isArray(finding)) {
+        const findings = finding;
+        if (findings.length > 100)
+            return mcpResponse({ ok: false, error: "Bulk add limited to 100 findings per call." });
+        if (findings.some((f) => f.length > 5000))
+            return mcpResponse({ ok: false, error: "One or more findings exceed 5000 character limit." });
+        return withWriteQueue(async () => {
+            runCustomHooks(phrenPath, "pre-finding", { PHREN_PROJECT: project });
+            const allPotentialDuplicates = [];
+            const extraAnnotationsByFinding = [];
+            for (const f of findings) {
+                const candidates = findJaccardCandidates(phrenPath, project, f);
+                if (candidates.length > 0)
+                    allPotentialDuplicates.push({ finding: f, candidates });
+                try {
+                    const conflicts = await checkSemanticConflicts(phrenPath, project, f);
+                    extraAnnotationsByFinding.push(conflicts.checked && conflicts.annotations.length > 0 ? conflicts.annotations : []);
+                }
+                catch (err) {
+                    logger.debug("add_finding", `bulk semanticConflict: ${errorMessage(err)}`);
+                    extraAnnotationsByFinding.push([]);
+                }
+            }
+            const result = addFindingsToFile(phrenPath, project, findings, {
+                extraAnnotationsByFinding,
+                sessionId,
+            });
+            if (!result.ok)
+                return mcpResponse({ ok: false, error: result.error });
+            const { added, skipped, rejected } = result.data;
+            if (added.length > 0) {
+                runCustomHooks(phrenPath, "post-finding", { PHREN_PROJECT: project });
+                incrementSessionFindings(phrenPath, added.length, sessionId, project);
+                updateFileInIndex(path.join(phrenPath, project, "FINDINGS.md"));
+            }
+            const rejectedMsg = rejected.length > 0 ? `, ${rejected.length} rejected` : "";
+            return mcpResponse({
+                ok: true,
+                message: `Added ${added.length}/${findings.length} findings (${skipped.length} duplicates skipped${rejectedMsg})`,
+                data: {
+                    project,
+                    added,
+                    skipped,
+                    rejected,
+                    ...(allPotentialDuplicates.length > 0 ? { potentialDuplicates: allPotentialDuplicates } : {}),
+                },
+            });
+        });
+    }
+    if (finding.length > 5000)
+        return mcpResponse({ ok: false, error: "Finding text exceeds 5000 character limit." });
+    const normalizedScope = normalizeMemoryScope(scope ?? "shared");
+    if (!normalizedScope)
+        return mcpResponse({ ok: false, error: `Invalid scope: "${scope}". Use lowercase letters/numbers with '-' or '_' (max 64 chars), e.g. "researcher".` });
+    return withWriteQueue(async () => {
+        try {
+            const taggedFinding = findingType ? `[${findingType}] ${finding}` : finding;
+            // Jaccard "maybe zone" scan — free, no LLM call. Return candidates so the agent decides.
+            const potentialDuplicates = findJaccardCandidates(phrenPath, project, taggedFinding);
+            const semanticConflicts = await checkSemanticConflicts(phrenPath, project, taggedFinding);
+            runCustomHooks(phrenPath, "pre-finding", { PHREN_PROJECT: project });
+            const result = addFindingToFile(phrenPath, project, taggedFinding, citation, {
+                sessionId,
+                source,
+                scope: normalizedScope,
+                extraAnnotations: semanticConflicts.checked ? semanticConflicts.annotations : undefined,
+            });
+            if (!result.ok) {
+                return mcpResponse({ ok: false, error: result.error });
+            }
+            if (result.data.status === "skipped") {
+                return mcpResponse({ ok: true, message: result.data.message, data: { project, finding: taggedFinding, status: "skipped" } });
+            }
+            updateFileInIndex(path.join(phrenPath, project, "FINDINGS.md"));
+            if (result.data.status === "added" || result.data.status === "created") {
+                runCustomHooks(phrenPath, "post-finding", { PHREN_PROJECT: project });
+                incrementSessionFindings(phrenPath, 1, sessionId, project);
+                extractFactFromFinding(phrenPath, project, taggedFinding);
+                // Bidirectional link: if there's an active task in this session, append this finding to it.
+                if (sessionId) {
+                    const activeTask = getActiveTaskForSession(phrenPath, sessionId, project);
+                    if (activeTask) {
+                        const taskMatch = activeTask.stableId ? `bid:${activeTask.stableId}` : activeTask.line;
+                        // Extract fid from the last written line in FINDINGS.md
+                        try {
+                            const findingsPath = path.join(phrenPath, project, "FINDINGS.md");
+                            const findingsContent = fs.readFileSync(findingsPath, "utf8");
+                            const lines = findingsContent.split("\n");
+                            const taggedText = taggedFinding.replace(/^-\s+/, "").trim().slice(0, 60).toLowerCase();
+                            for (let li = lines.length - 1; li >= 0; li--) {
+                                const l = lines[li];
+                                if (!l.startsWith("- "))
+                                    continue;
+                                const lineText = l.replace(/<!--.*?-->/g, "").replace(/^-\s+/, "").trim().slice(0, 60).toLowerCase();
+                                if (lineText === taggedText || l.toLowerCase().includes(taggedText.slice(0, 30))) {
+                                    const fidMatch = l.match(/<!--\s*fid:([a-z0-9]{8})\s*-->/);
+                                    if (fidMatch) {
+                                        appendChildFinding(phrenPath, project, taskMatch, `fid:${fidMatch[1]}`);
+                                    }
+                                    break;
+                                }
+                            }
+                        }
+                        catch {
+                            // Non-fatal: task-finding linkage is best-effort
+                        }
+                    }
+                }
+            }
+            const conflictsWithList = semanticConflicts.checked
+                ? extractConflictsWith(semanticConflicts.annotations)
+                : (result.data.message.match(/<!--\s*conflicts_with:\s*"([^"]+)"/)?.[1] ? [result.data.message.match(/<!--\s*conflicts_with:\s*"([^"]+)"/)[1]] : []);
+            const conflictsWith = conflictsWithList[0];
+            // Extract fragment hints synchronously from the finding text (regex only, no DB).
+            // Full DB fragment linking happens on the next index rebuild via updateFileInIndex →
+            // extractAndLinkFragments. We surface hints here so callers can see what was detected.
+            const detectedFragments = extractFragmentNames(taggedFinding);
+            return mcpResponse({
+                ok: true,
+                message: result.data.message,
+                data: {
+                    project,
+                    finding: taggedFinding,
+                    status: result.data.status,
+                    ...(conflictsWith ? { conflictsWith } : {}),
+                    ...(conflictsWithList.length > 0 ? { conflicts: conflictsWithList } : {}),
+                    ...(detectedFragments.length > 0 ? { detectedFragments } : {}),
+                    ...(potentialDuplicates.length > 0 ? { potentialDuplicates } : {}),
+                    scope: normalizedScope,
+                }
+            });
+        }
+        catch (err) {
+            if (err instanceof Error && err.message.includes("Rejected:")) {
+                return mcpResponse({ ok: false, error: errorMessage(err), errorCode: "VALIDATION_ERROR" });
+            }
+            return mcpResponse({ ok: false, error: `Unexpected error saving finding: ${errorMessage(err)}` });
+        }
+    });
+}
+async function handleSupersedeFinding(ctx, { project, finding_text, superseded_by }) {
+    const { phrenPath, withWriteQueue, updateFileInIndex } = ctx;
+    return withLifecycleMutation(phrenPath, project, withWriteQueue, updateFileInIndex, () => supersedeFinding(phrenPath, project, finding_text, superseded_by), (data) => ({
+        message: `Marked finding as superseded in ${project}.`,
+        data: { project, finding: data.finding, status: data.status, superseded_by: data.superseded_by },
+    }));
+}
+async function handleRetractFinding(ctx, { project, finding_text, reason }) {
+    const { phrenPath, withWriteQueue, updateFileInIndex } = ctx;
+    return withLifecycleMutation(phrenPath, project, withWriteQueue, updateFileInIndex, () => retractFindingLifecycle(phrenPath, project, finding_text, reason), (data) => ({
+        message: `Retracted finding in ${project}.`,
+        data: { project, finding: data.finding, status: data.status, reason: data.reason },
+    }));
+}
+async function handleResolveContradiction(ctx, { project, finding_text, finding_text_other, finding_a, finding_b, resolution }) {
+    const { phrenPath, withWriteQueue, updateFileInIndex } = ctx;
+    const findingText = (finding_text ?? finding_a)?.trim();
+    const findingTextOther = (finding_text_other ?? finding_b)?.trim();
+    if (!findingText || !findingTextOther) {
+        return mcpResponse({
+            ok: false,
+            error: "Both finding_text and finding_text_other are required.",
+        });
+    }
+    return withLifecycleMutation(phrenPath, project, withWriteQueue, updateFileInIndex, () => resolveFindingContradiction(phrenPath, project, findingText, findingTextOther, resolution), (data) => ({
+        message: `Resolved contradiction in ${project} with "${resolution}".`,
+        data: {
+            project,
+            resolution: data.resolution,
+            finding_text: data.finding_a,
+            finding_text_other: data.finding_b,
+            finding_a: data.finding_a,
+            finding_b: data.finding_b,
+        },
+    }));
+}
+async function handleGetContradictions(ctx, { project, finding_text }) {
+    const { phrenPath } = ctx;
+    if (project && !isValidProjectName(project))
+        return mcpResponse({ ok: false, error: `Invalid project name: "${project}"` });
+    const projects = project
+        ? [project]
+        : fs.readdirSync(phrenPath, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory() && !RESERVED_PROJECT_DIR_NAMES.has(entry.name) && isValidProjectName(entry.name))
+            .map((entry) => entry.name);
+    const contradictions = [];
+    for (const p of projects) {
+        const result = readFindings(phrenPath, p);
+        if (!result.ok)
+            continue;
+        for (const finding of result.data) {
+            if (finding.status !== "contradicted")
+                continue;
+            if (finding_text && !matchesFindingTextSelector(finding, finding_text))
+                continue;
+            contradictions.push({
+                project: p,
+                id: finding.id,
+                stableId: finding.stableId,
+                text: finding.text,
+                date: finding.date,
+                status_updated: finding.status_updated,
+                status_reason: finding.status_reason,
+                status_ref: finding.status_ref,
+            });
+        }
+    }
+    return mcpResponse({
+        ok: true,
+        message: contradictions.length
+            ? `Found ${contradictions.length} unresolved contradiction${contradictions.length === 1 ? "" : "s"}.`
+            : "No unresolved contradictions found.",
+        data: {
+            project: project ?? null,
+            finding_text: finding_text ?? null,
+            contradictions,
+        },
+    });
+}
+async function handleEditFinding(ctx, { project, old_text, new_text }) {
     const { phrenPath, withWriteQueue, updateFileInIndex } = ctx;
+    if (!isValidProjectName(project))
+        return mcpResponse({ ok: false, error: `Invalid project name: "${project}"` });
+    const editDenied = permissionDeniedError(phrenPath, "edit_finding", project);
+    if (editDenied)
+        return mcpResponse({ ok: false, error: editDenied });
+    return withWriteQueue(async () => {
+        const result = editFindingCore(phrenPath, project, old_text, new_text);
+        if (!result.ok)
+            return mcpResponse({ ok: false, error: result.error });
+        const resolvedFindingsDir = safeProjectPath(phrenPath, project);
+        if (resolvedFindingsDir)
+            updateFileInIndex(path.join(resolvedFindingsDir, "FINDINGS.md"));
+        return mcpResponse({
+            ok: true,
+            message: result.data,
+            data: { project, old_text, new_text },
+        });
+    });
+}
+async function handleRemoveFinding(ctx, { project, finding }) {
+    const { phrenPath, withWriteQueue, updateFileInIndex } = ctx;
+    if (!isValidProjectName(project))
+        return mcpResponse({ ok: false, error: `Invalid project name: "${project}"` });
+    const removeDenied = permissionDeniedError(phrenPath, "remove_finding", project);
+    if (removeDenied)
+        return mcpResponse({ ok: false, error: removeDenied });
+    if (Array.isArray(finding)) {
+        return withWriteQueue(async () => {
+            const result = removeFindingsCore(phrenPath, project, finding);
+            if (!result.ok)
+                return mcpResponse({ ok: false, error: result.message });
+            const resolvedFindingsDir = safeProjectPath(phrenPath, project);
+            if (resolvedFindingsDir)
+                updateFileInIndex(path.join(resolvedFindingsDir, "FINDINGS.md"));
+            return mcpResponse({ ok: true, message: result.message, data: result.data });
+        });
+    }
+    return withWriteQueue(async () => {
+        const result = removeFindingCore(phrenPath, project, finding);
+        if (!result.ok)
+            return mcpResponse({ ok: false, error: result.message });
+        const resolvedFindingsDir = safeProjectPath(phrenPath, project);
+        if (resolvedFindingsDir)
+            updateFileInIndex(path.join(resolvedFindingsDir, "FINDINGS.md"));
+        return mcpResponse({ ok: true, message: result.message, data: result.data });
+    });
+}
+async function handlePushChanges(ctx, { message }) {
+    const { phrenPath, withWriteQueue } = ctx;
+    return withWriteQueue(async () => {
+        const { execFileSync } = await import("child_process");
+        const runGit = (args, opts = {}) => execFileSync("git", args, {
+            cwd: phrenPath,
+            encoding: "utf8",
+            timeout: opts.timeout ?? EXEC_TIMEOUT_MS,
+            env: opts.env,
+            stdio: ["ignore", "pipe", "pipe"],
+        }).trim();
+        try {
+            const status = runGit(["status", "--porcelain"]);
+            if (!status)
+                return mcpResponse({ ok: true, message: "Nothing to save. Phren is up to date.", data: { files: 0, pushed: false } });
+            const files = status.split("\n").filter(Boolean);
+            const projectNames = Array.from(new Set(files
+                .map((line) => line.slice(3).trim().split("/")[0])
+                .filter((name) => name && !name.startsWith(".") && name !== "profiles")));
+            const commitMsg = message || `phren: save ${files.length} file(s) across ${projectNames.length} project(s)`;
+            runCustomHooks(phrenPath, "pre-save");
+            // Stage all files including untracked (new project dirs, first FINDINGS.md, etc.)
+            runGit(["add", "-A"]);
+            runGit(["commit", "-m", commitMsg]);
+            let hasRemote = false;
+            try {
+                const remotes = runGit(["remote"]);
+                hasRemote = remotes.length > 0;
+            }
+            catch (err) {
+                logger.warn("push_changes", `remoteCheck: ${errorMessage(err)}`);
+            }
+            if (!hasRemote) {
+                const changedFiles = status.split("\n").filter(Boolean).length;
+                return mcpResponse({ ok: true, message: `Saved ${changedFiles} changed file(s). No remote configured, skipping push.`, data: { files: changedFiles, pushed: false } });
+            }
+            let pushed = false;
+            let lastPushError = "";
+            const delays = [2000, 4000, 8000];
+            for (let attempt = 0; attempt <= 3; attempt++) {
+                try {
+                    runGit(["push"], { timeout: 15000 });
+                    pushed = true;
+                    break;
+                }
+                catch (pushErr) {
+                    lastPushError = pushErr instanceof Error ? pushErr.message : String(pushErr);
+                    debugLog(`Push attempt ${attempt + 1} failed: ${lastPushError}`);
+                    if (attempt < 3) {
+                        try {
+                            runGit(["pull", "--rebase", "--quiet"], { timeout: 15000 });
+                        }
+                        catch (pullErr) {
+                            logger.warn("push_changes", `pullRebase: ${pullErr instanceof Error ? pullErr.message : String(pullErr)}`);
+                            const resolved = autoMergeConflicts(phrenPath);
+                            if (resolved) {
+                                try {
+                                    runGit(["rebase", "--continue"], {
+                                        timeout: 10000,
+                                        env: { ...process.env, GIT_EDITOR: "true" },
+                                    });
+                                }
+                                catch (continueErr) {
+                                    logger.warn("push_changes", `rebaseContinue: ${continueErr instanceof Error ? continueErr.message : String(continueErr)}`);
+                                    try {
+                                        runGit(["rebase", "--abort"]);
+                                    }
+                                    catch (abortErr) {
+                                        logger.warn("push_changes", `rebaseAbort: ${abortErr instanceof Error ? abortErr.message : String(abortErr)}`);
+                                    }
+                                    break;
+                                }
+                            }
+                            else {
+                                try {
+                                    runGit(["rebase", "--abort"]);
+                                }
+                                catch (abortErr) {
+                                    logger.warn("push_changes", `rebaseAbort2: ${abortErr instanceof Error ? abortErr.message : String(abortErr)}`);
+                                }
+                                break;
+                            }
+                        }
+                        await new Promise(r => setTimeout(r, delays[attempt]));
+                    }
+                }
+            }
+            const changedFiles = status.split("\n").filter(Boolean).length;
+            runCustomHooks(phrenPath, "post-save", { PHREN_FILES_CHANGED: String(changedFiles), PHREN_PUSHED: String(pushed) });
+            if (pushed) {
+                return mcpResponse({ ok: true, message: `Saved ${changedFiles} changed file(s). Pushed to remote.`, data: { files: changedFiles, pushed: true } });
+            }
+            else {
+                return mcpResponse({
+                    ok: true,
+                    message: `Changes were committed but push failed.\n\nGit error: ${lastPushError}\n\nRun 'git push' manually from your phren directory.`,
+                    data: { files: changedFiles, pushed: false, pushError: lastPushError },
+                });
+            }
+        }
+        catch (err) {
+            return mcpResponse({ ok: false, error: `Save failed: ${errorMessage(err)}`, errorCode: "INTERNAL_ERROR" });
+        }
+    });
+}
+// ── Registration ─────────────────────────────────────────────────────────────
+export function register(server, ctx) {
     server.registerTool("add_finding", {
         title: "◆ phren · save finding",
         description: "Tell phren one or more insights for a project's FINDINGS.md. Call this the moment you discover " +
@@ -115,152 +496,7 @@ export function register(server, ctx) {
                 .describe("Classify this finding: 'decision' (architectural choice with rationale), 'pitfall' (bug or failure mode to avoid), 'pattern' (reusable approach that works well), 'tradeoff' (deliberate compromise), 'architecture' (structural design note), 'bug' (confirmed defect or failure)."),
             scope: z.string().optional().describe("Optional memory scope label. Defaults to 'shared'. Example: 'researcher' or 'builder'."),
         }),
-    }, async ({ project, finding, citation, sessionId, source, findingType, scope }) => {
-        if (!isValidProjectName(project))
-            return mcpResponse({ ok: false, error: `Invalid project name: "${project}"` });
-        const addFindingDenied = permissionDeniedError(phrenPath, "add_finding", project);
-        if (addFindingDenied)
-            return mcpResponse({ ok: false, error: addFindingDenied });
-        if (Array.isArray(finding)) {
-            const findings = finding;
-            if (findings.length > 100)
-                return mcpResponse({ ok: false, error: "Bulk add limited to 100 findings per call." });
-            if (findings.some((f) => f.length > 5000))
-                return mcpResponse({ ok: false, error: "One or more findings exceed 5000 character limit." });
-            return withWriteQueue(async () => {
-                runCustomHooks(phrenPath, "pre-finding", { PHREN_PROJECT: project });
-                const allPotentialDuplicates = [];
-                const extraAnnotationsByFinding = [];
-                for (const f of findings) {
-                    const candidates = findJaccardCandidates(phrenPath, project, f);
-                    if (candidates.length > 0)
-                        allPotentialDuplicates.push({ finding: f, candidates });
-                    try {
-                        const conflicts = await checkSemanticConflicts(phrenPath, project, f);
-                        extraAnnotationsByFinding.push(conflicts.checked && conflicts.annotations.length > 0 ? conflicts.annotations : []);
-                    }
-                    catch (err) {
-                        logger.debug("add_finding", `bulk semanticConflict: ${errorMessage(err)}`);
-                        extraAnnotationsByFinding.push([]);
-                    }
-                }
-                const result = addFindingsToFile(phrenPath, project, findings, {
-                    extraAnnotationsByFinding,
-                    sessionId,
-                });
-                if (!result.ok)
-                    return mcpResponse({ ok: false, error: result.error });
-                const { added, skipped, rejected } = result.data;
-                if (added.length > 0) {
-                    runCustomHooks(phrenPath, "post-finding", { PHREN_PROJECT: project });
-                    incrementSessionFindings(phrenPath, added.length, sessionId, project);
-                    updateFileInIndex(path.join(phrenPath, project, "FINDINGS.md"));
-                }
-                const rejectedMsg = rejected.length > 0 ? `, ${rejected.length} rejected` : "";
-                return mcpResponse({
-                    ok: true,
-                    message: `Added ${added.length}/${findings.length} findings (${skipped.length} duplicates skipped${rejectedMsg})`,
-                    data: {
-                        project,
-                        added,
-                        skipped,
-                        rejected,
-                        ...(allPotentialDuplicates.length > 0 ? { potentialDuplicates: allPotentialDuplicates } : {}),
-                    },
-                });
-            });
-        }
-        if (finding.length > 5000)
-            return mcpResponse({ ok: false, error: "Finding text exceeds 5000 character limit." });
-        const normalizedScope = normalizeMemoryScope(scope ?? "shared");
-        if (!normalizedScope)
-            return mcpResponse({ ok: false, error: `Invalid scope: "${scope}". Use lowercase letters/numbers with '-' or '_' (max 64 chars), e.g. "researcher".` });
-        return withWriteQueue(async () => {
-            try {
-                const taggedFinding = findingType ? `[${findingType}] ${finding}` : finding;
-                // Jaccard "maybe zone" scan — free, no LLM call. Return candidates so the agent decides.
-                const potentialDuplicates = findJaccardCandidates(phrenPath, project, taggedFinding);
-                const semanticConflicts = await checkSemanticConflicts(phrenPath, project, taggedFinding);
-                runCustomHooks(phrenPath, "pre-finding", { PHREN_PROJECT: project });
-                const result = addFindingToFile(phrenPath, project, taggedFinding, citation, {
-                    sessionId,
-                    source,
-                    scope: normalizedScope,
-                    extraAnnotations: semanticConflicts.checked ? semanticConflicts.annotations : undefined,
-                });
-                if (!result.ok) {
-                    return mcpResponse({ ok: false, error: result.error });
-                }
-                if (result.data.status === "skipped") {
-                    return mcpResponse({ ok: true, message: result.data.message, data: { project, finding: taggedFinding, status: "skipped" } });
-                }
-                updateFileInIndex(path.join(phrenPath, project, "FINDINGS.md"));
-                if (result.data.status === "added" || result.data.status === "created") {
-                    runCustomHooks(phrenPath, "post-finding", { PHREN_PROJECT: project });
-                    incrementSessionFindings(phrenPath, 1, sessionId, project);
-                    extractFactFromFinding(phrenPath, project, taggedFinding);
-                    // Bidirectional link: if there's an active task in this session, append this finding to it.
-                    if (sessionId) {
-                        const activeTask = getActiveTaskForSession(phrenPath, sessionId, project);
-                        if (activeTask) {
-                            const taskMatch = activeTask.stableId ? `bid:${activeTask.stableId}` : activeTask.line;
-                            // Extract fid from the last written line in FINDINGS.md
-                            try {
-                                const findingsPath = path.join(phrenPath, project, "FINDINGS.md");
-                                const findingsContent = fs.readFileSync(findingsPath, "utf8");
-                                const lines = findingsContent.split("\n");
-                                const taggedText = taggedFinding.replace(/^-\s+/, "").trim().slice(0, 60).toLowerCase();
-                                for (let li = lines.length - 1; li >= 0; li--) {
-                                    const l = lines[li];
-                                    if (!l.startsWith("- "))
-                                        continue;
-                                    const lineText = l.replace(/<!--.*?-->/g, "").replace(/^-\s+/, "").trim().slice(0, 60).toLowerCase();
-                                    if (lineText === taggedText || l.toLowerCase().includes(taggedText.slice(0, 30))) {
-                                        const fidMatch = l.match(/<!--\s*fid:([a-z0-9]{8})\s*-->/);
-                                        if (fidMatch) {
-                                            appendChildFinding(phrenPath, project, taskMatch, `fid:${fidMatch[1]}`);
-                                        }
-                                        break;
-                                    }
-                                }
-                            }
-                            catch {
-                                // Non-fatal: task-finding linkage is best-effort
-                            }
-                        }
-                    }
-                }
-                const conflictsWithList = semanticConflicts.checked
-                    ? extractConflictsWith(semanticConflicts.annotations)
-                    : (result.data.message.match(/<!--\s*conflicts_with:\s*"([^"]+)"/)?.[1] ? [result.data.message.match(/<!--\s*conflicts_with:\s*"([^"]+)"/)[1]] : []);
-                const conflictsWith = conflictsWithList[0];
-                // Extract fragment hints synchronously from the finding text (regex only, no DB).
-                // Full DB fragment linking happens on the next index rebuild via updateFileInIndex →
-                // extractAndLinkEntities. We surface hints here so callers can see what was detected.
-                const detectedFragments = extractFragmentNames(taggedFinding);
-                return mcpResponse({
-                    ok: true,
-                    message: result.data.message,
-                    data: {
-                        project,
-                        finding: taggedFinding,
-                        status: result.data.status,
-                        ...(conflictsWith ? { conflictsWith } : {}),
-                        ...(conflictsWithList.length > 0 ? { conflicts: conflictsWithList } : {}),
-                        ...(detectedFragments.length > 0 ? { detectedFragments } : {}),
-                        ...(potentialDuplicates.length > 0 ? { potentialDuplicates } : {}),
-                        scope: normalizedScope,
-                    }
-                });
-            }
-            catch (err) {
-                if (err instanceof Error && err.message.includes("Rejected:")) {
-                    return mcpResponse({ ok: false, error: errorMessage(err), errorCode: "VALIDATION_ERROR" });
-                }
-                return mcpResponse({ ok: false, error: `Unexpected error saving finding: ${errorMessage(err)}` });
-            }
-        });
-    });
+    }, (params) => handleAddFinding(ctx, params));
     server.registerTool("supersede_finding", {
         title: "◆ phren · supersede finding",
         description: "Mark an existing finding as superseded and link it to the newer finding text.",
@@ -269,12 +505,7 @@ export function register(server, ctx) {
             finding_text: z.string().describe("Finding to supersede (supports fid, exact text, or partial match)."),
             superseded_by: z.string().describe("Text of the new finding that supersedes this one."),
         }),
-    }, async ({ project, finding_text, superseded_by }) => {
-        return withLifecycleMutation(phrenPath, project, withWriteQueue, updateFileInIndex, () => supersedeFinding(phrenPath, project, finding_text, superseded_by), (data) => ({
-            message: `Marked finding as superseded in ${project}.`,
-            data: { project, finding: data.finding, status: data.status, superseded_by: data.superseded_by },
-        }));
-    });
+    }, (params) => handleSupersedeFinding(ctx, params));
     server.registerTool("retract_finding", {
         title: "◆ phren · retract finding",
         description: "Mark an existing finding as retracted and store the reason in lifecycle metadata.",
@@ -283,12 +514,7 @@ export function register(server, ctx) {
             finding_text: z.string().describe("Finding to retract (supports fid, exact text, or partial match)."),
             reason: z.string().describe("Reason for retraction."),
         }),
-    }, async ({ project, finding_text, reason }) => {
-        return withLifecycleMutation(phrenPath, project, withWriteQueue, updateFileInIndex, () => retractFindingLifecycle(phrenPath, project, finding_text, reason), (data) => ({
-            message: `Retracted finding in ${project}.`,
-            data: { project, finding: data.finding, status: data.status, reason: data.reason },
-        }));
-    });
+    }, (params) => handleRetractFinding(ctx, params));
     server.registerTool("resolve_contradiction", {
         title: "◆ phren · resolve contradiction",
         description: "Resolve a contradiction between two findings and update lifecycle status based on the chosen resolution.",
@@ -315,27 +541,7 @@ export function register(server, ctx) {
                 });
             }
         }),
-    }, async ({ project, finding_text, finding_text_other, finding_a, finding_b, resolution }) => {
-        const findingText = (finding_text ?? finding_a)?.trim();
-        const findingTextOther = (finding_text_other ?? finding_b)?.trim();
-        if (!findingText || !findingTextOther) {
-            return mcpResponse({
-                ok: false,
-                error: "Both finding_text and finding_text_other are required.",
-            });
-        }
-        return withLifecycleMutation(phrenPath, project, withWriteQueue, updateFileInIndex, () => resolveFindingContradiction(phrenPath, project, findingText, findingTextOther, resolution), (data) => ({
-            message: `Resolved contradiction in ${project} with "${resolution}".`,
-            data: {
-                project,
-                resolution: data.resolution,
-                finding_text: data.finding_a,
-                finding_text_other: data.finding_b,
-                finding_a: data.finding_a,
-                finding_b: data.finding_b,
-            },
-        }));
-    });
+    }, (params) => handleResolveContradiction(ctx, params));
     server.registerTool("get_contradictions", {
         title: "◆ phren · contradictions",
         description: "List unresolved contradictions (findings currently marked with status contradicted).",
@@ -343,48 +549,7 @@ export function register(server, ctx) {
             project: z.string().optional().describe("Optional project filter. When omitted, scans all projects."),
             finding_text: z.string().optional().describe("Optional finding selector (supports fid, exact text, or partial match)."),
         }),
-    }, async ({ project, finding_text }) => {
-        if (project && !isValidProjectName(project))
-            return mcpResponse({ ok: false, error: `Invalid project name: "${project}"` });
-        const projects = project
-            ? [project]
-            : fs.readdirSync(phrenPath, { withFileTypes: true })
-                .filter((entry) => entry.isDirectory() && !RESERVED_PROJECT_DIR_NAMES.has(entry.name) && isValidProjectName(entry.name))
-                .map((entry) => entry.name);
-        const contradictions = [];
-        for (const p of projects) {
-            const result = readFindings(phrenPath, p);
-            if (!result.ok)
-                continue;
-            for (const finding of result.data) {
-                if (finding.status !== "contradicted")
-                    continue;
-                if (finding_text && !matchesFindingTextSelector(finding, finding_text))
-                    continue;
-                contradictions.push({
-                    project: p,
-                    id: finding.id,
-                    stableId: finding.stableId,
-                    text: finding.text,
-                    date: finding.date,
-                    status_updated: finding.status_updated,
-                    status_reason: finding.status_reason,
-                    status_ref: finding.status_ref,
-                });
-            }
-        }
-        return mcpResponse({
-            ok: true,
-            message: contradictions.length
-                ? `Found ${contradictions.length} unresolved contradiction${contradictions.length === 1 ? "" : "s"}.`
-                : "No unresolved contradictions found.",
-            data: {
-                project: project ?? null,
-                finding_text: finding_text ?? null,
-                contradictions,
-            },
-        });
-    });
+    }, (params) => handleGetContradictions(ctx, params));
     server.registerTool("edit_finding", {
         title: "◆ phren · edit finding",
         description: "Edit a finding in place while preserving its metadata and history.",
@@ -393,26 +558,7 @@ export function register(server, ctx) {
             old_text: z.string().describe("Existing finding text to match."),
             new_text: z.string().describe("Replacement finding text."),
         }),
-    }, async ({ project, old_text, new_text }) => {
-        if (!isValidProjectName(project))
-            return mcpResponse({ ok: false, error: `Invalid project name: "${project}"` });
-        const editDenied = permissionDeniedError(phrenPath, "edit_finding", project);
-        if (editDenied)
-            return mcpResponse({ ok: false, error: editDenied });
-        return withWriteQueue(async () => {
-            const result = editFindingCore(phrenPath, project, old_text, new_text);
-            if (!result.ok)
-                return mcpResponse({ ok: false, error: result.error });
-            const resolvedFindingsDir = safeProjectPath(phrenPath, project);
-            if (resolvedFindingsDir)
-                updateFileInIndex(path.join(resolvedFindingsDir, "FINDINGS.md"));
-            return mcpResponse({
-                ok: true,
-                message: result.data,
-                data: { project, old_text, new_text },
-            });
-        });
-    });
+    }, (params) => handleEditFinding(ctx, params));
     server.registerTool("remove_finding", {
         title: "◆ phren · remove finding",
         description: "Remove one or more findings from a project's FINDINGS.md by matching text. Use this when a " +
@@ -425,33 +571,7 @@ export function register(server, ctx) {
                 z.array(z.string()).describe("List of partial texts to match and remove."),
             ]).describe("Text(s) to match and remove. Pass a string for one, or an array for bulk."),
         }),
-    }, async ({ project, finding }) => {
-        if (!isValidProjectName(project))
-            return mcpResponse({ ok: false, error: `Invalid project name: "${project}"` });
-        const removeDenied = permissionDeniedError(phrenPath, "remove_finding", project);
-        if (removeDenied)
-            return mcpResponse({ ok: false, error: removeDenied });
-        if (Array.isArray(finding)) {
-            return withWriteQueue(async () => {
-                const result = removeFindingsCore(phrenPath, project, finding);
-                if (!result.ok)
-                    return mcpResponse({ ok: false, error: result.message });
-                const resolvedFindingsDir = safeProjectPath(phrenPath, project);
-                if (resolvedFindingsDir)
-                    updateFileInIndex(path.join(resolvedFindingsDir, "FINDINGS.md"));
-                return mcpResponse({ ok: true, message: result.message, data: result.data });
-            });
-        }
-        return withWriteQueue(async () => {
-            const result = removeFindingCore(phrenPath, project, finding);
-            if (!result.ok)
-                return mcpResponse({ ok: false, error: result.message });
-            const resolvedFindingsDir = safeProjectPath(phrenPath, project);
-            if (resolvedFindingsDir)
-                updateFileInIndex(path.join(resolvedFindingsDir, "FINDINGS.md"));
-            return mcpResponse({ ok: true, message: result.message, data: result.data });
-        });
-    });
+    }, (params) => handleRemoveFinding(ctx, params));
     server.registerTool("push_changes", {
         title: "◆ phren · push",
         description: "Commit and push any changes in the phren store. Call this at the end of a session " +
@@ -460,108 +580,5 @@ export function register(server, ctx) {
         inputSchema: z.object({
             message: z.string().optional().describe("Commit message. Defaults to 'update phren'."),
         }),
-    }, async ({ message }) => {
-        return withWriteQueue(async () => {
-            const { execFileSync } = await import("child_process");
-            const runGit = (args, opts = {}) => execFileSync("git", args, {
-                cwd: phrenPath,
-                encoding: "utf8",
-                timeout: opts.timeout ?? EXEC_TIMEOUT_MS,
-                env: opts.env,
-                stdio: ["ignore", "pipe", "pipe"],
-            }).trim();
-            try {
-                const status = runGit(["status", "--porcelain"]);
-                if (!status)
-                    return mcpResponse({ ok: true, message: "Nothing to save. Phren is up to date.", data: { files: 0, pushed: false } });
-                const files = status.split("\n").filter(Boolean);
-                const projectNames = Array.from(new Set(files
-                    .map((line) => line.slice(3).trim().split("/")[0])
-                    .filter((name) => name && !name.startsWith(".") && name !== "profiles")));
-                const commitMsg = message || `phren: save ${files.length} file(s) across ${projectNames.length} project(s)`;
-                runCustomHooks(phrenPath, "pre-save");
-                // Stage all files including untracked (new project dirs, first FINDINGS.md, etc.)
-                runGit(["add", "-A"]);
-                runGit(["commit", "-m", commitMsg]);
-                let hasRemote = false;
-                try {
-                    const remotes = runGit(["remote"]);
-                    hasRemote = remotes.length > 0;
-                }
-                catch (err) {
-                    logger.warn("push_changes", `remoteCheck: ${errorMessage(err)}`);
-                }
-                if (!hasRemote) {
-                    const changedFiles = status.split("\n").filter(Boolean).length;
-                    return mcpResponse({ ok: true, message: `Saved ${changedFiles} changed file(s). No remote configured, skipping push.`, data: { files: changedFiles, pushed: false } });
-                }
-                let pushed = false;
-                let lastPushError = "";
-                const delays = [2000, 4000, 8000];
-                for (let attempt = 0; attempt <= 3; attempt++) {
-                    try {
-                        runGit(["push"], { timeout: 15000 });
-                        pushed = true;
-                        break;
-                    }
-                    catch (pushErr) {
-                        lastPushError = pushErr instanceof Error ? pushErr.message : String(pushErr);
-                        debugLog(`Push attempt ${attempt + 1} failed: ${lastPushError}`);
-                        if (attempt < 3) {
-                            try {
-                                runGit(["pull", "--rebase", "--quiet"], { timeout: 15000 });
-                            }
-                            catch (pullErr) {
-                                logger.warn("push_changes", `pullRebase: ${pullErr instanceof Error ? pullErr.message : String(pullErr)}`);
-                                const resolved = autoMergeConflicts(phrenPath);
-                                if (resolved) {
-                                    try {
-                                        runGit(["rebase", "--continue"], {
-                                            timeout: 10000,
-                                            env: { ...process.env, GIT_EDITOR: "true" },
-                                        });
-                                    }
-                                    catch (continueErr) {
-                                        logger.warn("push_changes", `rebaseContinue: ${continueErr instanceof Error ? continueErr.message : String(continueErr)}`);
-                                        try {
-                                            runGit(["rebase", "--abort"]);
-                                        }
-                                        catch (abortErr) {
-                                            logger.warn("push_changes", `rebaseAbort: ${abortErr instanceof Error ? abortErr.message : String(abortErr)}`);
-                                        }
-                                        break;
-                                    }
-                                }
-                                else {
-                                    try {
-                                        runGit(["rebase", "--abort"]);
-                                    }
-                                    catch (abortErr) {
-                                        logger.warn("push_changes", `rebaseAbort2: ${abortErr instanceof Error ? abortErr.message : String(abortErr)}`);
-                                    }
-                                    break;
-                                }
-                            }
-                            await new Promise(r => setTimeout(r, delays[attempt]));
-                        }
-                    }
-                }
-                const changedFiles = status.split("\n").filter(Boolean).length;
-                runCustomHooks(phrenPath, "post-save", { PHREN_FILES_CHANGED: String(changedFiles), PHREN_PUSHED: String(pushed) });
-                if (pushed) {
-                    return mcpResponse({ ok: true, message: `Saved ${changedFiles} changed file(s). Pushed to remote.`, data: { files: changedFiles, pushed: true } });
-                }
-                else {
-                    return mcpResponse({
-                        ok: true,
-                        message: `Changes were committed but push failed.\n\nGit error: ${lastPushError}\n\nRun 'git push' manually from your phren directory.`,
-                        data: { files: changedFiles, pushed: false, pushError: lastPushError },
-                    });
-                }
-            }
-            catch (err) {
-                return mcpResponse({ ok: false, error: `Save failed: ${errorMessage(err)}`, errorCode: "INTERNAL_ERROR" });
-            }
-        });
-    });
+    }, (params) => handlePushChanges(ctx, params));
 }