@phren/cli 0.0.10 → 0.0.12

package/mcp/dist/cli-govern.js

@@ -144,7 +144,7 @@ export async function handlePruneMemories(args = []) {
                 .filter((e) => e !== null);
         }
         catch (err) {
-            if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+            if ((process.env.PHREN_DEBUG))
                 process.stderr.write(`[phren] cli-govern retrievalLog readParse: ${errorMessage(err)}\n`);
         }
     }
@@ -255,7 +255,7 @@ export async function handleGcMaintain(args = []) {
     const sevenDaysAgo = new Date(Date.now() - 7 * 86400000).toISOString().slice(0, 10);
     let oldCommits = [];
     try {
-        const raw = execSync(`git log --oneline --before="${sevenDaysAgo}" --format="%H %s"`, { cwd: phrenPath, encoding: "utf8" }).trim();
+        const raw = execSync(`git log --before="${sevenDaysAgo}" --format="%H %ci %s"`, { cwd: phrenPath, encoding: "utf8" }).trim();
         if (raw) {
             oldCommits = raw.split("\n").filter((l) => l.includes("auto-save:") || l.includes("[auto]"));
         }
@@ -271,23 +271,21 @@ export async function handleGcMaintain(args = []) {
         report.commitsSquashed = oldCommits.length;
     }
     else {
-        // Group by ISO week (YYYY-Www) based on commit timestamp
+        // Group by ISO week based on commit timestamp (already in the log output)
         const commitsByWeek = new Map();
         for (const line of oldCommits) {
             const hash = line.split(" ")[0];
-            try {
-                const dateStr = execSync(`git log -1 --format="%ci" ${hash}`, { cwd: phrenPath, encoding: "utf8" }).trim();
-                const date = new Date(dateStr);
-                const weekStart = new Date(date);
-                weekStart.setDate(date.getDate() - date.getDay()); // start of week (Sunday)
-                const weekKey = weekStart.toISOString().slice(0, 10);
-                if (!commitsByWeek.has(weekKey))
-                    commitsByWeek.set(weekKey, []);
-                commitsByWeek.get(weekKey).push(hash);
-            }
-            catch {
-                // Skip commits we can't resolve
-            }
+            // Format: "HASH YYYY-MM-DD HH:MM:SS +ZZZZ subject..."
+            const dateMatch = line.match(/^[a-f0-9]+ (\d{4}-\d{2}-\d{2})/);
+            if (!dateMatch)
+                continue;
+            const date = new Date(dateMatch[1]);
+            const weekStart = new Date(date);
+            weekStart.setDate(date.getDate() - date.getDay());
+            const weekKey = weekStart.toISOString().slice(0, 10);
+            if (!commitsByWeek.has(weekKey))
+                commitsByWeek.set(weekKey, []);
+            commitsByWeek.get(weekKey).push(hash);
         }
         // For each week with multiple commits, soft-reset to oldest and amend into a summary
         for (const [weekKey, hashes] of commitsByWeek.entries()) {
@@ -320,64 +318,38 @@ export async function handleGcMaintain(args = []) {
             console.log("Commit squash: all old auto-save weeks have only one commit, nothing to squash.");
         }
     }
-    // 3. Prune stale session markers from ~/.phren/.sessions/ older than 30 days
-    const sessionsDir = path.join(phrenPath, ".sessions");
+    // 3–4. Prune stale files from .sessions/ and .runtime/
     const thirtyDaysAgo = Date.now() - 30 * 86400000;
-    if (fs.existsSync(sessionsDir)) {
-        const entries = fs.readdirSync(sessionsDir);
-        for (const entry of entries) {
-            const fullPath = path.join(sessionsDir, entry);
-            try {
-                const stat = fs.statSync(fullPath);
-                if (stat.mtimeMs < thirtyDaysAgo) {
-                    if (dryRun) {
-                        console.log(`[dry-run] Would remove session marker: .sessions/${entry}`);
-                    }
-                    else {
-                        fs.unlinkSync(fullPath);
-                    }
-                    report.sessionsRemoved++;
-                }
-            }
-            catch {
-                // Skip unreadable entries
-            }
-        }
-    }
-    const sessionsVerb = dryRun ? "Would remove" : "Removed";
-    console.log(`${sessionsVerb} ${report.sessionsRemoved} stale session marker(s) from .sessions/`);
-    // 4. Trim runtime logs from ~/.phren/.runtime/ older than 30 days
-    const runtimeDir = path.join(phrenPath, ".runtime");
-    const logExtensions = new Set([".log", ".jsonl", ".json"]);
-    if (fs.existsSync(runtimeDir)) {
-        const entries = fs.readdirSync(runtimeDir);
-        for (const entry of entries) {
-            const ext = path.extname(entry);
-            if (!logExtensions.has(ext))
-                continue;
-            // Never trim the active audit log or telemetry config
-            if (entry === "audit.log" || entry === "telemetry.json")
+    function pruneStaleFiles(dir, label, filter) {
+        let removed = 0;
+        if (!fs.existsSync(dir))
+            return removed;
+        for (const entry of fs.readdirSync(dir)) {
+            if (filter && !filter(entry))
                 continue;
-            const fullPath = path.join(runtimeDir, entry);
+            const fullPath = path.join(dir, entry);
             try {
-                const stat = fs.statSync(fullPath);
-                if (stat.mtimeMs < thirtyDaysAgo) {
+                if (fs.statSync(fullPath).mtimeMs < thirtyDaysAgo) {
                     if (dryRun) {
-                        console.log(`[dry-run] Would remove runtime log: .runtime/${entry}`);
+                        console.log(`[dry-run] Would remove: ${label}/${entry}`);
                     }
                     else {
                         fs.unlinkSync(fullPath);
                     }
-                    report.runtimeLogsRemoved++;
+                    removed++;
                 }
             }
-            catch {
-                // Skip unreadable entries
-            }
+            catch { /* skip unreadable */ }
         }
+        return removed;
     }
-    const logsVerb = dryRun ? "Would remove" : "Removed";
-    console.log(`${logsVerb} ${report.runtimeLogsRemoved} stale runtime log(s) from .runtime/`);
+    const logExtensions = new Set([".log", ".jsonl", ".json"]);
+    const protectedFiles = new Set(["audit.log", "telemetry.json"]);
+    report.sessionsRemoved = pruneStaleFiles(path.join(phrenPath, ".sessions"), ".sessions");
+    report.runtimeLogsRemoved = pruneStaleFiles(path.join(phrenPath, ".runtime"), ".runtime", (entry) => logExtensions.has(path.extname(entry)) && !protectedFiles.has(entry));
+    const verb = dryRun ? "Would remove" : "Removed";
+    console.log(`${verb} ${report.sessionsRemoved} stale session marker(s) from .sessions/`);
+    console.log(`${verb} ${report.runtimeLogsRemoved} stale runtime log(s) from .runtime/`);
     // 5. Summary
     if (!dryRun) {
         appendAuditLog(phrenPath, "maintain_gc", `gitGc=${report.gitGcRan} squashed=${report.commitsSquashed} sessions=${report.sessionsRemoved} logs=${report.runtimeLogsRemoved}`);
@@ -529,7 +501,7 @@ export async function handleBackgroundMaintenance(projectArg) {
             fs.unlinkSync(markers.lock);
         }
         catch (err) {
-            if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+            if ((process.env.PHREN_DEBUG))
                 process.stderr.write(`[phren] cli-govern backgroundMaintenance unlockFinal: ${errorMessage(err)}\n`);
         }
     }

package/mcp/dist/cli-graph.js

@@ -1,6 +1,7 @@
 import { getPhrenPath } from "./shared.js";
 import { buildIndex, queryRows } from "./shared-index.js";
 import { resolveRuntimeProfile } from "./runtime-profile.js";
+import { isValidProjectName, errorMessage } from "./utils.js";
 /**
  * CLI: phren graph [--project <name>] [--limit <n>]
  * Displays the fragment knowledge graph as a table.
@@ -18,6 +19,10 @@ export async function handleGraphRead(args) {
             limit = Math.min(Math.max(parseInt(args[++i], 10) || 20, 1), 200);
         }
     }
+    if (project && !isValidProjectName(project)) {
+        console.error(`Invalid project name: "${project}".`);
+        process.exit(1);
+    }
     const db = await buildIndex(phrenPath, profile);
     let sql;
     let params;
@@ -74,6 +79,10 @@ export async function handleGraphLink(args) {
         process.exit(1);
     }
     const [project, findingText, fragmentName] = args;
+    if (!isValidProjectName(project)) {
+        console.error(`Invalid project name: "${project}".`);
+        process.exit(1);
+    }
     const phrenPath = getPhrenPath();
     const profile = resolveRuntimeProfile(phrenPath);
     const db = await buildIndex(phrenPath, profile);
@@ -94,7 +103,10 @@ export async function handleGraphLink(args) {
     try {
         db.run("INSERT OR IGNORE INTO entities (name, type, first_seen_at) VALUES (?, ?, ?)", [normalizedFragment, "fragment", new Date().toISOString().slice(0, 10)]);
     }
-    catch { /* best effort */ }
+    catch (err) {
+        if (process.env.PHREN_DEBUG)
+            process.stderr.write(`[phren] graph link insert fragment: ${errorMessage(err)}\n`);
+    }
     const fragmentResult = db.exec("SELECT id FROM entities WHERE name = ? AND type = ?", [normalizedFragment, "fragment"]);
     if (!fragmentResult?.length || !fragmentResult[0]?.values?.length) {
         console.error("Failed to create fragment.");
@@ -104,7 +116,10 @@ export async function handleGraphLink(args) {
     try {
         db.run("INSERT OR IGNORE INTO entities (name, type, first_seen_at) VALUES (?, ?, ?)", [sourceDoc, "document", new Date().toISOString().slice(0, 10)]);
     }
-    catch { /* best effort */ }
+    catch (err) {
+        if (process.env.PHREN_DEBUG)
+            process.stderr.write(`[phren] graph link insert document: ${errorMessage(err)}\n`);
+    }
     const docResult = db.exec("SELECT id FROM entities WHERE name = ? AND type = ?", [sourceDoc, "document"]);
     if (!docResult?.length || !docResult[0]?.values?.length) {
         console.error("Failed to create document fragment.");
@@ -115,7 +130,7 @@ export async function handleGraphLink(args) {
         db.run("INSERT OR IGNORE INTO entity_links (source_id, target_id, rel_type, source_doc) VALUES (?, ?, ?, ?)", [sourceId, targetId, "mentions", sourceDoc]);
     }
     catch (err) {
-        console.error(`Failed to link: ${err instanceof Error ? err.message : String(err)}`);
+        console.error(`Failed to link: ${errorMessage(err)}`);
         process.exit(1);
     }
     // Persist to manual-links.json
@@ -144,7 +159,7 @@ export async function handleGraphLink(args) {
         });
     }
     catch (err) {
-        console.error(`Failed to persist manual link: ${err instanceof Error ? err.message : String(err)}`);
+        console.error(`Failed to persist manual link: ${errorMessage(err)}`);
         process.exit(1);
     }
     console.log(`Linked "${fragmentName}" to ${sourceDoc}.`);

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

@@ -1,6 +1,7 @@
 import * as fs from "fs";
 import * as path from "path";
 import { capCache } from "./shared.js";
+import { errorMessage } from "./utils.js";
 // ── Glob matching and project frontmatter ────────────────────────────────────
 const projectGlobCache = new Map();
 export function clearProjectGlobCache() {
@@ -45,7 +46,7 @@ function parseProjectGlobs(phrenPathLocal, project) {
     }
     catch (err) {
         if (process.env.PHREN_DEBUG)
-            process.stderr.write(`[phren] getProjectGlobs: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.stderr.write(`[phren] getProjectGlobs: ${errorMessage(err)}\n`);
     }
     projectGlobCache.set(project, globs);
     capCache(projectGlobCache);

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

@@ -1,7 +1,7 @@
 import { recordInjection, recordRetrieval, } from "./shared-governance.js";
 import { getDocSourceKey, } from "./shared-index.js";
 import { logImpact, extractFindingIdsFromSnippet, } from "./finding-impact.js";
-import { isFeatureEnabled } from "./utils.js";
+import { isFeatureEnabled, errorMessage } from "./utils.js";
 import { annotateStale } from "./cli-hooks-citations.js";
 import { approximateTokens, fileRelevanceBoost, branchMatchBoost } from "./shared-retrieval.js";
 // ── Progressive disclosure helpers ────────────────────────────────────────────
@@ -56,7 +56,7 @@ export function buildHookOutput(selected, usedTokens, intent, gitCtx, detectedPr
             }
             catch (err) {
                 if (process.env.PHREN_DEBUG)
-                    process.stderr.write(`[phren] injectContext recordRetrieval: ${err instanceof Error ? err.message : String(err)}\n`);
+                    process.stderr.write(`[phren] injectContext recordRetrieval: ${errorMessage(err)}\n`);
             }
         }
     }
@@ -108,7 +108,7 @@ export function buildHookOutput(selected, usedTokens, intent, gitCtx, detectedPr
             }
             catch (err) {
                 if (process.env.PHREN_DEBUG)
-                    process.stderr.write(`[phren] injectContext recordRetrievalOrdered: ${err instanceof Error ? err.message : String(err)}\n`);
+                    process.stderr.write(`[phren] injectContext recordRetrievalOrdered: ${errorMessage(err)}\n`);
             }
             parts.push(`[${getDocSourceKey(doc, phrenPathLocal)}] (${doc.type})`);
             parts.push(annotateStale(snippet));
@@ -116,7 +116,7 @@ export function buildHookOutput(selected, usedTokens, intent, gitCtx, detectedPr
         }
     }
     logImpact(phrenPathLocal, impactEntries);
-    parts.push("<phren-context>");
+    parts.push("</phren-context>");
     const changedCount = gitCtx?.changedFiles.size ?? 0;
     if (gitCtx) {
         const fileHits = selected.filter((r) => fileRelevanceBoost(r.doc.path, gitCtx.changedFiles) > 0).length;

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

@@ -749,7 +749,7 @@ export async function handleHookStop() {
                         }
                         catch (err) {
                             if (process.env.PHREN_DEBUG)
-                                process.stderr.write(`[phren] hookSessionStart transcriptParse: ${errorMessage(err)}\n`);
+                                process.stderr.write(`[phren] hookStop transcriptParse: ${errorMessage(err)}\n`);
                         }
                     }
                     captureInput = assistantTexts.join("\n");

package/mcp/dist/cli-hooks.js

@@ -5,7 +5,7 @@
 //   cli-hooks-output.ts     — hook output formatting
 //   cli-hooks-globs.ts      — project glob matching
 import { debugLog, sessionMarker, sessionsDir, getPhrenPath, } from "./shared.js";
-import { getRetentionPolicy, getWorkflowPolicy, } from "./shared-governance.js";
+import { mergeConfig, } from "./shared-governance.js";
 import { buildIndex, detectProject, } from "./shared-index.js";
 import { isProjectHookEnabled } from "./project-config.js";
 import { checkConsolidationNeeded, } from "./shared-content.js";
@@ -126,7 +126,7 @@ export async function handleHookPrompt() {
     }
     catch (err) {
         if (process.env.PHREN_DEBUG)
-            process.stderr.write(`[phren] hookPrompt stdinRead: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.stderr.write(`[phren] hookPrompt stdinRead: ${errorMessage(err)}\n`);
         process.exit(0);
     }
     const input = parseHookInput(raw);
@@ -164,7 +164,9 @@ export async function handleHookPrompt() {
         for (const kw of keywordEntries) {
             sessionTopics[kw] = (sessionTopics[kw] ?? 0) + 1;
         }
-        fs.writeFileSync(topicFile, JSON.stringify(sessionTopics));
+        const topicTmp = `${topicFile}.tmp-${process.pid}`;
+        fs.writeFileSync(topicTmp, JSON.stringify(sessionTopics));
+        fs.renameSync(topicTmp, topicFile);
         // Find hot topics (3+ mentions this session)
         hotTopics = Object.entries(sessionTopics)
             .filter(([, count]) => count >= 3)
@@ -182,6 +184,7 @@ export async function handleHookPrompt() {
         appendAuditLog(getPhrenPath(), "hook_prompt", `status=project_disabled project=${detectedProject}`);
         process.exit(0);
     }
+    const resolvedConfig = mergeConfig(getPhrenPath(), detectedProject ?? undefined);
     const safeQuery = buildRobustFtsQuery(keywords, detectedProject, getPhrenPath());
     if (!safeQuery)
         process.exit(0);
@@ -193,14 +196,17 @@ export async function handleHookPrompt() {
             process.exit(0);
         autoLearnQuerySynonyms(getPhrenPath(), detectedProject, keywordEntries, rows);
         const tTrust0 = Date.now();
-        const policy = getRetentionPolicy(getPhrenPath());
+        const policy = resolvedConfig.retentionPolicy;
         const memoryTtlDays = Number.parseInt(process.env.PHREN_MEMORY_TTL_DAYS || String(policy.ttlDays), 10);
         const trustResult = applyTrustFilter(rows, Number.isNaN(memoryTtlDays) ? policy.ttlDays : memoryTtlDays, policy.minInjectConfidence, policy.decay, getPhrenPath());
         rows = trustResult.rows;
         stage.trustMs = Date.now() - tTrust0;
         if (!rows.length)
             process.exit(0);
-        if (isFeatureEnabled("PHREN_FEATURE_AUTO_EXTRACT", true) && getProactivityLevelForFindings(getPhrenPath()) !== "low" && sessionId && detectedProject && cwd) {
+        const findingsProactivity = resolvedConfig.proactivity.findings
+            ?? resolvedConfig.proactivity.base
+            ?? getProactivityLevelForFindings(getPhrenPath());
+        if (isFeatureEnabled("PHREN_FEATURE_AUTO_EXTRACT", true) && findingsProactivity !== "low" && sessionId && detectedProject && cwd) {
             const marker = sessionMarker(getPhrenPath(), `extracted-${sessionId}-${detectedProject}`);
             if (!fs.existsSync(marker)) {
                 try {
@@ -260,7 +266,9 @@ export async function handleHookPrompt() {
             debugLog(`injection-budget: trimmed ${selected.length} -> ${kept.length} snippets to fit ${maxInjectTokens} token budget`);
         }
         const parts = buildHookOutput(budgetSelected, budgetUsedTokens, intent, gitCtx, detectedProject, stage, safeTokenBudget, getPhrenPath(), sessionId);
-        const taskLevel = getProactivityLevelForTask(getPhrenPath());
+        const taskLevel = resolvedConfig.proactivity.tasks
+            ?? resolvedConfig.proactivity.base
+            ?? getProactivityLevelForTask(getPhrenPath());
         const taskLifecycle = handleTaskPromptLifecycle({
             phrenPath: getPhrenPath(),
             prompt,
@@ -275,8 +283,7 @@ export async function handleHookPrompt() {
         }
         // Inject finding sensitivity agent instruction
         try {
-            const workflowPolicy = getWorkflowPolicy(getPhrenPath());
-            const sensitivity = workflowPolicy.findingSensitivity ?? "balanced";
+            const sensitivity = resolvedConfig.findingSensitivity ?? "balanced";
             const sensitivityConfig = FINDING_SENSITIVITY_CONFIG[sensitivity];
             if (sensitivityConfig) {
                 parts.push("");
@@ -304,36 +311,38 @@ export async function handleHookPrompt() {
         const noticeFile = sessionId ? sessionMarker(getPhrenPath(), `noticed-${sessionId}`) : null;
         const alreadyNoticed = noticeFile ? fs.existsSync(noticeFile) : false;
         if (!alreadyNoticed) {
-            // Clean up stale session markers (>24h old) from .sessions/ dir
-            try {
-                const cutoff = Date.now() - 86400000;
-                const sessDir = sessionsDir(getPhrenPath());
-                if (fs.existsSync(sessDir)) {
-                    for (const f of fs.readdirSync(sessDir)) {
-                        if (!f.startsWith("noticed-") && !f.startsWith("extracted-"))
+            // Defer stale session marker cleanup to after output — it's I/O-heavy and not needed for results
+            setImmediate(() => {
+                try {
+                    const cutoff = Date.now() - 86400000;
+                    const sessDir = sessionsDir(getPhrenPath());
+                    if (fs.existsSync(sessDir)) {
+                        for (const f of fs.readdirSync(sessDir)) {
+                            if (!f.startsWith("noticed-") && !f.startsWith("extracted-"))
+                                continue;
+                            const fp = `${sessDir}/${f}`;
+                            try {
+                                if (fs.statSync(fp).mtimeMs < cutoff)
+                                    fs.unlinkSync(fp);
+                            }
+                            catch { /* ignore per-file errors */ }
+                        }
+                    }
+                    // Also clean stale markers from the phren root
+                    for (const f of fs.readdirSync(getPhrenPath())) {
+                        if (!f.startsWith(".noticed-") && !f.startsWith(".extracted-"))
                             continue;
-                        const fp = `${sessDir}/${f}`;
-                        if (fs.statSync(fp).mtimeMs < cutoff)
+                        const fp = `${getPhrenPath()}/${f}`;
+                        try {
                             fs.unlinkSync(fp);
+                        }
+                        catch { /* ignore */ }
                     }
                 }
-                // Also clean stale markers from the phren root
-                for (const f of fs.readdirSync(getPhrenPath())) {
-                    if (!f.startsWith(".noticed-") && !f.startsWith(".extracted-"))
-                        continue;
-                    const fp = `${getPhrenPath()}/${f}`;
-                    try {
-                        fs.unlinkSync(fp);
-                    }
-                    catch (err) {
-                        if (process.env.PHREN_DEBUG)
-                            process.stderr.write(`[phren] hookPrompt staleNoticeUnlink: ${errorMessage(err)}\n`);
-                    }
+                catch (err) {
+                    debugLog(`stale notice cleanup failed: ${errorMessage(err)}`);
                 }
-            }
-            catch (err) {
-                debugLog(`stale notice cleanup failed: ${errorMessage(err)}`);
-            }
+            });
             const needed = checkConsolidationNeeded(getPhrenPath(), profile);
             if (needed.length > 0) {
                 const notices = needed.map((n) => {
@@ -345,7 +354,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 +376,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/cli-namespaces.js

@@ -5,6 +5,7 @@ import { expandHomePath, findProjectNameCaseInsensitive, getPhrenPath, getProjec
 import { isValidProjectName, errorMessage } from "./utils.js";
 import { readInstallPreferences, writeInstallPreferences } from "./init-preferences.js";
 import { buildSkillManifest, findLocalSkill, findSkill, getAllSkills } from "./skill-registry.js";
+import { detectSkillCollisions } from "./link-skills.js";
 import { setSkillEnabledAndSync, syncSkillLinksForScope } from "./skill-files.js";
 import { findProjectDir } from "./project-locator.js";
 import { TASK_FILE_ALIASES, addTask, completeTask, updateTask, reorderTask, pinTask, removeTask, workNextTask, tidyDoneTasks, linkTaskIssue, promoteTask, resolveTaskItem } from "./data-tasks.js";
@@ -76,7 +77,7 @@ function openInEditor(filePath) {
         execFileSync(editor, [filePath], { stdio: "inherit" });
     }
     catch (err) {
-        if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+        if ((process.env.PHREN_DEBUG))
             process.stderr.write(`[phren] openInEditor: ${errorMessage(err)}\n`);
         console.error(`Editor "${editor}" failed. Set $EDITOR to your preferred editor.`);
         process.exit(1);
@@ -145,7 +146,7 @@ export function handleSkillsNamespace(args, profile) {
             console.log(`Linked skill ${fileName} into ${project}.`);
         }
         catch (err) {
-            if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+            if ((process.env.PHREN_DEBUG))
                 process.stderr.write(`[phren] skill add symlinkFailed: ${errorMessage(err)}\n`);
             fs.copyFileSync(source, dest);
             console.log(`Copied skill ${fileName} into ${project}.`);
@@ -450,7 +451,7 @@ export function handleDetectSkills(args, profile) {
                 continue;
         }
         catch (err) {
-            if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+            if ((process.env.PHREN_DEBUG))
                 process.stderr.write(`[phren] skillList lstat: ${errorMessage(err)}\n`);
         }
         const name = entry.replace(/\.md$/, "");
@@ -548,6 +549,15 @@ function printSkillDoctor(scope, manifest, destDir) {
                 problems.push(`Mirror drift for ${skill.name}: expected ${dest} -> ${skill.root}`);
             }
         }
+        // Check for user-owned files blocking phren skill links
+        const phrenPath = getPhrenPath();
+        const srcDir = scope.toLowerCase() === "global"
+            ? path.join(phrenPath, "global", "skills")
+            : path.join(phrenPath, scope, "skills");
+        const collisions = detectSkillCollisions(srcDir, destDir, phrenPath);
+        for (const collision of collisions) {
+            problems.push(`Skill collision: ${collision.message}`);
+        }
     }
     if (!manifest.problems.length && !problems.length) {
         console.log("\nDoctor: no skill pipeline issues detected.");
@@ -853,7 +863,7 @@ function handleProjectsList(profile) {
             dirFiles = new Set(fs.readdirSync(projectDir));
         }
         catch (err) {
-            if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+            if ((process.env.PHREN_DEBUG))
                 process.stderr.write(`[phren] projects list readdir: ${errorMessage(err)}\n`);
             dirFiles = new Set();
         }
@@ -896,7 +906,7 @@ async function handleProjectsRemove(name, profile) {
         countFiles(projectDir);
     }
     catch (err) {
-        if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+        if ((process.env.PHREN_DEBUG))
             process.stderr.write(`[phren] projects remove countFiles: ${errorMessage(err)}\n`);
     }
     const readline = await import("readline");

package/mcp/dist/cli-search.js

@@ -34,7 +34,7 @@ export function readSearchHistory(phrenPath) {
             .map((line) => JSON.parse(line));
     }
     catch (err) {
-        if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+        if ((process.env.PHREN_DEBUG))
             process.stderr.write(`[phren] readSearchHistory: ${errorMessage(err)}\n`);
         return [];
     }
@@ -253,7 +253,7 @@ export async function runSearch(opts, phrenPath, profile) {
                     logSearchMiss(phrenPath, opts.query, opts.project);
                 }
                 catch (err) {
-                    if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+                    if ((process.env.PHREN_DEBUG))
                         process.stderr.write(`[phren] search logSearchMiss: ${errorMessage(err)}\n`);
                 }
             }

package/mcp/dist/cli.js

@@ -108,7 +108,7 @@ export async function runCliCommand(command, args) {
         case "session-context":
             return handleSessionContext();
         default:
-            console.error(`Unknown command: ${command}`);
+            console.error(`Unknown command: ${command}\nRun 'phren --help' for available commands.`);
             process.exit(1);
     }
 }

package/mcp/dist/content-archive.js

@@ -77,12 +77,11 @@ function parseActiveEntries(content) {
 /**
  * Check whether a bullet already exists in a reference file (already archived).
  */
-function isAlreadyArchived(referenceDir, bullet) {
+/** Build a Set of normalized bullet strings from all .md files in referenceDir. */
+function buildArchivedBulletSet(referenceDir) {
+    const bulletSet = new Set();
     if (!fs.existsSync(referenceDir))
-        return false;
-    const normalizedBullet = stripComments(bullet).replace(/^-\s+/, "").trim().toLowerCase();
-    if (!normalizedBullet)
-        return false;
+        return bulletSet;
     try {
         const stack = [referenceDir];
         while (stack.length > 0) {
@@ -100,17 +99,23 @@ function isAlreadyArchived(referenceDir, bullet) {
                     if (!line.startsWith("- "))
                         continue;
                     const normalizedLine = stripComments(line).replace(/^-\s+/, "").trim().toLowerCase();
-                    if (normalizedLine === normalizedBullet)
-                        return true;
+                    if (normalizedLine)
+                        bulletSet.add(normalizedLine);
                 }
             }
         }
     }
     catch (err) {
-        if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
-            process.stderr.write(`[phren] isDuplicateInReference: ${errorMessage(err)}\n`);
+        if ((process.env.PHREN_DEBUG))
+            process.stderr.write(`[phren] buildArchivedBulletSet: ${errorMessage(err)}\n`);
     }
-    return false;
+    return bulletSet;
+}
+function isAlreadyArchived(archivedSet, bullet) {
+    const normalizedBullet = stripComments(bullet).replace(/^-\s+/, "").trim().toLowerCase();
+    if (!normalizedBullet)
+        return false;
+    return archivedSet.has(normalizedBullet);
 }
 /**
  * Archive the oldest entries from FINDINGS.md into reference/{topic}.md files.
@@ -152,8 +157,11 @@ export function autoArchiveToReference(phrenPath, project, keepCount) {
                     throw wxErr;
                 }
             }
-            catch {
-                return phrenErr("Consolidation already running", PhrenError.LOCK_TIMEOUT);
+            catch (innerErr) {
+                if (innerErr.code === "EEXIST" || innerErr.code === "ENOENT") {
+                    return phrenErr("Consolidation already running", PhrenError.LOCK_TIMEOUT);
+                }
+                throw innerErr;
             }
         }
         else {
@@ -173,9 +181,10 @@ export function autoArchiveToReference(phrenPath, project, keepCount) {
             const referenceDir = path.join(resolvedDir, "reference");
             const { topics } = readProjectTopics(phrenPath, project);
             const today = new Date().toISOString().slice(0, 10);
+            const archivedSet = buildArchivedBulletSet(referenceDir);
             const actuallyArchived = [];
             for (const entry of toArchive) {
-                if (isAlreadyArchived(referenceDir, entry.bullet)) {
+                if (isAlreadyArchived(archivedSet, entry.bullet)) {
                     debugLog(`auto_archive: skipping already-archived entry: "${entry.bullet.slice(0, 60)}"`);
                     continue;
                 }
@@ -271,7 +280,7 @@ export function autoArchiveToReference(phrenPath, project, keepCount) {
             fs.unlinkSync(lockFile);
         }
         catch (err) {
-            if ((process.env.PHREN_DEBUG || process.env.PHREN_DEBUG))
+            if ((process.env.PHREN_DEBUG))
                 process.stderr.write(`[phren] autoArchiveToReference unlockFile: ${errorMessage(err)}\n`);
         }
     }