@phren/cli 0.0.6 → 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

@@ -345,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 {
@@ -367,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-learning.js

@@ -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(),
@@ -355,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";
@@ -94,6 +95,29 @@ function findMatchingFindingBullet(bulletLines, needle, match) {
     }
     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)
@@ -243,7 +267,10 @@ 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);
@@ -278,7 +305,10 @@ 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, () => {
@@ -376,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-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;
             }

package/mcp/dist/init-preferences.js

@@ -6,6 +6,7 @@ import * as path from "path";
 import * as crypto from "crypto";
 import { debugLog, installPreferencesFile } from "./phren-paths.js";
 import { errorMessage } from "./utils.js";
+import { withFileLock } from "./governance-locks.js";
 function preferencesFile(phrenPath) {
     return installPreferencesFile(phrenPath);
 }
@@ -24,7 +25,7 @@ function readPreferencesFile(file) {
         return {};
     }
 }
-function writePreferencesFile(file, current, patch) {
+function writePreferencesFileRaw(file, current, patch) {
     fs.mkdirSync(path.dirname(file), { recursive: true });
     const tmpPath = `${file}.tmp-${crypto.randomUUID()}`;
     fs.writeFileSync(tmpPath, JSON.stringify({
@@ -34,6 +35,12 @@ function writePreferencesFile(file, current, patch) {
     }, null, 2) + "\n");
     fs.renameSync(tmpPath, file);
 }
+function writePreferencesFile(file, patch) {
+    withFileLock(file, () => {
+        const current = readPreferencesFile(file);
+        writePreferencesFileRaw(file, current, patch);
+    });
+}
 export function readInstallPreferences(phrenPath) {
     return readPreferencesFile(preferencesFile(phrenPath));
 }
@@ -41,10 +48,18 @@ export function readGovernanceInstallPreferences(phrenPath) {
     return readPreferencesFile(governanceInstallPreferencesFile(phrenPath));
 }
 export function writeInstallPreferences(phrenPath, patch) {
-    writePreferencesFile(preferencesFile(phrenPath), readInstallPreferences(phrenPath), patch);
+    writePreferencesFile(preferencesFile(phrenPath), patch);
 }
 export function writeGovernanceInstallPreferences(phrenPath, patch) {
-    writePreferencesFile(governanceInstallPreferencesFile(phrenPath), readGovernanceInstallPreferences(phrenPath), patch);
+    writePreferencesFile(governanceInstallPreferencesFile(phrenPath), patch);
+}
+/** Atomically read-modify-write install preferences using a patcher function. */
+export function updateInstallPreferences(phrenPath, patcher) {
+    const file = preferencesFile(phrenPath);
+    withFileLock(file, () => {
+        const current = readPreferencesFile(file);
+        writePreferencesFileRaw(file, current, patcher(current));
+    });
 }
 export function getMcpEnabledPreference(phrenPath) {
     const prefs = readInstallPreferences(phrenPath);

package/mcp/dist/init.js

@@ -910,6 +910,17 @@ export async function runInit(opts = {}) {
     }
     let phrenPath = resolveInitPhrenPath(opts);
     const dryRun = Boolean(opts.dryRun);
+    // Migrate ~/.cortex → ~/.phren when upgrading from the old name.
+    // Only runs when the resolved phrenPath doesn't exist yet but ~/.cortex does.
+    if (!opts._walkthroughStoragePath && !fs.existsSync(phrenPath)) {
+        const cortexPath = path.resolve(homePath(".cortex"));
+        if (cortexPath !== phrenPath && fs.existsSync(cortexPath) && hasInstallMarkers(cortexPath)) {
+            if (!dryRun) {
+                fs.renameSync(cortexPath, phrenPath);
+            }
+            console.log(`Migrated ~/.cortex → ~/.phren`);
+        }
+    }
     let hasExistingInstall = hasInstallMarkers(phrenPath);
     // Interactive walkthrough for first-time installs (skip with --yes or non-TTY)
     if (!hasExistingInstall && !dryRun && !opts.yes && process.stdin.isTTY && process.stdout.isTTY) {

package/mcp/dist/mcp-config.js

@@ -5,14 +5,6 @@ import { PROACTIVITY_LEVELS, getProactivityLevel, getProactivityLevelForFindings
 import { readGovernanceInstallPreferences, writeGovernanceInstallPreferences, } from "./init-preferences.js";
 import { FINDING_SENSITIVITY_CONFIG } from "./cli-config.js";
 // ── Helpers ─────────────────────────────────────────────────────────────────
-function normalizeProactivityLevel(raw) {
-    if (!raw)
-        return undefined;
-    const normalized = raw.trim().toLowerCase();
-    return PROACTIVITY_LEVELS.includes(normalized)
-        ? normalized
-        : undefined;
-}
 function proactivitySnapshot(phrenPath) {
     const prefs = readGovernanceInstallPreferences(phrenPath);
     return {

package/mcp/dist/mcp-data.js

@@ -215,7 +215,14 @@ export function register(server, ctx) {
             }
             catch (indexError) {
                 // Index rebuild failed — restore backup if we replaced the project dir
-                if (overwrite) {
+                if (!overwrite) {
+                    // Non-overwrite case: no backup to restore — remove the orphaned project dir
+                    try {
+                        fs.rmSync(projectDir, { recursive: true });
+                    }
+                    catch { /* best-effort */ }
+                }
+                else {
                     // Find the backup dir that was created earlier
                     try {
                         for (const entry of fs.readdirSync(phrenPath)) {
@@ -287,7 +294,13 @@ export function register(server, ctx) {
                     return mcpResponse({ ok: false, error: `Archive "${project}.archived" already exists. Unarchive or remove it first.` });
                 }
                 fs.renameSync(projectDir, archiveDir);
-                await rebuildIndex();
+                try {
+                    await rebuildIndex();
+                }
+                catch (err) {
+                    fs.renameSync(archiveDir, projectDir);
+                    return mcpResponse({ ok: false, error: `Index rebuild failed after archive rename, rolled back: ${err instanceof Error ? err.message : String(err)}` });
+                }
                 return mcpResponse({
                     ok: true,
                     message: `Archived project "${project}". Data preserved at ${archiveDir}.`,
@@ -304,7 +317,13 @@ export function register(server, ctx) {
                 return mcpResponse({ ok: false, error: `No archive found for "${project}".`, data: { availableArchives: available } });
             }
             fs.renameSync(archiveDir, projectDir);
-            await rebuildIndex();
+            try {
+                await rebuildIndex();
+            }
+            catch (err) {
+                fs.renameSync(projectDir, archiveDir);
+                return mcpResponse({ ok: false, error: `Index rebuild failed after unarchive rename, rolled back: ${err instanceof Error ? err.message : String(err)}` });
+            }
             return mcpResponse({
                 ok: true,
                 message: `Unarchived project "${project}". It is now active again.`,

package/mcp/dist/mcp-extract.js

@@ -125,6 +125,7 @@ export function register(server, ctx) {
             }
             return mcpResponse({
                 ok: added.length > 0,
+                ...(added.length === 0 ? { error: `All ${findings.length} finding(s) were skipped (duplicates or errors).` } : {}),
                 message: `Extracted ${findings.length} finding(s): ${added.length} added, ${allSkipped.length} skipped (duplicates or errors).`,
                 data: { project, extracted: findings, added, skipped: allSkipped, dryRun: false },
             });

package/mcp/dist/mcp-finding.js

@@ -203,7 +203,7 @@ export function register(server, ctx) {
                 if (err instanceof Error && err.message.includes("Rejected:")) {
                     return mcpResponse({ ok: false, error: errorMessage(err), errorCode: "VALIDATION_ERROR" });
                 }
-                throw err;
+                return mcpResponse({ ok: false, error: `Unexpected error saving finding: ${errorMessage(err)}` });
             }
         });
     });

package/mcp/dist/mcp-hooks.js

@@ -2,7 +2,7 @@ import { mcpResponse } from "./mcp-types.js";
 import { z } from "zod";
 import * as fs from "fs";
 import * as path from "path";
-import { readInstallPreferences, writeInstallPreferences } from "./init-preferences.js";
+import { readInstallPreferences, updateInstallPreferences } from "./init-preferences.js";
 import { readCustomHooks, getHookTarget, HOOK_EVENT_VALUES } from "./hooks.js";
 import { hookConfigPath } from "./shared.js";
 import { PROJECT_HOOK_EVENTS, isProjectHookEnabled, readProjectConfig, writeProjectHookConfig } from "./project-config.js";
@@ -161,16 +161,15 @@ export function register(server, ctx) {
             if (!normalized) {
                 return mcpResponse({ ok: false, error: `Invalid tool "${tool}". Use: ${HOOK_TOOLS.join(", ")}` });
             }
-            const prefs = readInstallPreferences(phrenPath);
-            writeInstallPreferences(phrenPath, {
+            updateInstallPreferences(phrenPath, (prefs) => ({
                 hookTools: {
                     ...(prefs.hookTools && typeof prefs.hookTools === "object" ? prefs.hookTools : {}),
                     [normalized]: enabled,
                 },
-            });
+            }));
             return mcpResponse({ ok: true, message: `${enabled ? "Enabled" : "Disabled"} hooks for ${normalized}.`, data: { tool: normalized, enabled } });
         }
-        writeInstallPreferences(phrenPath, { hooksEnabled: enabled });
+        updateInstallPreferences(phrenPath, () => ({ hooksEnabled: enabled }));
         return mcpResponse({ ok: true, message: `${enabled ? "Enabled" : "Disabled"} hooks globally.`, data: { global: true, enabled } });
     });
     // ── add_custom_hook ──────────────────────────────────────────────────────
@@ -202,12 +201,26 @@ export function register(server, ctx) {
                 const { hostname } = new URL(trimmed);
                 const h = hostname.toLowerCase().replace(/^\[|\]$/g, ""); // strip IPv6 brackets
                 const ssrfBlocked = h === "localhost" ||
-                    h === "::1" ||
+                    // IPv4 private/loopback ranges
                     /^127\./.test(h) ||
                     /^10\./.test(h) ||
                     /^172\.(1[6-9]|2\d|3[01])\./.test(h) ||
                     /^192\.168\./.test(h) ||
                     /^169\.254\./.test(h) ||
+                    // IPv6 loopback
+                    h === "::1" ||
+                    // IPv6 ULA (fc00::/7 covers fc:: and fd::)
+                    h.startsWith("fc") ||
+                    h.startsWith("fd") ||
+                    // IPv6 link-local (fe80::/10)
+                    h.startsWith("fe80:") ||
+                    // IPv4-mapped IPv6 (::ffff:10.x.x.x, ::ffff:127.x.x.x, etc.)
+                    /^::ffff:/i.test(h) ||
+                    // Raw numeric IPv4 forms not normalized by all URL parsers:
+                    // decimal (2130706433), hex (0x7f000001), octal (0177.0.0.1 prefix)
+                    /^(0x[0-9a-f]+|0\d+)$/i.test(h) ||
+                    // Pure decimal integer that encodes an IPv4 address (8+ digits covers 0.0.0.0+)
+                    /^\d{8,10}$/.test(h) ||
                     h.endsWith(".local") ||
                     h.endsWith(".internal");
                 if (ssrfBlocked) {
@@ -226,10 +239,13 @@ export function register(server, ctx) {
             newHook = { event, command: command, ...(timeout !== undefined ? { timeout } : {}) };
         }
         return ctx.withWriteQueue(async () => {
-            const prefs = readInstallPreferences(phrenPath);
-            const existing = Array.isArray(prefs.customHooks) ? prefs.customHooks : [];
-            writeInstallPreferences(phrenPath, { ...prefs, customHooks: [...existing, newHook] });
-            return mcpResponse({ ok: true, message: `Added custom hook for "${event}": ${"webhook" in newHook ? "[webhook] " : ""}${getHookTarget(newHook)}`, data: { hook: newHook, total: existing.length + 1 } });
+            let totalAfter = 0;
+            updateInstallPreferences(phrenPath, (prefs) => {
+                const existing = Array.isArray(prefs.customHooks) ? prefs.customHooks : [];
+                totalAfter = existing.length + 1;
+                return { customHooks: [...existing, newHook] };
+            });
+            return mcpResponse({ ok: true, message: `Added custom hook for "${event}": ${"webhook" in newHook ? "[webhook] " : ""}${getHookTarget(newHook)}`, data: { hook: newHook, total: totalAfter } });
         });
     });
     // ── remove_custom_hook ───────────────────────────────────────────────────
@@ -242,15 +258,19 @@ export function register(server, ctx) {
         }),
     }, async ({ event, command }) => {
         return ctx.withWriteQueue(async () => {
-            const prefs = readInstallPreferences(phrenPath);
-            const existing = Array.isArray(prefs.customHooks) ? prefs.customHooks : [];
-            const remaining = existing.filter(h => h.event !== event || (command && !getHookTarget(h).includes(command)));
-            const removed = existing.length - remaining.length;
+            let removed = 0;
+            let remainingCount = 0;
+            updateInstallPreferences(phrenPath, (prefs) => {
+                const existing = Array.isArray(prefs.customHooks) ? prefs.customHooks : [];
+                const remaining = existing.filter(h => h.event !== event || (command != null && !getHookTarget(h).includes(command)));
+                removed = existing.length - remaining.length;
+                remainingCount = remaining.length;
+                return { customHooks: remaining };
+            });
             if (removed === 0) {
                 return mcpResponse({ ok: false, error: `No custom hooks matched event="${event}"${command ? ` command containing "${command}"` : ""}.` });
             }
-            writeInstallPreferences(phrenPath, { ...prefs, customHooks: remaining });
-            return mcpResponse({ ok: true, message: `Removed ${removed} custom hook(s) for "${event}".`, data: { removed, remaining: remaining.length } });
+            return mcpResponse({ ok: true, message: `Removed ${removed} custom hook(s) for "${event}".`, data: { removed, remaining: remainingCount } });
         });
     });
 }

package/mcp/dist/mcp-memory.js

@@ -41,7 +41,6 @@ export function register(server, ctx) {
             flushEntryScores(phrenPath);
             const feedbackWeights = {
                 helpful: 1.0,
-                not_helpful: -0.3,
                 reprompt: -0.5,
                 regression: -1.0,
             };

package/mcp/dist/mcp-ops.js

@@ -11,16 +11,9 @@ import { PROJECT_OWNERSHIP_MODES, parseProjectOwnershipMode } from "./project-co
 import { resolveRuntimeProfile } from "./runtime-profile.js";
 import { getMachineName } from "./machine-identity.js";
 import { getProjectConsolidationStatus, CONSOLIDATION_ENTRY_THRESHOLD } from "./content-validate.js";
-/** Translate a PhrenResult<string> into a standard McpToolResult shape. */
-function phrenResultToMcp(result) {
-    if (result.ok) {
-        return { ok: true, message: result.data };
-    }
-    return { ok: false, error: result.error, errorCode: result.code };
-}
 export function register(server, ctx) {
-    const { phrenPath, profile, withWriteQueue, updateFileInIndex } = ctx;
-    // ── get_consolidation_status ───────────────────────────────────────────────
+    const { phrenPath, profile, withWriteQueue } = ctx;
+    // ── add_project ────────────────────────────────────────────────────────────
     server.registerTool("add_project", {
         title: "◆ phren · add project",
         description: "Bootstrap a project into phren from a repo or working directory. " +
@@ -221,11 +214,13 @@ export function register(server, ctx) {
         const { runDoctor } = await import("./link-doctor.js");
         const result = await runDoctor(phrenPath, true, check_data ?? false);
         const lines = result.checks.map((c) => `${c.ok ? "ok" : "FAIL"} ${c.name}: ${c.detail}`);
+        const failCount = result.checks.filter((c) => !c.ok).length;
         return mcpResponse({
             ok: result.ok,
+            ...(result.ok ? {} : { error: `${failCount} check(s) could not be auto-fixed: ${lines.filter((l) => l.startsWith("FAIL")).join("; ")}` }),
             message: result.ok
                 ? `Doctor fix complete: all ${result.checks.length} checks passed`
-                : `Doctor fix complete: ${result.checks.filter((c) => !c.ok).length} issue(s) remain`,
+                : `Doctor fix complete: ${failCount} issue(s) remain`,
             data: {
                 machine: result.machine,
                 profile: result.profile,

package/mcp/dist/mcp-search.js

@@ -131,7 +131,13 @@ export function register(server, ctx) {
         }),
     }, async ({ id: rawId }) => {
         // Normalize ID: decode URL encoding and normalize path separators
-        const id = normalizeMemoryId(rawId);
+        let id;
+        try {
+            id = normalizeMemoryId(rawId);
+        }
+        catch {
+            return mcpResponse({ ok: false, error: `Invalid memory ID format: "${rawId}" contains malformed URL encoding.` });
+        }
         const match = id.match(/^mem:([^/]+)\/(.+)$/);
         if (!match) {
             return mcpResponse({ ok: false, error: `Invalid memory ID format "${rawId}". Expected mem:project/path/to/file.md.` });