@phren/cli 0.1.41 → 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 (63) 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/actions.js +1 -13
  6. package/dist/cli/extract.js +3 -2
  7. package/dist/cli/hooks-output.js +15 -6
  8. package/dist/cli/hooks.js +2 -2
  9. package/dist/cli/namespaces-utils.js +1 -1
  10. package/dist/content/archive.js +3 -2
  11. package/dist/content/dedup.js +4 -3
  12. package/dist/content/learning.js +5 -4
  13. package/dist/content/secrets.js +4 -1
  14. package/dist/data/access.js +10 -9
  15. package/dist/data/tasks.js +46 -6
  16. package/dist/finding/lifecycle.js +3 -2
  17. package/dist/governance/policy.js +4 -3
  18. package/dist/governance/scores.d.ts +9 -1
  19. package/dist/governance/scores.js +12 -1
  20. package/dist/init/init-uninstall.js +12 -2
  21. package/dist/profile-store.d.ts +2 -0
  22. package/dist/profile-store.js +13 -17
  23. package/dist/project-config.js +3 -2
  24. package/dist/project-topics.js +13 -12
  25. package/dist/shared/data-utils.js +13 -3
  26. package/dist/shared/fragment-graph.js +7 -2
  27. package/dist/shared/retrieval.d.ts +10 -0
  28. package/dist/shared/retrieval.js +17 -4
  29. package/dist/shell/entry.d.ts +8 -0
  30. package/dist/shell/entry.js +114 -58
  31. package/dist/shell/input.d.ts +1 -1
  32. package/dist/shell/input.js +4 -1
  33. package/dist/shell/keys.d.ts +36 -0
  34. package/dist/shell/keys.js +107 -0
  35. package/dist/shell/render.d.ts +33 -0
  36. package/dist/shell/render.js +216 -46
  37. package/dist/shell/shell.js +16 -3
  38. package/dist/shell/view.js +2 -1
  39. package/dist/store-registry.d.ts +13 -0
  40. package/dist/store-registry.js +106 -34
  41. package/dist/store-routing.d.ts +8 -0
  42. package/dist/store-routing.js +23 -1
  43. package/dist/tools/config.js +4 -3
  44. package/dist/tools/extract-facts.js +3 -2
  45. package/dist/tools/finding.js +6 -5
  46. package/dist/tools/memory.js +12 -5
  47. package/dist/tools/ops.js +1 -1
  48. package/dist/ui/server.js +2 -6
  49. package/dist/utils-fts.js +3 -2
  50. package/dist/utils-paths.d.ts +1 -0
  51. package/dist/utils-paths.js +1 -1
  52. package/dist/utils.d.ts +1 -1
  53. package/dist/utils.js +1 -1
  54. package/package.json +31 -4
  55. package/starter/global/skills/phren-consolidate/SKILL.md +152 -0
  56. package/starter/global/skills/phren-discover/SKILL.md +175 -0
  57. package/starter/global/skills/phren-init/SKILL.md +216 -0
  58. package/starter/global/skills/phren-profiles/SKILL.md +121 -0
  59. package/starter/global/skills/phren-sync/SKILL.md +261 -0
  60. package/dist/init-uninstall.d.ts +0 -3
  61. package/dist/init-uninstall.js +0 -514
  62. package/dist/init-walkthrough.d.ts +0 -55
  63. package/dist/init-walkthrough.js +0 -524
@@ -3,7 +3,8 @@ import * as fs from "fs";
3
3
  import * as path from "path";
4
4
  import { appendAuditLog, debugLog, getProjectDirs, isRecord, runtimeDir, runtimeHealthFile, withDefaults, phrenErr, PhrenError, phrenOk, resolveFindingsPath } from "../shared.js";
5
5
  import { withFileLock, isFiniteNumber, hasValidSchemaVersion } from "../shared/governance.js";
6
- import { errorMessage, isValidProjectName, safeProjectPath } from "../utils.js";
6
+ import { errorMessage, isValidProjectName } from "../utils.js";
7
+ import { storeAwareProjectPath } from "../store-routing.js";
7
8
  import { readProjectConfig } from "../project-config.js";
8
9
  import { getActiveProfileDefaults } from "../profile-store.js";
9
10
  import { runCustomHooks } from "../hooks.js";
@@ -666,7 +667,7 @@ function queueDedupKey(line) {
666
667
  export function appendReviewQueue(phrenPath, project, section, entries) {
667
668
  if (!isValidProjectName(project))
668
669
  return phrenErr(`Invalid project name: "${project}".`, PhrenError.INVALID_PROJECT_NAME);
669
- const resolvedDir = safeProjectPath(phrenPath, project);
670
+ const resolvedDir = storeAwareProjectPath(phrenPath, project);
670
671
  if (!resolvedDir || !fs.existsSync(resolvedDir))
671
672
  return phrenErr(`Project "${project}" not found in phren.`, PhrenError.PROJECT_NOT_FOUND);
672
673
  const queuePath = path.join(resolvedDir, "review.md");
@@ -815,7 +816,7 @@ export function pruneDeadMemories(phrenPath, project, dryRun) {
815
816
  return phrenErr(`Invalid project name: "${project}".`, PhrenError.INVALID_PROJECT_NAME);
816
817
  const dirs = project
817
818
  ? (() => {
818
- const resolvedProject = safeProjectPath(phrenPath, project);
819
+ const resolvedProject = storeAwareProjectPath(phrenPath, project);
819
820
  return resolvedProject ? [resolvedProject] : [];
820
821
  })()
821
822
  : getProjectDirs(phrenPath).filter((dir) => path.basename(dir) !== "global");
@@ -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;
@@ -4,7 +4,8 @@ import * as path from "path";
4
4
  import * as yaml from "js-yaml";
5
5
  import { readInstallPreferences } from "./init/preferences.js";
6
6
  import { debugLog } from "./shared.js";
7
- import { errorMessage, safeProjectPath } from "./utils.js";
7
+ import { errorMessage } from "./utils.js";
8
+ import { storeAwareProjectPath } from "./store-routing.js";
8
9
  import { withFileLock } from "./shared/governance.js";
9
10
  export const PROJECT_OWNERSHIP_MODES = ["phren-managed", "detached", "repo-managed"];
10
11
  export const PROJECT_HOOK_EVENTS = ["UserPromptSubmit", "Stop", "SessionStart", "PostToolUse"];
@@ -25,7 +26,7 @@ export function projectConfigPath(phrenPath, project) {
25
26
  return path.join(phrenPath, project, "phren.project.yaml");
26
27
  }
27
28
  function resolveProjectConfigPath(phrenPath, project) {
28
- return safeProjectPath(phrenPath, project, "phren.project.yaml");
29
+ return storeAwareProjectPath(phrenPath, project, "phren.project.yaml");
29
30
  }
30
31
  function writeProjectConfigFile(configPath, next) {
31
32
  fs.mkdirSync(path.dirname(configPath), { recursive: true });
@@ -3,7 +3,8 @@ import * as fs from "fs";
3
3
  import * as path from "path";
4
4
  import { debugLog } from "./shared.js";
5
5
  import { withFileLock } from "./shared/governance.js";
6
- import { STOP_WORDS, errorMessage, extractKeywords, isValidProjectName, safeProjectPath } from "./utils.js";
6
+ import { STOP_WORDS, errorMessage, extractKeywords, isValidProjectName } from "./utils.js";
7
+ import { storeAwareProjectPath } from "./store-routing.js";
7
8
  import { walkDirectory } from "./shared/data-utils.js";
8
9
  import { FINDINGS_FILENAME } from "./data/access.js";
9
10
  const TOPIC_CONFIG_FILENAME = "topic-config.json";
@@ -381,16 +382,16 @@ function ensureGeneralTopic(topics) {
381
382
  return [...topics, { ...GENERAL_TOPIC, keywords: [...GENERAL_TOPIC.keywords] }];
382
383
  }
383
384
  function topicConfigPath(phrenPath, project) {
384
- return safeProjectPath(phrenPath, project, TOPIC_CONFIG_FILENAME);
385
+ return storeAwareProjectPath(phrenPath, project, TOPIC_CONFIG_FILENAME);
385
386
  }
386
387
  function projectDirPath(phrenPath, project) {
387
- return safeProjectPath(phrenPath, project);
388
+ return storeAwareProjectPath(phrenPath, project);
388
389
  }
389
390
  function topicReferenceRelativePath(slug) {
390
391
  return path.posix.join("reference", "topics", `${slug}.md`);
391
392
  }
392
393
  export function topicReferencePath(phrenPath, project, slug) {
393
- return safeProjectPath(phrenPath, project, "reference", "topics", `${normalizeTopicSlug(slug)}.md`);
394
+ return storeAwareProjectPath(phrenPath, project, "reference", "topics", `${normalizeTopicSlug(slug)}.md`);
394
395
  }
395
396
  function readJsonFile(filePath) {
396
397
  try {
@@ -412,14 +413,14 @@ function countByTerm(terms) {
412
413
  function readTopicInputContent(phrenPath, project) {
413
414
  const parts = [];
414
415
  for (const file of ["CLAUDE.md", FINDINGS_FILENAME]) {
415
- const filePath = safeProjectPath(phrenPath, project, file);
416
+ const filePath = storeAwareProjectPath(phrenPath, project, file);
416
417
  if (!filePath || !fs.existsSync(filePath))
417
418
  continue;
418
419
  const content = fs.readFileSync(filePath, "utf8").trim();
419
420
  if (content)
420
421
  parts.push(content);
421
422
  }
422
- const referenceDir = safeProjectPath(phrenPath, project, "reference");
423
+ const referenceDir = storeAwareProjectPath(phrenPath, project, "reference");
423
424
  if (referenceDir && fs.existsSync(referenceDir)) {
424
425
  for (const filePath of readReferenceMarkdownFiles(referenceDir)) {
425
426
  try {
@@ -834,7 +835,7 @@ export function listProjectReferenceDocs(phrenPath, project, topics) {
834
835
  if (!projectDir)
835
836
  return { topicDocs: [], otherDocs: [] };
836
837
  const topicDocs = listProjectTopicDocs(phrenPath, project, topics);
837
- const referenceDir = safeProjectPath(phrenPath, project, "reference");
838
+ const referenceDir = storeAwareProjectPath(phrenPath, project, "reference");
838
839
  if (!referenceDir || !fs.existsSync(referenceDir))
839
840
  return { topicDocs, otherDocs: [] };
840
841
  const otherDocs = [];
@@ -857,7 +858,7 @@ export function listProjectReferenceDocs(phrenPath, project, topics) {
857
858
  }
858
859
  function listLegacyTopicDocs(phrenPath, project) {
859
860
  const projectDir = projectDirPath(phrenPath, project);
860
- const referenceDir = safeProjectPath(phrenPath, project, "reference");
861
+ const referenceDir = storeAwareProjectPath(phrenPath, project, "reference");
861
862
  if (!projectDir || !referenceDir || !fs.existsSync(referenceDir))
862
863
  return [];
863
864
  const files = fs.readdirSync(referenceDir, { withFileTypes: true })
@@ -898,7 +899,7 @@ function tokenizeSuggestionTerms(text) {
898
899
  function collectSuggestionCorpus(phrenPath, project) {
899
900
  const parts = [];
900
901
  for (const file of ["CLAUDE.md", "summary.md", FINDINGS_FILENAME]) {
901
- const filePath = safeProjectPath(phrenPath, project, file);
902
+ const filePath = storeAwareProjectPath(phrenPath, project, file);
902
903
  if (!filePath || !fs.existsSync(filePath))
903
904
  continue;
904
905
  const content = fs.readFileSync(filePath, "utf8");
@@ -1030,10 +1031,10 @@ function resolveReferenceContentPath(phrenPath, project, file) {
1030
1031
  return null;
1031
1032
  if (!file.endsWith(".md"))
1032
1033
  return null;
1033
- const filePath = safeProjectPath(phrenPath, project, file);
1034
+ const filePath = storeAwareProjectPath(phrenPath, project, file);
1034
1035
  if (!filePath)
1035
1036
  return null;
1036
- const referenceRoot = safeProjectPath(phrenPath, project, "reference");
1037
+ const referenceRoot = storeAwareProjectPath(phrenPath, project, "reference");
1037
1038
  if (!referenceRoot)
1038
1039
  return null;
1039
1040
  const normalizedRoot = referenceRoot + path.sep;
@@ -1051,7 +1052,7 @@ export function readReferenceContent(phrenPath, project, file) {
1051
1052
  }
1052
1053
  export function reclassifyLegacyTopicDocs(phrenPath, project) {
1053
1054
  const { topics } = readProjectTopics(phrenPath, project);
1054
- const referenceDir = safeProjectPath(phrenPath, project, "reference");
1055
+ const referenceDir = storeAwareProjectPath(phrenPath, project, "reference");
1055
1056
  if (!referenceDir || !fs.existsSync(referenceDir))
1056
1057
  return { movedFiles: 0, movedEntries: 0, skipped: [] };
1057
1058
  const skipped = [];
@@ -1,8 +1,9 @@
1
1
  import * as fs from "fs";
2
2
  import * as path from "path";
3
- import { phrenErr, PhrenError, phrenOk, } from "../shared.js";
3
+ import { phrenErr, PhrenError, phrenOk, parsePhrenErrorCode, } from "../shared.js";
4
4
  import { withFileLock as withFileLockRaw } from "./governance.js";
5
5
  import { isValidProjectName, safeProjectPath, errorMessage } from "../utils.js";
6
+ import { resolveProject } from "../store-routing.js";
6
7
  export function withSafeLock(filePath, fn) {
7
8
  try {
8
9
  return withFileLockRaw(filePath, fn);
@@ -46,8 +47,17 @@ export function ensureProject(phrenPath, project) {
46
47
  const dir = safeProjectPath(phrenPath, project);
47
48
  if (!dir)
48
49
  return phrenErr(`Project name "${project}" is not valid. Use lowercase letters, numbers, and hyphens (e.g. "my-project").`, PhrenError.INVALID_PROJECT_NAME);
49
- if (!fs.existsSync(dir)) {
50
+ if (fs.existsSync(dir))
51
+ return phrenOk(dir);
52
+ // Not in the primary store — the project may live in a registered secondary store.
53
+ try {
54
+ return phrenOk(resolveProject(phrenPath, project).projectDir);
55
+ }
56
+ catch (err) {
57
+ const msg = errorMessage(err);
58
+ if (parsePhrenErrorCode(msg) === PhrenError.VALIDATION_ERROR) {
59
+ return phrenErr(msg.replace(/^[A-Z_]+:\s*/, ""), PhrenError.VALIDATION_ERROR);
60
+ }
50
61
  return phrenErr(`No project "${project}" found. Add it with 'cd ~/your-project && phren add'.`, PhrenError.PROJECT_NOT_FOUND);
51
62
  }
52
- return phrenOk(dir);
53
63
  }
@@ -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;