@phren/cli 0.2.15 → 0.3.0

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 (392) 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 +195 -2
  7. package/dist/bridge/agent-hooks.js +1049 -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 +23 -0
  15. package/dist/bridge/code-note.js +51 -0
  16. package/dist/bridge/code-routes.d.ts +151 -0
  17. package/dist/bridge/code-routes.js +442 -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 +125 -0
  33. package/dist/bridge/dispatch-returns.js +283 -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 +210 -0
  37. package/dist/bridge/dispatch.js +286 -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 +28 -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 +61 -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 +54 -0
  96. package/dist/bridge/schedule-watch.js +255 -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 +36 -0
  104. package/dist/bridge/server-pane-routes.js +479 -0
  105. package/dist/bridge/server-routes.d.ts +108 -0
  106. package/dist/bridge/server-routes.js +556 -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 +96 -0
  136. package/dist/bridge/transcript-preview.js +491 -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 +46545 -21051
  146. package/dist/cli/actions.js +14 -1
  147. package/dist/cli/config-policy.js +25 -0
  148. package/dist/cli/config-proactivity.d.ts +3 -1
  149. package/dist/cli/config-proactivity.js +35 -3
  150. package/dist/cli/config.js +4 -1
  151. package/dist/cli/extract.d.ts +0 -8
  152. package/dist/cli/extract.js +4 -7
  153. package/dist/cli/govern.js +5 -2
  154. package/dist/cli/hooks-globs.js +1 -1
  155. package/dist/cli/hooks.d.ts +1 -1
  156. package/dist/cli/hooks.js +9 -7
  157. package/dist/cli/namespaces-projects.js +12 -6
  158. package/dist/cli/namespaces-store.js +37 -6
  159. package/dist/cli/namespaces-tasks.js +1 -1
  160. package/dist/cli/schedules.d.ts +1 -0
  161. package/dist/cli/schedules.js +164 -0
  162. package/dist/cli/session-background.js +1 -1
  163. package/dist/cli/session-git.d.ts +8 -5
  164. package/dist/cli/session-git.js +45 -120
  165. package/dist/cli/session-start.js +3 -1
  166. package/dist/cli/session-stop.js +19 -8
  167. package/dist/cli/team.js +13 -10
  168. package/dist/cli-handlers.d.ts +1 -1
  169. package/dist/cli-handlers.js +8 -4
  170. package/dist/cli-help.d.ts +5 -4
  171. package/dist/cli-help.js +15 -15
  172. package/dist/cli-registry.d.ts +4 -1
  173. package/dist/cli-registry.js +119 -6
  174. package/dist/content/archive.js +2 -2
  175. package/dist/content/citation.d.ts +11 -0
  176. package/dist/content/citation.js +18 -0
  177. package/dist/content/learning.js +2 -0
  178. package/dist/content/summarize.d.ts +14 -15
  179. package/dist/content/summarize.js +60 -5
  180. package/dist/content/validate.d.ts +17 -4
  181. package/dist/content/validate.js +200 -122
  182. package/dist/core/project-registry.d.ts +26 -0
  183. package/dist/core/project-registry.js +573 -0
  184. package/dist/core/project.js +2 -3
  185. package/dist/data/access.d.ts +16 -1
  186. package/dist/data/access.js +31 -3
  187. package/dist/data/tasks.d.ts +18 -3
  188. package/dist/data/tasks.js +8 -7
  189. package/dist/entrypoint.js +44 -10
  190. package/dist/fanout/adapters/claude.d.ts +2 -0
  191. package/dist/fanout/adapters/claude.js +7 -0
  192. package/dist/fanout/adapters/codex.d.ts +2 -0
  193. package/dist/fanout/adapters/codex.js +9 -0
  194. package/dist/fanout/adapters/opencode.d.ts +4 -0
  195. package/dist/fanout/adapters/opencode.js +9 -0
  196. package/dist/fanout/adapters/types.d.ts +21 -0
  197. package/dist/fanout/adapters/types.js +3 -0
  198. package/dist/fanout/command.d.ts +2 -0
  199. package/dist/fanout/command.js +78 -0
  200. package/dist/fanout/launcher.d.ts +27 -0
  201. package/dist/fanout/launcher.js +156 -0
  202. package/dist/fanout/opencode-serve.d.ts +24 -0
  203. package/dist/fanout/opencode-serve.js +191 -0
  204. package/dist/fanout/picker.d.ts +91 -0
  205. package/dist/fanout/picker.js +51 -0
  206. package/dist/fanout/usage.d.ts +5 -0
  207. package/dist/fanout/usage.js +51 -0
  208. package/dist/fanout/watchdog.d.ts +10 -0
  209. package/dist/fanout/watchdog.js +27 -0
  210. package/dist/filenames.d.ts +9 -0
  211. package/dist/filenames.js +11 -0
  212. package/dist/finding/context.js +4 -22
  213. package/dist/generated/memory-ui-graph.browser.js +525 -419
  214. package/dist/governance/policy-constants.d.ts +11 -0
  215. package/dist/governance/policy-constants.js +9 -0
  216. package/dist/governance/policy.d.ts +5 -8
  217. package/dist/governance/policy.js +11 -8
  218. package/dist/graph-core/camera.d.ts +24 -0
  219. package/dist/graph-core/camera.js +18 -0
  220. package/dist/graph-core/index.d.ts +2 -0
  221. package/dist/graph-core/index.js +2 -0
  222. package/dist/graph-core/labels.d.ts +77 -0
  223. package/dist/graph-core/labels.js +124 -0
  224. package/dist/graph-core/model.d.ts +13 -0
  225. package/dist/graph-core/model.js +33 -0
  226. package/dist/graph-core/types.d.ts +2 -0
  227. package/dist/home-paths.d.ts +7 -0
  228. package/dist/home-paths.js +21 -0
  229. package/dist/hooks.d.ts +3 -15
  230. package/dist/hooks.js +14 -1
  231. package/dist/index.js +24 -2
  232. package/dist/init/guard-globals.d.ts +1 -1
  233. package/dist/init/guard-globals.js +4 -4
  234. package/dist/init/init-configure.js +3 -3
  235. package/dist/init/init-uninstall.js +15 -5
  236. package/dist/init/init-walkthrough.js +1 -1
  237. package/dist/init/init.js +26 -6
  238. package/dist/init/management-preset.d.ts +1 -1
  239. package/dist/init/management-preset.js +2 -2
  240. package/dist/init/preferences.js +1 -1
  241. package/dist/init/self-wiring.js +1 -1
  242. package/dist/init/setup.d.ts +3 -26
  243. package/dist/init/setup.js +68 -593
  244. package/dist/init/shared.js +2 -0
  245. package/dist/init/store-gitignore.d.ts +1 -6
  246. package/dist/init/store-gitignore.js +2 -8
  247. package/dist/init/teardown.d.ts +1 -1
  248. package/dist/init/teardown.js +2 -2
  249. package/dist/link/context-imports.d.ts +15 -0
  250. package/dist/link/context-imports.js +101 -0
  251. package/dist/link/context.js +1 -1
  252. package/dist/link/doctor.d.ts +22 -1
  253. package/dist/link/doctor.js +128 -58
  254. package/dist/link/link.js +29 -61
  255. package/dist/link/refresh.js +2 -2
  256. package/dist/link/skills.js +26 -5
  257. package/dist/machine-identity.d.ts +3 -0
  258. package/dist/machine-identity.js +6 -0
  259. package/dist/mcp/profile.d.ts +2 -19
  260. package/dist/mcp/profile.js +64 -22
  261. package/dist/memory-ui-graph.runtime.js +525 -419
  262. package/dist/modules/code-package.d.ts +16 -0
  263. package/dist/modules/code-package.js +160 -0
  264. package/dist/modules/command.d.ts +2 -0
  265. package/dist/modules/command.js +67 -0
  266. package/dist/modules/config.d.ts +4 -0
  267. package/dist/modules/config.js +70 -0
  268. package/dist/modules/manifest.d.ts +41 -0
  269. package/dist/modules/manifest.js +1 -0
  270. package/dist/modules/provision.d.ts +3 -0
  271. package/dist/modules/provision.js +84 -0
  272. package/dist/modules/registry.d.ts +16 -0
  273. package/dist/modules/registry.js +250 -0
  274. package/dist/modules/runtime.d.ts +15 -0
  275. package/dist/modules/runtime.js +59 -0
  276. package/dist/package-metadata.js +10 -2
  277. package/dist/phren-dotenv.js +4 -2
  278. package/dist/phren-paths.d.ts +3 -2
  279. package/dist/phren-paths.js +4 -5
  280. package/dist/profile-store.js +43 -8
  281. package/dist/project-config.d.ts +19 -1
  282. package/dist/project-config.js +29 -3
  283. package/dist/project-topics.d.ts +1 -0
  284. package/dist/project-topics.js +13 -10
  285. package/dist/provider-adapters.js +1 -4
  286. package/dist/query-correlation.js +6 -6
  287. package/dist/session/artifacts.js +5 -5
  288. package/dist/session/checkpoints.js +5 -0
  289. package/dist/session/utils.d.ts +2 -2
  290. package/dist/session/utils.js +6 -6
  291. package/dist/shared/content.d.ts +1 -1
  292. package/dist/shared/content.js +1 -1
  293. package/dist/shared/data-utils.js +1 -1
  294. package/dist/shared/fragment-graph.d.ts +1 -1
  295. package/dist/shared/fragment-graph.js +5 -5
  296. package/dist/shared/index.js +48 -7
  297. package/dist/shared/retrieval.d.ts +18 -3
  298. package/dist/shared/retrieval.js +101 -12
  299. package/dist/shared/search-fallback.js +4 -6
  300. package/dist/shared/sqljs.d.ts +2 -0
  301. package/dist/shared/sqljs.js +4 -2
  302. package/dist/shared.d.ts +0 -1
  303. package/dist/shared.js +0 -1
  304. package/dist/shell/input.d.ts +1 -5
  305. package/dist/shell/input.js +16 -10
  306. package/dist/shell/palette.d.ts +2 -2
  307. package/dist/shell/palette.js +3 -7
  308. package/dist/shell/render.d.ts +3 -1
  309. package/dist/shell/render.js +4 -4
  310. package/dist/shell/shell.js +4 -1
  311. package/dist/shell/types.d.ts +1 -0
  312. package/dist/shell/types.js +4 -0
  313. package/dist/shell/view.d.ts +0 -4
  314. package/dist/shell/view.js +19 -27
  315. package/dist/skill/registry.js +25 -17
  316. package/dist/skill/state.d.ts +3 -0
  317. package/dist/skill/state.js +13 -7
  318. package/dist/status.js +38 -17
  319. package/dist/store-registry.d.ts +44 -18
  320. package/dist/store-registry.js +169 -60
  321. package/dist/store-weight.d.ts +1 -6
  322. package/dist/store-weight.js +4 -2
  323. package/dist/sync/auth-doctor.d.ts +8 -0
  324. package/dist/sync/auth-doctor.js +27 -0
  325. package/dist/sync/auth.d.ts +27 -0
  326. package/dist/sync/auth.js +114 -0
  327. package/dist/sync/conflict-resolve.d.ts +9 -0
  328. package/dist/sync/conflict-resolve.js +146 -0
  329. package/dist/sync/git-state.d.ts +4 -0
  330. package/dist/sync/git-state.js +49 -0
  331. package/dist/sync/outcome.d.ts +34 -0
  332. package/dist/sync/outcome.js +57 -0
  333. package/dist/sync/pull.d.ts +15 -7
  334. package/dist/sync/pull.js +84 -35
  335. package/dist/sync/store-merge.d.ts +29 -0
  336. package/dist/sync/store-merge.js +137 -0
  337. package/dist/sync/task-merge.d.ts +22 -0
  338. package/dist/sync/task-merge.js +158 -0
  339. package/dist/task/github.js +1 -1
  340. package/dist/task/lifecycle.d.ts +5 -0
  341. package/dist/task/lifecycle.js +67 -23
  342. package/dist/terminal-text.d.ts +5 -0
  343. package/dist/terminal-text.js +11 -0
  344. package/dist/test-global-setup.js +7 -0
  345. package/dist/tool-registry.d.ts +1 -1
  346. package/dist/tool-registry.js +3 -1
  347. package/dist/tools/code.d.ts +3 -0
  348. package/dist/tools/code.js +186 -0
  349. package/dist/tools/config.js +8 -0
  350. package/dist/tools/data.js +14 -7
  351. package/dist/tools/dispatch.d.ts +2 -0
  352. package/dist/tools/dispatch.js +66 -0
  353. package/dist/tools/finding.d.ts +11 -0
  354. package/dist/tools/finding.js +180 -123
  355. package/dist/tools/ops.js +5 -2
  356. package/dist/tools/search.js +21 -8
  357. package/dist/tools/session.js +21 -22
  358. package/dist/tools/tasks.js +8 -2
  359. package/dist/tools/types.d.ts +2 -2
  360. package/dist/tools/types.js +2 -2
  361. package/dist/ui/assets.js +1 -1
  362. package/dist/ui/data.js +14 -15
  363. package/dist/ui/deep-void.d.ts +1 -1
  364. package/dist/ui/deep-void.js +0 -1
  365. package/dist/ui/graph-chrome.d.ts +1 -1
  366. package/dist/ui/graph-chrome.js +51 -0
  367. package/dist/ui/page.js +5 -5
  368. package/dist/ui/scripts.js +67 -30
  369. package/dist/ui/server.js +52 -7
  370. package/dist/update.js +22 -11
  371. package/dist/utils-fts.js +1 -0
  372. package/dist/utils-helpers.d.ts +7 -0
  373. package/dist/utils-helpers.js +17 -0
  374. package/dist/utils.d.ts +1 -1
  375. package/dist/utils.js +1 -1
  376. package/package.json +49 -7
  377. package/plugins/opencode/phren-transcript.js +340 -0
  378. package/starter/README.md +4 -4
  379. package/starter/global/{CLAUDE.md → AGENTS.md} +2 -2
  380. package/starter/global/skills/conductor/SKILL.md +106 -0
  381. package/starter/global/skills/fanout/SKILL.md +20 -0
  382. package/starter/global/skills/phren-discover/SKILL.md +6 -6
  383. package/starter/global/skills/phren-init/SKILL.md +4 -4
  384. package/starter/global/skills/phren-sync/SKILL.md +3 -3
  385. package/starter/templates/frontend/reference/README.md +1 -1
  386. package/starter/templates/library/reference/README.md +1 -1
  387. package/starter/templates/monorepo/reference/README.md +1 -1
  388. package/starter/templates/python-project/reference/README.md +1 -1
  389. /package/starter/templates/frontend/{CLAUDE.md → AGENTS.md} +0 -0
  390. /package/starter/templates/library/{CLAUDE.md → AGENTS.md} +0 -0
  391. /package/starter/templates/monorepo/{CLAUDE.md → AGENTS.md} +0 -0
  392. /package/starter/templates/python-project/{CLAUDE.md → AGENTS.md} +0 -0
@@ -0,0 +1,11 @@
1
+ /**
2
+ * Governance enum values, kept in a dependency-free module so the profile store
3
+ * (and through it the phone Hook's module gating) does not pull the whole
4
+ * governance policy, hooks installer and file-lock machinery.
5
+ */
6
+ export declare const VALID_PROACTIVITY_LEVELS: readonly ["high", "medium", "low"];
7
+ export declare const VALID_TASK_MODES: readonly ["off", "manual", "suggest", "auto"];
8
+ export type TaskMode = typeof VALID_TASK_MODES[number];
9
+ export declare const VALID_FINDING_SENSITIVITY: readonly ["minimal", "conservative", "balanced", "aggressive"];
10
+ export type FindingSensitivityLevel = typeof VALID_FINDING_SENSITIVITY[number];
11
+ export declare const VALID_RISKY_SECTIONS: readonly ["Review", "Stale", "Conflicts"];
@@ -0,0 +1,9 @@
1
+ /**
2
+ * Governance enum values, kept in a dependency-free module so the profile store
3
+ * (and through it the phone Hook's module gating) does not pull the whole
4
+ * governance policy, hooks installer and file-lock machinery.
5
+ */
6
+ export const VALID_PROACTIVITY_LEVELS = ["high", "medium", "low"];
7
+ export const VALID_TASK_MODES = ["off", "manual", "suggest", "auto"];
8
+ export const VALID_FINDING_SENSITIVITY = ["minimal", "conservative", "balanced", "aggressive"];
9
+ export const VALID_RISKY_SECTIONS = ["Review", "Stale", "Conflicts"];
@@ -36,7 +36,7 @@ export interface IndexPolicy {
36
36
  * could go two months without syncing while every Stop hook looked healthy.
37
37
  * Failures now get their own values:
38
38
  *
39
- * - `pull-failed` — the pull/rebase leg failed, so push never ran
39
+ * - `pull-failed` - the fetch/merge leg failed, so push never ran
40
40
  * - `push-failed` — push was attempted and rejected
41
41
  * - `unrelated-histories` — local and remote share no merge base; no amount of
42
42
  * retrying will fix it, so it is called out by name
@@ -79,6 +79,9 @@ export interface RuntimeHealth {
79
79
  consecutiveFailures?: number;
80
80
  /** Last time a push actually reached the remote. */
81
81
  lastSuccessfulPushAt?: string;
82
+ /** Commits ahead of and behind the upstream tracking ref at the last sync outcome. */
83
+ ahead?: number;
84
+ behind?: number;
82
85
  };
83
86
  }
84
87
  export type SyncStatus = NonNullable<RuntimeHealth["lastSync"]>;
@@ -136,12 +139,7 @@ export interface ResolvedConfig {
136
139
  retentionPolicy: RetentionPolicy;
137
140
  workflowPolicy: WorkflowPolicy;
138
141
  }
139
- export declare const VALID_PROACTIVITY_LEVELS: readonly ["high", "medium", "low"];
140
- export declare const VALID_TASK_MODES: readonly ["off", "manual", "suggest", "auto"];
141
- export type TaskMode = typeof VALID_TASK_MODES[number];
142
- export declare const VALID_FINDING_SENSITIVITY: readonly ["minimal", "conservative", "balanced", "aggressive"];
143
- export type FindingSensitivityLevel = typeof VALID_FINDING_SENSITIVITY[number];
144
- export declare const VALID_RISKY_SECTIONS: readonly ["Review", "Stale", "Conflicts"];
142
+ export { VALID_PROACTIVITY_LEVELS, VALID_TASK_MODES, type TaskMode, VALID_FINDING_SENSITIVITY, type FindingSensitivityLevel, VALID_RISKY_SECTIONS, } from "./policy-constants.js";
145
143
  export declare function getProjectConfigOverrides(phrenPath: string, projectName: string): ProjectConfigOverrides | null;
146
144
  export declare function mergeConfig(phrenPath: string, projectName?: string, profile?: string): ResolvedConfig;
147
145
  export declare function getRetentionPolicy(phrenPath: string, projectName?: string): RetentionPolicy;
@@ -194,4 +192,3 @@ export interface PruneMemoriesResult {
194
192
  */
195
193
  export declare function pruneDeadMemories(phrenPath: string, project?: string, dryRun?: boolean): PhrenResult<PruneMemoriesResult>;
196
194
  export declare function consolidateProjectFindings(phrenPath: string, project: string, dryRun?: boolean): PhrenResult<string>;
197
- export {};
@@ -9,6 +9,7 @@ import { readProjectConfig } from "../project-config.js";
9
9
  import { getActiveProfileDefaults } from "../profile-store.js";
10
10
  import { runCustomHooks } from "../hooks.js";
11
11
  import { METADATA_REGEX, isCitationLine, isArchiveStart as isArchiveStartMeta, isArchiveEnd as isArchiveEndMeta, stripLifecycleMetadata as stripLifecycleMetadataMeta, } from "../content/metadata.js";
12
+ import { VALID_FINDING_SENSITIVITY, VALID_PROACTIVITY_LEVELS, VALID_TASK_MODES, VALID_RISKY_SECTIONS, } from "./policy-constants.js";
12
13
  /** @internal Exported for tests. */
13
14
  export const MAX_QUEUE_ENTRY_LENGTH = 500;
14
15
  export const PUSH_STATUSES = [
@@ -104,7 +105,7 @@ export const DEFAULT_INDEX_POLICY = {
104
105
  // Skills are instructions you invoke by name, not knowledge to retrieve:
105
106
  // indexed, they crowd the findings out of a prompt's context budget (nine of
106
107
  // twelve injections in one session were skill files). They stay reachable
107
- // through list_skills and the global CLAUDE.md.
108
+ // through list_skills and the global AGENTS.md.
108
109
  includeGlobs: ["**/*.md"],
109
110
  excludeGlobs: ["**/.git/**", "**/node_modules/**", "**/dist/**", "**/build/**", "**/skills/**", "**/.claude/skills/**"],
110
111
  includeHidden: false,
@@ -239,6 +240,10 @@ function normalizeRuntimeHealth(data) {
239
240
  normalized.lastSync.consecutiveFailures = data.lastSync.consecutiveFailures;
240
241
  if (typeof data.lastSync.lastSuccessfulPushAt === "string")
241
242
  normalized.lastSync.lastSuccessfulPushAt = data.lastSync.lastSuccessfulPushAt;
243
+ if (isFiniteNumber(data.lastSync.ahead))
244
+ normalized.lastSync.ahead = data.lastSync.ahead;
245
+ if (isFiniteNumber(data.lastSync.behind))
246
+ normalized.lastSync.behind = data.lastSync.behind;
242
247
  }
243
248
  return normalized;
244
249
  }
@@ -285,10 +290,7 @@ function normalizeIndexPolicy(data) {
285
290
  includeHidden: pickBoolean(data.includeHidden, DEFAULT_INDEX_POLICY.includeHidden),
286
291
  };
287
292
  }
288
- export const VALID_PROACTIVITY_LEVELS = ["high", "medium", "low"];
289
- export const VALID_TASK_MODES = ["off", "manual", "suggest", "auto"];
290
- export const VALID_FINDING_SENSITIVITY = ["minimal", "conservative", "balanced", "aggressive"];
291
- export const VALID_RISKY_SECTIONS = ["Review", "Stale", "Conflicts"];
293
+ export { VALID_PROACTIVITY_LEVELS, VALID_TASK_MODES, VALID_FINDING_SENSITIVITY, VALID_RISKY_SECTIONS, } from "./policy-constants.js";
292
294
  function pickEnum(value, allowed) {
293
295
  return typeof value === "string" && allowed.includes(value) ? value : undefined;
294
296
  }
@@ -815,7 +817,6 @@ function collectTtlExpiredEntries(file, project, ttlDays, lastRetrieval) {
815
817
  * filled up.
816
818
  */
817
819
  export function pruneDeadMemories(phrenPath, project, dryRun) {
818
- const policy = getRetentionPolicy(phrenPath);
819
820
  if (project && !isValidProjectName(project))
820
821
  return phrenErr(`Invalid project name: "${project}".`, PhrenError.INVALID_PROJECT_NAME);
821
822
  const dirs = project
@@ -825,12 +826,14 @@ export function pruneDeadMemories(phrenPath, project, dryRun) {
825
826
  })()
826
827
  : getProjectDirs(phrenPath).filter((dir) => path.basename(dir) !== "global");
827
828
  let pruned = 0;
828
- const cutoffDays = policy.retentionDays;
829
829
  const dryRunDetails = [];
830
830
  for (const dir of dirs) {
831
831
  const file = resolveFindingsPath(dir);
832
832
  if (!file)
833
833
  continue;
834
+ // Resolve per project: a project's own retentionDays override must win over
835
+ // the global window, as it already does on the injection path.
836
+ const cutoffDays = getRetentionPolicy(phrenPath, path.basename(dir)).retentionDays;
834
837
  // Q23: see docs/decisions/Q23-per-file-lock-concurrent-writers.md
835
838
  withFileLock(file, () => {
836
839
  const lines = fs.readFileSync(file, "utf8").split("\n");
@@ -892,7 +895,7 @@ export function pruneDeadMemories(phrenPath, project, dryRun) {
892
895
  if (!file)
893
896
  continue;
894
897
  const projectName = path.basename(dir);
895
- const expiredEntries = collectTtlExpiredEntries(file, projectName, policy.ttlDays, lastRetrieval);
898
+ const expiredEntries = collectTtlExpiredEntries(file, projectName, getRetentionPolicy(phrenPath, projectName).ttlDays, lastRetrieval);
896
899
  if (!expiredEntries.length)
897
900
  continue;
898
901
  ttlExpired += expiredEntries.length;
@@ -0,0 +1,24 @@
1
+ export type FreeSpaceViewport = {
2
+ width: number;
3
+ height: number;
4
+ topInset?: number;
5
+ /** Everything below the panel's top, including any tab bar inside the viewport. */
6
+ bottomInset: number;
7
+ gap?: number;
8
+ };
9
+ /** Center the node in the usable rectangle, reserving breathing room above the card. */
10
+ export declare function freeSpaceCenter(viewport: FreeSpaceViewport): {
11
+ x: number;
12
+ y: number;
13
+ };
14
+ /** Camera-plane offset whose perspective projection lands at the given pixel. */
15
+ export declare function perspectivePlaneOffset(point: {
16
+ x: number;
17
+ y: number;
18
+ }, viewport: {
19
+ width: number;
20
+ height: number;
21
+ }, depth: number, verticalFovDegrees: number, zoom?: number): {
22
+ x: number;
23
+ y: number;
24
+ };
@@ -0,0 +1,18 @@
1
+ /** Center the node in the usable rectangle, reserving breathing room above the card. */
2
+ export function freeSpaceCenter(viewport) {
3
+ const width = Math.max(1, viewport.width);
4
+ const height = Math.max(1, viewport.height);
5
+ const top = Math.min(height, Math.max(0, viewport.topInset ?? 0));
6
+ const bottom = Math.max(top, height - Math.max(0, viewport.bottomInset) - Math.max(0, viewport.gap ?? 24));
7
+ return { x: width / 2, y: (top + bottom) / 2 };
8
+ }
9
+ /** Camera-plane offset whose perspective projection lands at the given pixel. */
10
+ export function perspectivePlaneOffset(point, viewport, depth, verticalFovDegrees, zoom = 1) {
11
+ const width = Math.max(1, viewport.width);
12
+ const height = Math.max(1, viewport.height);
13
+ const halfHeight = depth * Math.tan(verticalFovDegrees * Math.PI / 360) / zoom;
14
+ return {
15
+ x: (point.x * 2 / width - 1) * halfHeight * width / height,
16
+ y: (1 - point.y * 2 / height) * halfHeight,
17
+ };
18
+ }
@@ -1,2 +1,4 @@
1
1
  export * from "./types.js";
2
2
  export * from "./model.js";
3
+ export * from "./labels.js";
4
+ export * from "./camera.js";
@@ -1,2 +1,4 @@
1
1
  export * from "./types.js";
2
2
  export * from "./model.js";
3
+ export * from "./labels.js";
4
+ export * from "./camera.js";
@@ -0,0 +1,77 @@
1
+ /**
2
+ * Screen-space label collision resolution shared by the browser 3D viewer
3
+ * (and unit-testable without a DOM). Pure rectangle logic: hosts project
4
+ * their labels to screen space, call `resolveLabelOverlaps` each frame, and
5
+ * hide whatever comes back outside the returned set.
6
+ *
7
+ * Must stay free of DOM, node builtins, and imports outside `src/graph-core/`.
8
+ */
9
+ export type LabelRect = {
10
+ x0: number;
11
+ y0: number;
12
+ x1: number;
13
+ y1: number;
14
+ };
15
+ export type LabelCandidate = {
16
+ id: string;
17
+ rect: LabelRect;
18
+ /** Project/group labels: always outrank leaves and never yield to them. */
19
+ isGroup: boolean;
20
+ /** Node degree; higher wins within a tier after `priority` and stickiness. */
21
+ degree: number;
22
+ /** Recency in ms (newer first); tie-break after `degree`. */
23
+ recency: number;
24
+ /** Focus/hover/search boost applied before stickiness within a tier. */
25
+ priority?: number;
26
+ };
27
+ export type LabelResolveOptions = {
28
+ /**
29
+ * Maximum labels (groups and leaves together) kept this frame, scaled to
30
+ * the viewport by the host. Groups sort first so landmarks claim slots
31
+ * before leaves; `labelDrawCap`'s floor keeps a typical project count
32
+ * drawable on a phone-sized canvas.
33
+ */
34
+ cap: number;
35
+ /** Ids visible last frame; sticky under hysteresis and cap pressure. */
36
+ previousVisible?: ReadonlySet<string>;
37
+ /** Extra pixels between rectangles (readability margin). Default 0. */
38
+ pad?: number;
39
+ /**
40
+ * Show/hide dead band in pixels, leaf-versus-leaf only: a previously-visible
41
+ * leaf shrinks by this before testing (marginal overlaps do not drop it), a
42
+ * newly shown leaf expands by this (it needs clearance to appear). Leaves
43
+ * always yield to groups on an exact intersection. Default 3.
44
+ */
45
+ hysteresisPx?: number;
46
+ /**
47
+ * Cleared and filled with the visible ids instead of allocating a new Set.
48
+ * Must not be the same object as `previousVisible` (the previous set is
49
+ * read while `into` is written).
50
+ */
51
+ into?: Set<string>;
52
+ };
53
+ export type LabelDrawCapOptions = {
54
+ /** Pixel area divisor: one label slot per `areaPerLabel` pixels squared. */
55
+ areaPerLabel?: number;
56
+ min?: number;
57
+ max?: number;
58
+ };
59
+ export declare function rectsIntersect(a: LabelRect, b: LabelRect): boolean;
60
+ /**
61
+ * Viewport-scaled budget for labels drawn in one frame. Groups count toward
62
+ * the cap; the default floor of 40 keeps a full project navigator (up to the
63
+ * survey's 40-project stores) drawable on a phone-sized viewport where pure
64
+ * area scaling would allow only ~29 slots.
65
+ */
66
+ export declare function labelDrawCap(width: number, height: number, options?: LabelDrawCapOptions): number;
67
+ /**
68
+ * Greedy placement in rank order. Group labels always win: they are placed
69
+ * first with exact rectangles and a leaf that intersects any group is hidden.
70
+ * Within a tier `priority`, stickiness, then degree, then recency decide.
71
+ * Leaf-versus-leaf conflicts use `hysteresisPx` so a shown label does not
72
+ * flicker out on a marginal overlap while a new label needs clearance before
73
+ * it appears. Duplicate ids keep the first candidate. The cap counts every
74
+ * label; when it is full the loop `continue`s (never `break`s) so a group
75
+ * that somehow sorts late is still tested rather than abandoned mid-list.
76
+ */
77
+ export declare function resolveLabelOverlaps(candidates: readonly LabelCandidate[], options: LabelResolveOptions): Set<string>;
@@ -0,0 +1,124 @@
1
+ /**
2
+ * Screen-space label collision resolution shared by the browser 3D viewer
3
+ * (and unit-testable without a DOM). Pure rectangle logic: hosts project
4
+ * their labels to screen space, call `resolveLabelOverlaps` each frame, and
5
+ * hide whatever comes back outside the returned set.
6
+ *
7
+ * Must stay free of DOM, node builtins, and imports outside `src/graph-core/`.
8
+ */
9
+ function expand(rect, by) {
10
+ if (by <= 0)
11
+ return rect;
12
+ return { x0: rect.x0 - by, y0: rect.y0 - by, x1: rect.x1 + by, y1: rect.y1 + by };
13
+ }
14
+ function shrink(rect, by) {
15
+ if (by <= 0)
16
+ return rect;
17
+ const x0 = rect.x0 + by;
18
+ const y0 = rect.y0 + by;
19
+ const x1 = rect.x1 - by;
20
+ const y1 = rect.y1 - by;
21
+ // Degenerate after erosion: report an empty rect, never an inverted one
22
+ // (an inverted rect can falsely "intersect" a large neighbour).
23
+ if (x1 <= x0 || y1 <= y0)
24
+ return { x0: 0, y0: 0, x1: 0, y1: 0 };
25
+ return { x0, y0, x1, y1 };
26
+ }
27
+ export function rectsIntersect(a, b) {
28
+ if (a.x1 <= a.x0 || a.y1 <= a.y0 || b.x1 <= b.x0 || b.y1 <= b.y0)
29
+ return false;
30
+ return a.x0 < b.x1 && a.x1 > b.x0 && a.y0 < b.y1 && a.y1 > b.y0;
31
+ }
32
+ /**
33
+ * Viewport-scaled budget for labels drawn in one frame. Groups count toward
34
+ * the cap; the default floor of 40 keeps a full project navigator (up to the
35
+ * survey's 40-project stores) drawable on a phone-sized viewport where pure
36
+ * area scaling would allow only ~29 slots.
37
+ */
38
+ export function labelDrawCap(width, height, options = {}) {
39
+ const areaPerLabel = options.areaPerLabel ?? 10000;
40
+ const min = options.min ?? 40;
41
+ const max = options.max ?? 72;
42
+ const area = Math.max(1, width) * Math.max(1, height);
43
+ return Math.min(max, Math.max(min, Math.round(area / areaPerLabel)));
44
+ }
45
+ function compareLabels(a, b, previous) {
46
+ // Invariant: `isGroup` first. The shared budget then always fills with
47
+ // landmark groups before any leaf, so a comparator tweak that lifts
48
+ // `priority` above `isGroup` cannot starve groups at the cap edge.
49
+ if (a.isGroup !== b.isGroup)
50
+ return a.isGroup ? -1 : 1;
51
+ const pa = a.priority ?? 0;
52
+ const pb = b.priority ?? 0;
53
+ if (pa !== pb)
54
+ return pb - pa;
55
+ // Stickiness before degree/recency: a shown label holds its slot under cap
56
+ // pressure and rank churn instead of flickering out and needing clearance
57
+ // to return.
58
+ const sa = previous?.has(a.id) ? 1 : 0;
59
+ const sb = previous?.has(b.id) ? 1 : 0;
60
+ if (sa !== sb)
61
+ return sb - sa;
62
+ if (a.degree !== b.degree)
63
+ return b.degree - a.degree;
64
+ if (a.recency !== b.recency)
65
+ return b.recency - a.recency;
66
+ return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
67
+ }
68
+ // Reused across calls so a 60fps host does not allocate a sort buffer per frame.
69
+ const scratchOrdered = [];
70
+ const scratchSeen = new Set();
71
+ /**
72
+ * Greedy placement in rank order. Group labels always win: they are placed
73
+ * first with exact rectangles and a leaf that intersects any group is hidden.
74
+ * Within a tier `priority`, stickiness, then degree, then recency decide.
75
+ * Leaf-versus-leaf conflicts use `hysteresisPx` so a shown label does not
76
+ * flicker out on a marginal overlap while a new label needs clearance before
77
+ * it appears. Duplicate ids keep the first candidate. The cap counts every
78
+ * label; when it is full the loop `continue`s (never `break`s) so a group
79
+ * that somehow sorts late is still tested rather than abandoned mid-list.
80
+ */
81
+ export function resolveLabelOverlaps(candidates, options) {
82
+ const previous = options.previousVisible;
83
+ const pad = options.pad ?? 0;
84
+ const hyst = options.hysteresisPx ?? 3;
85
+ const cap = Math.max(0, options.cap);
86
+ const into = options.into ?? new Set();
87
+ into.clear();
88
+ scratchOrdered.length = 0;
89
+ for (const candidate of candidates)
90
+ scratchOrdered.push(candidate);
91
+ scratchOrdered.sort((a, b) => compareLabels(a, b, previous));
92
+ scratchSeen.clear();
93
+ const placed = [];
94
+ for (const candidate of scratchOrdered) {
95
+ if (into.size >= cap)
96
+ continue;
97
+ if (scratchSeen.has(candidate.id))
98
+ continue;
99
+ scratchSeen.add(candidate.id);
100
+ const rect = expand(candidate.rect, pad);
101
+ const wasVisible = previous?.has(candidate.id) ?? false;
102
+ let blocked = false;
103
+ for (const p of placed) {
104
+ if (candidate.isGroup || p.isGroup) {
105
+ // Cross-tier and group-versus-group: exact rectangles only.
106
+ if (rectsIntersect(rect, p.rect)) {
107
+ blocked = true;
108
+ break;
109
+ }
110
+ continue;
111
+ }
112
+ const test = wasVisible ? shrink(rect, hyst) : expand(rect, hyst);
113
+ if (rectsIntersect(test, p.rect)) {
114
+ blocked = true;
115
+ break;
116
+ }
117
+ }
118
+ if (!blocked) {
119
+ into.add(candidate.id);
120
+ placed.push({ rect, isGroup: candidate.isGroup });
121
+ }
122
+ }
123
+ return into;
124
+ }
@@ -82,3 +82,16 @@ export interface SearchMatches {
82
82
  export declare function recomputeSearchMatches(visibleNodes: RuntimeNode[], query: string, filters: GraphFilters, scores: ScoreMap): SearchMatches;
83
83
  /** The best search hit for Enter-to-fly: first of the ranked results. */
84
84
  export declare function bestSearchMatch(results: RuntimeNode[]): RuntimeNode | null;
85
+ /**
86
+ * The dossier's ranked walk through one project: findings newest date first
87
+ * (payload order breaks ties), then tasks in payload order. That is the order
88
+ * the Memory list shows rows for the project, so Previous/Next and the
89
+ * keyboard arrows land where a reader scrolling the list would.
90
+ */
91
+ export declare function rankedProjectIds(nodes: readonly RawNode[], project: string): string[];
92
+ /**
93
+ * Previous/next id in a ranked list, wrapping at both ends. The list is the
94
+ * host's own order (the Memory list, the contents pane); `delta` is -1 or +1.
95
+ * Returns null for an empty list or an id that is not in it.
96
+ */
97
+ export declare function stepRanked(rankedIds: readonly string[], currentId: string, delta: number): string | null;
@@ -443,3 +443,36 @@ export function recomputeSearchMatches(visibleNodes, query, filters, scores) {
443
443
  export function bestSearchMatch(results) {
444
444
  return results.length ? results[0] : null;
445
445
  }
446
+ /**
447
+ * The dossier's ranked walk through one project: findings newest date first
448
+ * (payload order breaks ties), then tasks in payload order. That is the order
449
+ * the Memory list shows rows for the project, so Previous/Next and the
450
+ * keyboard arrows land where a reader scrolling the list would.
451
+ */
452
+ export function rankedProjectIds(nodes, project) {
453
+ const findings = nodes.filter((node) => node.project === project && deriveKind(node) === "finding");
454
+ findings.sort((a, b) => {
455
+ const left = a.date || "";
456
+ const right = b.date || "";
457
+ if (left === right)
458
+ return 0;
459
+ return left > right ? -1 : 1;
460
+ });
461
+ const tasks = nodes.filter((node) => node.project === project && deriveKind(node) === "task");
462
+ return [...findings, ...tasks].map((node) => node.id);
463
+ }
464
+ /**
465
+ * Previous/next id in a ranked list, wrapping at both ends. The list is the
466
+ * host's own order (the Memory list, the contents pane); `delta` is -1 or +1.
467
+ * Returns null for an empty list or an id that is not in it.
468
+ */
469
+ export function stepRanked(rankedIds, currentId, delta) {
470
+ if (rankedIds.length === 0)
471
+ return null;
472
+ const index = rankedIds.indexOf(currentId);
473
+ if (index < 0)
474
+ return null;
475
+ const total = rankedIds.length;
476
+ const next = (((index + delta) % total) + total) % total;
477
+ return rankedIds[next];
478
+ }
@@ -38,6 +38,8 @@ export type RawNode = {
38
38
  topicLabel?: string;
39
39
  findingCount?: number;
40
40
  taskCount?: number;
41
+ /** The number beside a project's label for the active filter (the phone sets it). */
42
+ labelCount?: number;
41
43
  };
42
44
  /**
43
45
  * Edge flavour. Absent (or "star") is the default project→leaf spoke the web
@@ -0,0 +1,7 @@
1
+ /** The user's home: an absolute `HOME` when set (tests and POSIX), else
2
+ * `USERPROFILE`, else the OS's answer. `os.homedir()` ignores `HOME` on Windows. */
3
+ export declare function homeDir(env?: NodeJS.ProcessEnv): string;
4
+ /** Claude Code's config directory: `CLAUDE_CONFIG_DIR`, else `~/.claude`. */
5
+ export declare function claudeConfigDir(env?: NodeJS.ProcessEnv): string;
6
+ /** Codex's home: `CODEX_HOME`, else `~/.codex`. */
7
+ export declare function codexHome(env?: NodeJS.ProcessEnv): string;
@@ -0,0 +1,21 @@
1
+ // The user's home and the agent config directories under it. Node builtins
2
+ // only: the Hook bundle reads these on cold start.
3
+ import { homedir } from "node:os";
4
+ import path from "node:path";
5
+ /** The user's home: an absolute `HOME` when set (tests and POSIX), else
6
+ * `USERPROFILE`, else the OS's answer. `os.homedir()` ignores `HOME` on Windows. */
7
+ export function homeDir(env = process.env) {
8
+ return env.HOME && path.isAbsolute(env.HOME) ? env.HOME : env.USERPROFILE || homedir();
9
+ }
10
+ function configuredDir(value, env, fallback) {
11
+ const configured = value?.trim();
12
+ return configured ? path.resolve(configured) : path.join(homeDir(env), fallback);
13
+ }
14
+ /** Claude Code's config directory: `CLAUDE_CONFIG_DIR`, else `~/.claude`. */
15
+ export function claudeConfigDir(env = process.env) {
16
+ return configuredDir(env.CLAUDE_CONFIG_DIR, env, ".claude");
17
+ }
18
+ /** Codex's home: `CODEX_HOME`, else `~/.codex`. */
19
+ export function codexHome(env = process.env) {
20
+ return configuredDir(env.CODEX_HOME, env, ".codex");
21
+ }
package/dist/hooks.d.ts CHANGED
@@ -14,21 +14,6 @@ export declare function detectInstalledTools(): Set<string>;
14
14
  * re-resolves on every run) or the ~/.local/bin/phren wrapper instead.
15
15
  */
16
16
  export declare function isEphemeralNpxPath(p: string): boolean;
17
- /**
18
- * The local file a hook command depends on — the `~/.local/bin/phren` wrapper,
19
- * or the script passed to `node`.
20
- *
21
- * Returns `null` for commands that re-resolve themselves on every run
22
- * (`npx -y @phren/cli …`), which cannot go stale, and for commands with no
23
- * recognisable path.
24
- *
25
- * Why this matters: `npm install -g @phren/cli` can move the package entry
26
- * between versions (0.1.40 moved it from `mcp/dist/index.js` to
27
- * `dist/index.js`). Hook commands in settings.json keep the old absolute path
28
- * and every hook then dies with MODULE_NOT_FOUND on every prompt and every
29
- * Stop — silently, because hook failures are not surfaced.
30
- */
31
- export declare function extractHookScriptPath(command: string): string | null;
32
17
  /**
33
18
  * Hook commands whose entrypoint no longer exists on disk. Deduplicated, so an
34
19
  * upgrade that breaks all four lifecycle hooks reports one path, not four.
@@ -81,6 +66,9 @@ export declare function ensureLocalBinOnWindowsPath(): "added" | "already" | "sk
81
66
  * `phren` command works without a global npm install. The wrapper simply execs
82
67
  * `node <entry_script> "$@"`.
83
68
  */
69
+ /** Whether a wrapper may be rewritten for `entry`: always, unless `entry` is
70
+ * an ephemeral npx copy and the wrapper already runs a lasting entry that exists. */
71
+ export declare function keepsWrapperEntry(existing: string, entry: string, exists?: (file: string) => boolean): boolean;
84
72
  export declare function installPhrenCliWrapper(phrenPath: string): boolean;
85
73
  export interface HookToolPreferences {
86
74
  claude?: boolean;
package/dist/hooks.js CHANGED
@@ -133,7 +133,7 @@ function isPathLike(token) {
133
133
  * and every hook then dies with MODULE_NOT_FOUND on every prompt and every
134
134
  * Stop — silently, because hook failures are not surfaced.
135
135
  */
136
- export function extractHookScriptPath(command) {
136
+ function extractHookScriptPath(command) {
137
137
  if (!command)
138
138
  return null;
139
139
  // `npx` re-resolves the package each run, so it is never stale.
@@ -488,6 +488,14 @@ try {
488
488
  * `phren` command works without a global npm install. The wrapper simply execs
489
489
  * `node <entry_script> "$@"`.
490
490
  */
491
+ /** Whether a wrapper may be rewritten for `entry`: always, unless `entry` is
492
+ * an ephemeral npx copy and the wrapper already runs a lasting entry that exists. */
493
+ export function keepsWrapperEntry(existing, entry, exists = fs.existsSync) {
494
+ if (!isEphemeralNpxPath(entry))
495
+ return true;
496
+ const current = [...existing.matchAll(/exec node '([^']+)'/g)].map(match => match[1]);
497
+ return !current.some(file => !isEphemeralNpxPath(file) && exists(file));
498
+ }
491
499
  export function installPhrenCliWrapper(phrenPath) {
492
500
  const isWindows = process.platform === "win32";
493
501
  const entry = resolveCliEntryScript();
@@ -501,6 +509,11 @@ export function installPhrenCliWrapper(phrenPath) {
501
509
  const existing = fs.readFileSync(wrapperPath, "utf8");
502
510
  if (!existing.includes("PHREN_CLI_WRAPPER"))
503
511
  return false;
512
+ // A one-off `npx @phren/cli` run must not repoint a wrapper that runs a
513
+ // lasting install (a checkout's build, a global package): the npx copy
514
+ // is older more often than not and its cache can vanish.
515
+ if (!keepsWrapperEntry(existing, entry))
516
+ return false;
504
517
  }
505
518
  catch {
506
519
  // File exists but unreadable — don't overwrite, could be a real binary
package/dist/index.js CHANGED
@@ -4,12 +4,15 @@ import * as path from "path";
4
4
  import { findPhrenPathWithArg, debugLog, ensureFtsCacheRootPrivate, runtimeDir, } from "./shared.js";
5
5
  import { log as structuredLog, logger } from "./logger.js";
6
6
  import { errorMessage } from "./utils.js";
7
+ import { nonInteractiveGitEnv } from "./utils-helpers.js";
7
8
  import { printIntegratedHelp, printIntegratedVersion, resolveTopLevelInvocation, runTopLevelCommand, } from "./entrypoint.js";
8
9
  // NOTE: the MCP-server-only module graph (MCP SDK, FTS indexer, tool registries,
9
10
  // startup-embedding, custom-hook engine) is intentionally NOT imported here. It is
10
11
  // dynamically imported inside main() so that top-level commands — hook-prompt,
11
12
  // --version, --help — which never reach main() do not pay its ~1.8s cold-start cost.
12
13
  // This matters most for the PostToolUse `hook-tool`, which spawns per tool call.
14
+ // Covers inherited Git subprocesses, including commands launched by plugins.
15
+ Object.assign(process.env, nonInteractiveGitEnv());
13
16
  const invocation = resolveTopLevelInvocation(process.argv.slice(2));
14
17
  if (invocation.kind === "help") {
15
18
  printIntegratedHelp();
@@ -80,6 +83,14 @@ async function main() {
80
83
  import("./package-metadata.js"),
81
84
  ]);
82
85
  const profile = resolveRuntimeProfile(phrenPath);
86
+ const { activateModules: moduleSnapshot } = await import("./modules/runtime.js");
87
+ const { BUILTIN_MODULES, toolOwner, disabledHint } = await import("./modules/registry.js");
88
+ const { resolveAllStores } = await import("./store-registry.js");
89
+ const { resolveStoreForProject } = await import("./tools/types.js");
90
+ const snapshots = new Map(resolveAllStores(phrenPath).filter(store => store.available !== false)
91
+ .map(store => [store.path, moduleSnapshot(store.path, profile)]));
92
+ const enabledModules = BUILTIN_MODULES.filter(module => [...snapshots.values()].some(snapshot => snapshot.has(module.name)));
93
+ const hasModule = (name) => enabledModules.some(module => module.name === name);
83
94
  cleanStaleLocks(phrenPath);
84
95
  // Before buildIndex() writes the first snapshot: the FTS cache is a full
85
96
  // SQLite export of the store, and on Linux it lands in a world-readable
@@ -187,6 +198,7 @@ async function main() {
187
198
  const mcpProfile = resolveMcpProfile(phrenPath);
188
199
  const gate = createToolGate({
189
200
  profile: mcpProfile,
201
+ modules: enabledModules,
190
202
  alwaysLoad: ALWAYS_LOAD_TOOLS,
191
203
  register: (name, config, handler) => origRegisterTool(name, config, handler),
192
204
  wrap: (registeredName, handler) => async (...args) => {
@@ -212,6 +224,13 @@ async function main() {
212
224
  }],
213
225
  };
214
226
  }
227
+ const owner = toolOwner(registeredName);
228
+ if (owner && owner.name !== "memory") {
229
+ const input = args[0];
230
+ const store = typeof input?.project === "string" ? resolveStoreForProject(ctx, input.project).phrenPath : phrenPath;
231
+ if (!snapshots.get(store)?.has(owner.name))
232
+ return mcpResponse({ ok: false, error: disabledHint(owner.name), errorCode: "UNAVAILABLE" });
233
+ }
215
234
  try {
216
235
  trackToolCall(phrenPath, registeredName);
217
236
  }
@@ -241,9 +260,10 @@ async function main() {
241
260
  };
242
261
  // Lazy-imported tool registries — only the MCP server needs them. Registration
243
262
  // order is irrelevant (each module registers a disjoint set of tools).
263
+ const codeAvailable = hasModule("code") && !!(await (await import("./modules/code-package.js")).loadCodePackage(phrenPath));
244
264
  const toolModules = await Promise.all([
245
265
  import("./tools/search.js"),
246
- import("./tools/tasks.js"),
266
+ ...(hasModule("tasks") ? [import("./tools/tasks.js")] : []),
247
267
  import("./tools/finding.js"),
248
268
  import("./tools/memory.js"),
249
269
  import("./tools/data.js"),
@@ -252,10 +272,12 @@ async function main() {
252
272
  import("./tools/ops.js"),
253
273
  import("./tools/skills.js"),
254
274
  import("./tools/hooks.js"),
255
- import("./tools/extract.js"),
275
+ ...(hasModule("git") ? [import("./tools/extract.js")] : []),
256
276
  import("./tools/config.js"),
257
277
  import("./tools/notes.js"),
258
278
  import("./tools/summaries.js"),
279
+ ...(codeAvailable ? [import("./tools/code.js")] : []),
280
+ ...(hasModule("conductor") ? [import("./tools/dispatch.js")] : []),
259
281
  ]);
260
282
  for (const mod of toolModules)
261
283
  mod.register(server, ctx);
@@ -17,7 +17,7 @@ export declare function looksLikePhrenRoot(candidate: string): boolean;
17
17
  export declare function isLiveForeignPhrenRoot(candidate: string, newPhrenPath: string): boolean;
18
18
  /**
19
19
  * Recover the phren root that owns a `~/.claude/CLAUDE.md` symlink, from the
20
- * link target's shape (`<root>/global/CLAUDE.md`). Returns null when the
20
+ * link target's shape (`<root>/global/AGENTS.md`). Returns null when the
21
21
  * target is not structured like a phren global file, i.e. it belongs to
22
22
  * something that is not phren and must not be touched.
23
23
  */