@phren/cli 0.0.1

package/mcp/dist/finding-impact.js

@@ -0,0 +1,181 @@
+import * as crypto from "crypto";
+import * as fs from "fs";
+import { impactLogFile } from "./shared.js";
+import { withFileLock } from "./shared-governance.js";
+let highImpactCache = null;
+function nowIso() {
+    return new Date().toISOString();
+}
+function normalizeFindingText(raw) {
+    return raw
+        .replace(/^-\s+/, "")
+        .replace(/<!--.*?-->/g, " ")
+        .replace(/\[confidence\s+[01](?:\.\d+)?\]/gi, " ")
+        .replace(/\s+/g, " ")
+        .trim()
+        .toLowerCase();
+}
+export function findingIdFromLine(line) {
+    const fid = line.match(/<!--\s*fid:([a-z0-9]{8})\s*-->/i);
+    if (fid?.[1])
+        return `fid:${fid[1].toLowerCase()}`;
+    const normalized = normalizeFindingText(line);
+    if (!normalized)
+        return "hash:empty";
+    const hash = crypto.createHash("sha1").update(normalized).digest("hex").slice(0, 12);
+    return `hash:${hash}`;
+}
+export function extractFindingIdsFromSnippet(snippet) {
+    const lines = snippet
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0);
+    const bulletLines = lines.filter((line) => line.startsWith("- "));
+    const candidates = bulletLines.length > 0 ? bulletLines : (lines[0] ? [lines[0]] : []);
+    const ids = new Set();
+    for (const line of candidates) {
+        ids.add(findingIdFromLine(line));
+    }
+    return [...ids];
+}
+function parseImpactLine(line) {
+    const trimmed = line.trim();
+    if (!trimmed)
+        return null;
+    try {
+        const parsed = JSON.parse(trimmed);
+        if (!parsed
+            || typeof parsed.findingId !== "string"
+            || typeof parsed.project !== "string"
+            || typeof parsed.timestamp !== "string"
+            || typeof parsed.sessionId !== "string"
+            || typeof parsed.taskCompleted !== "boolean") {
+            return null;
+        }
+        return {
+            findingId: parsed.findingId,
+            project: parsed.project,
+            timestamp: parsed.timestamp,
+            sessionId: parsed.sessionId,
+            taskCompleted: parsed.taskCompleted,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function readImpactSummary(phrenPath) {
+    const file = impactLogFile(phrenPath);
+    const surfaceCountByFinding = new Map();
+    const completedByFinding = new Set();
+    if (!fs.existsSync(file)) {
+        return {
+            surfaceCountByFinding,
+            completedByFinding,
+        };
+    }
+    const content = fs.readFileSync(file, "utf8");
+    for (const line of content.split("\n")) {
+        const entry = parseImpactLine(line);
+        if (!entry)
+            continue;
+        surfaceCountByFinding.set(entry.findingId, (surfaceCountByFinding.get(entry.findingId) ?? 0) + 1);
+        if (entry.taskCompleted) {
+            completedByFinding.add(entry.findingId);
+        }
+    }
+    return {
+        surfaceCountByFinding,
+        completedByFinding,
+    };
+}
+function appendImpact(phrenPath, entries) {
+    if (entries.length === 0)
+        return;
+    const file = impactLogFile(phrenPath);
+    withFileLock(file, () => {
+        const lines = entries.map((entry) => JSON.stringify(entry));
+        fs.appendFileSync(file, lines.join("\n") + "\n");
+    });
+}
+export function logImpact(phrenPath, entries) {
+    if (entries.length === 0)
+        return;
+    const timestamp = nowIso();
+    appendImpact(phrenPath, entries.map((entry) => ({
+        findingId: entry.findingId,
+        project: entry.project,
+        sessionId: entry.sessionId,
+        timestamp,
+        taskCompleted: false,
+    })));
+}
+export function getHighImpactFindings(phrenPath, minSurfaceCount = 3) {
+    const file = impactLogFile(phrenPath);
+    let stat = null;
+    try {
+        stat = fs.existsSync(file) ? fs.statSync(file) : null;
+    }
+    catch {
+        stat = null;
+    }
+    if (!stat)
+        return new Set();
+    if (highImpactCache
+        && highImpactCache.file === file
+        && highImpactCache.mtimeMs === stat.mtimeMs
+        && highImpactCache.size === stat.size
+        && highImpactCache.minSurfaceCount === minSurfaceCount) {
+        return new Set(highImpactCache.ids);
+    }
+    const summary = readImpactSummary(phrenPath);
+    const ids = new Set();
+    for (const [findingId, surfaceCount] of summary.surfaceCountByFinding.entries()) {
+        if (surfaceCount >= minSurfaceCount && summary.completedByFinding.has(findingId)) {
+            ids.add(findingId);
+        }
+    }
+    highImpactCache = {
+        file,
+        mtimeMs: stat.mtimeMs,
+        size: stat.size,
+        minSurfaceCount,
+        ids,
+    };
+    return new Set(ids);
+}
+export function markImpactEntriesCompletedForSession(phrenPath, sessionId, project) {
+    if (!sessionId)
+        return 0;
+    const file = impactLogFile(phrenPath);
+    if (!fs.existsSync(file))
+        return 0;
+    const updated = withFileLock(file, () => {
+        if (!fs.existsSync(file))
+            return 0;
+        const lines = fs.readFileSync(file, "utf8").split("\n");
+        let updatedCount = 0;
+        const rewritten = lines
+            .filter((line) => line.trim().length > 0)
+            .map((line) => {
+            const entry = parseImpactLine(line);
+            if (!entry)
+                return line;
+            if (entry.taskCompleted)
+                return line;
+            if (entry.sessionId !== sessionId)
+                return line;
+            if (project && entry.project !== project)
+                return line;
+            updatedCount += 1;
+            return JSON.stringify({ ...entry, taskCompleted: true });
+        });
+        if (updatedCount > 0) {
+            fs.writeFileSync(file, rewritten.join("\n") + "\n");
+        }
+        return updatedCount;
+    });
+    if (updated > 0)
+        highImpactCache = null;
+    return updated;
+}

package/mcp/dist/finding-journal.js

@@ -0,0 +1,122 @@
+import * as fs from "fs";
+import * as path from "path";
+import * as crypto from "crypto";
+import { runtimeDir, phrenOk, phrenErr, PhrenError } from "./shared.js";
+import { withFileLock } from "./shared-governance.js";
+import { addFindingToFile } from "./shared-content.js";
+import { isValidProjectName, errorMessage } from "./utils.js";
+function journalRoot(phrenPath) {
+    const dir = path.join(runtimeDir(phrenPath), "finding-journal");
+    fs.mkdirSync(dir, { recursive: true });
+    return dir;
+}
+function sanitizeSessionId(sessionId) {
+    const raw = (sessionId || `session-${new Date().toISOString().slice(0, 10)}`).trim();
+    const safe = raw.replace(/[^a-zA-Z0-9._-]+/g, "_").replace(/^_+|_+$/g, "");
+    return safe || "session";
+}
+function journalFileFor(phrenPath, project, sessionId) {
+    const projectDir = path.join(journalRoot(phrenPath), project);
+    fs.mkdirSync(projectDir, { recursive: true });
+    return path.join(projectDir, `${sanitizeSessionId(sessionId)}.jsonl`);
+}
+function listJournalFiles(phrenPath, project) {
+    const root = journalRoot(phrenPath);
+    const projects = project ? [project] : fs.readdirSync(root).filter((entry) => fs.statSync(path.join(root, entry)).isDirectory());
+    const files = [];
+    for (const projectName of projects) {
+        const projectDir = path.join(root, projectName);
+        if (!fs.existsSync(projectDir))
+            continue;
+        for (const entry of fs.readdirSync(projectDir)) {
+            if (!entry.endsWith(".jsonl"))
+                continue;
+            files.push(path.join(projectDir, entry));
+        }
+    }
+    return files.sort();
+}
+export function appendFindingJournal(phrenPath, project, text, opts = {}) {
+    if (!isValidProjectName(project))
+        return phrenErr(`Invalid project name: "${project}".`, PhrenError.INVALID_PROJECT_NAME);
+    const filePath = journalFileFor(phrenPath, project, opts.sessionId);
+    const entry = {
+        at: new Date().toISOString(),
+        project,
+        text,
+        ...(opts.source ? { source: opts.source } : {}),
+        ...(opts.sessionId ? { sessionId: opts.sessionId } : {}),
+        ...(opts.repo ? { repo: opts.repo } : {}),
+        ...(opts.commit ? { commit: opts.commit } : {}),
+        ...(opts.file ? { file: opts.file } : {}),
+    };
+    try {
+        withFileLock(filePath, () => {
+            fs.mkdirSync(path.dirname(filePath), { recursive: true });
+            fs.appendFileSync(filePath, JSON.stringify(entry) + "\n");
+        });
+        return phrenOk(filePath);
+    }
+    catch (err) {
+        return phrenErr(`Failed to append finding journal: ${errorMessage(err)}`, PhrenError.PERMISSION_DENIED);
+    }
+}
+export function compactFindingJournals(phrenPath, project) {
+    const result = {
+        filesProcessed: 0,
+        entriesProcessed: 0,
+        added: 0,
+        skipped: 0,
+        failed: 0,
+    };
+    for (const filePath of listJournalFiles(phrenPath, project)) {
+        const claimed = `${filePath}.${crypto.randomUUID()}.claim`;
+        try {
+            fs.renameSync(filePath, claimed);
+        }
+        catch {
+            continue;
+        }
+        result.filesProcessed += 1;
+        try {
+            const entries = fs.readFileSync(claimed, "utf8")
+                .split("\n")
+                .filter(Boolean)
+                .map((line) => {
+                try {
+                    return JSON.parse(line);
+                }
+                catch {
+                    return null;
+                }
+            })
+                .filter((entry) => Boolean(entry && entry.project && entry.text));
+            for (const entry of entries) {
+                result.entriesProcessed += 1;
+                const write = addFindingToFile(phrenPath, entry.project, entry.text, {
+                    ...(entry.repo ? { repo: entry.repo } : {}),
+                    ...(entry.commit ? { commit: entry.commit } : {}),
+                    ...(entry.file ? { file: entry.file } : {}),
+                }, {
+                    source: entry.source,
+                    sessionId: entry.sessionId,
+                });
+                if (!write.ok) {
+                    result.failed += 1;
+                    continue;
+                }
+                if (typeof write.data === "string" && write.data.includes("Skipped duplicate"))
+                    result.skipped += 1;
+                else
+                    result.added += 1;
+            }
+        }
+        finally {
+            try {
+                fs.unlinkSync(claimed);
+            }
+            catch { }
+        }
+    }
+    return result;
+}

package/mcp/dist/finding-lifecycle.js

@@ -0,0 +1,259 @@
+import * as fs from "fs";
+import * as path from "path";
+import { PhrenError, phrenErr, phrenOk } from "./phren-core.js";
+// Phren lifecycle comment prefix. No backward compat.
+const LIFECYCLE_PREFIX = "phren";
+import { withFileLock } from "./governance-locks.js";
+import { isValidProjectName, safeProjectPath } from "./utils.js";
+import { parseCreatedDate as parseCreatedDateMeta, parseStatusField, parseStatus, parseSupersession, parseContradiction, parseFindingId as parseFindingIdMeta, stripLifecycleMetadata, stripRelationMetadata, } from "./content-metadata.js";
+export const FINDING_LIFECYCLE_STATUSES = [
+    "active",
+    "superseded",
+    "contradicted",
+    "stale",
+    "invalid_citation",
+    "retracted",
+];
+function cleanCommentValue(value) {
+    return value.replace(/\s+/g, " ").trim();
+}
+function serializeCommentValue(value) {
+    return cleanCommentValue(value).replace(/"/g, "'");
+}
+function parseCreatedDate(line) {
+    const created = parseCreatedDateMeta(line);
+    return created ? cleanCommentValue(created) : undefined;
+}
+function matchField(line, field) {
+    return parseStatusField(line, field);
+}
+export function parseFindingLifecycle(line) {
+    const created = parseCreatedDate(line);
+    const normalizedStatus = parseStatus(line);
+    const normalized = {
+        status: normalizedStatus ?? "active",
+        status_updated: matchField(line, "status_updated") ?? created,
+        status_reason: matchField(line, "status_reason"),
+        status_ref: matchField(line, "status_ref"),
+    };
+    if (normalizedStatus)
+        return normalized;
+    const supersession = parseSupersession(line);
+    if (supersession) {
+        const updated = supersession.date || normalized.status_updated;
+        return {
+            status: "superseded",
+            status_updated: updated ? cleanCommentValue(updated) : undefined,
+            status_reason: normalized.status_reason ?? "superseded_by",
+            status_ref: normalized.status_ref ?? cleanCommentValue(supersession.ref || ""),
+        };
+    }
+    const contradictionRef = parseContradiction(line);
+    if (contradictionRef) {
+        return {
+            status: "contradicted",
+            status_updated: normalized.status_updated,
+            status_reason: normalized.status_reason ?? "conflicts_with",
+            status_ref: normalized.status_ref ?? cleanCommentValue(contradictionRef),
+        };
+    }
+    return normalized;
+}
+export function buildLifecycleComments(lifecycle, fallbackDate) {
+    const status = lifecycle?.status ?? "active";
+    const statusUpdated = lifecycle?.status_updated ?? fallbackDate;
+    const parts = [`<!-- ${LIFECYCLE_PREFIX}:status "${status}" -->`];
+    if (statusUpdated)
+        parts.push(`<!-- ${LIFECYCLE_PREFIX}:status_updated "${serializeCommentValue(statusUpdated)}" -->`);
+    if (lifecycle?.status_reason)
+        parts.push(`<!-- ${LIFECYCLE_PREFIX}:status_reason "${serializeCommentValue(lifecycle.status_reason)}" -->`);
+    if (lifecycle?.status_ref)
+        parts.push(`<!-- ${LIFECYCLE_PREFIX}:status_ref "${serializeCommentValue(lifecycle.status_ref)}" -->`);
+    return parts.join(" ");
+}
+export function stripLifecycleComments(line) {
+    return stripLifecycleMetadata(line);
+}
+export function isInactiveFindingLine(line) {
+    return parseFindingLifecycle(line).status !== "active";
+}
+function findingTextFromLine(line) {
+    return line
+        .replace(/^-\s+/, "")
+        .replace(/<!--.*?-->/g, "")
+        .trim();
+}
+function normalizeFindingText(value) {
+    return findingTextFromLine(value)
+        .replace(/\s+/g, " ")
+        .toLowerCase();
+}
+function removeRelationComments(line) {
+    return stripRelationMetadata(line);
+}
+function applyLifecycle(line, lifecycle, today, opts) {
+    let updated = stripLifecycleComments(removeRelationComments(line)).trimEnd();
+    if (opts?.supersededBy) {
+        updated += ` <!-- ${LIFECYCLE_PREFIX}:superseded_by "${serializeCommentValue(opts.supersededBy)}" ${today} -->`;
+    }
+    if (opts?.supersedes) {
+        updated += ` <!-- ${LIFECYCLE_PREFIX}:supersedes "${serializeCommentValue(opts.supersedes)}" -->`;
+    }
+    if (opts?.contradicts) {
+        const contradictionRef = serializeCommentValue(opts.contradicts);
+        updated += ` <!-- conflicts_with: "${contradictionRef}" --> <!-- ${LIFECYCLE_PREFIX}:contradicts "${contradictionRef}" -->`;
+    }
+    updated += ` ${buildLifecycleComments(lifecycle, today)}`;
+    return updated;
+}
+function matchFinding(lines, match) {
+    const needleRaw = match.trim();
+    if (!needleRaw)
+        return phrenErr("Finding text cannot be empty.", PhrenError.EMPTY_INPUT);
+    const needle = normalizeFindingText(needleRaw);
+    const bulletLines = lines
+        .map((line, index) => ({ line, index }))
+        .filter(({ line }) => line.startsWith("- "));
+    const fidNeedle = needle.replace(/^fid:/, "");
+    const fidMatches = /^[a-z0-9]{8}$/.test(fidNeedle)
+        ? bulletLines.filter(({ line }) => new RegExp(`<!--\\s*fid:${fidNeedle}\\s*-->`, "i").test(line))
+        : [];
+    const exactMatches = bulletLines.filter(({ line }) => normalizeFindingText(line) === needle);
+    const partialMatches = bulletLines.filter(({ line }) => {
+        const clean = normalizeFindingText(line);
+        return clean.includes(needle) || line.toLowerCase().includes(needle);
+    });
+    let selected;
+    if (fidMatches.length === 1) {
+        selected = fidMatches[0];
+    }
+    else if (exactMatches.length === 1) {
+        selected = exactMatches[0];
+    }
+    else if (exactMatches.length > 1) {
+        return phrenErr(`"${match}" is ambiguous (${exactMatches.length} exact matches). Use a more specific phrase.`, PhrenError.AMBIGUOUS_MATCH);
+    }
+    else if (partialMatches.length === 1) {
+        selected = partialMatches[0];
+    }
+    else if (partialMatches.length > 1) {
+        return phrenErr(`"${match}" is ambiguous (${partialMatches.length} partial matches). Use a more specific phrase.`, PhrenError.AMBIGUOUS_MATCH);
+    }
+    if (!selected) {
+        return phrenErr(`No finding matching "${match}".`, PhrenError.NOT_FOUND);
+    }
+    const stableId = parseFindingIdMeta(selected.line);
+    return phrenOk({
+        index: selected.index,
+        line: selected.line,
+        text: findingTextFromLine(selected.line),
+        stableId,
+    });
+}
+function findingsPathForProject(phrenPath, project) {
+    if (!isValidProjectName(project))
+        return phrenErr(`Invalid project name: "${project}"`, PhrenError.INVALID_PROJECT_NAME);
+    const projectDir = safeProjectPath(phrenPath, project);
+    if (!projectDir)
+        return phrenErr(`Invalid project name: "${project}"`, PhrenError.INVALID_PROJECT_NAME);
+    if (!fs.existsSync(projectDir))
+        return phrenErr(`Project "${project}" not found.`, PhrenError.PROJECT_NOT_FOUND);
+    const findingsPath = path.join(projectDir, "FINDINGS.md");
+    if (!fs.existsSync(findingsPath))
+        return phrenErr(`No FINDINGS.md found for "${project}".`, PhrenError.FILE_NOT_FOUND);
+    return phrenOk(findingsPath);
+}
+export function supersedeFinding(phrenPath, project, findingText, supersededBy) {
+    const pathResult = findingsPathForProject(phrenPath, project);
+    if (!pathResult.ok)
+        return pathResult;
+    const findingsPath = pathResult.data;
+    const ref = supersededBy.trim().slice(0, 60);
+    if (!ref)
+        return phrenErr("superseded_by cannot be empty.", PhrenError.EMPTY_INPUT);
+    return withFileLock(findingsPath, () => {
+        const lines = fs.readFileSync(findingsPath, "utf8").split("\n");
+        const matched = matchFinding(lines, findingText);
+        if (!matched.ok)
+            return matched;
+        const today = new Date().toISOString().slice(0, 10);
+        lines[matched.data.index] = applyLifecycle(lines[matched.data.index], { status: "superseded", status_updated: today, status_reason: "superseded_by", status_ref: ref }, today, { supersededBy: ref });
+        const normalized = lines.join("\n").replace(/\n{3,}/g, "\n\n").trimEnd() + "\n";
+        fs.writeFileSync(findingsPath, normalized);
+        return phrenOk({ finding: matched.data.text, superseded_by: ref, status: "superseded" });
+    });
+}
+export function retractFinding(phrenPath, project, findingText, reason) {
+    const pathResult = findingsPathForProject(phrenPath, project);
+    if (!pathResult.ok)
+        return pathResult;
+    const findingsPath = pathResult.data;
+    const reasonText = reason.trim();
+    if (!reasonText)
+        return phrenErr("reason cannot be empty.", PhrenError.EMPTY_INPUT);
+    return withFileLock(findingsPath, () => {
+        const lines = fs.readFileSync(findingsPath, "utf8").split("\n");
+        const matched = matchFinding(lines, findingText);
+        if (!matched.ok)
+            return matched;
+        const today = new Date().toISOString().slice(0, 10);
+        lines[matched.data.index] = applyLifecycle(lines[matched.data.index], { status: "retracted", status_updated: today, status_reason: reasonText }, today);
+        const normalized = lines.join("\n").replace(/\n{3,}/g, "\n\n").trimEnd() + "\n";
+        fs.writeFileSync(findingsPath, normalized);
+        return phrenOk({ finding: matched.data.text, reason: reasonText, status: "retracted" });
+    });
+}
+export function resolveFindingContradiction(phrenPath, project, findingA, findingB, resolution) {
+    const pathResult = findingsPathForProject(phrenPath, project);
+    if (!pathResult.ok)
+        return pathResult;
+    const findingsPath = pathResult.data;
+    return withFileLock(findingsPath, () => {
+        const lines = fs.readFileSync(findingsPath, "utf8").split("\n");
+        const matchedA = matchFinding(lines, findingA);
+        if (!matchedA.ok)
+            return matchedA;
+        const matchedB = matchFinding(lines, findingB);
+        if (!matchedB.ok)
+            return matchedB;
+        if (matchedA.data.index === matchedB.data.index) {
+            return phrenErr("finding_a and finding_b refer to the same finding.", PhrenError.VALIDATION_ERROR);
+        }
+        const today = new Date().toISOString().slice(0, 10);
+        const refA = matchedA.data.text.slice(0, 60);
+        const refB = matchedB.data.text.slice(0, 60);
+        let statusA = "active";
+        let statusB = "active";
+        if (resolution === "keep_a") {
+            lines[matchedA.data.index] = applyLifecycle(lines[matchedA.data.index], { status: "active", status_updated: today, status_reason: "contradiction_resolved_keep_a", status_ref: refB }, today);
+            lines[matchedB.data.index] = applyLifecycle(lines[matchedB.data.index], { status: "superseded", status_updated: today, status_reason: "contradiction_resolved_keep_a", status_ref: refA }, today, { supersededBy: refA });
+            statusA = "active";
+            statusB = "superseded";
+        }
+        else if (resolution === "keep_b") {
+            lines[matchedA.data.index] = applyLifecycle(lines[matchedA.data.index], { status: "superseded", status_updated: today, status_reason: "contradiction_resolved_keep_b", status_ref: refB }, today, { supersededBy: refB });
+            lines[matchedB.data.index] = applyLifecycle(lines[matchedB.data.index], { status: "active", status_updated: today, status_reason: "contradiction_resolved_keep_b", status_ref: refA }, today);
+            statusA = "superseded";
+            statusB = "active";
+        }
+        else if (resolution === "keep_both") {
+            lines[matchedA.data.index] = applyLifecycle(lines[matchedA.data.index], { status: "active", status_updated: today, status_reason: "contradiction_resolved_keep_both", status_ref: refB }, today);
+            lines[matchedB.data.index] = applyLifecycle(lines[matchedB.data.index], { status: "active", status_updated: today, status_reason: "contradiction_resolved_keep_both", status_ref: refA }, today);
+            statusA = "active";
+            statusB = "active";
+        }
+        else {
+            lines[matchedA.data.index] = applyLifecycle(lines[matchedA.data.index], { status: "retracted", status_updated: today, status_reason: "contradiction_retracted_both", status_ref: refB }, today);
+            lines[matchedB.data.index] = applyLifecycle(lines[matchedB.data.index], { status: "retracted", status_updated: today, status_reason: "contradiction_retracted_both", status_ref: refA }, today);
+            statusA = "retracted";
+            statusB = "retracted";
+        }
+        const normalized = lines.join("\n").replace(/\n{3,}/g, "\n\n").trimEnd() + "\n";
+        fs.writeFileSync(findingsPath, normalized);
+        return phrenOk({
+            resolution,
+            finding_a: { text: matchedA.data.text, status: statusA },
+            finding_b: { text: matchedB.data.text, status: statusB },
+        });
+    });
+}

package/mcp/dist/governance-audit.js

@@ -0,0 +1,22 @@
+import * as fs from "fs";
+import * as path from "path";
+import { debugLog } from "./shared.js";
+import { errorMessage } from "./utils.js";
+export function recordRetrieval(phrenPath, file, section) {
+    const dir = path.join(phrenPath, ".runtime");
+    fs.mkdirSync(dir, { recursive: true });
+    const logPath = path.join(dir, "retrieval-log.jsonl");
+    const entry = { file, section, retrievedAt: new Date().toISOString() };
+    fs.appendFileSync(logPath, JSON.stringify(entry) + "\n");
+    try {
+        const stat = fs.statSync(logPath);
+        if (stat.size > 500_000) {
+            const content = fs.readFileSync(logPath, "utf8");
+            const lines = content.split("\n").filter(Boolean);
+            fs.writeFileSync(logPath, lines.slice(-1000).join("\n") + "\n");
+        }
+    }
+    catch (err) {
+        debugLog(`recordRetrieval rotation failed: ${errorMessage(err)}`);
+    }
+}

package/mcp/dist/governance-locks.js

@@ -0,0 +1,96 @@
+import * as fs from "fs";
+import * as path from "path";
+import { debugLog } from "./shared.js";
+// Acquire the file lock, returning true on success or throwing on timeout.
+function acquireFileLock(lockPath) {
+    const maxWait = Number.parseInt(process.env.PHREN_FILE_LOCK_MAX_WAIT_MS || process.env.PHREN_FILE_LOCK_MAX_WAIT_MS || "5000", 10) || 5000;
+    const pollInterval = Number.parseInt((process.env.PHREN_FILE_LOCK_POLL_MS) || "100", 10) || 100;
+    const staleThreshold = Number.parseInt((process.env.PHREN_FILE_LOCK_STALE_MS) || "30000", 10) || 30000;
+    const waiter = new Int32Array(new SharedArrayBuffer(4));
+    const sleep = (ms) => Atomics.wait(waiter, 0, 0, ms);
+    fs.mkdirSync(path.dirname(lockPath), { recursive: true });
+    let waited = 0;
+    let hasLock = false;
+    while (waited < maxWait) {
+        try {
+            fs.writeFileSync(lockPath, `${process.pid}\n${Date.now()}`, { flag: "wx" });
+            hasLock = true;
+            break;
+        }
+        catch (err) {
+            if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+                process.stderr.write(`[phren] acquireFileLock lockWrite: ${err instanceof Error ? err.message : String(err)}\n`);
+            try {
+                const stat = fs.statSync(lockPath);
+                if (Date.now() - stat.mtimeMs > staleThreshold) {
+                    // Verify lock owner PID is dead before removing stale lock
+                    let ownerDead = true;
+                    try {
+                        const lockContent = fs.readFileSync(lockPath, "utf8");
+                        const lockPid = Number.parseInt(lockContent.split("\n")[0], 10);
+                        if (Number.isFinite(lockPid) && lockPid > 0) {
+                            try {
+                                process.kill(lockPid, 0); // signal 0 = check if alive
+                                ownerDead = false; // PID is still alive, don't steal the lock
+                            }
+                            catch {
+                                ownerDead = true; // PID is dead, safe to remove
+                            }
+                        }
+                    }
+                    catch {
+                        ownerDead = true; // Can't read lock file, treat as dead
+                    }
+                    if (ownerDead) {
+                        fs.unlinkSync(lockPath);
+                        continue;
+                    }
+                }
+            }
+            catch (statErr) {
+                if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+                    process.stderr.write(`[phren] acquireFileLock staleStat: ${statErr instanceof Error ? statErr.message : String(statErr)}\n`);
+                sleep(pollInterval);
+                waited += pollInterval;
+                continue;
+            }
+            sleep(pollInterval);
+            waited += pollInterval;
+        }
+    }
+    if (!hasLock) {
+        const msg = `withFileLock: could not acquire lock for "${path.basename(lockPath)}" within ${maxWait}ms`;
+        debugLog(msg);
+        throw new Error(msg);
+    }
+}
+function releaseFileLock(lockPath) {
+    try {
+        fs.unlinkSync(lockPath);
+    }
+    catch (err) {
+        if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+            process.stderr.write(`[phren] releaseFileLock: ${err instanceof Error ? err.message : String(err)}\n`);
+    }
+}
+// Q10: withFileLock now accepts both sync and async callbacks.
+// When the callback returns a Promise, the lock file is held until the
+// Promise settles — preventing concurrent processes from seeing partial state.
+export function withFileLock(filePath, fn) {
+    const lockPath = filePath + ".lock";
+    acquireFileLock(lockPath);
+    let result;
+    try {
+        result = fn();
+    }
+    catch (err) {
+        releaseFileLock(lockPath);
+        throw err;
+    }
+    // If the callback returned a Promise, hold the lock until it settles.
+    if (result instanceof Promise) {
+        return result.then((value) => { releaseFileLock(lockPath); return value; }, (err) => { releaseFileLock(lockPath); throw err; });
+    }
+    releaseFileLock(lockPath);
+    return result;
+}