@phren/cli 0.1.33 → 0.1.35

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -305,11 +305,11 @@ export function configureClaude(phrenPath, opts = {}) {
305
305
  upsertPhrenHook("UserPromptSubmit", {
306
306
  type: "command",
307
307
  command: lifecycle.userPromptSubmit || `node "${entryScript}" hook-prompt`,
308
- timeout: 3,
308
+ timeout: 10,
309
309
  });
310
310
  // Mirror pre-prompt custom hooks into Claude's settings.json as
311
311
  // peer UserPromptSubmit entries so they run in parallel with phren
312
- // and don't share its 3-second timeout budget. See
312
+ // and don't share its timeout budget. See
313
313
  // upsertCustomPrePromptSiblings docstring for details.
314
314
  try {
315
315
  upsertCustomPrePromptSiblings(hooksMap, phrenPath);
@@ -269,7 +269,7 @@ hooks:
269
269
  - hooks:
270
270
  - type: command
271
271
  command: "${promptCmd}"
272
- timeout: 3
272
+ timeout: 10
273
273
  Stop:
274
274
  - hooks:
275
275
  - type: command
package/dist/logger.js CHANGED
@@ -1,13 +1,32 @@
1
1
  import * as fs from "fs";
2
2
  import { runtimeFile, findPhrenPath } from "./shared.js";
3
3
  let _cachedPhrenPath;
4
+ const LOG_MAX_BYTES = 5_000_000; // rotate debug.log past ~5MB
5
+ const LOG_KEEP_LINES = 2000; // keep the most recent lines on rotation
6
+ /** Truncate debug.log to its last LOG_KEEP_LINES if it has grown past the cap. */
7
+ function rotateIfLarge(logPath) {
8
+ try {
9
+ if (fs.statSync(logPath).size <= LOG_MAX_BYTES)
10
+ return;
11
+ const lines = fs.readFileSync(logPath, "utf-8").split("\n");
12
+ fs.writeFileSync(logPath, lines.slice(-LOG_KEEP_LINES).join("\n"));
13
+ }
14
+ catch {
15
+ // statSync ENOENT (no file yet) or any IO error — nothing to rotate
16
+ }
17
+ }
4
18
  export function log(level, tool, message, extra) {
5
19
  try {
20
+ // debug-level logging is opt-in (matches debugLog). It was the bulk of the
21
+ // 30MB debug.log — mostly expected-ENOENT noise logged on the normal path.
22
+ if (level === "debug" && !process.env.PHREN_DEBUG)
23
+ return;
6
24
  if (_cachedPhrenPath === undefined)
7
25
  _cachedPhrenPath = findPhrenPath();
8
26
  if (!_cachedPhrenPath)
9
27
  return;
10
28
  const logPath = runtimeFile(_cachedPhrenPath, "debug.log");
29
+ rotateIfLarge(logPath);
11
30
  const line = JSON.stringify({ ts: new Date().toISOString(), level, tool, message, ...extra });
12
31
  fs.appendFileSync(logPath, line + "\n");
13
32
  }
@@ -47,6 +47,12 @@ export declare function sessionMarker(phrenPath: string, name: string): string;
47
47
  export declare function debugLog(msg: string): void;
48
48
  /** Always-on structured error log (no PHREN_DEBUG gate). */
49
49
  export declare function errorLog(tool: string, msg: string): void;
50
+ /**
51
+ * Truncate an append-only .jsonl to its last `keepLines` lines once it exceeds
52
+ * `maxBytes`. Best-effort: any IO error (including ENOENT) is ignored so callers
53
+ * never fail on rotation.
54
+ */
55
+ export declare function rotateJsonlIfLarge(filePath: string, maxBytes?: number, keepLines?: number): void;
50
56
  export declare function appendIndexEvent(phrenPath: string, event: Record<string, unknown>): void;
51
57
  /** Resolve the canonical findings file for a project directory. */
52
58
  export declare function resolveFindingsPath(projectDir: string): string | undefined;
@@ -307,9 +307,26 @@ export function errorLog(tool, msg) {
307
307
  // Logging must never throw
308
308
  }
309
309
  }
310
+ /**
311
+ * Truncate an append-only .jsonl to its last `keepLines` lines once it exceeds
312
+ * `maxBytes`. Best-effort: any IO error (including ENOENT) is ignored so callers
313
+ * never fail on rotation.
314
+ */
315
+ export function rotateJsonlIfLarge(filePath, maxBytes = 2_000_000, keepLines = 2000) {
316
+ try {
317
+ if (fs.statSync(filePath).size <= maxBytes)
318
+ return;
319
+ const lines = fs.readFileSync(filePath, "utf-8").split("\n");
320
+ fs.writeFileSync(filePath, lines.slice(-keepLines).join("\n"));
321
+ }
322
+ catch {
323
+ // no file yet or IO error — nothing to rotate
324
+ }
325
+ }
310
326
  export function appendIndexEvent(phrenPath, event) {
311
327
  try {
312
328
  const file = runtimeFile(phrenPath, "index-events.jsonl");
329
+ rotateJsonlIfLarge(file);
313
330
  fs.appendFileSync(file, JSON.stringify({ at: new Date().toISOString(), ...event }) + "\n");
314
331
  }
315
332
  catch (err) {
@@ -4,6 +4,8 @@ export { cosineFallback } from "./search-fallback.js";
4
4
  export { queryFragmentLinks, getFragmentBoostDocs, ensureGlobalEntitiesTable, queryCrossProjectFragments, logFragmentMiss, extractFragmentNames, } from "./fragment-graph.js";
5
5
  export { buildSourceDocKey, decodeFiniteNumber, decodeStringRow, extractSnippet, getDocSourceKey, normalizeMemoryId, queryDocBySourceKey, queryDocRows, queryRows, rowToDoc, rowToDocWithRowid, } from "../index-query.js";
6
6
  export type { SqlValue, DbRow, DocRow, SqlJsDatabase } from "../index-query.js";
7
+ /** Drain pending embeddings immediately (used by the MCP server's graceful shutdown). */
8
+ export declare function flushEmbeddingQueue(): Promise<void>;
7
9
  export declare function classifyFile(filename: string, relPath: string): string;
8
10
  /**
9
11
  * Resolve `@import shared/file.md` directives in document content.
@@ -21,6 +23,20 @@ export declare function normalizeIndexedContent(content: string, type: string, p
21
23
  */
22
24
  export declare function updateFileInIndex(db: SqlJsDatabase, filePath: string, phrenPath: string): void;
23
25
  export declare function buildIndex(phrenPath: string, profile?: string): Promise<SqlJsDatabase>;
26
+ /**
27
+ * Non-blocking index loader for the UserPromptSubmit / PostToolUse hooks.
28
+ * Unlike buildIndex(), this NEVER blocks a hook on a 2-12s rebuild:
29
+ * - exact stat-hash cache hit → serve it immediately (fast path);
30
+ * - miss but a usable (possibly stale) cache exists → serve the stale snapshot
31
+ * now and kick a *detached* `background-reindex` (deduped by the rebuild
32
+ * lock) so the next prompt gets fresh results. A single prompt's context may
33
+ * lag one write — far better than freezing the prompt;
34
+ * - cold start (no cache at all) → block once on a full build so the very first
35
+ * prompt isn't empty.
36
+ * Freshness stays correct over time: an edit bumps mtime → new stat-hash → this
37
+ * misses → a rebuild is scheduled → the following prompt hits the new cache.
38
+ */
39
+ export declare function loadIndexForHook(phrenPath: string, profile?: string): Promise<SqlJsDatabase>;
24
40
  /** Find the FTS cache file for a specific phrenPath+profile. Returns exists + size. */
25
41
  export declare function findFtsCacheForPath(phrenPath: string, profile?: string): {
26
42
  exists: boolean;
@@ -71,8 +71,9 @@ import { logger } from "../logger.js";
71
71
  import { formatActorAttribution, parseSourceComment } from "../content/citation.js";
72
72
  import { beginUserFragmentBuildCache, endUserFragmentBuildCache, extractAndLinkFragments, ensureGlobalEntitiesTable, } from "./fragment-graph.js";
73
73
  import { bootstrapSqlJs } from "./sqljs.js";
74
+ import { spawnDetachedChild } from "./process.js";
74
75
  import { getProjectOwnershipMode, getProjectSourcePath, readProjectConfig } from "../project-config.js";
75
- import { buildSourceDocKey, queryDocBySourceKey, queryDocRows, } from "../index-query.js";
76
+ import { buildSourceDocKey, decodeStringRow, getDocSourceKey, queryDocRows, queryRows, } from "../index-query.js";
76
77
  import { classifyTopicForText, readProjectTopics, } from "../project-topics.js";
77
78
  export { porterStem } from "./stemmer.js";
78
79
  export { cosineFallback } from "./search-fallback.js";
@@ -92,9 +93,19 @@ function scheduleEmbedding(phrenPath, docPath, content) {
92
93
  if (_embTimer)
93
94
  clearTimeout(_embTimer);
94
95
  _embTimer = setTimeout(() => { _embTimer = null; void _drainEmbQueue(); }, 500);
95
- // Unref so the timer doesn't keep short-lived CLI processes alive
96
+ // Unref so the timer doesn't keep short-lived CLI processes alive. Pending
97
+ // embeddings are lost if such a process exits first (acceptable: they're
98
+ // regenerated on demand); the MCP server calls flushEmbeddingQueue on shutdown.
96
99
  _embTimer.unref();
97
100
  }
101
+ /** Drain pending embeddings immediately (used by the MCP server's graceful shutdown). */
102
+ export async function flushEmbeddingQueue() {
103
+ if (_embTimer) {
104
+ clearTimeout(_embTimer);
105
+ _embTimer = null;
106
+ }
107
+ await _drainEmbQueue();
108
+ }
98
109
  async function _drainEmbQueue() {
99
110
  if (_embQueue.size === 0)
100
111
  return;
@@ -375,10 +386,17 @@ function computePhrenHash(phrenPath, profile, preGlobbed) {
375
386
  }
376
387
  const INDEX_HASHES_FILENAME = "index-hashes.json";
377
388
  const INDEX_SCHEMA_VERSION = 3; // bump when FTS schema changes to force full rebuild
389
+ // Deletion share above which an incremental update falls back to a full rebuild.
390
+ const MAX_INCREMENTAL_DELETE_RATIO = 0.5;
378
391
  function hashFileContent(filePath) {
379
392
  const content = fs.readFileSync(filePath, "utf-8");
380
393
  return crypto.createHash("sha256").update(content).digest("hex");
381
394
  }
395
+ /** Errors expected from idempotent schema migrations run against older cached DBs. */
396
+ function isExpectedMigrationError(err) {
397
+ const msg = errorMessage(err).toLowerCase();
398
+ return msg.includes("duplicate column name") || msg.includes("no such table");
399
+ }
382
400
  function loadHashMap(phrenPath) {
383
401
  const runtimeDir = path.join(phrenPath, ".runtime");
384
402
  const hashFile = path.join(runtimeDir, INDEX_HASHES_FILENAME);
@@ -392,7 +410,7 @@ function loadHashMap(phrenPath) {
392
410
  }
393
411
  return { hashes: {} };
394
412
  }
395
- function saveHashMap(phrenPath, hashes, knownPaths) {
413
+ function saveHashMap(phrenPath, hashes, knownPaths, meta) {
396
414
  const runtimeDir = path.join(phrenPath, ".runtime");
397
415
  try {
398
416
  fs.mkdirSync(runtimeDir, { recursive: true });
@@ -402,24 +420,34 @@ function saveHashMap(phrenPath, hashes, knownPaths) {
402
420
  // Prune entries for files that no longer exist to prevent ghost paths from causing
403
421
  // repeated full rebuilds when deleted files are found in the hash map.
404
422
  let existing = {};
423
+ let existingMeta = {};
405
424
  try {
406
425
  const data = JSON.parse(fs.readFileSync(hashFile, "utf-8"));
407
426
  if (data.hashes && typeof data.hashes === "object")
408
427
  existing = data.hashes;
428
+ if (data.meta && typeof data.meta === "object")
429
+ existingMeta = data.meta;
409
430
  }
410
431
  catch (err) {
411
432
  logger.debug("saveHashMap readExisting", errorMessage(err));
412
433
  }
413
434
  const merged = { ...existing, ...hashes };
435
+ const mergedMeta = { ...existingMeta, ...meta };
414
436
  // Remove entries for paths that no longer exist. When knownPaths is provided
415
437
  // (build passes supply the full file list), use set membership instead of
416
438
  // hitting the filesystem — avoids N sync stat calls inside the lock.
417
439
  for (const filePath of Object.keys(merged)) {
418
440
  if (knownPaths ? !knownPaths.has(filePath) : !fs.existsSync(filePath)) {
419
441
  delete merged[filePath];
442
+ delete mergedMeta[filePath];
420
443
  }
421
444
  }
422
- fs.writeFileSync(hashFile, JSON.stringify({ version: INDEX_SCHEMA_VERSION, hashes: merged }, null, 2));
445
+ // Drop meta for paths without a hash entry (meta is only an optimization).
446
+ for (const filePath of Object.keys(mergedMeta)) {
447
+ if (!(filePath in merged))
448
+ delete mergedMeta[filePath];
449
+ }
450
+ fs.writeFileSync(hashFile, JSON.stringify({ version: INDEX_SCHEMA_VERSION, hashes: merged, meta: mergedMeta }, null, 2));
423
451
  });
424
452
  }
425
453
  catch (err) {
@@ -680,7 +708,8 @@ export function updateFileInIndex(db, filePath, phrenPath) {
680
708
  try {
681
709
  const hashData = loadHashMap(phrenPath);
682
710
  hashData.hashes[resolvedPath] = hashFileContent(resolvedPath);
683
- saveHashMap(phrenPath, hashData.hashes);
711
+ const stat = fs.statSync(resolvedPath);
712
+ saveHashMap(phrenPath, hashData.hashes, undefined, { [resolvedPath]: { mtimeMs: stat.mtimeMs, size: stat.size } });
684
713
  }
685
714
  catch (err) {
686
715
  logger.debug("updateFileInIndex hashMap", errorMessage(err));
@@ -839,13 +868,29 @@ function mergeManualLinks(db, phrenPath) {
839
868
  return;
840
869
  try {
841
870
  const manualLinks = JSON.parse(fs.readFileSync(manualLinksPath, 'utf8'));
871
+ // Resolve all sourceDoc keys in one query instead of one lookup per link.
872
+ // Mirrors queryDocBySourceKey semantics: match project + basename(filename),
873
+ // then compare the full source-doc key.
874
+ const projects = [...new Set(manualLinks.map((l) => l.sourceDoc.match(/^([^/]+)\//)?.[1]).filter((p) => !!p))];
875
+ const filenames = [...new Set(manualLinks
876
+ .map((l) => l.sourceDoc.match(/^[^/]+\/(.+)$/)?.[1])
877
+ .filter((rest) => !!rest)
878
+ .map((rest) => path.basename(rest)))];
879
+ const validSourceKeys = new Set();
880
+ if (projects.length && filenames.length) {
881
+ const sql = `SELECT project, filename, path FROM docs WHERE project IN (${projects.map(() => "?").join(",")}) AND filename IN (${filenames.map(() => "?").join(",")})`;
882
+ const rows = queryRows(db, sql, [...projects, ...filenames]) ?? [];
883
+ for (const row of rows) {
884
+ const [project, filename, docPath] = decodeStringRow(row, 3, "mergeManualLinks");
885
+ validSourceKeys.add(getDocSourceKey({ project, filename, path: docPath }, phrenPath));
886
+ }
887
+ }
842
888
  let pruned = false;
843
889
  const validLinks = [];
844
890
  for (const link of manualLinks) {
845
891
  try {
846
892
  // Validate: skip manual links whose sourceDoc no longer exists in the index
847
- const docCheck = queryDocBySourceKey(db, phrenPath, link.sourceDoc);
848
- if (!docCheck) {
893
+ if (!validSourceKeys.has(link.sourceDoc)) {
849
894
  logger.debug("manualLinks", `pruning stale link to "${link.sourceDoc}"`);
850
895
  pruned = true;
851
896
  continue;
@@ -952,7 +997,11 @@ async function buildIndexImpl(phrenPath, profile) {
952
997
  try {
953
998
  db.run("ALTER TABLE entities ADD COLUMN first_seen_at TEXT");
954
999
  }
955
- catch { /* column already exists */ }
1000
+ catch (err) {
1001
+ // Usually "duplicate column name" — column already exists
1002
+ if (!isExpectedMigrationError(err))
1003
+ logger.warn("buildIndex migration", errorMessage(err));
1004
+ }
956
1005
  debugLog(`Loaded FTS index from cache (${hash.slice(0, 8)}) in ${Date.now() - t0}ms [sentinel-hit]`);
957
1006
  appendIndexEvent(phrenPath, {
958
1007
  event: "build_index",
@@ -992,16 +1041,31 @@ async function buildIndexImpl(phrenPath, profile) {
992
1041
  try {
993
1042
  db.run("ALTER TABLE entities ADD COLUMN first_seen_at TEXT");
994
1043
  }
995
- catch { /* column already exists — expected */ }
996
- // Compute current file hashes and determine what changed
1044
+ catch (err) {
1045
+ // Usually "duplicate column name" — column already exists
1046
+ if (!isExpectedMigrationError(err))
1047
+ logger.warn("buildIndex migration", errorMessage(err));
1048
+ }
1049
+ // Compute current file hashes and determine what changed.
1050
+ // Files whose mtime+size match the stored snapshot reuse the stored hash,
1051
+ // skipping a read+SHA256 per file; the content hash stays the source of
1052
+ // truth whenever the stat changed.
997
1053
  const allFiles = globResult.entries;
1054
+ const savedMeta = savedHashData.meta ?? {};
998
1055
  const currentHashes = {};
1056
+ const currentMeta = {};
999
1057
  const changedFiles = [];
1000
1058
  const newFiles = [];
1001
1059
  for (const entry of allFiles) {
1002
1060
  try {
1003
- const fileHash = hashFileContent(entry.fullPath);
1061
+ const stat = fs.statSync(entry.fullPath);
1062
+ const prevHash = savedHashes[entry.fullPath];
1063
+ const prevMeta = savedMeta[entry.fullPath];
1064
+ const statUnchanged = prevHash !== undefined && prevMeta !== undefined
1065
+ && prevMeta.mtimeMs === stat.mtimeMs && prevMeta.size === stat.size;
1066
+ const fileHash = statUnchanged ? prevHash : hashFileContent(entry.fullPath);
1004
1067
  currentHashes[entry.fullPath] = fileHash;
1068
+ currentMeta[entry.fullPath] = { mtimeMs: stat.mtimeMs, size: stat.size };
1005
1069
  if (!(entry.fullPath in savedHashes)) {
1006
1070
  newFiles.push(entry);
1007
1071
  }
@@ -1016,10 +1080,13 @@ async function buildIndexImpl(phrenPath, profile) {
1016
1080
  // Check for files missing from the index (deleted files)
1017
1081
  const currentPaths = new Set(Object.keys(currentHashes));
1018
1082
  const missingFromIndex = Object.keys(savedHashes).filter(p => !currentPaths.has(p));
1019
- // Force full rebuild if >20% of saved files are missing
1083
+ // Force a full rebuild when a large share of saved files vanished at once —
1084
+ // guards against pathological glob results (e.g. a temporarily unmounted
1085
+ // store dir) and bounds FTS bloat from mass tombstones. Smaller deletions
1086
+ // are removed incrementally.
1020
1087
  const totalSaved = Object.keys(savedHashes).length;
1021
- if (totalSaved > 0 && missingFromIndex.length / totalSaved > 0.2) {
1022
- debugLog(`>20% files missing (${missingFromIndex.length}/${totalSaved}), forcing full rebuild`);
1088
+ if (totalSaved > 0 && missingFromIndex.length / totalSaved > MAX_INCREMENTAL_DELETE_RATIO) {
1089
+ debugLog(`>${MAX_INCREMENTAL_DELETE_RATIO * 100}% files missing (${missingFromIndex.length}/${totalSaved}), forcing full rebuild`);
1023
1090
  // Fall through to full rebuild below
1024
1091
  }
1025
1092
  else if (changedFiles.length === 0 && newFiles.length === 0 && missingFromIndex.length === 0) {
@@ -1076,7 +1143,11 @@ async function buildIndexImpl(phrenPath, profile) {
1076
1143
  try {
1077
1144
  db.run("DELETE FROM global_entities WHERE doc_key = ?", [sourceDocKey]);
1078
1145
  }
1079
- catch { /* table may not exist in older cached DBs */ }
1146
+ catch (err) {
1147
+ // Usually "no such table" — table may not exist in older cached DBs
1148
+ if (!isExpectedMigrationError(err))
1149
+ logger.warn("buildIndex migration", errorMessage(err));
1150
+ }
1080
1151
  db.run("DELETE FROM docs WHERE path = ?", [entry.fullPath]);
1081
1152
  }
1082
1153
  if (insertFileIntoIndex(db, entry, phrenPath, { scheduleEmbeddings: true })) {
@@ -1103,7 +1174,7 @@ async function buildIndexImpl(phrenPath, profile) {
1103
1174
  throw err;
1104
1175
  }
1105
1176
  }
1106
- saveHashMap(phrenPath, currentHashes, new Set(Object.keys(currentHashes)));
1177
+ saveHashMap(phrenPath, currentHashes, new Set(Object.keys(currentHashes)), currentMeta);
1107
1178
  touchSentinel(phrenPath);
1108
1179
  invalidateDfCache();
1109
1180
  // Save updated cache
@@ -1160,6 +1231,7 @@ async function buildIndexImpl(phrenPath, profile) {
1160
1231
  ensureGlobalEntitiesTable(db);
1161
1232
  const allFiles = globResult.entries;
1162
1233
  const newHashes = {};
1234
+ const newMeta = {};
1163
1235
  let fileCount = 0;
1164
1236
  // Try loading cached fragment graph
1165
1237
  const graphPath = runtimeFile(phrenPath, 'entity-graph.json');
@@ -1167,6 +1239,8 @@ async function buildIndexImpl(phrenPath, profile) {
1167
1239
  for (const entry of allFiles) {
1168
1240
  try {
1169
1241
  newHashes[entry.fullPath] = hashFileContent(entry.fullPath);
1242
+ const stat = fs.statSync(entry.fullPath);
1243
+ newMeta[entry.fullPath] = { mtimeMs: stat.mtimeMs, size: stat.size };
1170
1244
  }
1171
1245
  catch (err) {
1172
1246
  logger.debug("computePhrenHash skip", errorMessage(err));
@@ -1202,7 +1276,7 @@ async function buildIndexImpl(phrenPath, profile) {
1202
1276
  // Always merge manual links (survive rebuild)
1203
1277
  mergeManualLinks(db, phrenPath);
1204
1278
  // ── Finalize: persist hashes, save cache, log ─────────────────────────────
1205
- saveHashMap(phrenPath, newHashes, new Set(Object.keys(newHashes)));
1279
+ saveHashMap(phrenPath, newHashes, new Set(Object.keys(newHashes)), newMeta);
1206
1280
  touchSentinel(phrenPath);
1207
1281
  invalidateDfCache();
1208
1282
  const buildMs = Date.now() - t0;
@@ -1360,6 +1434,78 @@ export async function buildIndex(phrenPath, profile) {
1360
1434
  _lastBuildKey = buildKey;
1361
1435
  return db;
1362
1436
  }
1437
+ /** Resolve the per-user FTS cache directory (os.tmpdir()/phren-fts-<uid>). */
1438
+ function ftsCacheDir() {
1439
+ let userSuffix;
1440
+ try {
1441
+ userSuffix = String(os.userInfo().uid);
1442
+ }
1443
+ catch (err) {
1444
+ logger.debug("ftsCacheDir userInfo", errorMessage(err));
1445
+ userSuffix = crypto.createHash("sha1").update(homeDir()).digest("hex").slice(0, 12);
1446
+ }
1447
+ return path.join(os.tmpdir(), `phren-fts-${userSuffix}`);
1448
+ }
1449
+ /**
1450
+ * Non-blocking index loader for the UserPromptSubmit / PostToolUse hooks.
1451
+ * Unlike buildIndex(), this NEVER blocks a hook on a 2-12s rebuild:
1452
+ * - exact stat-hash cache hit → serve it immediately (fast path);
1453
+ * - miss but a usable (possibly stale) cache exists → serve the stale snapshot
1454
+ * now and kick a *detached* `background-reindex` (deduped by the rebuild
1455
+ * lock) so the next prompt gets fresh results. A single prompt's context may
1456
+ * lag one write — far better than freezing the prompt;
1457
+ * - cold start (no cache at all) → block once on a full build so the very first
1458
+ * prompt isn't empty.
1459
+ * Freshness stays correct over time: an edit bumps mtime → new stat-hash → this
1460
+ * misses → a rebuild is scheduled → the following prompt hits the new cache.
1461
+ */
1462
+ export async function loadIndexForHook(phrenPath, profile) {
1463
+ const cacheDir = ftsCacheDir();
1464
+ const globResult = globAllFiles(phrenPath, profile);
1465
+ const hash = computePhrenHash(phrenPath, profile, globResult.filePaths);
1466
+ const cacheFile = path.join(cacheDir, `${hash}.db`);
1467
+ const SQL = await bootstrapSqlJs();
1468
+ // Fast path: exact stat-hash hit (no file changed mtime/size since the build).
1469
+ if (fs.existsSync(cacheFile)) {
1470
+ try {
1471
+ const db = new SQL.Database(fs.readFileSync(cacheFile));
1472
+ const docCount = db.exec("SELECT COUNT(*) FROM docs")?.[0]?.values?.[0]?.[0] ?? 0;
1473
+ if (docCount > 0) {
1474
+ appendIndexEvent(phrenPath, { event: "build_index", cache: "hit", hash: hash.slice(0, 12), elapsedMs: 0, profile: profile || "" });
1475
+ return db;
1476
+ }
1477
+ db.close();
1478
+ }
1479
+ catch (err) {
1480
+ debugLog(`loadIndexForHook fast-path load failed: ${errorMessage(err)}`);
1481
+ }
1482
+ }
1483
+ // Miss. Serve stale immediately if any cache exists; else cold-build once.
1484
+ let hasStale = false;
1485
+ try {
1486
+ hasStale = fs.existsSync(cacheDir) && fs.readdirSync(cacheDir).some(f => f.endsWith(".db"));
1487
+ }
1488
+ catch (err) {
1489
+ logger.debug("loadIndexForHook staleScan", errorMessage(err));
1490
+ }
1491
+ if (!hasStale) {
1492
+ return buildIndex(phrenPath, profile);
1493
+ }
1494
+ // Schedule a detached rebuild for next time (rebuild lock dedups concurrent hooks).
1495
+ if (!isRebuildLockHeld(phrenPath)) {
1496
+ const entry = process.argv[1];
1497
+ if (entry && /index\.(c?js|mjs|ts)$/.test(entry) && fs.existsSync(entry)) {
1498
+ try {
1499
+ spawnDetachedChild([entry, "background-reindex"], { phrenPath }).unref();
1500
+ debugLog(`loadIndexForHook: scheduled detached background-reindex (stat-hash miss ${hash.slice(0, 8)})`);
1501
+ }
1502
+ catch (err) {
1503
+ debugLog(`loadIndexForHook: detached reindex spawn failed: ${errorMessage(err)}`);
1504
+ }
1505
+ }
1506
+ }
1507
+ return loadIndexSnapshotOrEmpty(phrenPath, profile);
1508
+ }
1363
1509
  async function _buildIndexGuarded(phrenPath, profile) {
1364
1510
  const lockTarget = runtimeFile(phrenPath, "index-rebuild");
1365
1511
  if (isRebuildLockHeld(phrenPath)) {
@@ -68,17 +68,36 @@ function intentBoost(intent, docType) {
68
68
  return 2;
69
69
  return 0;
70
70
  }
71
+ // fileRelevanceBoost runs once per candidate doc during ranking, all sharing the
72
+ // same changedFiles Set. Cache the normalized view (keyed by the Set instance) so
73
+ // path normalization happens once per ranking pass instead of once per doc.
74
+ const _normalizedChangedFiles = new WeakMap();
75
+ function normalizeChangedFiles(changedFiles) {
76
+ let cached = _normalizedChangedFiles.get(changedFiles);
77
+ if (cached)
78
+ return cached;
79
+ const basenames = new Set();
80
+ const paths = [];
81
+ for (const cf of changedFiles) {
82
+ const n = cf.replace(/\\/g, "/");
83
+ basenames.add(path.basename(n));
84
+ paths.push(n);
85
+ }
86
+ cached = { basenames, paths };
87
+ _normalizedChangedFiles.set(changedFiles, cached);
88
+ return cached;
89
+ }
71
90
  export function fileRelevanceBoost(filePath, changedFiles) {
72
91
  if (changedFiles.size === 0)
73
92
  return 0;
74
93
  const normalized = filePath.replace(/\\/g, "/");
75
94
  const docBasename = path.basename(normalized);
76
- for (const cf of changedFiles) {
77
- const n = cf.replace(/\\/g, "/");
78
- // Exact basename match to avoid 'index.ts' matching 'shared-index.ts'
79
- if (path.basename(n) === docBasename)
80
- return 3;
81
- // Also match if the full changed-file path is a suffix of the doc path
95
+ const { basenames, paths } = normalizeChangedFiles(changedFiles);
96
+ // Exact basename match to avoid 'index.ts' matching 'shared-index.ts'
97
+ if (basenames.has(docBasename))
98
+ return 3;
99
+ // Also match if the full changed-file path is a suffix of the doc path
100
+ for (const n of paths) {
82
101
  if (normalized.endsWith(`/${n}`))
83
102
  return 3;
84
103
  }
package/dist/telemetry.js CHANGED
@@ -55,7 +55,10 @@ function flushTelemetryForPath(phrenPath) {
55
55
  const file = telemetryPath(phrenPath);
56
56
  try {
57
57
  fs.mkdirSync(path.dirname(file), { recursive: true });
58
- fs.writeFileSync(file, JSON.stringify(data, null, 2) + "\n");
58
+ // Usage stats are private to the user: owner-only perms, including files
59
+ // created by older versions (mode only applies on create).
60
+ fs.writeFileSync(file, JSON.stringify(data, null, 2) + "\n", { mode: 0o600 });
61
+ fs.chmodSync(file, 0o600);
59
62
  }
60
63
  catch (err) {
61
64
  logger.debug("telemetry flush", errorMessage(err));
@@ -1,3 +1,4 @@
1
1
  import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
2
2
  import { type McpContext } from "./types.js";
3
+ export declare function findConflictCandidates(phrenPath: string, project: string, finding: string): string[];
3
4
  export declare function register(server: McpServer, ctx: McpContext): void;
@@ -8,7 +8,7 @@ import { removeFinding as removeFindingCore, removeFindings as removeFindingsCor
8
8
  import { debugLog, EXEC_TIMEOUT_MS, FINDING_TYPES, normalizeMemoryScope, } from "../shared.js";
9
9
  import { getCurrentActor, getMachineName } from "../machine-identity.js";
10
10
  import { addFindingToFile, addFindingsToFile, checkSemanticConflicts, autoMergeConflicts, } from "../shared/content.js";
11
- import { jaccardTokenize, jaccardSimilarity, stripMetadata } from "../content/dedup.js";
11
+ import { jaccardTokenize, jaccardSimilarity, stripMetadata, detectConflicts, extractDynamicEntities } from "../content/dedup.js";
12
12
  import { runCustomHooks } from "../hooks.js";
13
13
  import { incrementSessionFindings } from "./session.js";
14
14
  import { extractFragmentNames } from "../shared/fragment-graph.js";
@@ -49,6 +49,30 @@ function findJaccardCandidates(phrenPath, project, finding) {
49
49
  return [];
50
50
  }
51
51
  }
52
+ // Heuristic conflict candidates surfaced to the calling agent so it can decide whether a
53
+ // genuine contradiction exists — no extra LLM/API call, the agent in the loop is the judge.
54
+ // Mirrors findJaccardCandidates (potential duplicates). Capped to keep the response small.
55
+ const MAX_CONFLICT_CANDIDATES = 5;
56
+ export function findConflictCandidates(phrenPath, project, finding) {
57
+ try {
58
+ const findingsPath = path.join(phrenPath, project, FINDINGS_FILENAME);
59
+ if (!fs.existsSync(findingsPath))
60
+ return [];
61
+ const content = fs.readFileSync(findingsPath, "utf8");
62
+ const activeBullets = content.split("\n").filter((l) => l.startsWith("- ") && !isInactiveFindingLine(l));
63
+ if (activeBullets.length === 0)
64
+ return [];
65
+ const dynamicEntities = extractDynamicEntities(phrenPath, project);
66
+ return detectConflicts(finding, activeBullets, dynamicEntities)
67
+ .map((line) => stripMetadata(line).replace(/^-\s+/, "").trim().slice(0, 80))
68
+ .filter((snippet) => snippet.length > 0)
69
+ .slice(0, MAX_CONFLICT_CANDIDATES);
70
+ }
71
+ catch (err) {
72
+ logger.debug("add_finding", `findConflictCandidates: ${errorMessage(err)}`);
73
+ return [];
74
+ }
75
+ }
52
76
  function extractConflictsWith(annotations) {
53
77
  return annotations
54
78
  .map((annotation) => annotation.match(/<!--\s*conflicts_with:\s*"([^"]+)"/)?.[1])
@@ -142,11 +166,15 @@ async function handleAddFinding(ctx, params) {
142
166
  return withWriteQueue(async () => {
143
167
  runCustomHooks(phrenPath, "pre-finding", { PHREN_PROJECT: project });
144
168
  const allPotentialDuplicates = [];
169
+ const allPotentialConflicts = [];
145
170
  const extraAnnotationsByFinding = [];
146
171
  for (const f of findings) {
147
172
  const candidates = findJaccardCandidates(phrenPath, project, f);
148
173
  if (candidates.length > 0)
149
174
  allPotentialDuplicates.push({ finding: f, candidates });
175
+ const conflictCandidates = findConflictCandidates(phrenPath, project, f);
176
+ if (conflictCandidates.length > 0)
177
+ allPotentialConflicts.push({ finding: f, candidates: conflictCandidates });
150
178
  try {
151
179
  const conflicts = await checkSemanticConflicts(phrenPath, project, f);
152
180
  extraAnnotationsByFinding.push(conflicts.checked && conflicts.annotations.length > 0 ? conflicts.annotations : []);
@@ -180,6 +208,7 @@ async function handleAddFinding(ctx, params) {
180
208
  skipped,
181
209
  rejected,
182
210
  ...(allPotentialDuplicates.length > 0 ? { potentialDuplicates: allPotentialDuplicates } : {}),
211
+ ...(allPotentialConflicts.length > 0 ? { potentialConflicts: allPotentialConflicts } : {}),
183
212
  },
184
213
  });
185
214
  });
@@ -191,6 +220,8 @@ async function handleAddFinding(ctx, params) {
191
220
  const taggedFinding = applyFindingTypePrefix(finding, findingType);
192
221
  // Jaccard "maybe zone" scan — free, no LLM call. Return candidates so the agent decides.
193
222
  const potentialDuplicates = findJaccardCandidates(phrenPath, project, taggedFinding);
223
+ // Heuristic contradiction candidates — also free, also agent-decides. No extra API call.
224
+ const potentialConflicts = findConflictCandidates(phrenPath, project, taggedFinding);
194
225
  const semanticConflicts = await checkSemanticConflicts(phrenPath, project, taggedFinding);
195
226
  runCustomHooks(phrenPath, "pre-finding", { PHREN_PROJECT: project });
196
227
  const result = addFindingToFile(phrenPath, project, taggedFinding, citation, {
@@ -249,9 +280,15 @@ async function handleAddFinding(ctx, params) {
249
280
  // Full DB fragment linking happens on the next index rebuild via updateFileInIndex →
250
281
  // extractAndLinkFragments. We surface hints here so callers can see what was detected.
251
282
  const detectedFragments = extractFragmentNames(taggedFinding);
283
+ // Surface heuristic conflict candidates for the agent to judge (only when the LLM path
284
+ // didn't already confirm a conflict, to avoid double-reporting the same relationship).
285
+ const conflictNote = (potentialConflicts.length > 0 && conflictsWithList.length === 0)
286
+ ? ` ⚠ Possible contradiction with existing finding(s): ${potentialConflicts.map((c) => `"${c}"`).join("; ")}.` +
287
+ ` If this genuinely contradicts one, resolve it with resolve_contradiction (or supersede_finding); if they're unrelated, ignore this note.`
288
+ : "";
252
289
  return mcpResponse({
253
290
  ok: true,
254
- message: result.data.message,
291
+ message: result.data.message + conflictNote,
255
292
  data: {
256
293
  project,
257
294
  finding: taggedFinding,
@@ -260,6 +297,7 @@ async function handleAddFinding(ctx, params) {
260
297
  ...(conflictsWithList.length > 0 ? { conflicts: conflictsWithList } : {}),
261
298
  ...(detectedFragments.length > 0 ? { detectedFragments } : {}),
262
299
  ...(potentialDuplicates.length > 0 ? { potentialDuplicates } : {}),
300
+ ...(potentialConflicts.length > 0 ? { potentialConflicts } : {}),
263
301
  scope: normalizedScope,
264
302
  }
265
303
  });
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@phren/cli",
3
- "version": "0.1.33",
3
+ "version": "0.1.35",
4
4
  "description": "Knowledge layer for AI agents — CLI, MCP server, and data layer",
5
5
  "type": "module",
6
6
  "bin": {
@@ -79,8 +79,8 @@
79
79
  "glob": "^13.0.6",
80
80
  "graphology": "^0.26.0",
81
81
  "graphology-layout-forceatlas2": "^0.10.1",
82
- "inquirer": "^13.4.2",
83
- "js-yaml": "^4.1.1",
82
+ "inquirer": "^14.0.2",
83
+ "js-yaml": "^4.2.0",
84
84
  "sigma": "^3.0.3",
85
85
  "sql.js-fts5": "^1.4.0",
86
86
  "zod": "^4.4.3"