@phren/cli 0.0.5 → 0.0.7

package/README.md

@@ -8,7 +8,7 @@
 </p>
 
 <p align="center">
-Phren is a git-backed knowledge layer that gives AI agents persistent memory across sessions, projects, and machines. Findings, decisions, and patterns are captured as markdown in a repo you control — no hosted service, no vendor lock-in.
+Every time you start a new session, your AI agent forgets everything it learned. Phren fixes that — findings, decisions, and patterns persist as markdown in a git repo you control. No database, no hosted service, no vendor lock-in. Works across sessions, projects, and machines.
 </p>
 
 ---
@@ -51,8 +51,8 @@ To add a project later, run `phren add` from that directory. To browse what phre
 
 - [Documentation site](https://alaarab.github.io/phren/)
 - [Whitepaper (PDF)](https://alaarab.github.io/phren/whitepaper.pdf)
-- [Architecture](docs/architecture.md)
-- [Contributing](CONTRIBUTING.md)
+- [Architecture](docs/architecture.md) — how retrieval, governance, and persistence fit together
+- [Contributing](CONTRIBUTING.md) — how to add tools, skills, and tests
 - [Security](SECURITY.md)
 
 ---

package/mcp/dist/cli-hooks-session.js

@@ -867,9 +867,15 @@ export async function handleHookStop() {
             appendAuditLog(phrenPath, "hook_stop", "status=clean");
             return;
         }
-        // Exclude sensitive files from staging: .env files and private keys should
-        // never be committed to the phren git repository.
-        const add = await runBestEffortGit(["add", "-A", "--", ":(exclude).env", ":(exclude)**/.env", ":(exclude)*.pem", ":(exclude)*.key"], phrenPath);
+        // Stage all changes first, then unstage any sensitive files that slipped
+        // through. Using pathspec exclusions with `git add -A` can fail when
+        // excluded paths are also gitignored (git treats the pathspec as an error).
+        let add = await runBestEffortGit(["add", "-A"], phrenPath);
+        if (add.ok) {
+            // Belt-and-suspenders: unstage sensitive files that .gitignore should
+            // already block. Failures here are non-fatal (files may not exist).
+            await runBestEffortGit(["reset", "HEAD", "--", ".env", "**/.env", "*.pem", "*.key"], phrenPath);
+        }
         let commitMsg = "auto-save phren";
         if (add.ok) {
             const diff = await runBestEffortGit(["diff", "--cached", "--stat", "--no-color"], phrenPath);

package/mcp/dist/cli-hooks.js

@@ -150,6 +150,26 @@ export async function handleHookPrompt() {
     if (!keywords)
         process.exit(0);
     debugLog(`hook-prompt keywords: "${keywords}"`);
+    // Session momentum: track topic frequencies within the session
+    let hotTopics = [];
+    if (sessionId) {
+        const topicFile = sessionMarker(getPhrenPath(), `topics-${sessionId}.json`);
+        let sessionTopics = {};
+        try {
+            if (fs.existsSync(topicFile)) {
+                sessionTopics = JSON.parse(fs.readFileSync(topicFile, 'utf8'));
+            }
+        }
+        catch { /* ignore parse errors */ }
+        for (const kw of keywordEntries) {
+            sessionTopics[kw] = (sessionTopics[kw] ?? 0) + 1;
+        }
+        fs.writeFileSync(topicFile, JSON.stringify(sessionTopics));
+        // Find hot topics (3+ mentions this session)
+        hotTopics = Object.entries(sessionTopics)
+            .filter(([, count]) => count >= 3)
+            .map(([topic]) => topic);
+    }
     const tIndex0 = Date.now();
     const db = await buildIndex(getPhrenPath(), profile);
     stage.indexMs = Date.now() - tIndex0;
@@ -197,20 +217,18 @@ export async function handleHookPrompt() {
         stage.rankMs = Date.now() - tRank0;
         if (!rows.length)
             process.exit(0);
-        const safeTokenBudget = clampInt(process.env.PHREN_CONTEXT_TOKEN_BUDGET, 550, 180, 10000);
+        let safeTokenBudget = clampInt(process.env.PHREN_CONTEXT_TOKEN_BUDGET, 550, 180, 10000);
         const safeLineBudget = clampInt(process.env.PHREN_CONTEXT_SNIPPET_LINES, 6, 2, 100);
         const safeCharBudget = clampInt(process.env.PHREN_CONTEXT_SNIPPET_CHARS, 520, 120, 10000);
+        // Session momentum: boost token budget for hot topics
+        if (hotTopics.length > 0) {
+            safeTokenBudget = Math.min(Math.floor(safeTokenBudget * 1.3), parseInt(process.env.PHREN_MAX_INJECT_TOKENS ?? '2000', 10));
+        }
         const tSelect0 = Date.now();
         const { selected, usedTokens } = selectSnippets(rows, keywords, safeTokenBudget, safeLineBudget, safeCharBudget);
         stage.selectMs = Date.now() - tSelect0;
         if (!selected.length)
             process.exit(0);
-        // Log query-to-finding correlations for future pre-warming (gated by env var)
-        try {
-            const { logCorrelations: logCorr } = await import("./query-correlation.js");
-            logCorr(getPhrenPath(), keywords, selected, sessionId);
-        }
-        catch { /* non-fatal */ }
         // Injection budget: cap total injected tokens across all content
         const maxInjectTokens = clampInt(process.env.PHREN_MAX_INJECT_TOKENS, 2000, 200, 20000);
         let budgetSelected = selected;
@@ -327,7 +345,7 @@ export async function handleHookPrompt() {
                 parts.push(`Findings ready for consolidation:`);
                 parts.push(notices.join("\n"));
                 parts.push(`Run phren-consolidate when ready.`);
-                parts.push(`<phren-notice>`);
+                parts.push(`</phren-notice>`);
             }
             if (noticeFile) {
                 try {
@@ -349,7 +367,7 @@ export async function handleHookPrompt() {
     }
     catch (err) {
         const msg = errorMessage(err);
-        process.stdout.write(`\n<phren-error>phren hook failed: ${msg}. Check ~/.phren/.runtime/debug.log for details.<phren-error>\n`);
+        process.stdout.write(`\n<phren-error>phren hook failed: ${msg}. Check ~/.phren/.runtime/debug.log for details.</phren-error>\n`);
         debugLog(`hook-prompt error: ${msg}`);
         process.exit(0);
     }

package/mcp/dist/content-citation.js

@@ -5,7 +5,7 @@ import { debugLog, EXEC_TIMEOUT_MS, EXEC_TIMEOUT_QUICK_MS } from "./shared.js";
 import { errorMessage, runGitOrThrow } from "./utils.js";
 import { findingIdFromLine } from "./finding-impact.js";
 import { METADATA_REGEX, isArchiveStart, isArchiveEnd } from "./content-metadata.js";
-import { FINDING_TYPE_DECAY, extractFindingType } from "./finding-lifecycle.js";
+import { FINDING_TYPE_DECAY, extractFindingType, parseFindingLifecycle } from "./finding-lifecycle.js";
 export const FINDING_PROVENANCE_SOURCES = [
     "human",
     "agent",
@@ -294,6 +294,7 @@ export function filterTrustedFindingsDetailed(content, opts) {
         ...(options.decay || {}),
     };
     const highImpactFindingIds = options.highImpactFindingIds;
+    const impactCounts = options.impactCounts;
     const project = options.project;
     const lines = content.split("\n");
     const out = [];
@@ -412,9 +413,29 @@ export function filterTrustedFindingsDetailed(content, opts) {
             confidence *= 0.9;
         if (project && highImpactFindingIds?.size) {
             const findingId = findingIdFromLine(line);
-            if (highImpactFindingIds.has(findingId))
-                confidence *= 1.15;
+            if (highImpactFindingIds.has(findingId)) {
+                // Get surface count for graduated boost
+                const surfaceCount = impactCounts?.get(findingId) ?? 3;
+                // Log-scaled: 3→1.15x, 10→1.28x, 30→1.38x, capped at 1.4x
+                const boost = Math.min(1.4, 1 + 0.1 * Math.log2(Math.max(3, surfaceCount)));
+                confidence *= boost;
+                // Decay resistance: confirmed findings decay 3x slower
+                if (effectiveDate) {
+                    const realAge = ageDaysForDate(effectiveDate);
+                    if (realAge !== null) {
+                        const slowedAge = Math.floor(realAge / 3);
+                        confidence = Math.max(confidence, confidenceForAge(slowedAge, decay));
+                    }
+                }
+            }
         }
+        const lifecycle = parseFindingLifecycle(line);
+        if (lifecycle?.status === "superseded")
+            confidence *= 0.25;
+        if (lifecycle?.status === "retracted")
+            confidence *= 0.1;
+        if (lifecycle?.status === "contradicted")
+            confidence *= 0.4;
         confidence = Math.max(0, Math.min(1, confidence));
         if (confidence < minConfidence) {
             issues.push({ date: effectiveDate || "unknown", bullet: line, reason: "stale" });

package/mcp/dist/content-learning.js

@@ -11,7 +11,7 @@ import { isDuplicateFinding, scanForSecrets, normalizeObservationTags, resolveCo
 import { validateFindingsFormat, validateFinding } from "./content-validate.js";
 import { countActiveFindings, autoArchiveToReference } from "./content-archive.js";
 import { resolveAutoFindingTaskItem, resolveFindingTaskReference, resolveFindingSessionId, } from "./finding-context.js";
-import { buildLifecycleComments, parseFindingLifecycle, stripLifecycleComments, } from "./finding-lifecycle.js";
+import { buildLifecycleComments, extractFindingType, parseFindingLifecycle, stripLifecycleComments, } from "./finding-lifecycle.js";
 import { METADATA_REGEX, } from "./content-metadata.js";
 /** Default cap for active findings before auto-archiving is triggered. */
 const DEFAULT_FINDINGS_CAP = 20;
@@ -71,12 +71,12 @@ function detectFindingProvenanceSource(explicitSource) {
         return "extract";
     if ((process.env.PHREN_HOOK_TOOL))
         return "hook";
-    if ((process.env.PHREN_ACTOR || process.env.PHREN_ACTOR)?.trim())
+    if (process.env.PHREN_ACTOR?.trim())
         return "agent";
     return "human";
 }
 function buildFindingSource(sessionId, explicitSource, scope) {
-    const actor = (process.env.PHREN_ACTOR || process.env.PHREN_ACTOR)?.trim() || undefined;
+    const actor = process.env.PHREN_ACTOR?.trim() || undefined;
     const source = {
         source: detectFindingProvenanceSource(explicitSource),
         machine: getMachineName(),
@@ -107,6 +107,22 @@ function resolveFindingCitationInput(phrenPath, project, citationInput) {
     }
     return phrenOk(Object.keys(resolved).length > 0 ? resolved : undefined);
 }
+export function autoDetectFindingType(text) {
+    const lower = text.toLowerCase();
+    if (/\b(we decided|decision:|chose .+ over|went with)\b/.test(lower))
+        return 'decision';
+    if (/\b(bug:|bug in|found a bug|broken|crashes|fails when)\b/.test(lower))
+        return 'bug';
+    if (/\b(workaround:|work around|temporary fix|hack:)\b/.test(lower))
+        return 'workaround';
+    if (/\b(pattern:|always .+ before|never .+ without|best practice)\b/.test(lower))
+        return 'pattern';
+    if (/\b(pitfall:|gotcha:|watch out|careful with|trap:)\b/.test(lower))
+        return 'pitfall';
+    if (/\b(currently|as of|right now|at the moment|observation:)\b/.test(lower))
+        return 'context';
+    return null;
+}
 function prepareFinding(learning, project, fullHistory, extraAnnotations, citationInput, source, nowIso, inferredRepo, headCommit, phrenPath) {
     const secretType = scanForSecrets(learning);
     if (secretType) {
@@ -114,10 +130,17 @@ function prepareFinding(learning, project, fullHistory, extraAnnotations, citati
     }
     const today = (nowIso ?? new Date().toISOString()).slice(0, 10);
     const { text: tagNormalized, warning: tagWarning } = normalizeObservationTags(learning);
-    const normalizedLearning = resolveCoref(tagNormalized, {
+    let normalizedLearning = resolveCoref(tagNormalized, {
         project,
         file: citationInput?.file,
     });
+    const existingType = extractFindingType('- ' + normalizedLearning);
+    if (!existingType) {
+        const detected = autoDetectFindingType(normalizedLearning);
+        if (detected) {
+            normalizedLearning = `[${detected}] ${normalizedLearning}`;
+        }
+    }
     const fid = crypto.randomBytes(4).toString("hex");
     const fidComment = `<!-- fid:${fid} -->`;
     const createdComment = `<!-- created: ${today} -->`;
@@ -332,7 +355,7 @@ export function addFindingToFile(phrenPath, project, learning, citationInput, op
                 if (!newLines[i].startsWith("- "))
                     continue;
                 if (newLines[i].includes(prepared.finding.bullet.slice(0, 40))) {
-                    if (!newLines[i].includes("phren:supersedes") && !newLines[i].includes("phren:supersedes")) {
+                    if (!newLines[i].includes("phren:supersedes")) {
                         const supersedesFirst60 = supersedesText.slice(0, 60);
                         newLines[i] = `${newLines[i]} <!-- phren:supersedes "${supersedesFirst60}" -->`;
                     }

package/mcp/dist/data-access.js

@@ -1,6 +1,7 @@
 import * as fs from "fs";
 import * as path from "path";
-import { phrenErr, PhrenError, phrenOk, forwardErr, getProjectDirs, } from "./shared.js";
+import * as yaml from "js-yaml";
+import { phrenErr, PhrenError, phrenOk, forwardErr, getProjectDirs, isRecord, } from "./shared.js";
 import { normalizeQueueEntryText, withFileLock as withFileLockRaw, } from "./shared-governance.js";
 import { addFindingToFile, } from "./shared-content.js";
 import { isValidProjectName, queueFilePath, safeProjectPath, errorMessage } from "./utils.js";
@@ -54,6 +55,69 @@ function normalizeFindingGroupKey(item) {
 function findingTimelineDate(item) {
     return item.status_updated || item.date || "0000-00-00";
 }
+function collectFindingBulletLines(lines) {
+    const bulletLines = [];
+    let inArchiveBlock = false;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (isArchiveStart(line)) {
+            inArchiveBlock = true;
+            continue;
+        }
+        if (isArchiveEnd(line)) {
+            inArchiveBlock = false;
+            continue;
+        }
+        if (!line.startsWith("- "))
+            continue;
+        bulletLines.push({ line, i, archived: inArchiveBlock });
+    }
+    return bulletLines;
+}
+function findMatchingFindingBullet(bulletLines, needle, match) {
+    const fidNeedle = needle.replace(/^fid:/, "");
+    const fidMatch = /^[a-z0-9]{8}$/.test(fidNeedle)
+        ? bulletLines.filter(({ line }) => new RegExp(`<!--\\s*fid:${fidNeedle}\\s*-->`).test(line))
+        : [];
+    const exactMatches = bulletLines.filter(({ line }) => line.replace(/^-\s+/, "").replace(/<!--.*?-->/g, "").trim().toLowerCase() === needle);
+    const partialMatches = bulletLines.filter(({ line }) => line.toLowerCase().includes(needle));
+    if (fidMatch.length === 1)
+        return { kind: "found", idx: fidMatch[0].i };
+    if (exactMatches.length === 1)
+        return { kind: "found", idx: exactMatches[0].i };
+    if (exactMatches.length > 1) {
+        return { kind: "ambiguous", error: `"${match}" is ambiguous (${exactMatches.length} exact matches). Use a more specific phrase.` };
+    }
+    if (partialMatches.length === 1)
+        return { kind: "found", idx: partialMatches[0].i };
+    if (partialMatches.length > 1) {
+        return { kind: "ambiguous", error: `"${match}" is ambiguous (${partialMatches.length} partial matches). Use a more specific phrase.` };
+    }
+    return { kind: "not_found" };
+}
+function validateAggregateQueueProfile(phrenPath, profile) {
+    if (!profile)
+        return phrenOk(undefined);
+    if (!isValidProjectName(profile)) {
+        return phrenErr(`Invalid PHREN_PROFILE value: ${profile}`, PhrenError.VALIDATION_ERROR);
+    }
+    const profilePath = path.join(phrenPath, "profiles", `${profile}.yaml`);
+    if (!fs.existsSync(profilePath)) {
+        return phrenErr(`Profile file not found: ${profilePath}`, PhrenError.FILE_NOT_FOUND);
+    }
+    let data;
+    try {
+        data = yaml.load(fs.readFileSync(profilePath, "utf-8"), { schema: yaml.CORE_SCHEMA });
+    }
+    catch {
+        return phrenErr(`Malformed profile YAML: ${profilePath}`, PhrenError.MALFORMED_YAML);
+    }
+    const projects = isRecord(data) ? data.projects : undefined;
+    if (!Array.isArray(projects)) {
+        return phrenErr(`Profile YAML missing valid "projects" array: ${profilePath}`, PhrenError.MALFORMED_YAML);
+    }
+    return phrenOk(undefined);
+}
 export function readFindings(phrenPath, project, opts = {}) {
     const ensured = ensureProject(phrenPath, project);
     if (!ensured.ok)
@@ -203,42 +267,29 @@ export function removeFinding(phrenPath, project, match) {
     const ensured = ensureProject(phrenPath, project);
     if (!ensured.ok)
         return forwardErr(ensured);
-    const findingsPath = path.join(ensured.data, 'FINDINGS.md');
+    const findingsPath = path.resolve(path.join(ensured.data, 'FINDINGS.md'));
+    if (!findingsPath.startsWith(phrenPath + path.sep) && findingsPath !== phrenPath) {
+        return phrenErr(`FINDINGS.md path escapes phren store`, PhrenError.VALIDATION_ERROR);
+    }
     const filePath = findingsPath;
     if (!fs.existsSync(filePath))
         return phrenErr(`No FINDINGS.md file found for "${project}". Add a finding first with add_finding or :find add.`, PhrenError.FILE_NOT_FOUND);
     return withSafeLock(filePath, () => {
         const lines = fs.readFileSync(filePath, "utf8").split("\n");
         const needle = match.trim().toLowerCase();
-        const bulletLines = lines.map((line, i) => ({ line, i })).filter(({ line }) => line.startsWith("- "));
-        // 0) Stable finding ID match (fid:XXXXXXXX or just the 8-char hex)
-        const fidNeedle = needle.replace(/^fid:/, "");
-        const fidMatch = /^[a-z0-9]{8}$/.test(fidNeedle)
-            ? bulletLines.filter(({ line }) => new RegExp(`<!--\\s*fid:${fidNeedle}\\s*-->`).test(line))
-            : [];
-        // 1) Exact text match (strip bullet prefix + metadata for comparison)
-        const exactMatches = bulletLines.filter(({ line }) => line.replace(/^-\s+/, "").replace(/<!--.*?-->/g, "").trim().toLowerCase() === needle);
-        // 2) Unique partial substring match
-        const partialMatches = bulletLines.filter(({ line }) => line.toLowerCase().includes(needle));
-        let idx;
-        if (fidMatch.length === 1) {
-            idx = fidMatch[0].i;
-        }
-        else if (exactMatches.length === 1) {
-            idx = exactMatches[0].i;
-        }
-        else if (exactMatches.length > 1) {
-            return phrenErr(`"${match}" is ambiguous (${exactMatches.length} exact matches). Use a more specific phrase.`, PhrenError.AMBIGUOUS_MATCH);
+        const bulletLines = collectFindingBulletLines(lines);
+        const activeMatch = findMatchingFindingBullet(bulletLines.filter(({ archived }) => !archived), needle, match);
+        if (activeMatch.kind === "ambiguous") {
+            return phrenErr(activeMatch.error, PhrenError.AMBIGUOUS_MATCH);
         }
-        else if (partialMatches.length === 1) {
-            idx = partialMatches[0].i;
-        }
-        else if (partialMatches.length > 1) {
-            return phrenErr(`"${match}" is ambiguous (${partialMatches.length} partial matches). Use a more specific phrase.`, PhrenError.AMBIGUOUS_MATCH);
-        }
-        else {
+        if (activeMatch.kind === "not_found") {
+            const archivedMatch = findMatchingFindingBullet(bulletLines.filter(({ archived }) => archived), needle, match);
+            if (archivedMatch.kind === "ambiguous" || archivedMatch.kind === "found") {
+                return phrenErr(`Finding "${match}" is archived and read-only. Restore or re-add it before mutating history.`, PhrenError.VALIDATION_ERROR);
+            }
             return phrenErr(`No finding matching "${match}" in project "${project}". Try a different search term or check :findings view.`, PhrenError.NOT_FOUND);
         }
+        const idx = activeMatch.idx;
         const removeCount = isCitationLine(lines[idx + 1] || "") ? 2 : 1;
         const matched = lines[idx];
         lines.splice(idx, removeCount);
@@ -254,39 +305,28 @@ export function editFinding(phrenPath, project, oldText, newText) {
     const newTextTrimmed = newText.trim();
     if (!newTextTrimmed)
         return phrenErr("New finding text cannot be empty.", PhrenError.EMPTY_INPUT);
-    const findingsPath = path.join(ensured.data, "FINDINGS.md");
+    const findingsPath = path.resolve(path.join(ensured.data, "FINDINGS.md"));
+    if (!findingsPath.startsWith(phrenPath + path.sep) && findingsPath !== phrenPath) {
+        return phrenErr(`FINDINGS.md path escapes phren store`, PhrenError.VALIDATION_ERROR);
+    }
     if (!fs.existsSync(findingsPath))
         return phrenErr(`No FINDINGS.md file found for "${project}".`, PhrenError.FILE_NOT_FOUND);
     return withSafeLock(findingsPath, () => {
         const lines = fs.readFileSync(findingsPath, "utf8").split("\n");
         const needle = oldText.trim().toLowerCase();
-        const bulletLines = lines.map((line, i) => ({ line, i })).filter(({ line }) => line.startsWith("- "));
-        // Stable finding ID match
-        const fidNeedle = needle.replace(/^fid:/, "");
-        const fidMatch = /^[a-z0-9]{8}$/.test(fidNeedle)
-            ? bulletLines.filter(({ line }) => new RegExp(`<!--\\s*fid:${fidNeedle}\\s*-->`).test(line))
-            : [];
-        const exactMatches = bulletLines.filter(({ line }) => line.replace(/^-\s+/, "").replace(/<!--.*?-->/g, "").trim().toLowerCase() === needle);
-        const partialMatches = bulletLines.filter(({ line }) => line.toLowerCase().includes(needle));
-        let idx;
-        if (fidMatch.length === 1) {
-            idx = fidMatch[0].i;
-        }
-        else if (exactMatches.length === 1) {
-            idx = exactMatches[0].i;
+        const bulletLines = collectFindingBulletLines(lines);
+        const activeMatch = findMatchingFindingBullet(bulletLines.filter(({ archived }) => !archived), needle, oldText);
+        if (activeMatch.kind === "ambiguous") {
+            return phrenErr(activeMatch.error, PhrenError.AMBIGUOUS_MATCH);
         }
-        else if (exactMatches.length > 1) {
-            return phrenErr(`"${oldText}" is ambiguous (${exactMatches.length} exact matches). Use a more specific phrase.`, PhrenError.AMBIGUOUS_MATCH);
-        }
-        else if (partialMatches.length === 1) {
-            idx = partialMatches[0].i;
-        }
-        else if (partialMatches.length > 1) {
-            return phrenErr(`"${oldText}" is ambiguous (${partialMatches.length} partial matches). Use a more specific phrase.`, PhrenError.AMBIGUOUS_MATCH);
-        }
-        else {
+        if (activeMatch.kind === "not_found") {
+            const archivedMatch = findMatchingFindingBullet(bulletLines.filter(({ archived }) => archived), needle, oldText);
+            if (archivedMatch.kind === "ambiguous" || archivedMatch.kind === "found") {
+                return phrenErr(`Finding "${oldText}" is archived and read-only. Restore or re-add it before mutating history.`, PhrenError.VALIDATION_ERROR);
+            }
             return phrenErr(`No finding matching "${oldText}" in project "${project}".`, PhrenError.NOT_FOUND);
         }
+        const idx = activeMatch.idx;
         // Preserve existing metadata comment (fid, citations, etc.)
         const existing = lines[idx];
         const metaMatch = existing.match(/(<!--.*?-->)/g);
@@ -366,6 +406,9 @@ export function readReviewQueue(phrenPath, project) {
     return phrenOk(items);
 }
 export function readReviewQueueAcrossProjects(phrenPath, profile) {
+    const validation = validateAggregateQueueProfile(phrenPath, profile);
+    if (!validation.ok)
+        return validation;
     const projects = getProjectDirs(phrenPath, profile)
         .map((dir) => path.basename(dir))
         .filter((project) => project !== "global")

package/mcp/dist/finding-impact.js

@@ -144,6 +144,29 @@ export function getHighImpactFindings(phrenPath, minSurfaceCount = 3) {
     };
     return new Set(ids);
 }
+export function getImpactSurfaceCounts(phrenPath, minSurfaces = 1) {
+    const file = impactLogFile(phrenPath);
+    if (!fs.existsSync(file))
+        return new Map();
+    const lines = fs.readFileSync(file, "utf8").split("\n").filter(Boolean);
+    const counts = new Map();
+    for (const line of lines) {
+        try {
+            const entry = JSON.parse(line);
+            if (entry.findingId) {
+                counts.set(entry.findingId, (counts.get(entry.findingId) ?? 0) + 1);
+            }
+        }
+        catch { }
+    }
+    // Filter by minimum
+    const filtered = new Map();
+    for (const [id, count] of counts) {
+        if (count >= minSurfaces)
+            filtered.set(id, count);
+    }
+    return filtered;
+}
 export function markImpactEntriesCompletedForSession(phrenPath, sessionId, project) {
     if (!sessionId)
         return 0;

package/mcp/dist/finding-lifecycle.js

@@ -5,7 +5,7 @@ import { PhrenError, phrenErr, phrenOk } from "./phren-core.js";
 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";
+import { isArchiveEnd, isArchiveStart, parseCreatedDate as parseCreatedDateMeta, parseStatusField, parseStatus, parseSupersession, parseContradiction, parseFindingId as parseFindingIdMeta, stripLifecycleMetadata, stripRelationMetadata, } from "./content-metadata.js";
 export const FINDING_TYPE_DECAY = {
     'pattern': { maxAgeDays: 365, decayMultiplier: 1.0 }, // Slow decay, long-lived
     'decision': { maxAgeDays: Infinity, decayMultiplier: 1.0 }, // Never decays
@@ -109,6 +109,49 @@ function normalizeFindingText(value) {
 function removeRelationComments(line) {
     return stripRelationMetadata(line);
 }
+function collectFindingBulletLines(lines) {
+    const bulletLines = [];
+    let inArchiveBlock = false;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (isArchiveStart(line)) {
+            inArchiveBlock = true;
+            continue;
+        }
+        if (isArchiveEnd(line)) {
+            inArchiveBlock = false;
+            continue;
+        }
+        if (!line.startsWith("- "))
+            continue;
+        bulletLines.push({ line, index: i, archived: inArchiveBlock });
+    }
+    return bulletLines;
+}
+function selectMatchingFinding(bulletLines, needle, match) {
+    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);
+    });
+    if (fidMatches.length === 1)
+        return phrenOk(fidMatches[0]);
+    if (exactMatches.length === 1)
+        return phrenOk(exactMatches[0]);
+    if (exactMatches.length > 1) {
+        return phrenErr(`"${match}" is ambiguous (${exactMatches.length} exact matches). Use a more specific phrase.`, PhrenError.AMBIGUOUS_MATCH);
+    }
+    if (partialMatches.length === 1)
+        return phrenOk(partialMatches[0]);
+    if (partialMatches.length > 1) {
+        return phrenErr(`"${match}" is ambiguous (${partialMatches.length} partial matches). Use a more specific phrase.`, PhrenError.AMBIGUOUS_MATCH);
+    }
+    return phrenOk(null);
+}
 function applyLifecycle(line, lifecycle, today, opts) {
     let updated = stripLifecycleComments(removeRelationComments(line)).trimEnd();
     if (opts?.supersededBy) {
@@ -129,35 +172,19 @@ function matchFinding(lines, match) {
     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);
-    }
+    const bulletLines = collectFindingBulletLines(lines);
+    const activeMatch = selectMatchingFinding(bulletLines.filter(({ archived }) => !archived), needle, match);
+    if (!activeMatch.ok)
+        return activeMatch;
+    const selected = activeMatch.data;
     if (!selected) {
+        const archivedMatch = selectMatchingFinding(bulletLines.filter(({ archived }) => archived), needle, match);
+        if (!archivedMatch.ok) {
+            return phrenErr(`Finding "${match}" is archived and read-only. Restore or re-add it before mutating history.`, PhrenError.VALIDATION_ERROR);
+        }
+        if (archivedMatch.data) {
+            return phrenErr(`Finding "${match}" is archived and read-only. Restore or re-add it before mutating history.`, PhrenError.VALIDATION_ERROR);
+        }
         return phrenErr(`No finding matching "${match}".`, PhrenError.NOT_FOUND);
     }
     const stableId = parseFindingIdMeta(selected.line);

package/mcp/dist/governance-locks.js

@@ -3,7 +3,7 @@ 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 maxWait = Number.parseInt(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));
@@ -29,12 +29,17 @@ function acquireFileLock(lockPath) {
                         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
+                            if (process.platform !== 'win32') {
+                                try {
+                                    process.kill(lockPid, 0);
+                                    ownerDead = false;
+                                }
+                                catch {
+                                    ownerDead = true;
+                                }
                             }
-                            catch {
-                                ownerDead = true; // PID is dead, safe to remove
+                            else {
+                                ownerDead = true;
                             }
                         }
                     }

package/mcp/dist/index.js

@@ -19,6 +19,7 @@ import { register as registerSkills } from "./mcp-skills.js";
 import { register as registerHooks } from "./mcp-hooks.js";
 import { register as registerExtract } from "./mcp-extract.js";
 import { register as registerConfig } from "./mcp-config.js";
+import { mcpResponse } from "./mcp-types.js";
 import { errorMessage } from "./utils.js";
 import { runTopLevelCommand } from "./entrypoint.js";
 import { startEmbeddingWarmup } from "./startup-embedding.js";
@@ -110,7 +111,7 @@ async function main() {
                 const message = errorMessage(err);
                 if (message.includes("Write timeout") || message.includes("Write queue full")) {
                     debugLog(`Write queue timeout: ${message}`);
-                    return { ok: false, error: `Write queue timeout: ${message}`, errorCode: "TIMEOUT" };
+                    return mcpResponse({ ok: false, error: `Write queue timeout: ${message}`, errorCode: "TIMEOUT" });
                 }
                 throw err;
             }