@phren/cli 0.1.42 → 0.1.44

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.
Files changed (38) hide show
  1. package/dist/capabilities/cli.js +1 -1
  2. package/dist/capabilities/mcp.js +1 -1
  3. package/dist/capabilities/vscode.js +3 -3
  4. package/dist/capabilities/web-ui.js +29 -29
  5. package/dist/cli/hooks-output.js +15 -6
  6. package/dist/cli/hooks.js +2 -2
  7. package/dist/governance/scores.d.ts +9 -1
  8. package/dist/governance/scores.js +12 -1
  9. package/dist/init/init-uninstall.js +12 -2
  10. package/dist/profile-store.d.ts +2 -0
  11. package/dist/profile-store.js +13 -17
  12. package/dist/shared/fragment-graph.js +7 -2
  13. package/dist/shared/retrieval.d.ts +10 -0
  14. package/dist/shared/retrieval.js +17 -4
  15. package/dist/shell/entry.d.ts +8 -0
  16. package/dist/shell/entry.js +114 -58
  17. package/dist/shell/input.d.ts +1 -1
  18. package/dist/shell/input.js +4 -1
  19. package/dist/shell/keys.d.ts +36 -0
  20. package/dist/shell/keys.js +107 -0
  21. package/dist/shell/render.d.ts +33 -0
  22. package/dist/shell/render.js +216 -46
  23. package/dist/shell/shell.js +16 -3
  24. package/dist/shell/view.js +2 -1
  25. package/dist/store-registry.d.ts +13 -0
  26. package/dist/store-registry.js +106 -34
  27. package/dist/tools/memory.js +12 -5
  28. package/dist/tools/ops.js +1 -1
  29. package/package.json +31 -4
  30. package/starter/global/skills/phren-consolidate/SKILL.md +152 -0
  31. package/starter/global/skills/phren-discover/SKILL.md +175 -0
  32. package/starter/global/skills/phren-init/SKILL.md +216 -0
  33. package/starter/global/skills/phren-profiles/SKILL.md +121 -0
  34. package/starter/global/skills/phren-sync/SKILL.md +261 -0
  35. package/dist/init-uninstall.d.ts +0 -3
  36. package/dist/init-uninstall.js +0 -514
  37. package/dist/init-walkthrough.d.ts +0 -55
  38. package/dist/init-walkthrough.js +0 -524
@@ -1,6 +1,6 @@
1
1
  export const cliManifest = {
2
2
  surface: "cli",
3
- version: "0.1.17",
3
+ version: "0.1.42",
4
4
  actions: {
5
5
  // Finding management
6
6
  "finding.add": { implemented: true, handler: "cli-actions.ts:handleAddFinding" },
@@ -1,6 +1,6 @@
1
1
  export const mcpManifest = {
2
2
  surface: "mcp",
3
- version: "0.1.17",
3
+ version: "0.1.42",
4
4
  actions: {
5
5
  // Finding management
6
6
  "finding.add": { implemented: true, handler: "index.ts:add_finding" },
@@ -1,6 +1,6 @@
1
1
  export const vscodeManifest = {
2
2
  surface: "vscode",
3
- version: "0.1.17",
3
+ version: "0.1.42",
4
4
  actions: {
5
5
  // Finding management
6
6
  "finding.add": { implemented: true, handler: "extension.ts:phren.addFinding" },
@@ -24,8 +24,8 @@ export const vscodeManifest = {
24
24
  "hook.errors": { implemented: false, reason: "Hook errors not exposed in VS Code" },
25
25
  // Search
26
26
  "search.fts": { implemented: true, handler: "searchQuickPick.ts:showSearchQuickPick" },
27
- "search.fragment": { implemented: true, handler: "phrenClient.ts:searchFragments" },
28
- "search.related_docs": { implemented: true, handler: "phrenClient.ts:getRelatedDocs" },
27
+ "search.fragment": { implemented: false, reason: "search_fragments is never called from the extension (no client method exists)" },
28
+ "search.related_docs": { implemented: false, reason: "get_related_docs is never called from the extension (no client method exists)" },
29
29
  "search.history": { implemented: true, handler: "searchQuickPick.ts:searchHistory (in-memory)" },
30
30
  // Graph
31
31
  "graph.read": { implemented: true, handler: "graphWebview.ts:showGraphWebview" },
@@ -1,58 +1,58 @@
1
1
  export const webUiManifest = {
2
2
  surface: "web-ui",
3
- version: "0.1.17",
3
+ version: "0.1.42",
4
4
  actions: {
5
5
  // Finding management
6
- "finding.add": { implemented: false, reason: "Web UI is read-only for findings (review queue only)" },
7
- "finding.remove": { implemented: false, reason: "Web UI is read-only for findings" },
8
- "finding.list": { implemented: true, handler: "memory-ui-server.ts:/api/project-content" },
6
+ "finding.add": { implemented: true, handler: "ui/server.ts:POST /api/findings/<project>" },
7
+ "finding.remove": { implemented: true, handler: "ui/server.ts:DELETE /api/findings/<project>" },
8
+ "finding.list": { implemented: true, handler: "ui/server.ts:/api/findings/<project> + /api/project-content" },
9
9
  "finding.filter_by_date": { implemented: false, reason: "No date filter in web UI API" },
10
- "finding.pin": { implemented: false, reason: "No pin action in web UI" },
10
+ "finding.pin": { implemented: false, reason: "Pinning to truths.md is CLI/MCP-only" },
11
11
  // Task management
12
- "task.add": { implemented: false, reason: "No task creation in web UI" },
13
- "task.complete": { implemented: false, reason: "No task completion in web UI" },
14
- "task.remove": { implemented: false, reason: "No task deletion in web UI" },
15
- "task.update": { implemented: false, reason: "No task update in web UI" },
16
- "task.list": { implemented: true, handler: "memory-ui-server.ts:/api/tasks" },
17
- "task.pin": { implemented: false, reason: "No task pinning in web UI" },
18
- "task.github_link": { implemented: false, reason: "No GitHub link in web UI" },
12
+ "task.add": { implemented: true, handler: "ui/server.ts:POST /api/tasks/add" },
13
+ "task.complete": { implemented: true, handler: "ui/server.ts:POST /api/tasks/complete" },
14
+ "task.remove": { implemented: true, handler: "ui/server.ts:POST /api/tasks/remove" },
15
+ "task.update": { implemented: true, handler: "ui/server.ts:POST /api/tasks/update" },
16
+ "task.list": { implemented: true, handler: "ui/server.ts:/api/tasks" },
17
+ "task.pin": { implemented: false, reason: "No task pinning in web UI (pinned flag is displayed read-only)" },
18
+ "task.github_link": { implemented: false, reason: "Issue links display in the task list; creating them is MCP/VS Code-only" },
19
19
  // Hook management
20
- "hook.list": { implemented: true, handler: "memory-ui-server.ts:/api/hooks" },
21
- "hook.toggle": { implemented: true, handler: "memory-ui-server.ts:/api/hook-toggle" },
20
+ "hook.list": { implemented: true, handler: "ui/server.ts:/api/hooks" },
21
+ "hook.toggle": { implemented: true, handler: "ui/server.ts:POST /api/hook-toggle" },
22
22
  "hook.toggle_per_project": { implemented: false, reason: "Per-project hook toggle not exposed in web UI" },
23
23
  "hook.custom_crud": { implemented: false, reason: "Custom hooks CRUD not exposed in web UI" },
24
24
  "hook.errors": { implemented: false, reason: "Hook errors not exposed in web UI" },
25
25
  // Search
26
- "search.fts": { implemented: true, handler: "memory-ui-server.ts:/api/search" },
26
+ "search.fts": { implemented: true, handler: "ui/server.ts:/api/search" },
27
27
  "search.fragment": { implemented: false, reason: "No fragment search in web UI" },
28
28
  "search.related_docs": { implemented: false, reason: "No related docs in web UI" },
29
29
  "search.history": { implemented: false, reason: "No search history in web UI" },
30
30
  // Graph
31
- "graph.read": { implemented: true, handler: "memory-ui-server.ts:/api/graph" },
32
- "graph.visualize": { implemented: true, handler: "memory-ui-graph-app.ts:graph tab (GraphRAG-style store>project>finding cages, Three.js / 3d-force-graph, CSS2D labels)" },
31
+ "graph.read": { implemented: true, handler: "ui/server.ts:/api/graph" },
32
+ "graph.visualize": { implemented: true, handler: "ui/graph.ts:graph tab (browser/graph bundle — store>project>finding cages, Three.js / 3d-force-graph, CSS2D labels)" },
33
33
  "graph.link_findings": { implemented: false, reason: "No link findings action in web UI" },
34
34
  // Config
35
- "config.get": { implemented: true, handler: "memory-ui-server.ts:/api/settings (read)" },
36
- "config.set": { implemented: true, handler: "memory-ui-server.ts:/api/settings (workflow policy, task mode)" },
35
+ "config.get": { implemented: true, handler: "ui/server.ts:/api/settings + /api/config" },
36
+ "config.set": { implemented: true, handler: "ui/server.ts:POST /api/settings/* (workflow policy, task mode, proactivity, finding sensitivity, index policy, auto-capture, mcp-enabled, project overrides, RBAC via /api/settings/access)" },
37
37
  // Health / Sync / Session
38
- "health.check": { implemented: true, handler: "memory-ui-server.ts:/api/runtime-health" },
38
+ "health.check": { implemented: true, handler: "ui/server.ts:/api/runtime-health" },
39
39
  "health.doctor_fix": { implemented: false, reason: "Doctor --fix is CLI-only" },
40
- "health.sync": { implemented: true, handler: "memory-ui-server.ts:/api/sync" },
40
+ "health.sync": { implemented: true, handler: "ui/server.ts:POST /api/sync" },
41
41
  "session.start": { implemented: false, reason: "Session lifecycle is not web UI driven" },
42
42
  "session.end": { implemented: false, reason: "Session lifecycle is not web UI driven" },
43
43
  // Skill management
44
- "skill.list": { implemented: true, handler: "memory-ui-server.ts:/api/skills" },
45
- "skill.read": { implemented: true, handler: "memory-ui-server.ts:/api/skill-content" },
46
- "skill.enable": { implemented: true, handler: "memory-ui-server.ts:/api/skill-toggle" },
47
- "skill.write": { implemented: true, handler: "memory-ui-server.ts:/api/skill-save" },
44
+ "skill.list": { implemented: true, handler: "ui/server.ts:/api/skills" },
45
+ "skill.read": { implemented: true, handler: "ui/server.ts:/api/skill-content" },
46
+ "skill.enable": { implemented: true, handler: "ui/server.ts:POST /api/skill-toggle" },
47
+ "skill.write": { implemented: true, handler: "ui/server.ts:POST /api/skill-save" },
48
48
  // Project management
49
- "project.list": { implemented: true, handler: "memory-ui-server.ts:/api/projects" },
49
+ "project.list": { implemented: true, handler: "ui/server.ts:/api/projects" },
50
50
  "project.manage": { implemented: false, reason: "No archive/unarchive in web UI" },
51
- "project.summary": { implemented: true, handler: "memory-ui-server.ts:/api/project-content" },
51
+ "project.summary": { implemented: true, handler: "ui/server.ts:/api/project-content" },
52
52
  "export.project": { implemented: false, reason: "Export/import not exposed in web UI" },
53
53
  "import.project": { implemented: false, reason: "Export/import not exposed in web UI" },
54
54
  // Profile / Machine
55
- "profile.switch": { implemented: false, reason: "No profile switching in web UI" },
56
- "profile.list": { implemented: false, reason: "No profile listing in web UI" },
55
+ "profile.switch": { implemented: true, handler: "ui/server.ts:POST /api/profile" },
56
+ "profile.list": { implemented: true, handler: "ui/server.ts:/api/profiles" },
57
57
  },
58
58
  };
@@ -3,7 +3,7 @@ import { getDocSourceKey, } from "../shared/index.js";
3
3
  import { logImpact, extractFindingIdsFromSnippet, } from "../finding/impact.js";
4
4
  import { isFeatureEnabled, errorMessage } from "../utils.js";
5
5
  import { annotateStale } from "./hooks-citations.js";
6
- import { approximateTokens, fileRelevanceBoost, branchMatchBoost } from "../shared/retrieval.js";
6
+ import { approximateTokens, fileRelevanceBoost, branchMatchBoost, SNIPPET_OVERHEAD_TOKENS } from "../shared/retrieval.js";
7
7
  import { logger } from "../logger.js";
8
8
  // ── Progressive disclosure helpers ────────────────────────────────────────────
9
9
  function buildOneLiner(snippet) {
@@ -17,10 +17,13 @@ function buildOneLiner(snippet) {
17
17
  }
18
18
  function buildCompactIndex(selected, phrenPathLocal) {
19
19
  const lines = [];
20
- for (const { doc, snippet } of selected) {
20
+ for (const { doc, snippet, key } of selected) {
21
21
  const id = `mem:${getDocSourceKey(doc, phrenPathLocal)}`;
22
22
  const summary = buildOneLiner(snippet);
23
- lines.push(`[${id}] ${doc.type}: ${summary}`);
23
+ // The fb: key rides here too. memory_feedback's description promises it
24
+ // appears in injected headers without qualification, and this path renders
25
+ // instead of the full one whenever progressive disclosure is enabled.
26
+ lines.push(`[${id}] fb:${key} ${doc.type}: ${summary}`);
24
27
  }
25
28
  return lines;
26
29
  }
@@ -78,14 +81,15 @@ export function buildHookOutput(selected, usedTokens, intent, gitCtx, detectedPr
78
81
  let totalTokens = 36; // base overhead
79
82
  const keep = ordered.map(() => true);
80
83
  for (let i = 0; i < ordered.length; i++) {
81
- totalTokens += approximateTokens(ordered[i].snippet) + 14;
84
+ // 24 ≈ header line ([source key] (type) fb:key) + blank separator.
85
+ totalTokens += approximateTokens(ordered[i].snippet) + SNIPPET_OVERHEAD_TOKENS;
82
86
  }
83
87
  // Trim from the middle (indices 1..N-2) if over budget
84
88
  if (totalTokens > tokenBudget) {
85
89
  for (let i = ordered.length - 2; i >= 1; i--) {
86
90
  if (totalTokens <= tokenBudget)
87
91
  break;
88
- totalTokens -= approximateTokens(ordered[i].snippet) + 14;
92
+ totalTokens -= approximateTokens(ordered[i].snippet) + SNIPPET_OVERHEAD_TOKENS;
89
93
  keep[i] = false;
90
94
  }
91
95
  ordered = ordered.filter((_, i) => keep[i]);
@@ -109,7 +113,12 @@ export function buildHookOutput(selected, usedTokens, intent, gitCtx, detectedPr
109
113
  catch (err) {
110
114
  logger.debug("hooks-output", `injectContext recordRetrievalOrdered: ${errorMessage(err)}`);
111
115
  }
112
- parts.push(`[${getDocSourceKey(doc, phrenPathLocal)}] (${doc.type})`);
116
+ // `fb:` is the memory_feedback handle. The tool scores entryScoreKey
117
+ // (project/filename:digest) — NOT the mem: source key and NOT an fid —
118
+ // and this header was the only place the injection pipeline had the
119
+ // key in hand; before it was printed here, the feedback loop was
120
+ // built, wired into ranking, and unreachable.
121
+ parts.push(`[${getDocSourceKey(doc, phrenPathLocal)}] (${doc.type}) fb:${key}`);
113
122
  parts.push(annotateStale(snippet));
114
123
  parts.push("");
115
124
  }
package/dist/cli/hooks.js CHANGED
@@ -34,7 +34,7 @@ export { handleHookSessionStart, handleHookStop, handleBackgroundSync, handleHoo
34
34
  import { searchDocumentsAsync, applyTrustFilter, rankResults, selectSnippets, detectTaskIntent, } from "../shared/retrieval.js";
35
35
  import { buildHookOutput } from "./hooks-output.js";
36
36
  import { getGitContext, trackSessionMetrics, } from "./hooks-session.js";
37
- import { approximateTokens } from "../shared/retrieval.js";
37
+ import { approximateTokens, SNIPPET_OVERHEAD_TOKENS } from "../shared/retrieval.js";
38
38
  import { resolveRuntimeProfile } from "../runtime-profile.js";
39
39
  import { handleTaskPromptLifecycle } from "../task/lifecycle.js";
40
40
  // Auto-learn from prompts was removed — it learned conversational noise ("bro", "idk", typos)
@@ -206,7 +206,7 @@ export async function handleHookPrompt() {
206
206
  const kept = [];
207
207
  let runningTokens = 36;
208
208
  for (const s of sorted) {
209
- const est = approximateTokens(s.snippet) + 14;
209
+ const est = approximateTokens(s.snippet) + SNIPPET_OVERHEAD_TOKENS;
210
210
  if (runningTokens + est <= maxInjectTokens) {
211
211
  kept.push(s);
212
212
  runningTokens += est;
@@ -8,5 +8,13 @@ export interface EntryScore {
8
8
  export declare function flushEntryScores(phrenPath: string): void;
9
9
  export declare function entryScoreKey(project: string, filename: string, snippet: string): string;
10
10
  export declare function recordInjection(phrenPath: string, key: string, sessionId?: string): void;
11
- export declare function recordFeedback(phrenPath: string, key: string, feedback: "helpful" | "reprompt" | "regression", sessionId?: string): void;
11
+ /**
12
+ * Injected snippet headers label the score key as `fb:<key>` so an agent can
13
+ * see it. Callers are told to pass it without that prefix, but a model that
14
+ * copies the token verbatim would otherwise score a key no `entryScoreKey`
15
+ * can ever produce — an `ok: true` no-op, which is exactly the silent failure
16
+ * printing the key was meant to end. Accept both spellings.
17
+ */
18
+ export declare function normalizeFeedbackKey(key: string): string;
19
+ export declare function recordFeedback(phrenPath: string, rawKey: string, feedback: "helpful" | "reprompt" | "regression", sessionId?: string): void;
12
20
  export declare function getQualityMultiplier(phrenPath: string, key: string): number;
@@ -244,7 +244,18 @@ export function recordInjection(phrenPath, key, sessionId) {
244
244
  debugLog(`Usage log rotation failed: ${errorMessage(err)}`);
245
245
  }
246
246
  }
247
- export function recordFeedback(phrenPath, key, feedback, sessionId) {
247
+ /**
248
+ * Injected snippet headers label the score key as `fb:<key>` so an agent can
249
+ * see it. Callers are told to pass it without that prefix, but a model that
250
+ * copies the token verbatim would otherwise score a key no `entryScoreKey`
251
+ * can ever produce — an `ok: true` no-op, which is exactly the silent failure
252
+ * printing the key was meant to end. Accept both spellings.
253
+ */
254
+ export function normalizeFeedbackKey(key) {
255
+ return key.startsWith("fb:") ? key.slice(3) : key;
256
+ }
257
+ export function recordFeedback(phrenPath, rawKey, feedback, sessionId) {
258
+ const key = normalizeFeedbackKey(rawKey);
248
259
  const delta = {};
249
260
  if (feedback === "helpful")
250
261
  delta.helpful = 1;
@@ -38,8 +38,18 @@ function runSyncCommand(command, args) {
38
38
  }
39
39
  }
40
40
  function shouldUninstallCurrentGlobalPackage() {
41
- // Always attempt to remove the global package if it exists, regardless of
42
- // whether the uninstaller was invoked from the global install or a local repo.
41
+ // `npm uninstall -g` resolves against the machine's real npm prefix, which
42
+ // no amount of PHREN_PATH/HOME redirection sandboxes. A test that spawns
43
+ // `phren uninstall` against temp directories would therefore delete the
44
+ // developer's actual global install — it did, repeatedly, before this
45
+ // guard. The test helpers set this for every spawned CLI.
46
+ if (process.env.PHREN_SKIP_GLOBAL_NPM_UNINSTALL === "1") {
47
+ log(` Skipped global npm package removal (PHREN_SKIP_GLOBAL_NPM_UNINSTALL=1)`);
48
+ return false;
49
+ }
50
+ // Otherwise always attempt to remove the global package if it exists,
51
+ // regardless of whether the uninstaller was invoked from the global install
52
+ // or a local repo.
43
53
  const npmRootResult = runSyncCommand(getNpmCommand(), ["root", "-g"]);
44
54
  if (!npmRootResult.ok)
45
55
  return false;
@@ -23,6 +23,8 @@ export interface ProjectCard {
23
23
  name: string;
24
24
  summary: string;
25
25
  docs: string[];
26
+ /** Name of the non-primary store this project lives in, if any. */
27
+ store?: string;
26
28
  }
27
29
  export declare function resolveActiveProfile(phrenPath: string, requestedProfile?: string): PhrenResult<string | undefined>;
28
30
  export declare function getDefaultMachineAlias(): string;
@@ -306,22 +306,14 @@ function buildProjectCard(dir) {
306
306
  return { name, summary, docs };
307
307
  }
308
308
  export function listProjectCards(phrenPath, profile) {
309
- const dirs = getProjectDirs(phrenPath, profile).sort((a, b) => path.basename(a).localeCompare(path.basename(b)));
309
+ const dirs = getProjectDirs(phrenPath, profile);
310
310
  const cards = dirs.map(buildProjectCard);
311
311
  const seen = new Set(dirs.map((d) => path.basename(d)));
312
- // Include projects from team stores, filtered by active profile
312
+ // Team stores carry their own subscription list (StoreEntry.projects, applied
313
+ // by getStoreProjectDirs). The profile's project list scopes the *primary*
314
+ // store, so filtering team projects through it hid every one of them — a
315
+ // profile never names projects that live in someone else's store.
313
316
  try {
314
- // Resolve the profile's project allow-list (if any)
315
- let profileProjectNames;
316
- if (profile) {
317
- const profiles = listProfiles(phrenPath);
318
- if (profiles.ok) {
319
- const active = profiles.data.find((p) => p.name === profile);
320
- if (active && active.projects.length > 0) {
321
- profileProjectNames = new Set(active.projects);
322
- }
323
- }
324
- }
325
317
  for (const store of getNonPrimaryStores(phrenPath)) {
326
318
  if (!fs.existsSync(store.path))
327
319
  continue;
@@ -329,19 +321,23 @@ export function listProjectCards(phrenPath, profile) {
329
321
  const name = path.basename(dir);
330
322
  if (seen.has(name) || name === "global")
331
323
  continue;
332
- if (profileProjectNames && !profileProjectNames.has(name))
333
- continue;
334
324
  seen.add(name);
335
- cards.push(buildProjectCard(dir));
325
+ cards.push({ ...buildProjectCard(dir), store: store.name });
336
326
  }
337
327
  }
338
328
  }
339
329
  catch {
340
330
  // store-registry not available or error loading, continue with primary only
341
331
  }
342
- // Prepend global as a pinned entry so it's always accessible from the shell
332
+ cards.sort((a, b) => a.name.localeCompare(b.name));
333
+ // Prepend global as a pinned entry so it's always accessible from the shell.
334
+ // getProjectDirs already returns it whenever the profile names it, so drop
335
+ // that copy rather than listing global twice.
343
336
  const globalDir = path.join(phrenPath, "global");
344
337
  if (fs.existsSync(globalDir)) {
338
+ const listed = cards.findIndex((card) => card.name === "global");
339
+ if (listed >= 0)
340
+ cards.splice(listed, 1);
345
341
  cards.unshift(buildProjectCard(globalDir));
346
342
  }
347
343
  return cards;
@@ -1,5 +1,6 @@
1
1
  import { decodeStringRow } from "./index.js";
2
2
  import * as fs from "fs";
3
+ import * as path from "path";
3
4
  import { runtimeFile } from "../shared.js";
4
5
  import { logger } from "../logger.js";
5
6
  import { UNIVERSAL_TECH_TERMS_RE } from "../phren-core.js";
@@ -181,8 +182,12 @@ function readUserDefinedFragmentsFromDisk(claudeMdPath) {
181
182
  export function beginUserFragmentBuildCache(phrenPath, projects) {
182
183
  _activeBuildCacheKeyPrefix = `${phrenPath}/`;
183
184
  for (const project of projects) {
185
+ // The cache key stays a slash-joined string — it is only ever compared
186
+ // against other keys built the same way. The file path is a real path, so
187
+ // it goes through path.join: concatenating with "/" reads fine on Windows
188
+ // but produces a mixed-separator string that no other code path matches.
184
189
  const cacheKey = `${phrenPath}/${project}`;
185
- const claudeMdPath = `${phrenPath}/${project}/CLAUDE.md`;
190
+ const claudeMdPath = path.join(phrenPath, project, "CLAUDE.md");
186
191
  try {
187
192
  const loaded = readUserDefinedFragmentsFromDisk(claudeMdPath);
188
193
  if (!loaded) {
@@ -209,7 +214,7 @@ export function endUserFragmentBuildCache(phrenPath) {
209
214
  _activeBuildCacheKeyPrefix = null;
210
215
  }
211
216
  function parseUserDefinedFragments(phrenPath, project) {
212
- const claudeMdPath = `${phrenPath}/${project}/CLAUDE.md`;
217
+ const claudeMdPath = path.join(phrenPath, project, "CLAUDE.md");
213
218
  const cacheKey = `${phrenPath}/${project}`;
214
219
  try {
215
220
  // Active build path: no sync I/O in per-file extraction.
@@ -2,6 +2,16 @@ import { type RetentionPolicy } from "./governance.js";
2
2
  import { type DocRow, type SqlJsDatabase } from "./index.js";
3
3
  import type { GitContext } from "../cli/hooks-session.js";
4
4
  export type { GitContext } from "../cli/hooks-session.js";
5
+ /**
6
+ * Per-snippet overhead charged against the token budget: the header line
7
+ * (`[<source key>] (<type>) fb:<score key>`) plus its blank separator.
8
+ *
9
+ * Selection and rendering MUST charge the same amount. When they drifted
10
+ * apart, `selectSnippets` admitted a snippet on one estimate and
11
+ * `buildHookOutput` re-checked it against a larger one, silently dropping a
12
+ * middle snippet that legitimately fit.
13
+ */
14
+ export declare const SNIPPET_OVERHEAD_TOKENS = 24;
5
15
  export declare function detectTaskIntent(prompt: string): "debug" | "review" | "build" | "docs" | "skill" | "general";
6
16
  export declare function fileRelevanceBoost(filePath: string, changedFiles: Set<string>): number;
7
17
  export declare function branchMatchBoost(content: string, branch: string | undefined): number;
@@ -27,6 +27,16 @@ const WEAK_CROSS_PROJECT_OVERLAP_MAX = 0.18;
27
27
  const WEAK_CROSS_PROJECT_OVERLAP_PENALTY = 0.75;
28
28
  const LOW_FOCUS_SNIPPET_SCORE = 0.3;
29
29
  const VERY_LOW_FOCUS_SNIPPET_SCORE = 0.14;
30
+ /**
31
+ * Per-snippet overhead charged against the token budget: the header line
32
+ * (`[<source key>] (<type>) fb:<score key>`) plus its blank separator.
33
+ *
34
+ * Selection and rendering MUST charge the same amount. When they drifted
35
+ * apart, `selectSnippets` admitted a snippet on one estimate and
36
+ * `buildHookOutput` re-checked it against a larger one, silently dropping a
37
+ * middle snippet that legitimately fit.
38
+ */
39
+ export const SNIPPET_OVERHEAD_TOKENS = 24;
30
40
  const LOW_FOCUS_SNIPPET_LINE_CAP = 3;
31
41
  const LOW_FOCUS_SNIPPET_CHAR_FRACTION = 0.55;
32
42
  const TASK_RESCUE_MIN_OVERLAP = 0.3;
@@ -555,7 +565,10 @@ export async function searchFederatedStores(localPhrenPath, options) {
555
565
  return allRows;
556
566
  }
557
567
  // ── Trust filter ─────────────────────────────────────────────────────────────
558
- const TRUST_FILTERED_TYPES = new Set(["findings", "reference", "knowledge"]);
568
+ // "knowledge" was a doc type until the 0.0.x renames; classifyFile can no
569
+ // longer produce it, so listing it here was dead weight that made the set
570
+ // read as broader than it is.
571
+ const TRUST_FILTERED_TYPES = new Set(["findings", "reference"]);
559
572
  /**
560
573
  * Doc types that must never be pushed into an agent's prompt automatically.
561
574
  *
@@ -883,7 +896,7 @@ export function selectSnippets(rows, keywords, tokenBudget, lineBudget, charBudg
883
896
  ? overlapScore(queryTokens, `${doc.filename}\n${snippet}`)
884
897
  : focusScore;
885
898
  }
886
- let est = approximateTokens(snippet) + 14;
899
+ let est = approximateTokens(snippet) + SNIPPET_OVERHEAD_TOKENS;
887
900
  if (selected.length > 0 && focusScore < VERY_LOW_FOCUS_SNIPPET_SCORE && usedTokens + est > Math.floor(tokenBudget * 0.8)) {
888
901
  continue;
889
902
  }
@@ -891,7 +904,7 @@ export function selectSnippets(rows, keywords, tokenBudget, lineBudget, charBudg
891
904
  break;
892
905
  if (selected.length === 0 && usedTokens + est > tokenBudget) {
893
906
  snippet = compactSnippet(snippet, 3, Math.floor(charBudget * 0.55));
894
- est = approximateTokens(snippet) + 14;
907
+ est = approximateTokens(snippet) + SNIPPET_OVERHEAD_TOKENS;
895
908
  }
896
909
  const key = entryScoreKey(doc.project, doc.filename, doc.content);
897
910
  selected.push({ doc, snippet, key });
@@ -903,7 +916,7 @@ export function selectSnippets(rows, keywords, tokenBudget, lineBudget, charBudg
903
916
  // rounding / compaction producing more tokens than estimated during selection)
904
917
  while (selected.length > 1 && usedTokens > tokenBudget) {
905
918
  const removed = selected.pop();
906
- usedTokens -= approximateTokens(removed.snippet) + 14;
919
+ usedTokens -= approximateTokens(removed.snippet) + SNIPPET_OVERHEAD_TOKENS;
907
920
  }
908
921
  return { selected, usedTokens };
909
922
  }
@@ -13,6 +13,14 @@ interface StartupIntroPlan {
13
13
  dwellMs: number;
14
14
  markSeen: boolean;
15
15
  }
16
+ /**
17
+ * The intro used to attach its own stdin listener while the shell's key handler
18
+ * was already live, so the keypress that dismissed the splash was *also* fed to
19
+ * the shell (pressing "q" at the splash quit phren outright) and the intro's
20
+ * animation frames raced the first dashboard repaint. Key delivery is now owned
21
+ * by startShell, which hands the intro a one-shot waiter that consumes the key.
22
+ */
23
+ export type KeypressWaiter = () => Promise<void>;
16
24
  export declare function resolveStartupIntroPlan(phrenPath: string, version?: string): StartupIntroPlan;
17
25
  export declare function startLiveStatePoller({ phrenPath, shell, repaint, isExiting, intervalMs, computeToken, }: {
18
26
  phrenPath: string;