@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,250 @@
1
+ import * as fs from "node:fs";
2
+ import * as path from "node:path";
3
+ import * as yaml from "js-yaml";
4
+ import { z } from "zod";
5
+ import { VERSION } from "../package-metadata.js";
6
+ const core = (names) => names.map(name => ({ name, profiles: ["core", "full"] }));
7
+ const full = (names) => names.map(name => ({ name, profiles: ["full"] }));
8
+ const routes = (method, paths) => paths.map(path => ({ method, path }));
9
+ // DELETE is only used by conductor grants today; the manifest type stays open.
10
+ export const BUILTIN_MODULES = [
11
+ {
12
+ schemaVersion: 1, name: "memory", version: VERSION, defaultEnabled: true, requires: [],
13
+ tools: [
14
+ ...core(["search_knowledge", "get_memory_detail", "get_project_summary", "add_finding", "revise_finding", "session", "phren_admin"]),
15
+ ...full([
16
+ "list_projects", "get_findings", "store_list", "supersede_finding", "retract_finding",
17
+ "resolve_contradiction", "get_contradictions", "edit_finding", "remove_finding", "push_changes",
18
+ "pin_memory", "get_truths", "memory_feedback", "export_project", "import_project", "manage_project",
19
+ "search_fragments", "get_related_docs", "read_graph", "link_findings", "cross_project_fragments",
20
+ "session_start", "session_end", "session_context", "session_history",
21
+ "add_project", "health_check", "doctor_fix", "list_hook_errors", "get_review_queue", "manage_review_item",
22
+ "list_skills", "read_skill", "write_skill", "remove_skill", "toggle_skill",
23
+ "list_hooks", "toggle_hooks", "add_custom_hook", "remove_custom_hook", "get_config", "set_config",
24
+ "get_notes", "add_note", "edit_note", "remove_note", "promote_note", "get_topic_summaries", "set_topic_summary",
25
+ ]),
26
+ ],
27
+ cliCommands: [
28
+ "init", "quickstart", "add", "projects", "search", "status", "doctor", "web-ui", "graph", "shell",
29
+ "add-finding", "pin", "review", "session-context", "sessions", "finding", "note", "notes",
30
+ "search-fragments", "related-docs", "truths", "promote", "skills", "detect-skills", "hooks", "config",
31
+ "maintain", "consolidation-status", "quality-feedback", "mcp-mode", "hooks-mode", "preset", "snippet",
32
+ "verify", "uninstall", "update", "profile", "store", "team", "modules list", "modules enable", "modules disable",
33
+ "hook-prompt", "hook-session-start", "hook-stop", "hook-context", "hook-tool", "background-sync",
34
+ "background-maintenance", "background-reindex", "debug-injection", "inspect-index", "skill-list",
35
+ "policy", "workflow", "index-policy", "govern-memories", "prune-memories", "consolidate-memories", "link",
36
+ ],
37
+ agentHooks: [
38
+ { agents: ["claude", "codex", "copilot", "cursor"], events: ["SessionStart"], handler: "phren hook-session-start" },
39
+ { agents: ["claude", "codex", "copilot", "cursor"], events: ["UserPromptSubmit"], handler: "phren hook-prompt" },
40
+ { agents: ["claude", "codex", "copilot", "cursor"], events: ["Stop"], handler: "phren hook-stop" },
41
+ { agents: ["claude"], events: ["PostToolUse"], handler: "phren hook-tool" },
42
+ ],
43
+ hookRoutes: [], capabilities: ["memory"],
44
+ storeFiles: [
45
+ "phren.root.yaml", "machines.yaml", "profiles/*.yaml", ".config/modules.yaml", ".config/*.json",
46
+ "<project>/AGENTS.md", "<project>/summary.md", "<project>/FINDINGS.md", "<project>/truths.md",
47
+ "<project>/review.md", "<project>/notes/*.md", "<project>/reference/**", "<project>/skills/**",
48
+ "<project>/phren.project.yaml", "<project>/preferences.json", ".runtime/sessions/session-*.json",
49
+ ".runtime/sessions/last-summary.json",
50
+ ],
51
+ localFiles: [],
52
+ phoneScreens: [{ screen: "ProjectsView", capability: "memory" }, { screen: "SearchView", capability: "memory" }],
53
+ skills: ["phren-init", "phren-sync", "phren-profiles", "phren-discover", "phren-consolidate", "phren-summarize"],
54
+ },
55
+ {
56
+ schemaVersion: 1, name: "tasks", version: VERSION, defaultEnabled: false, requires: ["memory"],
57
+ tools: [
58
+ ...core(["get_tasks", "add_task", "manage_task"]),
59
+ ...full(["complete_task", "remove_task", "update_task", "tidy_done_tasks", "pin_task"]),
60
+ ],
61
+ cliCommands: ["task", "tasks", "config task-mode", "config proactivity.tasks"], agentHooks: [], hookRoutes: [], capabilities: ["tasks"],
62
+ storeFiles: ["<project>/tasks.md", ".sessions/checkpoint-*.json"], localFiles: [],
63
+ phoneScreens: [{ screen: "TasksView", capability: "tasks" }], skills: [],
64
+ },
65
+ {
66
+ schemaVersion: 1, name: "hook", version: VERSION, defaultEnabled: false, requires: ["memory"],
67
+ tools: [],
68
+ cliCommands: [
69
+ "bridge", "bridge install", "bridge update", "bridge uninstall", "bridge rollback", "bridge status",
70
+ "bridge doctor", "bridge usage", "bridge usage-statusline", "bridge hook", "bridge serve", "bridge ssh",
71
+ "bridge fanouts archive", "canary",
72
+ ],
73
+ agentHooks: [
74
+ { agents: ["codex", "claude"], events: ["SessionStart", "UserPromptSubmit", "Stop", "PermissionRequest"], handler: "bridge-hook.mjs hook <agent>" },
75
+ { agents: ["claude"], events: ["PreCompact"], handler: "bridge-hook.mjs hook claude" },
76
+ { agents: ["copilot"], events: ["SessionStart", "UserPromptSubmit"], handler: "bridge-hook.mjs hook copilot" },
77
+ ],
78
+ hookRoutes: [
79
+ ...routes("GET", [
80
+ "/v1/health", "/v1/health/details", "/v1/health/peers", "/v1/muxes", "/v1/activity", "/v1/metrics", "/v1/web-servers", "/v1/simulators",
81
+ "/v1/simulators/screenshot", "/v1/simulators/apps", "/v1/files", "/v1/models", "/v1/projects/files",
82
+ "/v1/uploads/image", "/v1/files/range", "/v1/usage", "/v1/push/status", "/v1/projects/locate", "/v1/projects/repos",
83
+ "/v1/workspaces", "/v1/workspaces/panes", "/v1/transcripts/blob", "/v1/transcripts/history",
84
+ "/v1/subagents", "/v1/subagents/transcript", "/v1/subagents/messages",
85
+ ]),
86
+ ...routes("POST", [
87
+ "/v1/push/register", "/v1/push/answer", "/v1/push/target", "/v1/files", "/v1/projects/add", "/v1/simulators/action",
88
+ "/v1/workspaces/launch", "/v1/workspaces/create", "/v1/workspaces/focus", "/v1/workspaces/rename",
89
+ "/v1/workspaces/close", "/v1/prompt", "/v1/model", "/v1/side-question/dismiss", "/v1/keys", "/v1/secret", "/v1/upload",
90
+ "/v1/approvals/answer", "/v1/questions/answer", "/v1/subagents/resume", "/v1/subagents/archive-finished", "/v1/canary",
91
+ "/v1/speech",
92
+ ]),
93
+ ...routes("WS", ["/v1/transcripts", "/v1/status", "/v1/overview", "/v1/speech/transcribe"]),
94
+ ],
95
+ capabilities: [
96
+ "hook", "transcript", "progress", "images", "prompt", "stop", "terminal", "shell", "herdr",
97
+ "webServers", "webPreview", "activity", "approvals", "questions", "accountUsage", "providers",
98
+ "files", "repositoryFiles", "subagents", "sideQuestions", "approvalPush", "simulators", "overviewStream", "speech", "transcribe",
99
+ ],
100
+ storeFiles: [".runtime/sessions/opencode-*.events.jsonl", ".runtime/approvals/opencode-*.json"],
101
+ localFiles: ["<bridge>/installed.json", "<bridge>/versions/**", "<bridge>/current", "<bridge>/dispatch", "<bridge>/computer-id", "<bridge>/canary.json", "<bridge>/canary-daily"],
102
+ phoneScreens: [{ screen: "LiveSessionsView", capability: "hook" }, { screen: "AgentChatView", capability: "transcript" }],
103
+ skills: [],
104
+ },
105
+ {
106
+ schemaVersion: 1, name: "git", version: VERSION, defaultEnabled: false, requires: ["memory"],
107
+ tools: full(["auto_extract_findings"]), cliCommands: ["maintain extract", "extract-memories"],
108
+ agentHooks: [
109
+ { agents: ["codex", "claude"], events: ["PreToolUse", "PostToolUse"], handler: "bridge-hook.mjs hook <agent>" },
110
+ ],
111
+ hookRoutes: routes("POST", [
112
+ "/v1/diff", "/v1/web-servers/session", "/v1/git/status", "/v1/git/log", "/v1/git/branches", "/v1/git/pulls",
113
+ "/v1/git/tree", "/v1/git/worktrees", "/v1/git/stage", "/v1/git/unstage", "/v1/git/discard",
114
+ "/v1/git/commit", "/v1/git/push", "/v1/git/pr",
115
+ ]),
116
+ capabilities: ["git", "diff"], storeFiles: [], localFiles: ["<bridge>/changes/**", "<bridge>/changes-scratch/**"],
117
+ phoneScreens: [{ screen: "AgentChangesView", capability: "git" }], skills: [],
118
+ },
119
+ {
120
+ schemaVersion: 1, name: "schedules", version: VERSION, defaultEnabled: false, requires: ["memory"],
121
+ tools: [], cliCommands: ["schedule"], agentHooks: [],
122
+ hookRoutes: routes("POST", ["/v1/schedules", "/v1/schedules/run", "/v1/schedules/history"]),
123
+ capabilities: ["schedules"], storeFiles: ["<project>/schedules.yaml", ".runtime/agent-fanouts/<run-id>/**"],
124
+ localFiles: ["<bridge>/schedule-runs.jsonl"],
125
+ phoneScreens: [{ screen: "SchedulesView", capability: "schedules" }], skills: [],
126
+ },
127
+ {
128
+ schemaVersion: 1, name: "conductor", version: VERSION, defaultEnabled: false, requires: ["memory", "hook"],
129
+ tools: full(["dispatch", "dispatch_returns", "hand_off", "live_sessions"]), cliCommands: ["dispatch", "dispatch status", "dispatch returns", "dispatch sessions", "hand-off", "conductor", "conductor grants", "bridge enroll-computer"], agentHooks: [],
130
+ hookRoutes: [...routes("GET", ["/v1/dispatch", "/v1/dispatch/capacity", "/v1/conductor/grants"]),
131
+ ...routes("POST", ["/v1/dispatch", "/v1/dispatch/workers", "/v1/dispatch/returns", "/v1/conductor/grants"]), ...routes("DELETE", ["/v1/conductor/grants"])],
132
+ capabilities: ["dispatch"], storeFiles: ["global/skills/conductor/**"],
133
+ localFiles: ["<bridge>/hooks.yaml", "<bridge>/conductor.yaml", "<bridge>/dispatches/*.json"], phoneScreens: [], skills: ["conductor"],
134
+ },
135
+ {
136
+ schemaVersion: 1, name: "fanout", version: VERSION, defaultEnabled: false, requires: ["memory", "hook"],
137
+ tools: [], cliCommands: ["fanout"], agentHooks: [], hookRoutes: [], capabilities: [],
138
+ storeFiles: [".config/fanout.yaml"], localFiles: ["<store>/.runtime/agent-fanouts/**"],
139
+ phoneScreens: [], skills: ["fanout"],
140
+ },
141
+ {
142
+ schemaVersion: 1, name: "code", version: VERSION, defaultEnabled: false, requires: ["memory"],
143
+ tools: full(["code_search", "code_definition", "code_references", "code_outline", "code_usage"]),
144
+ cliCommands: ["code index", "code status", "code search", "code outline", "code refs", "code def", "code usage"],
145
+ agentHooks: [],
146
+ hookRoutes: [...routes("GET", ["/v1/code/tree", "/v1/code/usage-page", "/v1/code/changed", "/v1/code/change-counts", "/v1/code/status", "/v1/code/search", "/v1/code/outline", "/v1/code/outline-summary", "/v1/code/file-references", "/v1/code/definition", "/v1/code/references", "/v1/code/usage"]), ...routes("POST", ["/v1/code/note", "/v1/code/reindex", "/v1/code/disable"])],
147
+ capabilities: ["code"],
148
+ storeFiles: [], localFiles: ["<store>/.runtime/code/*.sqlite"],
149
+ phoneScreens: [{ screen: "CodeView", capability: "code" }], skills: ["code"],
150
+ },
151
+ ];
152
+ const overrides = z.record(z.string(), z.boolean());
153
+ const configSchema = z.object({
154
+ version: z.literal(1),
155
+ enabled: overrides.optional(),
156
+ profiles: z.record(z.string(), z.object({ enabled: overrides.optional() }).strict()).optional(),
157
+ }).strict();
158
+ export function readConfig(store) {
159
+ let source;
160
+ try {
161
+ source = fs.readFileSync(path.join(store, ".config", "modules.yaml"), "utf8");
162
+ }
163
+ catch (error) {
164
+ if (error.code === "ENOENT")
165
+ return undefined;
166
+ throw new Error("Cannot read .config/modules.yaml.");
167
+ }
168
+ let config;
169
+ try {
170
+ config = configSchema.parse(yaml.load(source, { schema: yaml.CORE_SCHEMA }));
171
+ }
172
+ catch {
173
+ throw new Error("Invalid .config/modules.yaml: expected version: 1 and boolean module overrides.");
174
+ }
175
+ return validateConfig(config, true);
176
+ }
177
+ /** Warned once per process so serve's migrate-then-snapshot double read stays one line. */
178
+ const warnedUnknownModules = new Set();
179
+ /**
180
+ * Unknown keys belong to a newer CLI that enabled a module this build (the
181
+ * Hook) does not know; they are ignored, kept for writes, and warned about
182
+ * once instead of failing every Hook connection.
183
+ */
184
+ export function validateConfig(input, warnUnknown = false) {
185
+ const parsed = configSchema.safeParse(input);
186
+ if (!parsed.success)
187
+ throw new Error("Invalid .config/modules.yaml: expected version: 1 and boolean module overrides.");
188
+ const config = parsed.data;
189
+ const names = new Set(BUILTIN_MODULES.map(module => module.name));
190
+ const unknown = new Set();
191
+ for (const values of [config.enabled, ...Object.values(config.profiles ?? {}).map(profile => profile.enabled)]) {
192
+ for (const [name, value] of Object.entries(values ?? {})) {
193
+ if (!names.has(name)) {
194
+ unknown.add(name);
195
+ continue;
196
+ }
197
+ if (name === "memory" && !value)
198
+ throw new Error("The memory module cannot be disabled.");
199
+ }
200
+ }
201
+ for (const name of unknown) {
202
+ if (!warnUnknown || warnedUnknownModules.has(name))
203
+ continue;
204
+ warnedUnknownModules.add(name);
205
+ console.error(`warning: unknown module "${name}" in .config/modules.yaml ignored by Hook ${VERSION}`);
206
+ }
207
+ return config;
208
+ }
209
+ /** Reads never mutate configuration or enable dependencies implicitly. */
210
+ export function enabled(store, profile) {
211
+ return resolveModules(readConfig(store), profile);
212
+ }
213
+ export function resolveModules(config, profile) {
214
+ const selected = profile && config?.profiles && Object.hasOwn(config.profiles, profile) ? config.profiles[profile].enabled : undefined;
215
+ const modules = BUILTIN_MODULES.filter(module => selected?.[module.name] ?? config?.enabled?.[module.name] ?? module.defaultEnabled);
216
+ const names = new Set(modules.map(module => module.name));
217
+ for (const module of modules) {
218
+ for (const dependency of module.requires) {
219
+ if (!names.has(dependency))
220
+ throw new Error(`Module "${module.name}" requires enabled module "${dependency}".`);
221
+ }
222
+ }
223
+ return modules;
224
+ }
225
+ export function moduleSource(config, name, profile) {
226
+ if (profile && Object.hasOwn(config?.profiles ?? {}, profile) && Object.hasOwn(config?.profiles?.[profile].enabled ?? {}, name))
227
+ return "profile";
228
+ return Object.hasOwn(config?.enabled ?? {}, name) ? "store" : "default";
229
+ }
230
+ export function toolOwner(name) {
231
+ return BUILTIN_MODULES.find(module => module.tools.some(tool => tool.name === name));
232
+ }
233
+ export function commandOwner(command) {
234
+ command = command.toLowerCase();
235
+ let owner;
236
+ let length = 0;
237
+ for (const module of BUILTIN_MODULES)
238
+ for (const entry of module.cliCommands) {
239
+ if ((command === entry || command.startsWith(entry + " ")) && entry.length > length) {
240
+ owner = module;
241
+ length = entry.length;
242
+ }
243
+ }
244
+ return owner;
245
+ }
246
+ export function disabledHint(name) {
247
+ if (name === "code")
248
+ return "phren code needs @phren/code: run phren modules enable code";
249
+ return `module ${name} is disabled; enable it with phren modules enable ${name}`;
250
+ }
@@ -0,0 +1,15 @@
1
+ import type { ModuleManifest } from "./manifest.js";
2
+ export interface ModuleSnapshot {
3
+ store: string;
4
+ profile: string;
5
+ modules: readonly ModuleManifest[];
6
+ generation: string;
7
+ has(name: string): boolean;
8
+ }
9
+ export declare function moduleSnapshot(store: string, profile?: string, legacyHook?: boolean): ModuleSnapshot;
10
+ export declare function moduleEnabled(store: string, name: string, profile?: string): boolean;
11
+ export declare function requireModule(store: string, name: string, profile?: string): void;
12
+ export declare function migrateInstalledModules(store: string, legacyHook?: boolean): void;
13
+ /** The version in <bridge>/installed.json, or undefined when no Hook is installed. */
14
+ export declare function installedHookVersion(): string | undefined;
15
+ export declare function activateModules(store: string, profile?: string, legacyHook?: boolean): ModuleSnapshot;
@@ -0,0 +1,59 @@
1
+ import { createHash } from "node:crypto";
2
+ import * as fs from "node:fs";
3
+ import * as path from "node:path";
4
+ import { homedir } from "node:os";
5
+ import { resolveRuntimeProfile } from "../runtime-profile.js";
6
+ import { installPreferencesFile } from "../phren-paths.js";
7
+ import { migrateModules } from "./config.js";
8
+ import { BUILTIN_MODULES, resolveModules, disabledHint, readConfig } from "./registry.js";
9
+ /** The runtime profile for module gating; unscoped while a store is still being set up. */
10
+ function snapshotProfile(store) {
11
+ try {
12
+ return resolveRuntimeProfile(store);
13
+ }
14
+ catch {
15
+ return "";
16
+ }
17
+ }
18
+ export function moduleSnapshot(store, profile = snapshotProfile(store), legacyHook = false) {
19
+ const config = readConfig(store);
20
+ const hasStore = !!config || fs.existsSync(path.join(store, "phren.root.yaml")) || fs.existsSync(installPreferencesFile(store));
21
+ const modules = !hasStore && legacyHook
22
+ ? BUILTIN_MODULES.filter(module => ["hook", "git", "schedules", "conductor"].includes(module.name))
23
+ : resolveModules(config ?? (hasStore ? { version: 1, enabled: { tasks: true } } : undefined), profile);
24
+ const names = new Set(modules.map(module => module.name));
25
+ const generation = createHash("sha256").update(JSON.stringify([store, profile, modules.map(module => [module.name, module.version])])).digest("hex").slice(0, 16);
26
+ return { store, profile, modules, generation, has: name => names.has(name) };
27
+ }
28
+ export function moduleEnabled(store, name, profile) {
29
+ return moduleSnapshot(store, profile).has(name);
30
+ }
31
+ export function requireModule(store, name, profile) {
32
+ if (!moduleEnabled(store, name, profile))
33
+ throw new Error(disabledHint(name));
34
+ }
35
+ export function migrateInstalledModules(store, legacyHook = false) {
36
+ const hookRoot = process.env.PHREN_BRIDGE_HOME || path.join(homedir(), ".local", "share", "phren", "bridge");
37
+ const installedHook = legacyHook || fs.existsSync(path.join(hookRoot, "installed.json"));
38
+ // A store without .config was never set up; migration must not create it and
39
+ // make `phren add` believe the store is ready.
40
+ if (!fs.existsSync(path.join(store, ".config")))
41
+ return;
42
+ if (readConfig(store) || fs.existsSync(path.join(store, "phren.root.yaml")) || fs.existsSync(installPreferencesFile(store)))
43
+ migrateModules(store, installedHook);
44
+ }
45
+ /** The version in <bridge>/installed.json, or undefined when no Hook is installed. */
46
+ export function installedHookVersion() {
47
+ const hookRoot = process.env.PHREN_BRIDGE_HOME || path.join(homedir(), ".local", "share", "phren", "bridge");
48
+ try {
49
+ const parsed = JSON.parse(fs.readFileSync(path.join(hookRoot, "installed.json"), "utf8"));
50
+ return typeof parsed.version === "string" && parsed.version.trim() ? parsed.version.trim() : undefined;
51
+ }
52
+ catch {
53
+ return undefined;
54
+ }
55
+ }
56
+ export function activateModules(store, profile = snapshotProfile(store), legacyHook = false) {
57
+ migrateInstalledModules(store, legacyHook);
58
+ return moduleSnapshot(store, profile, legacyHook);
59
+ }
@@ -5,9 +5,17 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
5
5
  export const ROOT = path.join(__dirname, "..");
6
6
  const PACKAGE_JSON_PATH = path.join(ROOT, "package.json");
7
7
  function readPackageJson() {
8
- return JSON.parse(fs.readFileSync(PACKAGE_JSON_PATH, "utf8"));
8
+ // The Hook bundle is copied alone into the bridge's version folder, where
9
+ // no package.json sits beside it; the build inlines PHREN_HOOK_VERSION.
10
+ try {
11
+ return JSON.parse(fs.readFileSync(PACKAGE_JSON_PATH, "utf8"));
12
+ }
13
+ catch {
14
+ return {};
15
+ }
9
16
  }
17
+ const BUNDLED_VERSION = typeof PHREN_HOOK_VERSION === "string" ? PHREN_HOOK_VERSION : "0.0.0";
10
18
  const PACKAGE_JSON = readPackageJson();
11
19
  export const PACKAGE_NAME = PACKAGE_JSON.name || "phren";
12
- export const VERSION = PACKAGE_JSON.version || "0.0.0";
20
+ export const VERSION = PACKAGE_JSON.version || BUNDLED_VERSION;
13
21
  export const PACKAGE_SPEC = `${PACKAGE_NAME}@${VERSION}`;
@@ -4,7 +4,9 @@ import * as path from "path";
4
4
  let _loadedEnvKey;
5
5
  let _loadedEnvPath = null;
6
6
  let _loadedEnvMtimeMs = -1;
7
- function homeDir() {
7
+ // Private copy: importing homeDir from phren-paths here would create a cycle,
8
+ // since phren-paths imports this module and bootstraps it at module load.
9
+ function dotenvHomeDir() {
8
10
  return process.env.HOME || process.env.USERPROFILE || os.homedir();
9
11
  }
10
12
  function parseAndApplyDotEnv(filePath) {
@@ -28,7 +30,7 @@ function resolveDotEnvPath(phrenPath) {
28
30
  const candidates = [
29
31
  phrenPath ? path.join(phrenPath, ".env") : null,
30
32
  envPath ? path.join(envPath, ".env") : null,
31
- path.join(homeDir(), ".phren", ".env"),
33
+ path.join(dotenvHomeDir(), ".phren", ".env"),
32
34
  ].filter((candidate) => Boolean(candidate));
33
35
  const seen = new Set();
34
36
  for (const candidate of candidates) {
@@ -1,3 +1,4 @@
1
+ import { homeDir } from "./home-paths.js";
1
2
  export type InstallMode = "shared" | "project-local";
2
3
  export type SyncMode = "managed-git" | "workspace-git";
3
4
  export interface PhrenRootManifest {
@@ -11,7 +12,7 @@ export interface InstallContext extends PhrenRootManifest {
11
12
  phrenPath: string;
12
13
  }
13
14
  export declare const ROOT_MANIFEST_FILENAME = "phren.root.yaml";
14
- export declare function homeDir(): string;
15
+ export { homeDir };
15
16
  export declare function homePath(...parts: string[]): string;
16
17
  export declare function expandHomePath(input: string): string;
17
18
  export declare function defaultPhrenPath(): string;
@@ -26,7 +27,7 @@ export interface AtomicWriteOptions {
26
27
  */
27
28
  mode?: number;
28
29
  }
29
- export declare function atomicWriteText(filePath: string, content: string, opts?: AtomicWriteOptions): void;
30
+ export declare function atomicWriteText(filePath: string, content: string | Uint8Array, opts?: AtomicWriteOptions): void;
30
31
  /**
31
32
  * Create (or tighten) a directory that holds per-user private data — runtime
32
33
  * logs, session transcripts, credential stores.
@@ -4,18 +4,17 @@ import * as path from "path";
4
4
  import * as crypto from "crypto";
5
5
  import * as yaml from "js-yaml";
6
6
  import { bootstrapPhrenDotEnv } from "./phren-dotenv.js";
7
+ import { homeDir } from "./home-paths.js";
7
8
  import { PhrenError, isRecord, loadYamlDocument, RESERVED_PROJECT_DIR_NAMES } from "./phren-core.js";
8
9
  import { errorMessage, isValidProjectName, safeProjectPath } from "./utils.js";
9
- import { FINDINGS_FILENAME } from "./data/access.js";
10
+ import { FINDINGS_FILENAME } from "./filenames.js";
10
11
  bootstrapPhrenDotEnv();
11
12
  function stderrLog(msg) { try {
12
13
  process.stderr.write("[phren] " + msg + "\n");
13
14
  }
14
15
  catch { } }
15
16
  export const ROOT_MANIFEST_FILENAME = "phren.root.yaml";
16
- export function homeDir() {
17
- return process.env.HOME || process.env.USERPROFILE || os.homedir();
18
- }
17
+ export { homeDir };
19
18
  export function homePath(...parts) {
20
19
  return path.join(homeDir(), ...parts);
21
20
  }
@@ -685,7 +684,7 @@ export function computePhrenLiveStateToken(phrenPath) {
685
684
  for (const projectDir of projectDirs) {
686
685
  const project = path.basename(projectDir);
687
686
  parts.push(`project:${project}`);
688
- for (const file of ["CLAUDE.md", "summary.md", FINDINGS_FILENAME, "tasks.md", "review.md", "truths.md", "topic-config.json", "phren.project.yaml"]) {
687
+ for (const file of ["AGENTS.md", "summary.md", FINDINGS_FILENAME, "tasks.md", "review.md", "truths.md", "topic-config.json", "phren.project.yaml"]) {
689
688
  pushFileToken(parts, path.join(projectDir, file));
690
689
  }
691
690
  pushDirTokens(parts, path.join(projectDir, "reference"));
@@ -6,11 +6,10 @@ import { loadYamlDocument } from "./phren-core.js";
6
6
  import { phrenErr, PhrenError, phrenOk, forwardErr, getProjectDirs, readRootManifest, } from "./shared.js";
7
7
  import { defaultMachineName, getMachineName } from "./machine-identity.js";
8
8
  import { errorMessage, isValidProjectName } from "./utils.js";
9
- import { TASK_FILE_ALIASES } from "./data/tasks.js";
10
- import { FINDINGS_FILENAME } from "./data/access.js";
9
+ import { FINDINGS_FILENAME, TASK_FILE_ALIASES } from "./filenames.js";
11
10
  import { withSafeLock } from "./shared/data-utils.js";
12
11
  import { logger } from "./logger.js";
13
- import { VALID_FINDING_SENSITIVITY, VALID_PROACTIVITY_LEVELS, VALID_TASK_MODES, VALID_RISKY_SECTIONS, } from "./governance/policy.js";
12
+ import { VALID_FINDING_SENSITIVITY, VALID_PROACTIVITY_LEVELS, VALID_TASK_MODES, VALID_RISKY_SECTIONS, } from "./governance/policy-constants.js";
14
13
  import { getNonPrimaryStores, getStoreProjectDirs } from "./store-registry.js";
15
14
  export function resolveActiveProfile(phrenPath, requestedProfile) {
16
15
  const manifest = readRootManifest(phrenPath);
@@ -105,12 +104,28 @@ export function setMachineProfile(phrenPath, machine, profile) {
105
104
  const machinesPath = path.join(phrenPath, "machines.yaml");
106
105
  return withSafeLock(machinesPath, () => {
107
106
  const current = listMachines(phrenPath);
107
+ // writeMachines rebuilds the whole file, so rewriting one phren cannot parse
108
+ // from an empty map would drop every other machine's mapping. The file is
109
+ // git-synced, so conflict markers are the likely cause. A comments-only file
110
+ // (the shipped starter) also fails to parse and is fine to write into.
111
+ if (!current.ok && current.code !== PhrenError.FILE_NOT_FOUND && hasMachineEntries(machinesPath)) {
112
+ return phrenErr(`${machinesPath} could not be parsed, so phren will not rewrite it. Fix the file by hand (check for git conflict markers), then map again.`, PhrenError.MALFORMED_YAML);
113
+ }
108
114
  const data = current.ok ? current.data : {};
109
115
  data[machine] = profile;
110
116
  writeMachines(phrenPath, data);
111
117
  return phrenOk(`Mapped machine ${machine} -> ${profile}.`);
112
118
  });
113
119
  }
120
+ /** Does machines.yaml hold anything besides comments and blank lines? */
121
+ function hasMachineEntries(machinesPath) {
122
+ try {
123
+ return loadYamlDocument(fs.readFileSync(machinesPath, "utf8"), () => true) === true;
124
+ }
125
+ catch {
126
+ return false;
127
+ }
128
+ }
114
129
  function pickEnumVal(value, allowed) {
115
130
  return typeof value === "string" && allowed.includes(value) ? value : undefined;
116
131
  }
@@ -236,14 +251,34 @@ export function listProfiles(phrenPath) {
236
251
  }
237
252
  return phrenOk(profiles);
238
253
  }
254
+ /**
255
+ * Rewrite a profile's projects, keeping every other key (the `defaults:` policy
256
+ * block included) and the file's leading comment, the way writeMachines does.
257
+ */
239
258
  function writeProfile(file, name, projects, description) {
240
259
  const backup = `${file}.bak`;
241
- if (fs.existsSync(file))
260
+ const existing = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
261
+ if (existing)
242
262
  fs.copyFileSync(file, backup);
263
+ // listProfiles already refused an unparsable file, so this parse succeeds.
264
+ const parsed = existing ? loadYamlDocument(existing, (text) => yaml.load(text, { schema: yaml.CORE_SCHEMA })) : undefined;
265
+ const rest = parsed && typeof parsed === "object" && !Array.isArray(parsed)
266
+ ? { ...parsed }
267
+ : {};
268
+ delete rest.name;
269
+ delete rest.description;
270
+ delete rest.projects;
271
+ const headerLines = [];
272
+ for (const line of existing.split("\n")) {
273
+ if (!line.startsWith("#") && line.trim() !== "")
274
+ break;
275
+ headerLines.push(line);
276
+ }
277
+ const header = headerLines.length ? `${headerLines.join("\n").replace(/\n+$/, "")}\n` : "";
243
278
  const normalized = [...new Set(projects)].sort();
244
- const out = yaml.dump({ name, ...(description ? { description } : {}), projects: normalized }, { lineWidth: 1000 });
279
+ const out = yaml.dump({ name, ...(description ? { description } : {}), projects: normalized, ...rest }, { lineWidth: 1000 });
245
280
  const tmpPath = `${file}.tmp-${crypto.randomUUID()}`;
246
- fs.writeFileSync(tmpPath, out);
281
+ fs.writeFileSync(tmpPath, header + out);
247
282
  fs.renameSync(tmpPath, file);
248
283
  }
249
284
  export function addProjectToProfile(phrenPath, profile, project) {
@@ -289,7 +324,7 @@ export function removeProjectFromProfile(phrenPath, profile, project) {
289
324
  function buildProjectCard(dir) {
290
325
  const name = path.basename(dir);
291
326
  const summaryFile = path.join(dir, "summary.md");
292
- const claudeFile = path.join(dir, "CLAUDE.md");
327
+ const claudeFile = path.join(dir, "AGENTS.md");
293
328
  const summarySource = fs.existsSync(summaryFile)
294
329
  ? fs.readFileSync(summaryFile, "utf8")
295
330
  : fs.existsSync(claudeFile)
@@ -299,7 +334,7 @@ function buildProjectCard(dir) {
299
334
  .split("\n")
300
335
  .map((line) => line.trim())
301
336
  .find((line) => line && !line.startsWith("#")) || "";
302
- const docs = ["CLAUDE.md", FINDINGS_FILENAME, "summary.md", "review.md"]
337
+ const docs = ["AGENTS.md", FINDINGS_FILENAME, "summary.md", "review.md"]
303
338
  .filter((file) => fs.existsSync(path.join(dir, file)));
304
339
  const taskFile = TASK_FILE_ALIASES.find((file) => fs.existsSync(path.join(dir, file)));
305
340
  if (taskFile)
@@ -25,7 +25,14 @@ export interface ProjectAccessControl {
25
25
  }
26
26
  export interface ProjectConfig {
27
27
  ownership?: ProjectOwnershipMode;
28
+ /**
29
+ * The folder the project was last added from, on whichever machine that was.
30
+ * Kept for older CLIs; a synced store shares it across every computer, so
31
+ * it is only authoritative on the machine that wrote it.
32
+ */
28
33
  sourcePath?: string;
34
+ /** Per-machine source folders, keyed by `getMachineName()`. Wins over `sourcePath`. */
35
+ sourcePaths?: Record<string, string>;
29
36
  skills?: boolean;
30
37
  hooks?: {
31
38
  enabled?: boolean;
@@ -47,7 +54,18 @@ export declare function clearProjectConfigCache(): void;
47
54
  export declare function readProjectConfig(phrenPath: string, project: string): ProjectConfig;
48
55
  export declare function writeProjectConfig(phrenPath: string, project: string, patch: Partial<ProjectConfig>): ProjectConfig;
49
56
  export declare function updateProjectConfigOverrides(phrenPath: string, project: string, updater: (current: ProjectConfigOverrides) => ProjectConfigOverrides): ProjectConfig;
50
- export declare function getProjectSourcePath(phrenPath: string, project: string, config?: ProjectConfig): string | undefined;
57
+ /**
58
+ * Where this project's source lives on this machine. The store syncs between
59
+ * computers, so the shared `sourcePath` is often another machine's folder:
60
+ * this machine's `sourcePaths` entry wins, and the shared value is only used
61
+ * when nothing more specific was recorded.
62
+ */
63
+ export declare function getProjectSourcePath(phrenPath: string, project: string, config?: ProjectConfig, machine?: string): string | undefined;
64
+ /**
65
+ * Record `sourceRoot` as this machine's folder for the project, alongside the
66
+ * legacy shared `sourcePath` older CLIs read.
67
+ */
68
+ export declare function recordProjectSourcePath(phrenPath: string, project: string, sourceRoot: string, patch?: Partial<ProjectConfig>, machine?: string): ProjectConfig;
51
69
  export declare function getProjectOwnershipDefault(phrenPath: string): ProjectOwnershipMode;
52
70
  export declare function getProjectOwnershipMode(phrenPath: string, project: string, config?: ProjectConfig): ProjectOwnershipMode;
53
71
  export declare function isProjectHookEnabled(phrenPath: string, project: string | null | undefined, event: ProjectHookEvent, config?: ProjectConfig): boolean;
@@ -7,7 +7,8 @@ import { readInstallPreferences } from "./init/preferences.js";
7
7
  import { debugLog } from "./shared.js";
8
8
  import { errorMessage } from "./utils.js";
9
9
  import { storeAwareProjectPath } from "./store-routing.js";
10
- import { withFileLock } from "./shared/governance.js";
10
+ import { withFileLock } from "./governance/locks.js";
11
+ import { getMachineName } from "./machine-identity.js";
11
12
  export const PROJECT_OWNERSHIP_MODES = ["phren-managed", "detached", "repo-managed"];
12
13
  export const PROJECT_HOOK_EVENTS = ["UserPromptSubmit", "Stop", "SessionStart", "PostToolUse"];
13
14
  export function parseProjectOwnershipMode(raw) {
@@ -107,10 +108,35 @@ export function updateProjectConfigOverrides(phrenPath, project, updater) {
107
108
  return next;
108
109
  });
109
110
  }
110
- export function getProjectSourcePath(phrenPath, project, config) {
111
- const raw = (config ?? readProjectConfig(phrenPath, project)).sourcePath;
111
+ /**
112
+ * Where this project's source lives on this machine. The store syncs between
113
+ * computers, so the shared `sourcePath` is often another machine's folder:
114
+ * this machine's `sourcePaths` entry wins, and the shared value is only used
115
+ * when nothing more specific was recorded.
116
+ */
117
+ export function getProjectSourcePath(phrenPath, project, config, machine = getMachineName()) {
118
+ const resolved = config ?? readProjectConfig(phrenPath, project);
119
+ const perMachine = resolved.sourcePaths && typeof resolved.sourcePaths === "object" && !Array.isArray(resolved.sourcePaths)
120
+ ? resolved.sourcePaths[machine]
121
+ : undefined;
122
+ const raw = typeof perMachine === "string" && perMachine.trim() ? perMachine : resolved.sourcePath;
112
123
  return typeof raw === "string" && raw.trim() ? path.resolve(raw) : undefined;
113
124
  }
125
+ /**
126
+ * Record `sourceRoot` as this machine's folder for the project, alongside the
127
+ * legacy shared `sourcePath` older CLIs read.
128
+ */
129
+ export function recordProjectSourcePath(phrenPath, project, sourceRoot, patch = {}, machine = getMachineName()) {
130
+ const current = readProjectConfig(phrenPath, project);
131
+ const existing = current.sourcePaths && typeof current.sourcePaths === "object" && !Array.isArray(current.sourcePaths)
132
+ ? current.sourcePaths
133
+ : {};
134
+ return writeProjectConfig(phrenPath, project, {
135
+ ...patch,
136
+ sourcePath: sourceRoot,
137
+ sourcePaths: { ...existing, [machine]: sourceRoot },
138
+ });
139
+ }
114
140
  export function getProjectOwnershipDefault(phrenPath) {
115
141
  return parseProjectOwnershipMode(readInstallPreferences(phrenPath).projectOwnershipDefault) ?? "phren-managed";
116
142
  }
@@ -71,6 +71,7 @@ export declare function readProjectTopics(phrenPath: string, project: string): {
71
71
  source: ProjectTopicSource;
72
72
  topics: ProjectTopic[];
73
73
  domain?: string;
74
+ error?: string;
74
75
  };
75
76
  export declare function pinProjectTopicSuggestion(phrenPath: string, project: string, topic: ProjectTopic): {
76
77
  ok: true;