@phren/cli 0.0.6 → 0.0.8

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-config.js

@@ -162,15 +162,15 @@ export function removeMcpServerAtPath(filePath) {
     return removed;
 }
 export function isPhrenCommand(command) {
-    // Detect PHREN_PATH= or legacy PHREN_PATH= env var prefix (present in all lifecycle hook commands)
-    if (/\b(?:PHREN_PATH|PHREN_PATH)=/.test(command))
+    // Detect PHREN_PATH= env var prefix (present in all lifecycle hook commands)
+    if (/\bPHREN_PATH=/.test(command))
         return true;
-    // Detect npx phren/phren package references
-    if (command.includes("phren") || command.includes("phren"))
+    // Detect npx phren package references
+    if (command.includes("phren"))
         return true;
-    // Detect bare "phren" or "phren" executable segment
+    // Detect bare "phren" executable segment
     const segments = command.split(/[/\\\s]+/);
-    if (segments.some(seg => seg === "phren" || seg.startsWith("phren@") || seg === "phren" || seg.startsWith("phren@")))
+    if (segments.some(seg => seg === "phren" || seg.startsWith("phren@")))
         return true;
     // Also match commands that include hook subcommands (used when installed via absolute path)
     const HOOK_MARKERS = ["hook-prompt", "hook-stop", "hook-session-start", "hook-tool"];

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

@@ -109,7 +109,7 @@ function hasInstallMarkers(phrenPath) {
         fs.existsSync(path.join(phrenPath, "global")));
 }
 function resolveInitPhrenPath(opts) {
-    const raw = opts._walkthroughStoragePath || (process.env.PHREN_PATH || process.env.PHREN_PATH) || DEFAULT_PHREN_PATH;
+    const raw = opts._walkthroughStoragePath || (process.env.PHREN_PATH) || DEFAULT_PHREN_PATH;
     return path.resolve(expandHomePath(raw));
 }
 function detectRepoRootForStorage(phrenPath) {
@@ -910,6 +910,39 @@ 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`);
+        }
+    }
+    // Rename stale cortex-*.md skill files left over from the rebrand.
+    // Runs on every init so users who already migrated the directory still get the fix.
+    const skillsMigrateDir = path.join(phrenPath, "global", "skills");
+    if (!dryRun && fs.existsSync(skillsMigrateDir)) {
+        for (const entry of fs.readdirSync(skillsMigrateDir)) {
+            if (!entry.endsWith(".md"))
+                continue;
+            if (entry === "cortex.md") {
+                const dest = path.join(skillsMigrateDir, "phren.md");
+                if (!fs.existsSync(dest)) {
+                    fs.renameSync(path.join(skillsMigrateDir, entry), dest);
+                }
+            }
+            else if (entry.startsWith("cortex-")) {
+                const newName = entry.replace(/^cortex-/, "phren-");
+                const dest = path.join(skillsMigrateDir, newName);
+                if (!fs.existsSync(dest)) {
+                    fs.renameSync(path.join(skillsMigrateDir, entry), dest);
+                }
+            }
+        }
+    }
     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) {
@@ -1404,7 +1437,7 @@ export async function runInit(opts = {}) {
     log(``);
 }
 export async function runMcpMode(modeArg) {
-    const phrenPath = findPhrenPath() || (process.env.PHREN_PATH || process.env.PHREN_PATH) || DEFAULT_PHREN_PATH;
+    const phrenPath = findPhrenPath() || (process.env.PHREN_PATH) || DEFAULT_PHREN_PATH;
     const manifest = readRootManifest(phrenPath);
     const normalizedArg = modeArg?.trim().toLowerCase();
     if (!normalizedArg || normalizedArg === "status") {
@@ -1475,7 +1508,7 @@ export async function runMcpMode(modeArg) {
     log(`Restart your agent to apply changes.`);
 }
 export async function runHooksMode(modeArg) {
-    const phrenPath = findPhrenPath() || (process.env.PHREN_PATH || process.env.PHREN_PATH) || DEFAULT_PHREN_PATH;
+    const phrenPath = findPhrenPath() || (process.env.PHREN_PATH) || DEFAULT_PHREN_PATH;
     const manifest = readRootManifest(phrenPath);
     const normalizedArg = modeArg?.trim().toLowerCase();
     if (!normalizedArg || normalizedArg === "status") {
@@ -1633,7 +1666,7 @@ export async function runUninstall() {
     catch (err) {
         debugLog(`uninstall: cleanup failed for ${codexToml}: ${errorMessage(err)}`);
     }
-    const codexCandidates = codexJsonCandidates((process.env.PHREN_PATH || process.env.PHREN_PATH) || DEFAULT_PHREN_PATH);
+    const codexCandidates = codexJsonCandidates((process.env.PHREN_PATH) || DEFAULT_PHREN_PATH);
     for (const mcpFile of codexCandidates) {
         try {
             if (removeMcpServerAtPath(mcpFile)) {
@@ -1645,7 +1678,7 @@ export async function runUninstall() {
         }
     }
     // Remove Copilot hooks file (written by configureAllHooks)
-    const copilotHooksFile = hookConfigPath("copilot", (process.env.PHREN_PATH || process.env.PHREN_PATH) || DEFAULT_PHREN_PATH);
+    const copilotHooksFile = hookConfigPath("copilot", (process.env.PHREN_PATH) || DEFAULT_PHREN_PATH);
     try {
         if (fs.existsSync(copilotHooksFile)) {
             fs.unlinkSync(copilotHooksFile);
@@ -1656,7 +1689,7 @@ export async function runUninstall() {
         debugLog(`uninstall: cleanup failed for ${copilotHooksFile}: ${errorMessage(err)}`);
     }
     // Remove phren entries from Cursor hooks file (may contain non-phren entries)
-    const cursorHooksFile = hookConfigPath("cursor", (process.env.PHREN_PATH || process.env.PHREN_PATH) || DEFAULT_PHREN_PATH);
+    const cursorHooksFile = hookConfigPath("cursor", (process.env.PHREN_PATH) || DEFAULT_PHREN_PATH);
     try {
         if (fs.existsSync(cursorHooksFile)) {
             const raw = JSON.parse(fs.readFileSync(cursorHooksFile, "utf8"));
@@ -1677,7 +1710,7 @@ export async function runUninstall() {
         debugLog(`uninstall: cleanup failed for ${cursorHooksFile}: ${errorMessage(err)}`);
     }
     // Remove Codex hooks file in phren path
-    const uninstallPhrenPath = (process.env.PHREN_PATH || process.env.PHREN_PATH) || DEFAULT_PHREN_PATH;
+    const uninstallPhrenPath = (process.env.PHREN_PATH) || DEFAULT_PHREN_PATH;
     const codexHooksFile = hookConfigPath("codex", uninstallPhrenPath);
     try {
         if (fs.existsSync(codexHooksFile)) {

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)}` });
             }
         });
     });