@phren/cli 0.2.14 → 0.2.16

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 (387) hide show
  1. package/README.md +2 -2
  2. package/dist/agent-instructions.d.ts +12 -0
  3. package/dist/agent-instructions.js +52 -0
  4. package/dist/bridge/agent-hook-stores.d.ts +32 -0
  5. package/dist/bridge/agent-hook-stores.js +67 -0
  6. package/dist/bridge/agent-hooks.d.ts +193 -2
  7. package/dist/bridge/agent-hooks.js +1045 -38
  8. package/dist/bridge/canary.d.ts +27 -0
  9. package/dist/bridge/canary.js +189 -0
  10. package/dist/bridge/changes.d.ts +57 -0
  11. package/dist/bridge/changes.js +403 -0
  12. package/dist/bridge/client.d.ts +3 -0
  13. package/dist/bridge/client.js +36 -0
  14. package/dist/bridge/code-note.d.ts +22 -0
  15. package/dist/bridge/code-note.js +42 -0
  16. package/dist/bridge/code-routes.d.ts +133 -0
  17. package/dist/bridge/code-routes.js +319 -0
  18. package/dist/bridge/codex-threads.d.ts +27 -0
  19. package/dist/bridge/codex-threads.js +442 -0
  20. package/dist/bridge/command.d.ts +7 -0
  21. package/dist/bridge/command.js +50 -5
  22. package/dist/bridge/computer-names.d.ts +4 -0
  23. package/dist/bridge/computer-names.js +16 -0
  24. package/dist/bridge/computers.d.ts +9 -0
  25. package/dist/bridge/computers.js +111 -0
  26. package/dist/bridge/context.d.ts +14 -0
  27. package/dist/bridge/context.js +149 -0
  28. package/dist/bridge/dispatch-command.d.ts +3 -0
  29. package/dist/bridge/dispatch-command.js +93 -0
  30. package/dist/bridge/dispatch-hosts.d.ts +23 -0
  31. package/dist/bridge/dispatch-hosts.js +25 -0
  32. package/dist/bridge/dispatch-returns.d.ts +123 -0
  33. package/dist/bridge/dispatch-returns.js +279 -0
  34. package/dist/bridge/dispatch-tree.d.ts +54 -0
  35. package/dist/bridge/dispatch-tree.js +198 -0
  36. package/dist/bridge/dispatch.d.ts +207 -0
  37. package/dist/bridge/dispatch.js +261 -0
  38. package/dist/bridge/enroll.d.ts +31 -0
  39. package/dist/bridge/enroll.js +236 -0
  40. package/dist/bridge/fanout-messages.d.ts +74 -0
  41. package/dist/bridge/fanout-messages.js +230 -0
  42. package/dist/bridge/fanouts.d.ts +160 -0
  43. package/dist/bridge/fanouts.js +702 -0
  44. package/dist/bridge/file-range.d.ts +16 -0
  45. package/dist/bridge/file-range.js +90 -0
  46. package/dist/bridge/files.d.ts +20 -0
  47. package/dist/bridge/files.js +54 -0
  48. package/dist/bridge/git-publish.d.ts +23 -0
  49. package/dist/bridge/git-publish.js +145 -0
  50. package/dist/bridge/git-worktrees.d.ts +21 -0
  51. package/dist/bridge/git-worktrees.js +150 -0
  52. package/dist/bridge/git.d.ts +54 -0
  53. package/dist/bridge/git.js +552 -0
  54. package/dist/bridge/grants.d.ts +31 -0
  55. package/dist/bridge/grants.js +181 -0
  56. package/dist/bridge/hand-off.d.ts +79 -0
  57. package/dist/bridge/hand-off.js +151 -0
  58. package/dist/bridge/health.d.ts +128 -0
  59. package/dist/bridge/health.js +260 -0
  60. package/dist/bridge/herdr.d.ts +79 -6
  61. package/dist/bridge/herdr.js +292 -27
  62. package/dist/bridge/hook-main.js +2 -0
  63. package/dist/bridge/install.d.ts +32 -1
  64. package/dist/bridge/install.js +225 -38
  65. package/dist/bridge/launch-worktree.d.ts +21 -0
  66. package/dist/bridge/launch-worktree.js +70 -0
  67. package/dist/bridge/limits.d.ts +20 -0
  68. package/dist/bridge/limits.js +65 -0
  69. package/dist/bridge/locate.d.ts +16 -0
  70. package/dist/bridge/locate.js +75 -0
  71. package/dist/bridge/metrics.d.ts +29 -0
  72. package/dist/bridge/metrics.js +71 -0
  73. package/dist/bridge/model-switch.d.ts +35 -0
  74. package/dist/bridge/model-switch.js +250 -0
  75. package/dist/bridge/models.d.ts +46 -0
  76. package/dist/bridge/models.js +257 -0
  77. package/dist/bridge/opencode-approvals.d.ts +6 -0
  78. package/dist/bridge/opencode-approvals.js +60 -0
  79. package/dist/bridge/pane-text.d.ts +15 -0
  80. package/dist/bridge/pane-text.js +23 -0
  81. package/dist/bridge/peers.d.ts +27 -0
  82. package/dist/bridge/peers.js +130 -0
  83. package/dist/bridge/projects.d.ts +12 -1
  84. package/dist/bridge/projects.js +268 -20
  85. package/dist/bridge/protocol.d.ts +35 -2
  86. package/dist/bridge/protocol.js +42 -7
  87. package/dist/bridge/push.d.ts +83 -0
  88. package/dist/bridge/push.js +199 -0
  89. package/dist/bridge/questions.d.ts +38 -0
  90. package/dist/bridge/questions.js +205 -0
  91. package/dist/bridge/schedule-format.d.ts +103 -0
  92. package/dist/bridge/schedule-format.js +266 -0
  93. package/dist/bridge/schedule-launch.d.ts +11 -0
  94. package/dist/bridge/schedule-launch.js +169 -0
  95. package/dist/bridge/schedule-watch.d.ts +52 -0
  96. package/dist/bridge/schedule-watch.js +242 -0
  97. package/dist/bridge/schedules.d.ts +48 -0
  98. package/dist/bridge/schedules.js +205 -0
  99. package/dist/bridge/server-launch.d.ts +14 -0
  100. package/dist/bridge/server-launch.js +218 -0
  101. package/dist/bridge/server-overview.d.ts +45 -0
  102. package/dist/bridge/server-overview.js +102 -0
  103. package/dist/bridge/server-pane-routes.d.ts +29 -0
  104. package/dist/bridge/server-pane-routes.js +400 -0
  105. package/dist/bridge/server-routes.d.ts +106 -0
  106. package/dist/bridge/server-routes.js +538 -0
  107. package/dist/bridge/server-stream.d.ts +46 -0
  108. package/dist/bridge/server-stream.js +253 -0
  109. package/dist/bridge/server.d.ts +3 -15
  110. package/dist/bridge/server.js +162 -264
  111. package/dist/bridge/session-servers.d.ts +24 -0
  112. package/dist/bridge/session-servers.js +136 -0
  113. package/dist/bridge/side-questions.d.ts +74 -0
  114. package/dist/bridge/side-questions.js +252 -0
  115. package/dist/bridge/simulators.d.ts +28 -0
  116. package/dist/bridge/simulators.js +198 -0
  117. package/dist/bridge/speech-transcribe.d.ts +24 -0
  118. package/dist/bridge/speech-transcribe.js +124 -0
  119. package/dist/bridge/speech.d.ts +35 -0
  120. package/dist/bridge/speech.js +98 -0
  121. package/dist/bridge/steps.d.ts +13 -0
  122. package/dist/bridge/steps.js +222 -0
  123. package/dist/bridge/tab-activity.d.ts +18 -0
  124. package/dist/bridge/tab-activity.js +99 -0
  125. package/dist/bridge/terminal-choice.d.ts +64 -0
  126. package/dist/bridge/terminal-choice.js +281 -0
  127. package/dist/bridge/transcript-claude.d.ts +22 -0
  128. package/dist/bridge/transcript-claude.js +353 -0
  129. package/dist/bridge/transcript-codex.d.ts +30 -0
  130. package/dist/bridge/transcript-codex.js +282 -0
  131. package/dist/bridge/transcript-copilot.d.ts +4 -0
  132. package/dist/bridge/transcript-copilot.js +14 -0
  133. package/dist/bridge/transcript-opencode.d.ts +5 -0
  134. package/dist/bridge/transcript-opencode.js +26 -0
  135. package/dist/bridge/transcript-preview.d.ts +94 -0
  136. package/dist/bridge/transcript-preview.js +476 -0
  137. package/dist/bridge/transcripts.d.ts +81 -4
  138. package/dist/bridge/transcripts.js +332 -67
  139. package/dist/bridge/transport.d.ts +3 -0
  140. package/dist/bridge/transport.js +96 -15
  141. package/dist/bridge/uploads.d.ts +15 -0
  142. package/dist/bridge/uploads.js +44 -2
  143. package/dist/bridge/usage.d.ts +124 -0
  144. package/dist/bridge/usage.js +859 -0
  145. package/dist/bridge-hook.mjs +41246 -21385
  146. package/dist/cli/actions.js +14 -1
  147. package/dist/cli/config-proactivity.d.ts +3 -1
  148. package/dist/cli/config-proactivity.js +35 -3
  149. package/dist/cli/config.js +4 -1
  150. package/dist/cli/extract.js +3 -6
  151. package/dist/cli/govern.js +5 -2
  152. package/dist/cli/hooks-globs.js +1 -1
  153. package/dist/cli/hooks.d.ts +1 -1
  154. package/dist/cli/hooks.js +9 -7
  155. package/dist/cli/namespaces-projects.js +12 -6
  156. package/dist/cli/namespaces-store.js +37 -6
  157. package/dist/cli/namespaces-tasks.js +1 -1
  158. package/dist/cli/schedules.d.ts +1 -0
  159. package/dist/cli/schedules.js +164 -0
  160. package/dist/cli/session-background.js +1 -1
  161. package/dist/cli/session-git.d.ts +8 -5
  162. package/dist/cli/session-git.js +45 -120
  163. package/dist/cli/session-start.js +3 -1
  164. package/dist/cli/session-stop.js +19 -8
  165. package/dist/cli/team.js +13 -10
  166. package/dist/cli-handlers.d.ts +1 -1
  167. package/dist/cli-handlers.js +8 -4
  168. package/dist/cli-help.d.ts +5 -4
  169. package/dist/cli-help.js +15 -15
  170. package/dist/cli-registry.d.ts +4 -1
  171. package/dist/cli-registry.js +119 -6
  172. package/dist/content/archive.js +2 -2
  173. package/dist/content/citation.d.ts +11 -0
  174. package/dist/content/citation.js +18 -0
  175. package/dist/content/learning.js +2 -0
  176. package/dist/content/summarize.d.ts +14 -15
  177. package/dist/content/summarize.js +60 -5
  178. package/dist/content/validate.d.ts +3 -1
  179. package/dist/content/validate.js +26 -8
  180. package/dist/core/project-registry.d.ts +26 -0
  181. package/dist/core/project-registry.js +573 -0
  182. package/dist/core/project.js +2 -3
  183. package/dist/data/access.d.ts +7 -1
  184. package/dist/data/access.js +13 -3
  185. package/dist/data/tasks.d.ts +18 -3
  186. package/dist/data/tasks.js +8 -7
  187. package/dist/entrypoint.js +44 -10
  188. package/dist/fanout/adapters/claude.d.ts +2 -0
  189. package/dist/fanout/adapters/claude.js +7 -0
  190. package/dist/fanout/adapters/codex.d.ts +2 -0
  191. package/dist/fanout/adapters/codex.js +9 -0
  192. package/dist/fanout/adapters/opencode.d.ts +4 -0
  193. package/dist/fanout/adapters/opencode.js +9 -0
  194. package/dist/fanout/adapters/types.d.ts +21 -0
  195. package/dist/fanout/adapters/types.js +3 -0
  196. package/dist/fanout/command.d.ts +2 -0
  197. package/dist/fanout/command.js +78 -0
  198. package/dist/fanout/launcher.d.ts +27 -0
  199. package/dist/fanout/launcher.js +156 -0
  200. package/dist/fanout/opencode-serve.d.ts +24 -0
  201. package/dist/fanout/opencode-serve.js +191 -0
  202. package/dist/fanout/picker.d.ts +91 -0
  203. package/dist/fanout/picker.js +51 -0
  204. package/dist/fanout/usage.d.ts +5 -0
  205. package/dist/fanout/usage.js +51 -0
  206. package/dist/fanout/watchdog.d.ts +10 -0
  207. package/dist/fanout/watchdog.js +27 -0
  208. package/dist/filenames.d.ts +9 -0
  209. package/dist/filenames.js +11 -0
  210. package/dist/finding/context.js +4 -22
  211. package/dist/generated/memory-ui-graph.browser.js +279 -283
  212. package/dist/governance/policy-constants.d.ts +11 -0
  213. package/dist/governance/policy-constants.js +9 -0
  214. package/dist/governance/policy.d.ts +5 -8
  215. package/dist/governance/policy.js +7 -5
  216. package/dist/graph-core/camera.d.ts +24 -0
  217. package/dist/graph-core/camera.js +18 -0
  218. package/dist/graph-core/index.d.ts +2 -0
  219. package/dist/graph-core/index.js +2 -0
  220. package/dist/graph-core/labels.d.ts +77 -0
  221. package/dist/graph-core/labels.js +124 -0
  222. package/dist/graph-core/model.d.ts +13 -0
  223. package/dist/graph-core/model.js +33 -0
  224. package/dist/graph-core/types.d.ts +2 -0
  225. package/dist/home-paths.d.ts +7 -0
  226. package/dist/home-paths.js +21 -0
  227. package/dist/hooks.d.ts +3 -0
  228. package/dist/hooks.js +13 -0
  229. package/dist/index.js +24 -2
  230. package/dist/init/guard-globals.d.ts +1 -1
  231. package/dist/init/guard-globals.js +4 -4
  232. package/dist/init/init-configure.js +3 -3
  233. package/dist/init/init-uninstall.js +2 -2
  234. package/dist/init/init-walkthrough.d.ts +2 -0
  235. package/dist/init/init-walkthrough.js +17 -6
  236. package/dist/init/init.js +26 -6
  237. package/dist/init/management-preset.d.ts +1 -1
  238. package/dist/init/management-preset.js +2 -2
  239. package/dist/init/preferences.js +1 -1
  240. package/dist/init/self-wiring.js +1 -1
  241. package/dist/init/setup.d.ts +3 -26
  242. package/dist/init/setup.js +49 -588
  243. package/dist/init/shared.js +2 -0
  244. package/dist/init/store-gitignore.d.ts +1 -1
  245. package/dist/init/store-gitignore.js +2 -0
  246. package/dist/init/teardown.d.ts +1 -1
  247. package/dist/init/teardown.js +2 -2
  248. package/dist/link/context.js +1 -1
  249. package/dist/link/doctor.d.ts +22 -1
  250. package/dist/link/doctor.js +100 -54
  251. package/dist/link/link.js +29 -61
  252. package/dist/link/refresh.js +2 -2
  253. package/dist/link/skills.js +26 -5
  254. package/dist/machine-identity.d.ts +3 -0
  255. package/dist/machine-identity.js +6 -0
  256. package/dist/mcp/profile.d.ts +2 -15
  257. package/dist/mcp/profile.js +64 -9
  258. package/dist/memory-ui-graph.runtime.js +279 -283
  259. package/dist/modules/code-package.d.ts +16 -0
  260. package/dist/modules/code-package.js +152 -0
  261. package/dist/modules/command.d.ts +2 -0
  262. package/dist/modules/command.js +67 -0
  263. package/dist/modules/config.d.ts +4 -0
  264. package/dist/modules/config.js +70 -0
  265. package/dist/modules/manifest.d.ts +41 -0
  266. package/dist/modules/manifest.js +1 -0
  267. package/dist/modules/provision.d.ts +3 -0
  268. package/dist/modules/provision.js +84 -0
  269. package/dist/modules/registry.d.ts +16 -0
  270. package/dist/modules/registry.js +250 -0
  271. package/dist/modules/runtime.d.ts +15 -0
  272. package/dist/modules/runtime.js +59 -0
  273. package/dist/package-metadata.js +10 -2
  274. package/dist/phren-dotenv.js +4 -2
  275. package/dist/phren-paths.d.ts +3 -2
  276. package/dist/phren-paths.js +4 -5
  277. package/dist/profile-store.js +4 -5
  278. package/dist/project-config.d.ts +19 -1
  279. package/dist/project-config.js +29 -3
  280. package/dist/project-topics.js +4 -4
  281. package/dist/provider-adapters.js +1 -4
  282. package/dist/query-correlation.js +6 -6
  283. package/dist/session/artifacts.js +5 -5
  284. package/dist/session/checkpoints.js +5 -0
  285. package/dist/session/utils.d.ts +2 -2
  286. package/dist/session/utils.js +6 -6
  287. package/dist/shared/content.d.ts +1 -1
  288. package/dist/shared/content.js +1 -1
  289. package/dist/shared/data-utils.js +1 -1
  290. package/dist/shared/fragment-graph.d.ts +1 -1
  291. package/dist/shared/fragment-graph.js +5 -5
  292. package/dist/shared/index.js +48 -7
  293. package/dist/shared/retrieval.d.ts +18 -1
  294. package/dist/shared/retrieval.js +100 -11
  295. package/dist/shared/search-fallback.js +4 -6
  296. package/dist/shared/sqljs.d.ts +2 -0
  297. package/dist/shared/sqljs.js +4 -2
  298. package/dist/shared.d.ts +0 -1
  299. package/dist/shared.js +0 -1
  300. package/dist/shell/input.d.ts +1 -5
  301. package/dist/shell/input.js +16 -10
  302. package/dist/shell/palette.d.ts +2 -2
  303. package/dist/shell/palette.js +3 -7
  304. package/dist/shell/render.d.ts +3 -1
  305. package/dist/shell/render.js +4 -4
  306. package/dist/shell/shell.js +4 -1
  307. package/dist/shell/types.d.ts +1 -0
  308. package/dist/shell/types.js +4 -0
  309. package/dist/shell/view.d.ts +0 -4
  310. package/dist/shell/view.js +19 -27
  311. package/dist/skill/registry.js +25 -17
  312. package/dist/skill/state.d.ts +3 -0
  313. package/dist/skill/state.js +13 -7
  314. package/dist/status.js +38 -17
  315. package/dist/store-registry.d.ts +44 -18
  316. package/dist/store-registry.js +169 -60
  317. package/dist/store-weight.d.ts +1 -6
  318. package/dist/store-weight.js +4 -2
  319. package/dist/sync/auth-doctor.d.ts +8 -0
  320. package/dist/sync/auth-doctor.js +27 -0
  321. package/dist/sync/auth.d.ts +27 -0
  322. package/dist/sync/auth.js +114 -0
  323. package/dist/sync/conflict-resolve.d.ts +9 -0
  324. package/dist/sync/conflict-resolve.js +146 -0
  325. package/dist/sync/git-state.d.ts +4 -0
  326. package/dist/sync/git-state.js +49 -0
  327. package/dist/sync/outcome.d.ts +34 -0
  328. package/dist/sync/outcome.js +57 -0
  329. package/dist/sync/pull.d.ts +15 -7
  330. package/dist/sync/pull.js +84 -35
  331. package/dist/sync/store-merge.d.ts +29 -0
  332. package/dist/sync/store-merge.js +137 -0
  333. package/dist/sync/task-merge.d.ts +22 -0
  334. package/dist/sync/task-merge.js +158 -0
  335. package/dist/task/github.js +1 -1
  336. package/dist/task/lifecycle.d.ts +5 -0
  337. package/dist/task/lifecycle.js +67 -23
  338. package/dist/terminal-text.d.ts +5 -0
  339. package/dist/terminal-text.js +11 -0
  340. package/dist/test-global-setup.js +7 -0
  341. package/dist/tool-registry.d.ts +1 -1
  342. package/dist/tool-registry.js +3 -1
  343. package/dist/tools/code.d.ts +3 -0
  344. package/dist/tools/code.js +178 -0
  345. package/dist/tools/config.js +5 -0
  346. package/dist/tools/data.js +14 -7
  347. package/dist/tools/dispatch.d.ts +2 -0
  348. package/dist/tools/dispatch.js +66 -0
  349. package/dist/tools/finding.js +43 -41
  350. package/dist/tools/ops.js +5 -2
  351. package/dist/tools/search.js +21 -8
  352. package/dist/tools/session.js +21 -22
  353. package/dist/tools/tasks.js +8 -2
  354. package/dist/tools/types.d.ts +2 -2
  355. package/dist/tools/types.js +2 -2
  356. package/dist/ui/assets.js +1 -1
  357. package/dist/ui/data.js +14 -15
  358. package/dist/ui/deep-void.d.ts +1 -1
  359. package/dist/ui/deep-void.js +0 -1
  360. package/dist/ui/graph-chrome.d.ts +1 -1
  361. package/dist/ui/graph-chrome.js +51 -0
  362. package/dist/ui/page.js +5 -5
  363. package/dist/ui/scripts.js +67 -30
  364. package/dist/ui/server.js +34 -6
  365. package/dist/update.js +1 -1
  366. package/dist/utils-fts.js +1 -0
  367. package/dist/utils-helpers.d.ts +7 -0
  368. package/dist/utils-helpers.js +17 -0
  369. package/dist/utils.d.ts +1 -1
  370. package/dist/utils.js +1 -1
  371. package/package.json +45 -3
  372. package/plugins/opencode/phren-transcript.js +340 -0
  373. package/starter/README.md +4 -4
  374. package/starter/global/{CLAUDE.md → AGENTS.md} +2 -2
  375. package/starter/global/skills/conductor/SKILL.md +106 -0
  376. package/starter/global/skills/fanout/SKILL.md +20 -0
  377. package/starter/global/skills/phren-discover/SKILL.md +6 -6
  378. package/starter/global/skills/phren-init/SKILL.md +4 -4
  379. package/starter/global/skills/phren-sync/SKILL.md +3 -3
  380. package/starter/templates/frontend/reference/README.md +1 -1
  381. package/starter/templates/library/reference/README.md +1 -1
  382. package/starter/templates/monorepo/reference/README.md +1 -1
  383. package/starter/templates/python-project/reference/README.md +1 -1
  384. /package/starter/templates/frontend/{CLAUDE.md → AGENTS.md} +0 -0
  385. /package/starter/templates/library/{CLAUDE.md → AGENTS.md} +0 -0
  386. /package/starter/templates/monorepo/{CLAUDE.md → AGENTS.md} +0 -0
  387. /package/starter/templates/python-project/{CLAUDE.md → AGENTS.md} +0 -0
@@ -2,13 +2,13 @@ import * as crypto from "crypto";
2
2
  import * as fs from "fs";
3
3
  import * as path from "path";
4
4
  import { withFileLock } from "../shared/governance.js";
5
- import { atomicWriteJson, debugError, readSessionStateFile, scanSessionFiles, sessionFileForId, sessionsDir, writeSessionStateFile, } from "./utils.js";
5
+ import { atomicWriteJson, debugError, readSessionStateFile, scanSessionFiles, sessionFileForId, runtimeSessionsDir, writeSessionStateFile, } from "./utils.js";
6
6
  function normalizeSummary(summary) {
7
7
  const trimmed = summary?.trim();
8
8
  return trimmed ? trimmed : undefined;
9
9
  }
10
10
  function sessionMessagesFileForId(phrenPath, sessionId) {
11
- return path.join(sessionsDir(phrenPath), `session-${sessionId}-messages.json`);
11
+ return path.join(runtimeSessionsDir(phrenPath), `session-${sessionId}-messages.json`);
12
12
  }
13
13
  function inferProjectForSession(phrenPath, sessionId) {
14
14
  return readSessionState(phrenPath, sessionId)?.project;
@@ -53,7 +53,7 @@ function parseSessionMessagesSnapshot(filePath) {
53
53
  }
54
54
  }
55
55
  function listSessionMessageSnapshots(phrenPath) {
56
- const dir = sessionsDir(phrenPath);
56
+ const dir = runtimeSessionsDir(phrenPath);
57
57
  let entries;
58
58
  try {
59
59
  entries = fs.readdirSync(dir, { withFileTypes: true });
@@ -88,7 +88,7 @@ function listSessionMessageSnapshots(phrenPath) {
88
88
  return snapshots;
89
89
  }
90
90
  export function lastSummaryPath(phrenPath) {
91
- return path.join(sessionsDir(phrenPath), "last-summary.json");
91
+ return path.join(runtimeSessionsDir(phrenPath), "last-summary.json");
92
92
  }
93
93
  export function readLastSummary(phrenPath) {
94
94
  try {
@@ -129,7 +129,7 @@ export function findMostRecentSummaryWithProject(phrenPath, project) {
129
129
  if (fastPath && (!project || fastPath.project === project)) {
130
130
  return fastPath;
131
131
  }
132
- const dir = sessionsDir(phrenPath);
132
+ const dir = runtimeSessionsDir(phrenPath);
133
133
  const results = scanSessionFiles(dir, readSessionStateFile, (state) => typeof state.summary === "string" && state.summary.trim().length > 0, { errorScope: "findMostRecentSummaryWithProject" });
134
134
  if (!project) {
135
135
  if (results.length === 0)
@@ -1,3 +1,4 @@
1
+ import { moduleEnabled } from "../modules/runtime.js";
1
2
  import * as fs from "fs";
2
3
  import * as path from "path";
3
4
  import { errorMessage } from "../utils.js";
@@ -51,6 +52,8 @@ function readCheckpointFile(filePath) {
51
52
  }
52
53
  }
53
54
  export function writeTaskCheckpoint(phrenPath, checkpoint) {
55
+ if (!moduleEnabled(phrenPath, "tasks"))
56
+ return;
54
57
  const filePath = checkpointPath(phrenPath, checkpoint.project, checkpoint.taskId);
55
58
  const normalizedCheckpoint = {
56
59
  ...checkpoint,
@@ -59,6 +62,8 @@ export function writeTaskCheckpoint(phrenPath, checkpoint) {
59
62
  atomicWriteJson(filePath, normalizedCheckpoint);
60
63
  }
61
64
  export function listTaskCheckpoints(phrenPath, project) {
65
+ if (!moduleEnabled(phrenPath, "tasks"))
66
+ return [];
62
67
  const dir = checkpointDir(phrenPath);
63
68
  let files;
64
69
  try {
@@ -1,3 +1,4 @@
1
+ export { sessionsDir } from "../phren-paths.js";
1
2
  /**
2
3
  * Write JSON to a file atomically using temp-file + rename.
3
4
  * Ensures the parent directory exists before writing.
@@ -17,7 +18,7 @@ export interface SessionState {
17
18
  /** When true, this session was created by the coding agent runtime. */
18
19
  agentCreated?: boolean;
19
20
  }
20
- export declare function sessionsDir(phrenPath: string): string;
21
+ export declare function runtimeSessionsDir(phrenPath: string): string;
21
22
  export declare function sessionFileForId(phrenPath: string, sessionId: string): string;
22
23
  export declare function isSessionStateFileName(name: string): boolean;
23
24
  export declare function readSessionStateFile(file: string): SessionState | null;
@@ -43,4 +44,3 @@ export declare function scanSessionFiles<T>(dir: string, parse: (filePath: strin
43
44
  includeMtime?: boolean;
44
45
  errorScope?: string;
45
46
  }): SessionFileEntry<T>[];
46
- export {};
@@ -1,23 +1,23 @@
1
1
  import * as fs from "fs";
2
2
  import * as path from "path";
3
3
  import { errorMessage } from "../utils.js";
4
+ // The experimental agent imports the sessions directory from here.
5
+ export { sessionsDir } from "../phren-paths.js";
6
+ import { atomicWriteText } from "../phren-paths.js";
4
7
  /**
5
8
  * Write JSON to a file atomically using temp-file + rename.
6
9
  * Ensures the parent directory exists before writing.
7
10
  */
8
11
  export function atomicWriteJson(filePath, data) {
9
- fs.mkdirSync(path.dirname(filePath), { recursive: true });
10
- const tmpPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
11
- fs.writeFileSync(tmpPath, JSON.stringify(data, null, 2) + "\n");
12
- fs.renameSync(tmpPath, filePath);
12
+ atomicWriteText(filePath, JSON.stringify(data, null, 2) + "\n");
13
13
  }
14
- export function sessionsDir(phrenPath) {
14
+ export function runtimeSessionsDir(phrenPath) {
15
15
  const dir = path.join(phrenPath, ".runtime", "sessions");
16
16
  fs.mkdirSync(dir, { recursive: true });
17
17
  return dir;
18
18
  }
19
19
  export function sessionFileForId(phrenPath, sessionId) {
20
- return path.join(sessionsDir(phrenPath), `session-${sessionId}.json`);
20
+ return path.join(runtimeSessionsDir(phrenPath), `session-${sessionId}.json`);
21
21
  }
22
22
  export function isSessionStateFileName(name) {
23
23
  return name.startsWith("session-") &&
@@ -1,4 +1,4 @@
1
- export { type ConsolidationNeeded, type ConsolidationStatus, checkConsolidationNeeded, validateFindingsFormat, stripTaskDoneSection, validateTaskFormat, extractConflictVersions, mergeFindings, mergeTask, autoMergeConflicts, } from "../content/validate.js";
1
+ export { type ConsolidationNeeded, type ConsolidationStatus, checkConsolidationNeeded, validateFindingsFormat, stripTaskDoneSection, validateTaskFormat, extractConflictVersions, mergeFindings, mergeTask, isAutoMergeableStorePath, autoMergeConflicts, } from "../content/validate.js";
2
2
  export { filterTrustedFindings, filterTrustedFindingsDetailed, } from "../content/citation.js";
3
3
  export { scanForSecrets, resolveCoref, isDuplicateFinding, detectConflicts, extractDynamicEntities, checkSemanticDedup, checkSemanticConflicts, } from "../content/dedup.js";
4
4
  export { countActiveFindings, autoArchiveToReference, } from "../content/archive.js";
@@ -1,5 +1,5 @@
1
1
  // Barrel re-export. Internal code imports from the specific modules directly.
2
- export { checkConsolidationNeeded, validateFindingsFormat, stripTaskDoneSection, validateTaskFormat, extractConflictVersions, mergeFindings, mergeTask, autoMergeConflicts, } from "../content/validate.js";
2
+ export { checkConsolidationNeeded, validateFindingsFormat, stripTaskDoneSection, validateTaskFormat, extractConflictVersions, mergeFindings, mergeTask, isAutoMergeableStorePath, autoMergeConflicts, } from "../content/validate.js";
3
3
  export { filterTrustedFindings, filterTrustedFindingsDetailed, } from "../content/citation.js";
4
4
  export { scanForSecrets, resolveCoref, isDuplicateFinding, detectConflicts, extractDynamicEntities, checkSemanticDedup, checkSemanticConflicts, } from "../content/dedup.js";
5
5
  export { countActiveFindings, autoArchiveToReference, } from "../content/archive.js";
@@ -1,7 +1,7 @@
1
1
  import * as fs from "fs";
2
2
  import * as path from "path";
3
3
  import { phrenErr, PhrenError, phrenOk, parsePhrenErrorCode, } from "../shared.js";
4
- import { withFileLock as withFileLockRaw } from "./governance.js";
4
+ import { withFileLock as withFileLockRaw } from "../governance/locks.js";
5
5
  import { isValidProjectName, safeProjectPath, errorMessage } from "../utils.js";
6
6
  import { resolveProject } from "../store-routing.js";
7
7
  export function withSafeLock(filePath, fn) {
@@ -34,7 +34,7 @@ export declare function extractFragmentNames(content: string): string[];
34
34
  */
35
35
  export declare function ensureGlobalEntitiesTable(db: SqlJsDatabase): void;
36
36
  /**
37
- * Prime CLAUDE.md fragments per project for a single build pass.
37
+ * Prime AGENTS.md fragments per project for a single build pass.
38
38
  * During an active build, extractAndLinkFragments resolves user fragments from this
39
39
  * in-memory map and avoids per-file sync stat/read calls.
40
40
  */
@@ -152,7 +152,7 @@ export function ensureGlobalEntitiesTable(db) {
152
152
  }
153
153
  }
154
154
  /**
155
- * Parse user-defined fragment names from CLAUDE.md frontmatter.
155
+ * Parse user-defined fragment names from AGENTS.md frontmatter.
156
156
  * Looks for: <!-- phren:fragments: Redis,MyService,InternalAPI -->
157
157
  * Also supports legacy: <!-- phren:entities: ... -->
158
158
  *
@@ -175,7 +175,7 @@ function readUserDefinedFragmentsFromDisk(claudeMdPath) {
175
175
  return { mtime: stat.mtimeMs, fragments };
176
176
  }
177
177
  /**
178
- * Prime CLAUDE.md fragments per project for a single build pass.
178
+ * Prime AGENTS.md fragments per project for a single build pass.
179
179
  * During an active build, extractAndLinkFragments resolves user fragments from this
180
180
  * in-memory map and avoids per-file sync stat/read calls.
181
181
  */
@@ -187,7 +187,7 @@ export function beginUserFragmentBuildCache(phrenPath, projects) {
187
187
  // it goes through path.join: concatenating with "/" reads fine on Windows
188
188
  // but produces a mixed-separator string that no other code path matches.
189
189
  const cacheKey = `${phrenPath}/${project}`;
190
- const claudeMdPath = path.join(phrenPath, project, "CLAUDE.md");
190
+ const claudeMdPath = path.join(phrenPath, project, "AGENTS.md");
191
191
  try {
192
192
  const loaded = readUserDefinedFragmentsFromDisk(claudeMdPath);
193
193
  if (!loaded) {
@@ -214,7 +214,7 @@ export function endUserFragmentBuildCache(phrenPath) {
214
214
  _activeBuildCacheKeyPrefix = null;
215
215
  }
216
216
  function parseUserDefinedFragments(phrenPath, project) {
217
- const claudeMdPath = path.join(phrenPath, project, "CLAUDE.md");
217
+ const claudeMdPath = path.join(phrenPath, project, "AGENTS.md");
218
218
  const cacheKey = `${phrenPath}/${project}`;
219
219
  try {
220
220
  // Active build path: no sync I/O in per-file extraction.
@@ -319,7 +319,7 @@ export function extractAndLinkFragments(db, content, sourceDoc, phrenPath) {
319
319
  for (const phrase of capitalizedPhrases) {
320
320
  fragmentNames.push(phrase);
321
321
  }
322
- // Add user-defined fragments from CLAUDE.md frontmatter
322
+ // Add user-defined fragments from AGENTS.md frontmatter
323
323
  if (phrenPath) {
324
324
  const projectMatch = sourceDoc.match(/^([^/]+)\//);
325
325
  if (projectMatch) {
@@ -1,3 +1,5 @@
1
+ import { moduleSnapshot } from "../modules/runtime.js";
2
+ import { skillEnabled } from "../modules/provision.js";
1
3
  import * as fs from "fs";
2
4
  import * as path from "path";
3
5
  import * as os from "os";
@@ -153,6 +155,7 @@ async function _drainEmbQueue() {
153
155
  }
154
156
  }
155
157
  const FILE_TYPE_MAP = {
158
+ "agents.md": "claude",
156
159
  "claude.md": "claude",
157
160
  "summary.md": "summary",
158
161
  "findings.md": "findings",
@@ -299,7 +302,7 @@ function computePhrenHash(phrenPath, profile, preGlobbed) {
299
302
  matched.add(f);
300
303
  }
301
304
  for (const f of matched) {
302
- if (ownership === "repo-managed" && path.basename(f).toLowerCase() === "claude.md")
305
+ if (ownership === "repo-managed" && path.basename(f).toLowerCase() === "agents.md")
303
306
  continue;
304
307
  files.push(path.join(dir, f));
305
308
  }
@@ -516,7 +519,7 @@ function getRepoManagedInstructionEntries(phrenPath, project) {
516
519
  const repoDir = getProjectSourcePath(phrenPath, project);
517
520
  if (!repoDir)
518
521
  return [];
519
- const candidates = ["CLAUDE.md", path.join(".claude", "CLAUDE.md")];
522
+ const candidates = ["AGENTS.md", "CLAUDE.md", path.join(".claude", "CLAUDE.md")];
520
523
  const entries = [];
521
524
  for (const relFile of candidates) {
522
525
  const fullPath = path.join(repoDir, relFile);
@@ -541,6 +544,7 @@ function globAllFiles(phrenPath, profile) {
541
544
  for (const dir of projectDirs) {
542
545
  const projectName = path.basename(dir);
543
546
  const storePath = path.dirname(dir);
547
+ const modules = moduleSnapshot(storePath, profile);
544
548
  const config = readProjectConfig(storePath, projectName);
545
549
  const ownership = getProjectOwnershipMode(storePath, projectName, config);
546
550
  const mdFilesSet = new Set();
@@ -558,10 +562,14 @@ function globAllFiles(phrenPath, profile) {
558
562
  const relFiles = [...mdFilesSet].sort();
559
563
  for (const relFile of relFiles) {
560
564
  const filename = path.basename(relFile);
561
- if (ownership === "repo-managed" && filename.toLowerCase() === "claude.md")
565
+ if (ownership === "repo-managed" && ["agents.md", "claude.md"].includes(filename.toLowerCase()))
562
566
  continue;
563
567
  const fullPath = path.join(dir, relFile);
564
568
  const type = classifyFile(filename, relFile);
569
+ if (type === "task" && !modules.has("tasks"))
570
+ continue;
571
+ if (relFile.startsWith("skills/") && !skillEnabled(storePath, relFile.split("/")[1], profile))
572
+ continue;
565
573
  entries.push({ fullPath, project: projectName, filename, type, relFile });
566
574
  allAbsolutePaths.push(fullPath);
567
575
  }
@@ -577,6 +585,8 @@ function globAllFiles(phrenPath, profile) {
577
585
  if (fs.existsSync(globalSkillsDir)) {
578
586
  const skillFiles = globSync("**/*.md", { cwd: globalSkillsDir, nodir: true });
579
587
  for (const relFile of skillFiles) {
588
+ if (!skillEnabled(phrenPath, relFile.split("/")[0], profile))
589
+ continue;
580
590
  const fullPath = path.join(globalSkillsDir, relFile);
581
591
  const filename = path.basename(relFile);
582
592
  entries.push({ fullPath, project: "global", filename, type: "skill", relFile: `skills/${relFile}` });
@@ -646,7 +656,7 @@ function extractLegacyTopicSlug(entry) {
646
656
  * Build-scoped memo for `readProjectTopics()`.
647
657
  *
648
658
  * `readProjectTopics` derives adaptive topics by reading and tokenising the
649
- * *whole* project corpus — CLAUDE.md, FINDINGS.md and every reference/*.md —
659
+ * *whole* project corpus — AGENTS.md, FINDINGS.md and every reference/*.md —
650
660
  * on each call (see `buildTopicContentSignal` in project-topics.ts). It is
651
661
  * called once per reference document, so a project with R reference docs read
652
662
  * and tokenised its own corpus R times per rebuild. Measured on a 1892-file
@@ -776,6 +786,11 @@ export function updateFileInIndex(db, filePath, phrenPath) {
776
786
  const project = rel.split(path.sep)[0];
777
787
  const relFile = rel.split(path.sep).slice(1).join(path.sep);
778
788
  const type = classifyFile(filename, relFile);
789
+ const modules = moduleSnapshot(phrenPath);
790
+ if (type === "task" && !modules.has("tasks"))
791
+ return;
792
+ if (relFile.startsWith("skills/") && !skillEnabled(phrenPath, relFile.split("/")[1]))
793
+ return;
779
794
  const entry = { fullPath: resolvedPath, project, filename, type, relFile };
780
795
  // Single read feeds the insert, fragment extraction and the content hash.
781
796
  const raw = readFileOrNull(resolvedPath);
@@ -1683,7 +1698,7 @@ function isDbOpen(db) {
1683
1698
  }
1684
1699
  export async function buildIndex(phrenPath, profile, options = {}) {
1685
1700
  const debounceMs = getIndexDebounceMs();
1686
- const buildKey = `${phrenPath}|${profile ?? ""}`;
1701
+ const buildKey = storeCacheKey(phrenPath, profile);
1687
1702
  if (!options.force &&
1688
1703
  debounceMs > 0 &&
1689
1704
  _lastBuiltDb !== null &&
@@ -1721,8 +1736,10 @@ function ftsCacheRoot() {
1721
1736
  * Identity therefore has to live in the path.
1722
1737
  */
1723
1738
  function storeCacheKey(phrenPath, profile) {
1739
+ const generations = [...new Set([phrenPath, ...getAllStoreProjectDirs(phrenPath, profile).map(dir => path.dirname(dir))])]
1740
+ .sort().map(store => moduleSnapshot(store, profile).generation).join("|");
1724
1741
  return crypto.createHash("sha1")
1725
- .update(`${path.resolve(phrenPath)}|${profile ?? ""}`)
1742
+ .update(`${path.resolve(phrenPath)}|${profile ?? ""}|${generations}`)
1726
1743
  .digest("hex")
1727
1744
  .slice(0, 16);
1728
1745
  }
@@ -1948,6 +1965,24 @@ export function findFtsCacheForPath(phrenPath, profile) {
1948
1965
  }
1949
1966
  return { exists: false };
1950
1967
  }
1968
+ /**
1969
+ * The nearest ancestor of `dir` (itself included) that is a git checkout named
1970
+ * `project`, compared case-insensitively. Used only when a project's
1971
+ * registered source folder doesn't exist on this machine.
1972
+ */
1973
+ function localCheckoutNamed(dir, project) {
1974
+ const wanted = project.toLowerCase();
1975
+ let current = dir;
1976
+ for (;;) {
1977
+ if (path.basename(current).toLowerCase() === wanted && fs.existsSync(path.join(current, ".git"))) {
1978
+ return current;
1979
+ }
1980
+ const parent = path.dirname(current);
1981
+ if (parent === current)
1982
+ return null;
1983
+ current = parent;
1984
+ }
1985
+ }
1951
1986
  export function detectProject(phrenPath, cwd, profile) {
1952
1987
  const manifest = readRootManifest(phrenPath);
1953
1988
  if (manifest?.installMode === "project-local") {
@@ -1963,8 +1998,14 @@ export function detectProject(phrenPath, cwd, profile) {
1963
1998
  // Try the project's own store path first (handles team store projects),
1964
1999
  // then fall back to primary phrenPath
1965
2000
  const storePhrenPath = path.dirname(dir);
1966
- const sourcePath = getProjectSourcePath(storePhrenPath, projectName)
2001
+ const configuredPath = getProjectSourcePath(storePhrenPath, projectName)
1967
2002
  || getProjectSourcePath(phrenPath, projectName);
2003
+ // The store is shared between computers, so the registered folder may be
2004
+ // another machine's (e.g. /home/other/Projects/x). When it doesn't exist
2005
+ // here, fall back to the checkout on this machine named after the project.
2006
+ const sourcePath = configuredPath && fs.existsSync(configuredPath)
2007
+ ? configuredPath
2008
+ : localCheckoutNamed(resolvedCwd, projectName) ?? configuredPath;
1968
2009
  if (!sourcePath)
1969
2010
  continue;
1970
2011
  // Exact first. Then case-insensitive: a sourcePath written on a
@@ -28,6 +28,23 @@ export declare function wantsTasks(prompt: string, intent: ReturnType<typeof det
28
28
  export declare function detectTaskIntent(prompt: string): "debug" | "review" | "build" | "docs" | "skill" | "general";
29
29
  export declare function fileRelevanceBoost(filePath: string, changedFiles: Set<string>): number;
30
30
  export declare function branchMatchBoost(content: string, branch: string | undefined): number;
31
+ /** A doc's bullets (with their continuation lines) or, with none, its
32
+ * paragraphs: the unit relevance is judged on. Topic archives are one doc
33
+ * with hundreds of bullets, so a whole-file score matches almost anything. */
34
+ export declare function contentChunks(content: string, maxChunks?: number): string[];
35
+ export interface ChunkMatch {
36
+ chunk: string;
37
+ distinct: number;
38
+ rarity: number;
39
+ }
40
+ /** The doc's best chunk for this prompt: most summed keyword rarity among
41
+ * chunks with the most distinct keyword matches. */
42
+ export declare function bestChunkMatch(queryTokens: string[], doc: Pick<DocRow, "content">, rarity?: Map<string, number>): ChunkMatch | null;
43
+ /** How rare each prompt token is across the index: normalised IDF, 1 for a
44
+ * token in one doc, near 0 for one in every doc. One FTS count per token. */
45
+ /** `tokenRarity` for a prompt's keywords, tokenised as the floor tokenises them. */
46
+ export declare function promptRarity(db: SqlJsDatabase | null | undefined, keywords: string): Map<string, number>;
47
+ export declare function tokenRarity(db: SqlJsDatabase | null | undefined, queryTokens: string[]): Map<string, number>;
31
48
  /**
32
49
  * Item 4: Reciprocal Rank Fusion — merges ranked result lists from multiple search tiers.
33
50
  * Documents appearing in multiple tiers get a higher combined score.
@@ -141,7 +158,7 @@ export { DEFAULT_MIN_QUERY_RELEVANCE };
141
158
  export declare function applyRelevanceFloor(rows: DocRow[], keywords: string, gitCtx: {
142
159
  branch?: string;
143
160
  changedFiles?: Set<string>;
144
- } | null, detectedProject: string | null, floor?: number): DocRow[];
161
+ } | null, detectedProject: string | null, floor?: number, rarity?: Map<string, number>): DocRow[];
145
162
  export declare function selectSnippets(rows: DocRow[], keywords: string, tokenBudget: number, lineBudget: number, charBudget: number): {
146
163
  selected: SelectedSnippet[];
147
164
  usedTokens: number;
@@ -47,6 +47,17 @@ const LOW_FOCUS_SNIPPET_CHAR_FRACTION = 0.55;
47
47
  * PHREN_MIN_QUERY_RELEVANCE (0 disables the floor). */
48
48
  const DEFAULT_MIN_QUERY_RELEVANCE = 0.12;
49
49
  const CROSS_PROJECT_MIN_QUERY_RELEVANCE = 0.25;
50
+ /** A chunk (one bullet or paragraph) must match this many distinct prompt
51
+ * keywords before its doc is worth injecting. */
52
+ const MIN_CHUNK_MATCHES = 2;
53
+ /** The matched keywords' summed rarity (normalised IDF, 0..1 each) a chunk
54
+ * needs. Common words across the index ("main", "push", "agent") weigh little,
55
+ * project and technical terms a lot, so a prompt of common words clears
56
+ * nothing. With no detected project (the conductor) the bar is higher. */
57
+ const MIN_CHUNK_RARITY = 0.55;
58
+ const NO_PROJECT_MIN_CHUNK_RARITY = 0.6;
59
+ /** Rarity for a token the index never saw, or when no index is at hand. */
60
+ const DEFAULT_TOKEN_RARITY = 0.5;
50
61
  const TASK_RESCUE_MIN_OVERLAP = 0.3;
51
62
  const TASK_RESCUE_OVERLAP_MARGIN = 0.12;
52
63
  const TASK_RESCUE_SCORE_MARGIN = 0.6;
@@ -205,9 +216,81 @@ function overlapScore(queryTokens, content) {
205
216
  return matched / denominator;
206
217
  }
207
218
  function docOverlapScore(queryTokens, doc) {
208
- const corpus = `${doc.project} ${doc.filename} ${doc.type} ${doc.path}\n${doc.content.slice(0, 5000)}`;
219
+ // Never the path: every store path contains "/.phren/", so "phren" would match every doc.
220
+ const corpus = `${doc.project} ${doc.filename} ${doc.type}\n${doc.content.slice(0, 5000)}`;
209
221
  return overlapScore(queryTokens, corpus);
210
222
  }
223
+ /** A doc's bullets (with their continuation lines) or, with none, its
224
+ * paragraphs: the unit relevance is judged on. Topic archives are one doc
225
+ * with hundreds of bullets, so a whole-file score matches almost anything. */
226
+ export function contentChunks(content, maxChunks = 600) {
227
+ const chunks = [];
228
+ let current = [];
229
+ const flush = () => { if (current.length)
230
+ chunks.push(current.join("\n")); current = []; };
231
+ for (const line of content.split("\n")) {
232
+ const trimmed = line.trim();
233
+ if (!trimmed) {
234
+ flush();
235
+ continue;
236
+ }
237
+ if (/^([-*+]|\d+[.)])\s/.test(trimmed) || trimmed.startsWith("#"))
238
+ flush();
239
+ current.push(line);
240
+ if (chunks.length >= maxChunks)
241
+ break;
242
+ }
243
+ flush();
244
+ return chunks.slice(0, maxChunks);
245
+ }
246
+ /** The doc's best chunk for this prompt: most summed keyword rarity among
247
+ * chunks with the most distinct keyword matches. */
248
+ export function bestChunkMatch(queryTokens, doc, rarity) {
249
+ if (!queryTokens.length)
250
+ return null;
251
+ const wanted = new Set(queryTokens);
252
+ let best = null;
253
+ for (const chunk of contentChunks(doc.content)) {
254
+ const tokens = new Set(tokenizeForOverlap(chunk, Number.POSITIVE_INFINITY));
255
+ let distinct = 0, weight = 0;
256
+ for (const token of wanted) {
257
+ if (!tokens.has(token))
258
+ continue;
259
+ distinct += 1;
260
+ weight += rarity?.get(token) ?? DEFAULT_TOKEN_RARITY;
261
+ }
262
+ if (!distinct)
263
+ continue;
264
+ if (!best || weight > best.rarity || (weight === best.rarity && distinct > best.distinct))
265
+ best = { chunk, distinct, rarity: weight };
266
+ }
267
+ return best;
268
+ }
269
+ /** How rare each prompt token is across the index: normalised IDF, 1 for a
270
+ * token in one doc, near 0 for one in every doc. One FTS count per token. */
271
+ /** `tokenRarity` for a prompt's keywords, tokenised as the floor tokenises them. */
272
+ export function promptRarity(db, keywords) {
273
+ return tokenRarity(db, tokenizeForOverlap(keywords));
274
+ }
275
+ export function tokenRarity(db, queryTokens) {
276
+ const rarity = new Map();
277
+ if (!db || !queryTokens.length)
278
+ return rarity;
279
+ try {
280
+ const total = Number(queryRows(db, "SELECT COUNT(*) FROM docs", [])?.[0]?.[0] ?? 0);
281
+ if (!(total > 1))
282
+ return rarity;
283
+ const scale = Math.log(total + 1);
284
+ for (const token of queryTokens.slice(0, 12)) {
285
+ if (!/^[a-z0-9_-]+$/.test(token))
286
+ continue;
287
+ const df = Number(queryRows(db, "SELECT COUNT(*) FROM docs WHERE docs MATCH ?", [`"${token}"*`])?.[0]?.[0] ?? 0);
288
+ rarity.set(token, Math.max(0, Math.min(1, Math.log((total + 1) / (df + 1)) / scale)));
289
+ }
290
+ }
291
+ catch { /* the default rarity stands in */ }
292
+ return rarity;
293
+ }
211
294
  function loadSemanticFallbackWindow(db, startRowid, limit, project, wrapBefore) {
212
295
  const where = [
213
296
  project ? "project = ?" : "",
@@ -888,24 +971,27 @@ export { DEFAULT_MIN_QUERY_RELEVANCE };
888
971
  * floor to 0 (env PHREN_MIN_QUERY_RELEVANCE=0) disables it and restores the
889
972
  * previous always-fill behavior.
890
973
  */
891
- export function applyRelevanceFloor(rows, keywords, gitCtx, detectedProject, floor = DEFAULT_MIN_QUERY_RELEVANCE) {
974
+ export function applyRelevanceFloor(rows, keywords, gitCtx, detectedProject, floor = DEFAULT_MIN_QUERY_RELEVANCE, rarity) {
892
975
  if (!(floor > 0))
893
976
  return rows;
894
977
  const queryTokens = tokenizeForOverlap(keywords);
895
- if (!queryTokens.length)
896
- return rows; // no query signal to judge against
897
978
  const changedFiles = gitCtx?.changedFiles ?? new Set();
898
- const branch = gitCtx?.branch;
899
979
  const crossFloor = Math.max(floor, CROSS_PROJECT_MIN_QUERY_RELEVANCE);
980
+ // Fewer meaningful keywords than a chunk must match: nothing can be about
981
+ // this prompt ("Yes"), so only the structural signals remain.
982
+ const minRarity = detectedProject ? MIN_CHUNK_RARITY : NO_PROJECT_MIN_CHUNK_RARITY;
900
983
  return rows.filter((doc) => {
984
+ // A changed file is a tie to this work; a branch name is not: its words
985
+ // ("audio") run through a whole project's memory. It still orders results.
901
986
  if (fileRelevanceBoost(doc.path, changedFiles) > 0)
902
987
  return true;
903
- if (branchMatchBoost(doc.content, branch) > 0)
904
- return true;
905
- if (detectedProject && doc.project === detectedProject && doc.type === "canonical")
906
- return true;
988
+ if (queryTokens.length < MIN_CHUNK_MATCHES)
989
+ return false;
990
+ const match = bestChunkMatch(queryTokens, doc, rarity);
991
+ if (!match || match.distinct < MIN_CHUNK_MATCHES || match.rarity < minRarity)
992
+ return false;
907
993
  const isCrossProject = Boolean(detectedProject) && doc.project !== detectedProject;
908
- return docOverlapScore(queryTokens, doc) >= (isCrossProject ? crossFloor : floor);
994
+ return overlapScore(queryTokens, match.chunk) >= (isCrossProject ? crossFloor : floor);
909
995
  });
910
996
  }
911
997
  export function selectSnippets(rows, keywords, tokenBudget, lineBudget, charBudget) {
@@ -931,7 +1017,10 @@ export function selectSnippets(rows, keywords, tokenBudget, lineBudget, charBudg
931
1017
  // unconditionally true of everything injected, so it is checked here too.
932
1018
  if (!isInjectableDocType(doc.type))
933
1019
  continue;
934
- let snippet = compactSnippet(extractSnippet(doc.content, keywords, 8), lineBudget, charBudget);
1020
+ // The bullet that matched, not the doc's opening lines.
1021
+ const match = bestChunkMatch(queryTokens, doc);
1022
+ const source = match && match.distinct >= MIN_CHUNK_MATCHES ? match.chunk : extractSnippet(doc.content, keywords, 8);
1023
+ let snippet = compactSnippet(source, lineBudget, charBudget);
935
1024
  if (!snippet.trim())
936
1025
  continue;
937
1026
  // Mark findings with stale citations before injection
@@ -66,7 +66,7 @@ function cachedTokenize(text) {
66
66
  const hit = tokenCache.get(key);
67
67
  if (hit)
68
68
  return hit;
69
- const tokens = tokenize(text);
69
+ const tokens = stemmedTerms(text);
70
70
  if (tokenCache.size >= MAX_TOKEN_CACHE) {
71
71
  // Evict oldest entry
72
72
  tokenCache.delete(tokenCache.keys().next().value ?? "");
@@ -88,10 +88,8 @@ function loadCosineFallbackWindow(db, startRowid, limit, wrapBefore) {
88
88
  const rows = db.exec(`SELECT rowid, project, filename, type, content, path FROM docs WHERE ${where} ORDER BY rowid LIMIT ?`, params);
89
89
  return rows?.[0]?.values ?? [];
90
90
  }
91
- /**
92
- * Tokenize text into non-stop-word tokens for TF-IDF computation, with stemming.
93
- */
94
- function tokenize(text) {
91
+ /** Punctuation-free, stop-word-free, Porter-stemmed terms for TF-IDF scoring. */
92
+ function stemmedTerms(text) {
95
93
  return text
96
94
  .toLowerCase()
97
95
  .replace(/[^\w\s]/g, " ")
@@ -107,7 +105,7 @@ function tokenize(text) {
107
105
  * Pass the real total when docs is a pre-filtered subset so IDF scores are not inflated.
108
106
  */
109
107
  function tfidfCosine(docs, query, corpusN) {
110
- const queryTokens = tokenize(query);
108
+ const queryTokens = stemmedTerms(query);
111
109
  if (queryTokens.length === 0)
112
110
  return docs.map(() => 0);
113
111
  // Collect all unique terms from query + all docs (use cached tokenization for repeated content)
@@ -1,5 +1,7 @@
1
1
  /**
2
2
  * Bootstrap sql.js-fts5: find the WASM binary and initialise the library.
3
3
  * Shared across shared-index.ts and embedding.ts to avoid duplication.
4
+ * The require is lazy so importing this module (the Hook bundle pulls it in
5
+ * through the CLI context) does not need the native package on disk.
4
6
  */
5
7
  export declare function bootstrapSqlJs(): Promise<unknown>;
@@ -32,12 +32,14 @@ function findWasmBinary() {
32
32
  }
33
33
  return undefined;
34
34
  }
35
- const _initSqlJs = require("sql.js-fts5");
36
35
  /**
37
36
  * Bootstrap sql.js-fts5: find the WASM binary and initialise the library.
38
37
  * Shared across shared-index.ts and embedding.ts to avoid duplication.
38
+ * The require is lazy so importing this module (the Hook bundle pulls it in
39
+ * through the CLI context) does not need the native package on disk.
39
40
  */
40
41
  export async function bootstrapSqlJs() {
42
+ const initSqlJs = require("sql.js-fts5");
41
43
  const wasmBinary = findWasmBinary();
42
- return _initSqlJs(wasmBinary ? { wasmBinary } : {});
44
+ return initSqlJs(wasmBinary ? { wasmBinary } : {});
43
45
  }
package/dist/shared.d.ts CHANGED
@@ -2,7 +2,6 @@ export type { HookToolName } from "./provider-adapters.js";
2
2
  export { HOOK_TOOL_NAMES, hookConfigPath } from "./provider-adapters.js";
3
3
  export { EXEC_TIMEOUT_MS, EXEC_TIMEOUT_QUICK_MS, PhrenError, type PhrenErrorCode, type PhrenResult, phrenOk, phrenErr, forwardErr, parsePhrenErrorCode, isRecord, withDefaults, FINDING_TYPES, type FindingType, FINDING_TAGS, type FindingTag, KNOWN_OBSERVATION_TAGS, DOC_TYPES, type DocType, capCache, RESERVED_PROJECT_DIR_NAMES, } from "./phren-core.js";
4
4
  export { ROOT_MANIFEST_FILENAME, type InstallMode, type SyncMode, type PhrenRootManifest, type InstallContext, isInstallMode, homeDir, homePath, expandHomePath, defaultPhrenPath, rootManifestPath, readRootManifest, writeRootManifest, resolveInstallContext, findNearestPhrenPath, isProjectLocalMode, runtimeDir, tryUnlink, sessionsDir, runtimeFile, installPreferencesFile, runtimeHealthFile, shellStateFile, sessionMetricsFile, memoryScoresFile, memoryUsageLogFile, lookupEventsLogFile, sessionMarker, debugLog, appendIndexEvent, resolveFindingsPath, findPhrenPath, ensurePhrenPath, findPhrenPathWithArg, normalizeProjectNameForCreate, projectSlugFromPath, canonicalProjectKey, findProjectNameCaseInsensitive, findProjectNamesByCanonicalKey, findArchivedProjectNameCaseInsensitive, getProjectDirs, listInvalidProjectDirs, collectNativeMemoryFiles, nativeMemoryEnabled, computePhrenLiveStateToken, getPhrenPath, qualityMarkers, atomicWriteText, ensurePrivateDir, ftsCacheRoot, ensureFtsCacheRootPrivate, } from "./phren-paths.js";
5
- export { PROACTIVITY_LEVELS, type ProactivityLevel, parseProactivityLevel, getProactivityLevel, getProactivityLevelForFindings, getProactivityLevelForTask, hasExplicitFindingSignal, hasExplicitTaskSignal, hasExecutionIntent, hasDiscoveryIntent, shouldAutoCaptureFindingsForLevel, shouldAutoCaptureTaskForLevel, } from "./proactivity.js";
6
5
  export declare function normalizeMemoryScope(scope?: string | null): string | undefined;
7
6
  export declare function isMemoryScopeVisible(itemScope: string | undefined, activeScope?: string): boolean;
8
7
  export declare function impactLogFile(phrenPath: string): string;
package/dist/shared.js CHANGED
@@ -7,7 +7,6 @@ const MAX_LOG_LINES = 1000;
7
7
  export { HOOK_TOOL_NAMES, hookConfigPath } from "./provider-adapters.js";
8
8
  export { EXEC_TIMEOUT_MS, EXEC_TIMEOUT_QUICK_MS, PhrenError, phrenOk, phrenErr, forwardErr, parsePhrenErrorCode, isRecord, withDefaults, FINDING_TYPES, FINDING_TAGS, KNOWN_OBSERVATION_TAGS, DOC_TYPES, capCache, RESERVED_PROJECT_DIR_NAMES, } from "./phren-core.js";
9
9
  export { ROOT_MANIFEST_FILENAME, isInstallMode, homeDir, homePath, expandHomePath, defaultPhrenPath, rootManifestPath, readRootManifest, writeRootManifest, resolveInstallContext, findNearestPhrenPath, isProjectLocalMode, runtimeDir, tryUnlink, sessionsDir, runtimeFile, installPreferencesFile, runtimeHealthFile, shellStateFile, sessionMetricsFile, memoryScoresFile, memoryUsageLogFile, lookupEventsLogFile, sessionMarker, debugLog, appendIndexEvent, resolveFindingsPath, findPhrenPath, ensurePhrenPath, findPhrenPathWithArg, normalizeProjectNameForCreate, projectSlugFromPath, canonicalProjectKey, findProjectNameCaseInsensitive, findProjectNamesByCanonicalKey, findArchivedProjectNameCaseInsensitive, getProjectDirs, listInvalidProjectDirs, collectNativeMemoryFiles, nativeMemoryEnabled, computePhrenLiveStateToken, getPhrenPath, qualityMarkers, atomicWriteText, ensurePrivateDir, ftsCacheRoot, ensureFtsCacheRootPrivate, } from "./phren-paths.js";
10
- export { PROACTIVITY_LEVELS, parseProactivityLevel, getProactivityLevel, getProactivityLevelForFindings, getProactivityLevelForTask, hasExplicitFindingSignal, hasExplicitTaskSignal, hasExecutionIntent, hasDiscoveryIntent, shouldAutoCaptureFindingsForLevel, shouldAutoCaptureTaskForLevel, } from "./proactivity.js";
11
10
  const MEMORY_SCOPE_PATTERN = /^[a-z][a-z0-9_-]{0,63}$/;
12
11
  export function normalizeMemoryScope(scope) {
13
12
  if (typeof scope !== "string")
@@ -1,7 +1,3 @@
1
- /**
2
- * Command palette and input handling for the phren interactive shell.
3
- * Extracted from shell.ts to keep the orchestrator under 300 lines.
4
- */
5
1
  import { ShellState } from "../data/access.js";
6
2
  import { type DoctorResultLike, type ShellDeps, type ShellView } from "./types.js";
7
3
  import type { GraphController } from "./graph/controller.js";
@@ -52,7 +48,7 @@ export interface NavigationHost extends PaletteHost {
52
48
  }
53
49
  /**
54
50
  * The file `e` and `E` edit for the current view. Skills edit their own
55
- * markdown; a project edits the CLAUDE.md the store owns and symlinks into the
51
+ * markdown; a project edits the AGENTS.md the store owns and symlinks into the
56
52
  * repo, so editing here reaches every linked checkout.
57
53
  */
58
54
  export declare function editTargetFor(host: NavigationHost, item: {