clinkx 1.2.0 → 1.4.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 (371) hide show
  1. package/CHANGELOG.md +60 -0
  2. package/README.md +17 -8
  3. package/clinkx-workflows/dist/architecture-arena/admission.d.ts +16 -0
  4. package/clinkx-workflows/dist/architecture-arena/admission.js +107 -0
  5. package/clinkx-workflows/dist/architecture-arena/admission.js.map +1 -0
  6. package/clinkx-workflows/dist/architecture-arena/contract.d.ts +1368 -0
  7. package/clinkx-workflows/dist/architecture-arena/contract.js +254 -0
  8. package/clinkx-workflows/dist/architecture-arena/contract.js.map +1 -0
  9. package/clinkx-workflows/dist/architecture-arena/runtime.d.ts +53 -0
  10. package/clinkx-workflows/dist/architecture-arena/runtime.js +511 -0
  11. package/clinkx-workflows/dist/architecture-arena/runtime.js.map +1 -0
  12. package/clinkx-workflows/dist/architecture-comparison/admission.d.ts +17 -1
  13. package/clinkx-workflows/dist/architecture-comparison/admission.js +27 -4
  14. package/clinkx-workflows/dist/architecture-comparison/admission.js.map +1 -1
  15. package/clinkx-workflows/dist/architecture-comparison/contract.d.ts +59 -62
  16. package/clinkx-workflows/dist/architecture-comparison/contract.js +4 -21
  17. package/clinkx-workflows/dist/architecture-comparison/contract.js.map +1 -1
  18. package/clinkx-workflows/dist/architecture-comparison/runtime.d.ts +4 -3
  19. package/clinkx-workflows/dist/architecture-comparison/runtime.js +22 -67
  20. package/clinkx-workflows/dist/architecture-comparison/runtime.js.map +1 -1
  21. package/clinkx-workflows/dist/artifacts.d.ts +19 -4
  22. package/clinkx-workflows/dist/artifacts.js +16 -7
  23. package/clinkx-workflows/dist/artifacts.js.map +1 -1
  24. package/clinkx-workflows/dist/backend.d.ts +30 -0
  25. package/clinkx-workflows/dist/child-env.d.ts +3 -0
  26. package/clinkx-workflows/dist/child-env.js +11 -0
  27. package/clinkx-workflows/dist/child-env.js.map +1 -1
  28. package/clinkx-workflows/dist/clink-client.d.ts +8 -2
  29. package/clinkx-workflows/dist/clink-client.js +4 -2
  30. package/clinkx-workflows/dist/clink-client.js.map +1 -1
  31. package/clinkx-workflows/dist/context-preflight.d.ts +6 -0
  32. package/clinkx-workflows/dist/context-preflight.js.map +1 -1
  33. package/clinkx-workflows/dist/council-execution-policy.d.ts +3 -1
  34. package/clinkx-workflows/dist/council-execution-policy.js +4 -0
  35. package/clinkx-workflows/dist/council-execution-policy.js.map +1 -1
  36. package/clinkx-workflows/dist/dashboard/api-routes.d.ts +21 -0
  37. package/clinkx-workflows/dist/dashboard/api-routes.js +27 -0
  38. package/clinkx-workflows/dist/dashboard/api-routes.js.map +1 -1
  39. package/clinkx-workflows/dist/dashboard/auth/challenge-store.d.ts +13 -0
  40. package/clinkx-workflows/dist/dashboard/auth/challenge-store.js.map +1 -1
  41. package/clinkx-workflows/dist/dashboard/auth/controller.d.ts +27 -0
  42. package/clinkx-workflows/dist/dashboard/auth/controller.js +262 -23
  43. package/clinkx-workflows/dist/dashboard/auth/controller.js.map +1 -1
  44. package/clinkx-workflows/dist/dashboard/auth/settings-step-up.d.ts +62 -0
  45. package/clinkx-workflows/dist/dashboard/auth/settings-step-up.js +70 -0
  46. package/clinkx-workflows/dist/dashboard/auth/settings-step-up.js.map +1 -0
  47. package/clinkx-workflows/dist/dashboard/contracts.d.ts +586 -586
  48. package/clinkx-workflows/dist/dashboard/progress-report-contract.d.ts +28 -28
  49. package/clinkx-workflows/dist/dashboard/request-admission.d.ts +6 -0
  50. package/clinkx-workflows/dist/dashboard/request-admission.js +9 -0
  51. package/clinkx-workflows/dist/dashboard/request-admission.js.map +1 -1
  52. package/clinkx-workflows/dist/dashboard/server-factory.js +15 -1
  53. package/clinkx-workflows/dist/dashboard/server-factory.js.map +1 -1
  54. package/clinkx-workflows/dist/dashboard/session-log-contract.d.ts +32 -32
  55. package/clinkx-workflows/dist/dashboard/settings-contract.d.ts +1806 -0
  56. package/clinkx-workflows/dist/dashboard/settings-contract.js +630 -0
  57. package/clinkx-workflows/dist/dashboard/settings-contract.js.map +1 -0
  58. package/clinkx-workflows/dist/dashboard/settings-process-reader.d.ts +48 -0
  59. package/clinkx-workflows/dist/dashboard/settings-process-reader.js +195 -0
  60. package/clinkx-workflows/dist/dashboard/settings-process-reader.js.map +1 -0
  61. package/clinkx-workflows/dist/dashboard/settings-routes.d.ts +87 -0
  62. package/clinkx-workflows/dist/dashboard/settings-routes.js +690 -0
  63. package/clinkx-workflows/dist/dashboard/settings-routes.js.map +1 -0
  64. package/clinkx-workflows/dist/dashboard-ui/assets/index-DSOtuS0p.js +122 -0
  65. package/clinkx-workflows/dist/dashboard-ui/assets/style-C5guUjwN.css +1 -0
  66. package/clinkx-workflows/dist/dashboard-ui/index.html +2 -2
  67. package/clinkx-workflows/dist/delegate-signature.d.ts +4 -3
  68. package/clinkx-workflows/dist/delegate-signature.js +4 -3
  69. package/clinkx-workflows/dist/delegate-signature.js.map +1 -1
  70. package/clinkx-workflows/dist/durable-file-core.d.ts +76 -0
  71. package/clinkx-workflows/dist/durable-file-core.js +146 -0
  72. package/clinkx-workflows/dist/durable-file-core.js.map +1 -0
  73. package/clinkx-workflows/dist/durable-file.d.ts +13 -0
  74. package/clinkx-workflows/dist/durable-file.js +22 -0
  75. package/clinkx-workflows/dist/durable-file.js.map +1 -0
  76. package/clinkx-workflows/dist/engine.d.ts +42 -7
  77. package/clinkx-workflows/dist/engine.js +196 -24
  78. package/clinkx-workflows/dist/engine.js.map +1 -1
  79. package/clinkx-workflows/dist/index.js +68 -2
  80. package/clinkx-workflows/dist/index.js.map +1 -1
  81. package/clinkx-workflows/dist/ping-pong/admission.d.ts +127 -0
  82. package/clinkx-workflows/dist/ping-pong/admission.js +522 -0
  83. package/clinkx-workflows/dist/ping-pong/admission.js.map +1 -0
  84. package/clinkx-workflows/dist/ping-pong/contract.d.ts +2539 -0
  85. package/clinkx-workflows/dist/ping-pong/contract.js +819 -0
  86. package/clinkx-workflows/dist/ping-pong/contract.js.map +1 -0
  87. package/clinkx-workflows/dist/ping-pong/control.d.ts +67 -0
  88. package/clinkx-workflows/dist/ping-pong/control.js +12 -0
  89. package/clinkx-workflows/dist/ping-pong/control.js.map +1 -0
  90. package/clinkx-workflows/dist/ping-pong/runtime-handle.d.ts +24 -0
  91. package/clinkx-workflows/dist/ping-pong/runtime-handle.js +55 -0
  92. package/clinkx-workflows/dist/ping-pong/runtime-handle.js.map +1 -0
  93. package/clinkx-workflows/dist/ping-pong/runtime.d.ts +235 -0
  94. package/clinkx-workflows/dist/ping-pong/runtime.js +1183 -0
  95. package/clinkx-workflows/dist/ping-pong/runtime.js.map +1 -0
  96. package/clinkx-workflows/dist/ping-pong/settle.d.ts +57 -0
  97. package/clinkx-workflows/dist/ping-pong/settle.js +58 -0
  98. package/clinkx-workflows/dist/ping-pong/settle.js.map +1 -0
  99. package/clinkx-workflows/dist/ping-pong/sidecar.d.ts +65 -0
  100. package/clinkx-workflows/dist/ping-pong/sidecar.js +138 -0
  101. package/clinkx-workflows/dist/ping-pong/sidecar.js.map +1 -0
  102. package/clinkx-workflows/dist/plan-review/publication.d.ts +2 -1
  103. package/clinkx-workflows/dist/plan-review/publication.js +5 -6
  104. package/clinkx-workflows/dist/plan-review/publication.js.map +1 -1
  105. package/clinkx-workflows/dist/plan-review/snapshot.d.ts +3 -2
  106. package/clinkx-workflows/dist/plan-review/snapshot.js +8 -8
  107. package/clinkx-workflows/dist/plan-review/snapshot.js.map +1 -1
  108. package/clinkx-workflows/dist/recipe-host.d.ts +315 -0
  109. package/clinkx-workflows/dist/recipe-host.js +183 -0
  110. package/clinkx-workflows/dist/recipe-host.js.map +1 -0
  111. package/clinkx-workflows/dist/recipe-seats.d.ts +96 -0
  112. package/clinkx-workflows/dist/recipe-seats.js +163 -0
  113. package/clinkx-workflows/dist/recipe-seats.js.map +1 -0
  114. package/clinkx-workflows/dist/recipe-shared/evidence.d.ts +67 -0
  115. package/clinkx-workflows/dist/recipe-shared/evidence.js +111 -0
  116. package/clinkx-workflows/dist/recipe-shared/evidence.js.map +1 -0
  117. package/clinkx-workflows/dist/reducers/index.d.ts +9 -1
  118. package/clinkx-workflows/dist/reducers/index.js +30 -0
  119. package/clinkx-workflows/dist/reducers/index.js.map +1 -1
  120. package/clinkx-workflows/dist/run-lock-reclaim.d.ts +44 -0
  121. package/clinkx-workflows/dist/run-lock-reclaim.js +86 -0
  122. package/clinkx-workflows/dist/run-lock-reclaim.js.map +1 -0
  123. package/clinkx-workflows/dist/settings/audit.d.ts +101 -0
  124. package/clinkx-workflows/dist/settings/audit.js +318 -0
  125. package/clinkx-workflows/dist/settings/audit.js.map +1 -0
  126. package/clinkx-workflows/dist/settings/bootstrap.d.ts +35 -0
  127. package/clinkx-workflows/dist/settings/bootstrap.js +52 -0
  128. package/clinkx-workflows/dist/settings/bootstrap.js.map +1 -0
  129. package/clinkx-workflows/dist/settings/codec.d.ts +51 -0
  130. package/clinkx-workflows/dist/settings/codec.js +410 -0
  131. package/clinkx-workflows/dist/settings/codec.js.map +1 -0
  132. package/clinkx-workflows/dist/settings/durable-write.d.ts +48 -0
  133. package/clinkx-workflows/dist/settings/durable-write.js +31 -0
  134. package/clinkx-workflows/dist/settings/durable-write.js.map +1 -0
  135. package/clinkx-workflows/dist/settings/index.d.ts +20 -0
  136. package/clinkx-workflows/dist/settings/index.js +23 -0
  137. package/clinkx-workflows/dist/settings/index.js.map +1 -0
  138. package/clinkx-workflows/dist/settings/loader.d.ts +80 -0
  139. package/clinkx-workflows/dist/settings/loader.js +577 -0
  140. package/clinkx-workflows/dist/settings/loader.js.map +1 -0
  141. package/clinkx-workflows/dist/settings/lock.d.ts +108 -0
  142. package/clinkx-workflows/dist/settings/lock.js +344 -0
  143. package/clinkx-workflows/dist/settings/lock.js.map +1 -0
  144. package/clinkx-workflows/dist/settings/paths.d.ts +65 -0
  145. package/clinkx-workflows/dist/settings/paths.js +173 -0
  146. package/clinkx-workflows/dist/settings/paths.js.map +1 -0
  147. package/clinkx-workflows/dist/settings/process-heartbeat.d.ts +47 -0
  148. package/clinkx-workflows/dist/settings/process-heartbeat.js +305 -0
  149. package/clinkx-workflows/dist/settings/process-heartbeat.js.map +1 -0
  150. package/clinkx-workflows/dist/settings/registry.d.ts +178 -0
  151. package/clinkx-workflows/dist/settings/registry.js +1285 -0
  152. package/clinkx-workflows/dist/settings/registry.js.map +1 -0
  153. package/clinkx-workflows/dist/settings/schema.d.ts +404 -0
  154. package/clinkx-workflows/dist/settings/schema.js +415 -0
  155. package/clinkx-workflows/dist/settings/schema.js.map +1 -0
  156. package/clinkx-workflows/dist/settings/store.d.ts +157 -0
  157. package/clinkx-workflows/dist/settings/store.js +842 -0
  158. package/clinkx-workflows/dist/settings/store.js.map +1 -0
  159. package/clinkx-workflows/dist/state-schema.d.ts +11 -0
  160. package/clinkx-workflows/dist/state-schema.js +4 -1
  161. package/clinkx-workflows/dist/state-schema.js.map +1 -1
  162. package/clinkx-workflows/dist/state.d.ts +178 -3
  163. package/clinkx-workflows/dist/state.js +618 -83
  164. package/clinkx-workflows/dist/state.js.map +1 -1
  165. package/clinkx-workflows/dist/stdio-entry.d.ts +2 -0
  166. package/clinkx-workflows/dist/stdio-entry.js +52 -0
  167. package/clinkx-workflows/dist/stdio-entry.js.map +1 -0
  168. package/clinkx-workflows/dist/transport.d.ts +2 -1
  169. package/clinkx-workflows/dist/transport.js +5 -0
  170. package/clinkx-workflows/dist/transport.js.map +1 -1
  171. package/clinkx-workflows/dist/validators/architecture-arena.d.ts +6 -0
  172. package/clinkx-workflows/dist/validators/architecture-arena.js +16 -0
  173. package/clinkx-workflows/dist/validators/architecture-arena.js.map +1 -0
  174. package/clinkx-workflows/dist/validators/index.js +4 -0
  175. package/clinkx-workflows/dist/validators/index.js.map +1 -1
  176. package/clinkx-workflows/dist/validators/ping-pong.d.ts +6 -0
  177. package/clinkx-workflows/dist/validators/ping-pong.js +10 -0
  178. package/clinkx-workflows/dist/validators/ping-pong.js.map +1 -0
  179. package/clinkx-workflows/dist/workflow-tools.d.ts +51 -5
  180. package/clinkx-workflows/dist/workflow-tools.js +785 -34
  181. package/clinkx-workflows/dist/workflow-tools.js.map +1 -1
  182. package/clinkx-workflows/dist/workflow-verification-contract.d.ts +4 -4
  183. package/clinkx-workflows/templates/architecture-arena/candidate.txt +39 -0
  184. package/clinkx-workflows/templates/architecture-arena/judge.txt +34 -0
  185. package/clinkx-workflows/templates/ping-pong/implement.txt +14 -0
  186. package/clinkx-workflows/templates/ping-pong/remediate.txt +14 -0
  187. package/clinkx-workflows/templates/ping-pong/review.txt +27 -0
  188. package/clinkx-workflows/workflows/architecture-arena.yaml +127 -0
  189. package/clinkx-workflows/workflows/ping-pong.yaml +158 -0
  190. package/dist/context-builder/bundle.js +4 -3
  191. package/dist/context-builder/bundle.js.map +1 -1
  192. package/dist/context-builder/delegate-packet.d.ts +1 -0
  193. package/dist/context-builder/delegate-packet.js +66 -7
  194. package/dist/context-builder/delegate-packet.js.map +1 -1
  195. package/dist/context-builder/delegate-validation.d.ts +12 -3
  196. package/dist/context-builder/delegate-validation.js +23 -13
  197. package/dist/context-builder/delegate-validation.js.map +1 -1
  198. package/dist/context-builder/external-gaps.d.ts +14 -3
  199. package/dist/context-builder/external-gaps.js +124 -18
  200. package/dist/context-builder/external-gaps.js.map +1 -1
  201. package/dist/context-builder/handler.js +108 -191
  202. package/dist/context-builder/handler.js.map +1 -1
  203. package/dist/context-builder/review-coverage.js +27 -1
  204. package/dist/context-builder/review-coverage.js.map +1 -1
  205. package/dist/context-builder/secrets.js +1 -1
  206. package/dist/context-builder/secrets.js.map +1 -1
  207. package/dist/context-builder/versions.d.ts +10 -4
  208. package/dist/context-builder/versions.js +10 -4
  209. package/dist/context-builder/versions.js.map +1 -1
  210. package/dist/context-builder/workflow-runner.js +33 -24
  211. package/dist/context-builder/workflow-runner.js.map +1 -1
  212. package/dist/dashboard-cli.d.ts +2 -0
  213. package/dist/dashboard-cli.js +197 -58
  214. package/dist/dashboard-cli.js.map +1 -1
  215. package/dist/dashboard-companion/client.d.ts +10 -0
  216. package/dist/dashboard-companion/client.js +43 -1
  217. package/dist/dashboard-companion/client.js.map +1 -1
  218. package/dist/dashboard-companion/config.d.ts +19 -1
  219. package/dist/dashboard-companion/config.js +104 -3
  220. package/dist/dashboard-companion/config.js.map +1 -1
  221. package/dist/dashboard-companion/protocol.d.ts +16 -0
  222. package/dist/dashboard-companion/protocol.js +55 -1
  223. package/dist/dashboard-companion/protocol.js.map +1 -1
  224. package/dist/dashboard-companion/workstation-binding.d.ts +69 -0
  225. package/dist/dashboard-companion/workstation-binding.js +192 -0
  226. package/dist/dashboard-companion/workstation-binding.js.map +1 -0
  227. package/dist/dashboard-gateway/admin-cli.d.ts +10 -0
  228. package/dist/dashboard-gateway/admin-cli.js +266 -0
  229. package/dist/dashboard-gateway/admin-cli.js.map +1 -0
  230. package/dist/dashboard-gateway/config.d.ts +50 -0
  231. package/dist/dashboard-gateway/config.js +235 -1
  232. package/dist/dashboard-gateway/config.js.map +1 -1
  233. package/dist/dashboard-gateway/connection-registry.d.ts +100 -0
  234. package/dist/dashboard-gateway/connection-registry.js +228 -0
  235. package/dist/dashboard-gateway/connection-registry.js.map +1 -0
  236. package/dist/dashboard-gateway/control-plane/account-auth.d.ts +78 -0
  237. package/dist/dashboard-gateway/control-plane/account-auth.js +198 -0
  238. package/dist/dashboard-gateway/control-plane/account-auth.js.map +1 -0
  239. package/dist/dashboard-gateway/control-plane/billing.d.ts +264 -0
  240. package/dist/dashboard-gateway/control-plane/billing.js +787 -0
  241. package/dist/dashboard-gateway/control-plane/billing.js.map +1 -0
  242. package/dist/dashboard-gateway/control-plane/contracts.d.ts +1293 -0
  243. package/dist/dashboard-gateway/control-plane/contracts.js +280 -0
  244. package/dist/dashboard-gateway/control-plane/contracts.js.map +1 -0
  245. package/dist/dashboard-gateway/control-plane/cookies.d.ts +13 -0
  246. package/dist/dashboard-gateway/control-plane/cookies.js +46 -0
  247. package/dist/dashboard-gateway/control-plane/cookies.js.map +1 -0
  248. package/dist/dashboard-gateway/control-plane/credentials.d.ts +63 -0
  249. package/dist/dashboard-gateway/control-plane/credentials.js +66 -0
  250. package/dist/dashboard-gateway/control-plane/credentials.js.map +1 -0
  251. package/dist/dashboard-gateway/control-plane/entitlements.d.ts +118 -0
  252. package/dist/dashboard-gateway/control-plane/entitlements.js +329 -0
  253. package/dist/dashboard-gateway/control-plane/entitlements.js.map +1 -0
  254. package/dist/dashboard-gateway/control-plane/errors.d.ts +17 -0
  255. package/dist/dashboard-gateway/control-plane/errors.js +23 -0
  256. package/dist/dashboard-gateway/control-plane/errors.js.map +1 -0
  257. package/dist/dashboard-gateway/control-plane/hosts.d.ts +6 -0
  258. package/dist/dashboard-gateway/control-plane/hosts.js +16 -0
  259. package/dist/dashboard-gateway/control-plane/hosts.js.map +1 -0
  260. package/dist/dashboard-gateway/control-plane/http.d.ts +34 -0
  261. package/dist/dashboard-gateway/control-plane/http.js +331 -0
  262. package/dist/dashboard-gateway/control-plane/http.js.map +1 -0
  263. package/dist/dashboard-gateway/control-plane/schema.d.ts +9 -0
  264. package/dist/dashboard-gateway/control-plane/schema.js +247 -0
  265. package/dist/dashboard-gateway/control-plane/schema.js.map +1 -0
  266. package/dist/dashboard-gateway/control-plane/secrets.d.ts +20 -0
  267. package/dist/dashboard-gateway/control-plane/secrets.js +39 -0
  268. package/dist/dashboard-gateway/control-plane/secrets.js.map +1 -0
  269. package/dist/dashboard-gateway/control-plane/store.d.ts +579 -0
  270. package/dist/dashboard-gateway/control-plane/store.js +1115 -0
  271. package/dist/dashboard-gateway/control-plane/store.js.map +1 -0
  272. package/dist/dashboard-gateway/cookie-boundary.d.ts +60 -0
  273. package/dist/dashboard-gateway/cookie-boundary.js +205 -0
  274. package/dist/dashboard-gateway/cookie-boundary.js.map +1 -0
  275. package/dist/dashboard-gateway/index.js +271 -494
  276. package/dist/dashboard-gateway/index.js.map +1 -1
  277. package/dist/dashboard-gateway/main.js +7 -2
  278. package/dist/dashboard-gateway/main.js.map +1 -1
  279. package/dist/dashboard-gateway/routing.d.ts +43 -0
  280. package/dist/dashboard-gateway/routing.js +65 -0
  281. package/dist/dashboard-gateway/routing.js.map +1 -0
  282. package/dist/dashboard-gateway/tenant-gateway.d.ts +56 -0
  283. package/dist/dashboard-gateway/tenant-gateway.js +989 -0
  284. package/dist/dashboard-gateway/tenant-gateway.js.map +1 -0
  285. package/dist/dashboard-gateway/tenant-main.d.ts +41 -0
  286. package/dist/dashboard-gateway/tenant-main.js +303 -0
  287. package/dist/dashboard-gateway/tenant-main.js.map +1 -0
  288. package/dist/dashboard-gateway/tunnel-errors.d.ts +16 -0
  289. package/dist/dashboard-gateway/tunnel-errors.js +22 -0
  290. package/dist/dashboard-gateway/tunnel-errors.js.map +1 -0
  291. package/dist/dashboard-gateway/tunnel-http.d.ts +21 -0
  292. package/dist/dashboard-gateway/tunnel-http.js +195 -0
  293. package/dist/dashboard-gateway/tunnel-http.js.map +1 -0
  294. package/dist/elaris/config.d.ts +10 -0
  295. package/dist/elaris/config.js +27 -1
  296. package/dist/elaris/config.js.map +1 -1
  297. package/dist/elaris/tools.js +4 -1
  298. package/dist/elaris/tools.js.map +1 -1
  299. package/dist/handler.d.ts +6 -0
  300. package/dist/handler.js +17 -1
  301. package/dist/handler.js.map +1 -1
  302. package/dist/index.d.ts +0 -31
  303. package/dist/index.js +41 -404
  304. package/dist/index.js.map +1 -1
  305. package/dist/lib.d.ts +17 -0
  306. package/dist/lib.js +17 -0
  307. package/dist/lib.js.map +1 -0
  308. package/dist/local-clink-backend.d.ts +2 -1
  309. package/dist/local-clink-backend.js +28 -4
  310. package/dist/local-clink-backend.js.map +1 -1
  311. package/dist/parsers/extract.d.ts +19 -1
  312. package/dist/parsers/extract.js +68 -3
  313. package/dist/parsers/extract.js.map +1 -1
  314. package/dist/pipeline.d.ts +17 -1
  315. package/dist/pipeline.js +34 -6
  316. package/dist/pipeline.js.map +1 -1
  317. package/dist/process-group.d.ts +65 -0
  318. package/dist/process-group.js +153 -0
  319. package/dist/process-group.js.map +1 -0
  320. package/dist/progress-report/lock.d.ts +17 -59
  321. package/dist/progress-report/lock.js +25 -329
  322. package/dist/progress-report/lock.js.map +1 -1
  323. package/dist/progress-report/schema.d.ts +23 -23
  324. package/dist/project-verification/files.js +1 -1
  325. package/dist/project-verification/files.js.map +1 -1
  326. package/dist/project-verification/process.js +23 -44
  327. package/dist/project-verification/process.js.map +1 -1
  328. package/dist/project-verification/service.js +9 -1
  329. package/dist/project-verification/service.js.map +1 -1
  330. package/dist/prompt.d.ts +7 -0
  331. package/dist/prompt.js +18 -1
  332. package/dist/prompt.js.map +1 -1
  333. package/dist/recipe-host/git-trust.d.ts +43 -0
  334. package/dist/recipe-host/git-trust.js +360 -0
  335. package/dist/recipe-host/git-trust.js.map +1 -0
  336. package/dist/recipe-host/git.d.ts +42 -0
  337. package/dist/recipe-host/git.js +207 -0
  338. package/dist/recipe-host/git.js.map +1 -0
  339. package/dist/recipe-host/native-recipe-host.d.ts +127 -0
  340. package/dist/recipe-host/native-recipe-host.js +880 -0
  341. package/dist/recipe-host/native-recipe-host.js.map +1 -0
  342. package/dist/recipe-host/seat-cwd.d.ts +16 -0
  343. package/dist/recipe-host/seat-cwd.js +170 -0
  344. package/dist/recipe-host/seat-cwd.js.map +1 -0
  345. package/dist/runner.d.ts +43 -1
  346. package/dist/runner.js +234 -35
  347. package/dist/runner.js.map +1 -1
  348. package/dist/server.js +84 -5
  349. package/dist/server.js.map +1 -1
  350. package/dist/settings-cli/clients.d.ts +137 -0
  351. package/dist/settings-cli/clients.js +1124 -0
  352. package/dist/settings-cli/clients.js.map +1 -0
  353. package/dist/settings-cli/commands.d.ts +67 -0
  354. package/dist/settings-cli/commands.js +726 -0
  355. package/dist/settings-cli/commands.js.map +1 -0
  356. package/dist/settings-cli/format.d.ts +34 -0
  357. package/dist/settings-cli/format.js +40 -0
  358. package/dist/settings-cli/format.js.map +1 -0
  359. package/dist/settings-cli/main.d.ts +18 -0
  360. package/dist/settings-cli/main.js +256 -0
  361. package/dist/settings-cli/main.js.map +1 -0
  362. package/dist/stdio-main.d.ts +73 -0
  363. package/dist/stdio-main.js +455 -0
  364. package/dist/stdio-main.js.map +1 -0
  365. package/docs/configuration.md +362 -40
  366. package/docs/engineering-recipes.md +291 -0
  367. package/docs/security.md +234 -6
  368. package/docs/verification/project-checks.md +24 -2
  369. package/package.json +6 -2
  370. package/clinkx-workflows/dist/dashboard-ui/assets/index-BdpmbPps.js +0 -115
  371. package/clinkx-workflows/dist/dashboard-ui/assets/style-Im5i1iAs.css +0 -1
@@ -105,7 +105,7 @@ Full field reference:
105
105
  | `roles` | record<string,Role> | `{}` | Role prompts selected by request `role` (default: `"default"`). |
106
106
  | `supports_images` | boolean | `false` | Informational (v1 does not inline image bytes). |
107
107
  | `requires_tty` | boolean | `false` | If true: ClinkX rejects the call (PTY/TTY not supported in v1). |
108
- | `result_contract` | object | `{ enabled:false, filename:"RESULT.md" }` | Optional file-based result extraction from the run dir. |
108
+ | `result_contract` | object | `{ enabled:false, filename:"RESULT.md" }` | Optional file-based result extraction from the run dir. A complete valid result file takes precedence. For JSON-enforced calls the prompt says the file must hold exactly the single JSON value (no Markdown); if the file is invalid or salvage-only, a complete, unsalvaged parser JSON document from untruncated stdout is used instead and `_debug.result_contract_rejected` (`invalid_json` \| `salvage_only`) records it. |
109
109
  | `prompt_mode` | enum | `"stdin"` | One of: `stdin`, `arg`, `file`. Controls how the assembled prompt is delivered. |
110
110
  | `prompt_file_flag` | string | (optional) | Flag starting with `-`, valid only with `prompt_mode:"file"`; delivery emits the flag and generated path together. |
111
111
  | `invocation_overrides` | object | (optional) | Strict adapter consent block for per-call `model` and `effort`. Each knob declares an exactly two-token `args` template; effort also requires `allowed_values`. Load-time validation rejects a knob flag that exactly equals any `unsafe_args` token, `prompt_file_flag`, `native_output_file_flag`, or `stdin_placeholder_arg`. Collisions with base `args` / role `extra_args` remain legal (replacement targets). Not supported on `backend:"app_server"`. |
@@ -255,45 +255,346 @@ If `glm-5.3[1m]` 404s, fall back to the 200k pin: drop the `[1m]` suffix, set `C
255
255
 
256
256
  ## Environment Variables
257
257
 
258
- | Variable | Purpose | Default |
259
- | --- | --- | --- |
260
- | `CLINKX_CONFIG_PATH` | Override adapter config file/directory. Replaces the `CLINKX_HOME`, XDG, and packaged adapter tiers entirely. | unset |
261
- | `CLINKX_ALLOWED_ROOTS` | Comma-separated allow-roots for file/image access and verification projects/evidence. Verification projects need a source root; artifact-only roots can host evidence. State and artifact roots are added even with an explicit workspace allowlist; see [Durable storage roots](#durable-storage-roots). An entry naming an existing regular file grants only that canonical file. An entry that is a dangling symlink, inaccessible (`EACCES`, `EPERM`, `ENOTDIR`, `ELOOP`), or neither a directory nor a regular file fails startup with `CLINKX_ALLOWED_ROOTS entry "<entry>" is unusable: <reason>. Fix or remove this entry from CLINKX_ALLOWED_ROOTS.`; a nonexistent entry is accepted. Fatal at startup also when cwd is filesystem root and this is unset. | `process.cwd()` |
262
- | `CLINKX_WORKFLOWS_WORKSPACE_ROOT` | Workflow workspace root (plan_file containment, relative `cb_*` / `context_files` resolution). Unset/empty warns and falls back to `process.cwd()`. | unset → cwd |
263
- | `CLINKX_WORKFLOWS_CONTEXT_PREFLIGHT_ENABLED` | Master switch for workflow context preflight. Unset/empty is enabled. Exactly `false` injects no runner and skips default-delegate startup validation. | `true` |
264
- | `CLINKX_TIMEOUT_SECONDS` | Default timeout (seconds) | `600` |
265
- | `CLINKX_SERVER_IDLE_TIMEOUT_SECONDS` | Opt-in idle lifetime for either STDIO server, in seconds. `0` disables idle shutdown; distinct from adapter output-idle timeouts. | `0` |
266
- | `CLINKX_MAX_CONCURRENT` | Concurrent subprocess limit (fail-fast) | `5` |
267
- | `CLINKX_MAX_PROMPT_BYTES` | Max prompt bytes written/passed to subprocess | `1048576` |
268
- | `CLINKX_MAX_OUTPUT_BYTES` | Legacy per-stream capture control, superseded by CLINKX_MAX_CAPTURE_BYTES. Used as fallback when CLINKX_MAX_CAPTURE_BYTES is not set. | `10485760` |
269
- | `CLINKX_MAX_CAPTURE_BYTES` | Per-stream capture retention ceiling (head + tail ring buffer). When output exceeds this, the middle is discarded and `_truncation` metadata is emitted. Result-contract-extracted calls are unaffected since output is read from a file. | `2097152` |
270
- | `CLINKX_STRICT_FIDELITY` | When `true`, standalone clink returns `isError: true` if capture-layer truncation is detected on stdout-extracted (non-result-contract) calls. | `false` |
271
- | `CLINKX_MAX_RESPONSE_CHARS` | Max chars returned in tool result (post-parse) | `20000` |
272
- | `CLINKX_LOG_LEVEL` | Logger verbosity | `info` |
273
- | `CLINKX_WORKFLOWS_STATE_DIR` | Absolute workflow state root shared by the workflow server and dashboard. The dashboard scans its `runs/` child; launch both processes with the same value. Relative values and filesystem roots fail at startup; see [Durable storage roots](#durable-storage-roots). | See precedence below. |
274
- | `CLINKX_WORKFLOWS_ARTIFACTS_DIR` | Absolute disposable per-run artifacts root. Relative values and filesystem roots fail at startup. | `$TMPDIR/clinkx-workflows/artifacts` (`/tmp` when `TMPDIR` is unset) |
275
- | `CLINKX_HOME` | Root directory for durable ClinkX data (workflow state, context-builder runs, user adapters and rosters). Absolute; its canonical identity must not be a filesystem root, the effective home directory, or an ancestor of that home. Per-area variables override it. | `~/.clinkx` |
276
- | `CLINKX_WORKFLOWS_DASHBOARD_PORT` | Dashboard listener port; local passkey mode binds both loopback families, while cloud passkey mode binds the private container interface. `0` selects an ephemeral local port. | `4180` |
277
- | `CLINKX_WORKFLOWS_DASHBOARD_AUTH_MODE` | Dashboard auth selector. `passkey` is the default. `bearer` is a temporary rollback until the real local and live Traefik proof gates pass. `none` disables authentication entirely for loopback-only local testing (rejected in remote/gateway mode; the cloud artifacts never set it). | `passkey` |
278
- | `CLINKX_WORKFLOWS_DASHBOARD_CREDENTIAL_DIR` | Optional absolute, non-root passkey credential directory. Overrides credential storage only, not workflow state. Containers pin it to the independent writable `/data/dashboard-credentials` volume. | `${CLINKX_WORKFLOWS_STATE_DIR}/dashboard/webauthn` |
279
- | `CLINKX_WORKFLOWS_PROGRESS_REPORT_OVERRIDE_DIR` | Optional absolute, non-root parent directory for dashboard-private sidecars: `progress-report-status-overrides.json` and `prompt-builder-library.json`. Unset/empty keeps them beside `progress-reports/` under the workflow state directory. Containers pin it to the independent writable `/data/dashboard-overrides` volume so those files survive a read-only producer-state mount. Neither file is an execution input. | `${CLINKX_WORKFLOWS_STATE_DIR}` |
280
- | `CLINKX_WORKFLOWS_DASHBOARD_RP_NAME` | WebAuthn RP display name shown by the authenticator. | `ClinkX Dashboard` |
281
- | `CLINKX_WORKFLOWS_DASHBOARD_SESSION_TTL_SECONDS` | Absolute, non-sliding passkey session lifetime in seconds. | `43200` |
282
- | `CLINKX_WORKFLOWS_DASHBOARD_MAX_STATE_BYTES` | Maximum admitted `state.json` bytes per run. Strict integer range `1048576..67108864`. | `16777216` |
283
- | `CLINKX_WORKFLOWS_DASHBOARD_PUBLIC_API_ORIGIN` | Cloud dashboard canonical HTTPS origin. In passkey mode it must exactly equal the UI origin below; the hostname becomes the RP ID and IP literals are rejected. | _(unset → local)_ |
284
- | `CLINKX_WORKFLOWS_DASHBOARD_UI_ORIGIN` | Cloud dashboard canonical HTTPS origin. Passkey mode requires the same origin as the API. | _(unset → local)_ |
285
- | `CLINKX_WORKFLOWS_RETAIN_SUCCEEDED_DAYS` | Retention for ordinary synchronous successes after `run.lock` release. `0` keeps indefinitely. | `1` |
286
- | `CLINKX_WORKFLOWS_RETAIN_ASYNC_DAYS` | Retention for successful detached runs. `0` keeps indefinitely. | `1` |
287
- | `CLINKX_WORKFLOWS_RETAIN_FAILED_DAYS` | Retention for failed runs. `0` keeps indefinitely. | `30` |
288
- | `CLINKX_WORKFLOWS_RETAIN_CANCELLED_DAYS` | Retention for cancelled runs. `0` keeps indefinitely. | `30` |
289
- | `CLINKX_WORKFLOWS_RETAIN_DEBUG_DAYS` | Retention for debug-kept runs. `0` keeps indefinitely. | `7` |
290
- | `CLINKX_INVOCATION_AUDIT_V2_PERSISTENCE_ENABLED` | Reader-first activation for all invocation-audit V2 writes. Only exact `true` enables root workflow call invocation, Activity V2, and context-builder sidecar updates; every other value preserves old-reader-safe writes. Readers stay V1/V2-capable. | `false` |
291
- | `CLINKX_SESSION_LOG_TOOL_ARGUMENTS_PERSISTENCE_ENABLED` | Reader-first activation for live tool arguments, derived summaries, and best-effort coverage metadata. Only exact `true` enables writes; read once per producer at creation. Readers always accept extended events; disabling never rewrites existing journals. | `false` |
292
- | `CLINKX_OBSERVED_INVOCATION_PERSISTENCE_ENABLED` | Reader-first activation for sibling `ObservedInvocationV1` writes (workflow call entries, Activity V3). Only exact `true` persists child-reported model/effort; every other value omits the field. Independent of the V2 gate. Readers always accept the envelope. | `false` |
293
- | `CLINKX_DIRECT_SESSION_LOGS_ENABLED` | Master opt-OUT for retaining activity-family session logs on direct `clink` single runs that did not supply their own owner. When on (default), structured-parser providers (`claude_stream_json`, `codex_jsonl`, `agy_stream_json`) write a session log that surfaces in the dashboard "Single calls" list. Set to `false` to disable synthesis — those runs then show "This session log was not retained." Workflow/context runs and callers that supply their own owner are unaffected. Text-parser providers are never retained regardless of this flag. | `true` |
294
- | `CLINKX_CONTEXT_BUILDER_RUNS_DIR` | Durable run directory for `context_builder` receipts, manifests, bundles, and candidate artifacts. The directory is created with private permissions where supported and must not be a broad root, home directory, workspace root, or ancestor of the workspace. | `${CLINKX_HOME:-~/.clinkx}/context-builder/runs` |
295
- | `CLINKX_CONTEXT_BUILDER_MAX_CONCURRENT` | Fail-fast concurrency limit for `context_builder`. Requests are rejected when the limit is saturated; they are not queued. | `1` |
296
- | `CLINKX_CONTEXT_ALLOW_SECRETS` | Environment-wide default for whether `context_builder` includes secret material (API keys, private keys, tokens, `.env`/`.pem`/`id_rsa`/`credentials.json`) verbatim in bundles, delegate packets, and downstream council/provider subprocesses. `false` restores fail-closed omission/redaction. Overridden per-call by `allow_secrets` and per-workflow by `cb_allow_secrets`. See "Context builder secret material". | `true` |
258
+ | Variable | Purpose | Default | Settings class |
259
+ | --- | --- | --- | --- |
260
+ | `CLINKX_SETTINGS` | Bootstrap switch: exactly `off` disables settings-file loading entirely (servers treat the file as absent; the settings CLI still works). | unset (loading on) | env-only (bootstrap switch) |
261
+ | `CLINKX_SETTINGS_DIR` | Overrides the settings directory (see [Settings file](#settings-file)). Must be absolute, not a filesystem root, not the home directory or an ancestor of it, and not inside `CLINKX_HOME`. An invalid value is warned about and treated as "no settings". | `$HOME/.config/clinkx/settings` | env-only (bootstrap locator) |
262
+ | `CLINKX_CONFIG_PATH` | Override adapter config file/directory. Replaces the `CLINKX_HOME`, XDG, and packaged adapter tiers entirely. | unset | env-only |
263
+ | `CLINKX_ALLOWED_ROOTS` | Comma-separated allow-roots for file/image access and verification projects/evidence. Verification projects need a source root; artifact-only roots can host evidence. State and artifact roots are added even with an explicit workspace allowlist; see [Durable storage roots](#durable-storage-roots). An entry naming an existing regular file grants only that canonical file. An entry that is a dangling symlink, inaccessible (`EACCES`, `EPERM`, `ENOTDIR`, `ELOOP`), or neither a directory nor a regular file fails startup with `CLINKX_ALLOWED_ROOTS entry "<entry>" is unusable: <reason>. Fix or remove this entry from CLINKX_ALLOWED_ROOTS.`; a nonexistent entry is accepted. Fatal at startup also when cwd is filesystem root and this is unset. | `process.cwd()` | policy |
264
+ | `CLINKX_WORKFLOWS_WORKSPACE_ROOT` | Workflow workspace root (plan_file containment, relative `cb_*` / `context_files` resolution). Unset/empty warns and falls back to `process.cwd()`. | unset → cwd | env-only |
265
+ | `CLINKX_WORKFLOWS_CONTEXT_PREFLIGHT_ENABLED` | Master switch for workflow context preflight. Unset/empty is enabled. Exactly `false` injects no runner and skips default-delegate startup validation. | `true` | feature |
266
+ | `CLINKX_TIMEOUT_SECONDS` | Default timeout (seconds). **Dead**: per-call `timeout_seconds` and every shipped adapter's own `timeout_seconds` win, and the workflow child environment deletes it — there is no fallback path left. Safe to remove from client configs. | `600` | dead |
267
+ | `CLINKX_SERVER_IDLE_TIMEOUT_SECONDS` | Opt-in idle lifetime for either STDIO server, in seconds. `0` disables idle shutdown; distinct from adapter output-idle timeouts. Accepts plain decimals only (`1.5`, never `1e-7`); the dashboard renders it with a decimal field (`numberKind:"decimal"`). | `0` | tuning |
268
+ | `CLINKX_MAX_CONCURRENT` | Concurrent subprocess limit (fail-fast) | `5` | tuning |
269
+ | `CLINKX_MAX_PROMPT_BYTES` | Max prompt bytes written/passed to subprocess | `1048576` | tuning |
270
+ | `CLINKX_MAX_OUTPUT_BYTES` | Legacy per-stream capture control, superseded by CLINKX_MAX_CAPTURE_BYTES. Used as fallback when CLINKX_MAX_CAPTURE_BYTES is not set. | `10485760` | legacy alias of `CLINKX_MAX_CAPTURE_BYTES` |
271
+ | `CLINKX_MAX_CAPTURE_BYTES` | Per-stream capture retention ceiling (head + tail ring buffer). When output exceeds this, the middle is discarded and `_truncation` metadata is emitted. Result-contract-extracted calls are unaffected since output is read from a file. | `2097152` | tuning (legacy alias: `CLINKX_MAX_OUTPUT_BYTES`) |
272
+ | `CLINKX_SESSION_LOG_MAX_LINE_CHARS` | Max chars per retained session-log line before bounding. | `1048576` | tuning |
273
+ | `CLINKX_STRICT_FIDELITY` | When `true`, standalone clink returns `isError: true` if capture-layer truncation is detected on stdout-extracted (non-result-contract) calls. | `false` | feature |
274
+ | `CLINKX_MAX_RESPONSE_CHARS` | Max chars returned in tool result (post-parse) | `20000` | tuning |
275
+ | `CLINKX_LOG_LEVEL` | Logger verbosity | `info` | tuning |
276
+ | `CLINKX_WORKFLOWS_LOG_LEVEL` | Workflow-engine logger verbosity. Enters the workflow resume fingerprint: editing it can strand unfinished resumable runs. | `info` | tuning (resume fingerprint) |
277
+ | `CLINKX_WORKFLOWS_STATE_DIR` | Absolute workflow state root shared by the workflow server and dashboard. The dashboard scans its `runs/` child; launch both processes with the same value. Relative values and filesystem roots fail at startup; see [Durable storage roots](#durable-storage-roots). | See precedence below. | env-only |
278
+ | `CLINKX_WORKFLOWS_ARTIFACTS_DIR` | Absolute disposable per-run artifacts root. Relative values and filesystem roots fail at startup. | `$TMPDIR/clinkx-workflows/artifacts` (`/tmp` when `TMPDIR` is unset) | env-only |
279
+ | `CLINKX_HOME` | Root directory for durable ClinkX data (workflow state, context-builder runs, user adapters and rosters). Absolute; its canonical identity must not be a filesystem root, the effective home directory, or an ancestor of that home. Per-area variables override it. | `~/.clinkx` | env-only |
280
+ | `CLINKX_WORKFLOWS_CONTEXT_CACHE_MAX_ENTRIES` | LRU cap for committed workflow context cache runs (`wfctx-*`). | `50` | tuning |
281
+ | `CLINKX_WORKFLOWS_CONTEXT_CACHE_TTL_SECONDS` | TTL for committed workflow context cache runs (`wfctx-*`). | `86400` | tuning |
282
+ | `CLINKX_WORKFLOWS_CONTEXT_DEFAULT` | Soft default for workflow context mode when `cb_context_mode` is omitted or `inherit`: `full`, `deterministic`, or `off`. | `full` | tuning |
283
+ | `CLINKX_WORKFLOWS_CONTEXT_DEFAULT_CURATOR` | Curator adapter used by the injected default context delegate; startup requires it plus the finalizer to resolve. | `codex` | tuning |
284
+ | `CLINKX_WORKFLOWS_MAX_CONCURRENT_ASYNC` | Process-wide cap on concurrently-admitted workflow runs (blocking and async share one mutex map); exceeding it is rejected without queuing. | `1` | tuning |
285
+ | `CLINKX_WORKFLOWS_MAX_PARALLEL` | Max workflow stage calls executing in parallel. | `5` | tuning |
286
+ | `CLINKX_WORKFLOWS_MAX_PROMPT_BYTES` | Workflow-engine prompt budget ceiling (distinct from the root bridge's `CLINKX_MAX_PROMPT_BYTES`). | `900000` | tuning |
287
+ | `CLINKX_WORKFLOWS_CHILD_MAX_CONCURRENT` | Concurrency limit for workflow child processes. Enters the workflow resume fingerprint. | `5` | tuning (resume fingerprint) |
288
+ | `CLINKX_WORKFLOWS_CHILD_MAX_RESPONSE_CHARS` | Response cap for workflow child processes. Enters the workflow resume fingerprint. | `200000` | tuning (resume fingerprint) |
289
+ | `CLINKX_WORKFLOWS_CHILD_MAX_OUTPUT_BYTES` | Output cap for workflow child processes. Enters the workflow resume fingerprint. | `10485760` | tuning (resume fingerprint) |
290
+ | `CLINKX_WORKFLOWS_CHILD_MAX_PROMPT_BYTES` | Prompt cap for workflow child processes. Enters the workflow resume fingerprint. | `1048576` | tuning (resume fingerprint) |
291
+ | `CLINKX_DASHBOARD_ACTIVITY_RETAIN_RESULT` | Opt in to retaining the bounded final text of direct `clink` calls in the dashboard activity journal. | `false` | feature |
292
+ | `CLINKX_WORKFLOWS_DASHBOARD_PORT` | Dashboard listener port; local passkey mode binds both loopback families, while cloud passkey mode binds the private container interface. `0` selects an ephemeral local port. | `4180` | deployment-only |
293
+ | `CLINKX_WORKFLOWS_DASHBOARD_AUTH_MODE` | Dashboard auth selector. `passkey` is the default. `bearer` is a temporary rollback until the real local and live Traefik proof gates pass. `none` disables authentication entirely for loopback-only local testing (rejected in remote/gateway mode; the cloud artifacts never set it). | `passkey` | deployment-only |
294
+ | `CLINKX_WORKFLOWS_DASHBOARD_CREDENTIAL_DIR` | Optional absolute, non-root passkey credential directory. Overrides credential storage only, not workflow state. Containers pin it to the independent writable `/data/dashboard-credentials` volume. | `${CLINKX_WORKFLOWS_STATE_DIR}/dashboard/webauthn` | deployment-only |
295
+ | `CLINKX_WORKFLOWS_PROGRESS_REPORT_OVERRIDE_DIR` | Optional absolute, non-root parent directory for dashboard-private sidecars: `progress-report-status-overrides.json` and `prompt-builder-library.json`. Unset/empty keeps them beside `progress-reports/` under the workflow state directory. Containers pin it to the independent writable `/data/dashboard-overrides` volume so those files survive a read-only producer-state mount. Neither file is an execution input. A companion in workstation-key mode (`clxd_` token) also keeps `workstation-binding.json` here; with this variable unset, that one file goes to `${CLINKX_WORKFLOWS_STATE_DIR}/dashboard/binding/` instead, because the state root contains the default credential directory. | `${CLINKX_WORKFLOWS_STATE_DIR}` | env-only |
296
+ | `CLINKX_WORKFLOWS_DASHBOARD_RP_NAME` | WebAuthn RP display name shown by the authenticator. | `ClinkX Dashboard` | deployment-only |
297
+ | `CLINKX_WORKFLOWS_DASHBOARD_SESSION_TTL_SECONDS` | Absolute, non-sliding passkey session lifetime in seconds. | `43200` | deployment-only |
298
+ | `CLINKX_WORKFLOWS_DASHBOARD_MAX_STATE_BYTES` | Maximum admitted `state.json` bytes per run. Strict integer range `1048576..67108864`. | `16777216` | deployment-only |
299
+ | `CLINKX_WORKFLOWS_DASHBOARD_PUBLIC_API_ORIGIN` | Cloud dashboard canonical HTTPS origin. In passkey mode it must exactly equal the UI origin below; the hostname becomes the RP ID and IP literals are rejected. | _(unset → local)_ | deployment-only |
300
+ | `CLINKX_WORKFLOWS_DASHBOARD_UI_ORIGIN` | Cloud dashboard canonical HTTPS origin. Passkey mode requires the same origin as the API. | _(unset → local)_ | deployment-only |
301
+ | `CLINKX_WORKFLOWS_RETAIN_SUCCEEDED_DAYS` | Retention for ordinary synchronous successes after `run.lock` release. `0` keeps indefinitely. | `1` | retention |
302
+ | `CLINKX_WORKFLOWS_RETAIN_ASYNC_DAYS` | Retention for successful detached runs. `0` keeps indefinitely. | `1` | retention |
303
+ | `CLINKX_WORKFLOWS_RETAIN_FAILED_DAYS` | Retention for failed runs. Recipe run directories (any run with a `recipe-state.json` sidecar) use it for every terminal status, so it is also the effective `ping-pong` decision TTL; successful runs with degraded health keep at least this long. `0` keeps indefinitely. | `30` | retention |
304
+ | `CLINKX_WORKFLOWS_RETAIN_CANCELLED_DAYS` | Retention for cancelled runs. `0` keeps indefinitely. | `30` | retention |
305
+ | `CLINKX_WORKFLOWS_RETAIN_DEBUG_DAYS` | Retention for debug-kept runs. `0` keeps indefinitely. | `7` | retention |
306
+ | `CLINKX_INVOCATION_AUDIT_V2_PERSISTENCE_ENABLED` | Reader-first activation for all invocation-audit V2 writes. Only exact `true` enables root workflow call invocation, Activity V2, and context-builder sidecar updates; every other value preserves old-reader-safe writes. Readers stay V1/V2-capable. | `false` | reader-first |
307
+ | `CLINKX_SESSION_LOG_TOOL_ARGUMENTS_PERSISTENCE_ENABLED` | Reader-first activation for live tool arguments, derived summaries, and best-effort coverage metadata. Only exact `true` enables writes; read once per producer at creation. Readers always accept extended events; disabling never rewrites existing journals. | `false` | reader-first |
308
+ | `CLINKX_OBSERVED_INVOCATION_PERSISTENCE_ENABLED` | Reader-first activation for sibling `ObservedInvocationV1` writes (workflow call entries, Activity V3). Only exact `true` persists child-reported model/effort; every other value omits the field. Independent of the V2 gate. Readers always accept the envelope. | `false` | reader-first |
309
+ | `CLINKX_DIRECT_SESSION_LOGS_ENABLED` | Master opt-OUT for retaining activity-family session logs on direct `clink` single runs that did not supply their own owner. When on (default), structured-parser providers (`claude_stream_json`, `codex_jsonl`, `agy_stream_json`) write a session log that surfaces in the dashboard "Single calls" list. Set to `false` to disable synthesis — those runs then show "This session log was not retained." Workflow/context runs and callers that supply their own owner are unaffected. Text-parser providers are never retained regardless of this flag. | `true` | feature |
310
+ | `CLINKX_CONTEXT_BUILDER_RUNS_DIR` | Durable run directory for `context_builder` receipts, manifests, bundles, and candidate artifacts. The directory is created with private permissions where supported and must not be a broad root, home directory, workspace root, or ancestor of the workspace. | `${CLINKX_HOME:-~/.clinkx}/context-builder/runs` | env-only |
311
+ | `CLINKX_CONTEXT_BUILDER_MAX_CONCURRENT` | Fail-fast concurrency limit for `context_builder`. Requests are rejected when the limit is saturated; they are not queued. | `1` | tuning |
312
+ | `CLINKX_CONTEXT_ALLOW_SECRETS` | Environment-wide default for whether `context_builder` includes secret material (API keys, private keys, tokens, `.env`/`.pem`/`id_rsa`/`credentials.json`) verbatim in bundles, delegate packets, and downstream council/provider subprocesses. `false` restores fail-closed omission/redaction. Overridden per-call by `allow_secrets` and per-workflow by `cb_allow_secrets`. See "Context builder secret material". | `true` | policy |
313
+ | `CLINKX_APP_SERVER_ENABLED` | Master opt-in for the async `clink_agent_run` / `clink_agent_manage` tools; `backend:"app_server"` adapters stay excluded from sync paths regardless. | `false` | policy |
314
+ | `CLINKX_MAX_ACTIVE_TURNS` | Codex app-server active-turn lease cap (sole concurrency gate for sessions). | `5` | tuning |
315
+ | `CLINKX_MAX_RETAINED_SESSIONS` | Max retained idle app-server sessions before oldest-first eviction. | `20` | tuning |
316
+ | `CLINKX_SESSION_TTL_SECONDS` | Idle app-server session TTL before reaping (0 disables). | `1800` | tuning |
317
+ | `CLINKX_SESSION_EVENT_BUFFER` | Per-session bounded event-ring capacity. | `500` | tuning |
318
+ | `CLINKX_SESSION_EVENT_TEXT_MAX` | Max chars retained for high-volume event text fields (delta/item.text). | `2000` | tuning |
319
+ | `CLINKX_TURN_TIMEOUT_SECONDS` | Wall-clock turn timeout before interrupt/escalation (0 disables). | `600` | tuning |
320
+ | `CLINKX_APPROVAL_TIMEOUT_SECONDS` | Pending-approval timeout before auto-decline/escalation (0 disables). | `120` | tuning |
321
+ | `CLINKX_TURN_INTERRUPT_BUDGET_SECONDS` | Bounded budget for the interrupt/decline RPC round-trip before escalation. | `10` | tuning |
322
+ | `CLINKX_TERMINAL_WAIT_BUDGET_SECONDS` | Bounded budget to await a terminal turn/completed before escalation. | `10` | tuning |
323
+ | `CLINKX_APP_SERVER_START_BUDGET_SECONDS` | Bounded budget for the pre-turn startup RPC sequence (ensureReady/thread/turn). | `60` | tuning |
324
+ | `CLINKX_APP_SERVER_MIN_VERSION` | Minimum accepted Codex app-server version (parsed from userAgent). | `0.140.0` | policy |
325
+ | `CLINKX_APP_SERVER_MAX_VERSION` | Known-good Codex app-server version ceiling; above it warns unless strict. | `0.140.0` | policy |
326
+ | `CLINKX_APP_SERVER_STRICT_VERSION` | When truthy, reject (not warn) a Codex app-server above the max version. | `false` | policy |
327
+ | `CLINKX_MAX_AGENT_DEPTH` | Recursion depth ceiling; refuses nested app-server sessions beyond it. | `2` | policy |
328
+ | `CLINKX_WORKFLOWS_ALLOW_UNSAFE_ASYNC_CAP` | When `false`, an `async_cap` above the context-builder maximum is auto-capped; when `true`, ClinkX warns but admits the raw cap. | `false` | policy |
329
+ | `CLINKX_ELARIS_ENABLED` | Master opt-in for `clink_elaris_run` / `clink_elaris_manage`. Requires `CLINKX_ELARIS_BASE_URL` (env or settings file); a file-enabled flag without a resolvable URL falls back to `false` with a warning. | `false` | policy |
330
+ | `CLINKX_ELARIS_BASE_URL` | Remote Elaris origin. Absolute HTTPS, except `http://localhost`, loopback IPs; credentials, query, fragment, and non-root paths are rejected. No per-call override. | (unset) | policy |
331
+ | `CLINKX_ELARIS_DEFAULT_MODEL_ID` | Optional fallback `model_id` for `clink_elaris_run`; when absent, callers must pass `model_id`. | (unset) | tuning |
332
+ | `CLINKX_ELARIS_API_KEY` | Bearer key for the Elaris remote API. Stored only in the 0600 `secrets.json` (never in `settings.json`, never returned, never logged); write it with `clinkx settings secret set CLINKX_ELARIS_API_KEY`. | (unset) | secret |
333
+ | `CLINKX_ELARIS_REQUEST_TIMEOUT_SECONDS` | Per-HTTP-request timeout for Elaris client calls. Must be positive. | `30` | tuning |
334
+ | `CLINKX_ELARIS_WAIT_TIMEOUT_SECONDS` | Default bounded wait-loop timeout for `wait:true` / `op:"wait"`. Must be positive. | `300` | tuning |
335
+ | `CLINKX_ELARIS_REDACT_AGGRESSIVE` | Enables extra Elaris response redaction pass(es). | `false` | policy |
336
+
337
+ ### Settings file
338
+
339
+ The environment variables above carry a **Settings class** marker. Every key
340
+ whose class is `tuning`, `retention`, `feature`, `reader-first`, `policy` or
341
+ `secret` can also live in a per-workstation **settings file** managed by the
342
+ `clinkx settings` CLI and the dashboard Settings page; keys marked `env-only`
343
+ or `deployment-only` never come from the file, and `dead` keys are ignored by
344
+ this ClinkX entirely.
345
+
346
+ **Location.** The file lives at `$HOME/.config/clinkx/settings/settings.json`
347
+ — deliberately outside `~/.clinkx` (which may carry Syncthing markers) and
348
+ with `XDG_CONFIG_HOME` **ignored** on purpose: some environments (Codex) strip
349
+ XDG variables, so honoring them would make the location depend on the client
350
+ that spawned the server. `CLINKX_SETTINGS_DIR` overrides the directory; the
351
+ override must be absolute, not a filesystem root, not the home directory or an
352
+ ancestor of it, and not inside `CLINKX_HOME`. An invalid override is warned
353
+ about and treated as "no settings" — never fatal. In container deployments the
354
+ settings directory is a dedicated writable bind; run `clinkx settings init`
355
+ once on the host before the first `compose up` (the compose file does not
356
+ create the host path itself).
357
+
358
+ **Precedence.** Per key: explicit environment variable > settings file >
359
+ built-in default. An env var present with an **empty value still shadows** the
360
+ file (backward compatible: existing client env blocks keep winning), and
361
+ legacy aliases count as env-present for their canonical key — env
362
+ `CLINKX_MAX_OUTPUT_BYTES` blocks a file value for `CLINKX_MAX_CAPTURE_BYTES`.
363
+ Only *valid* file values are filled, and only for keys absent from the
364
+ pre-start environment; invalid values fall back per key (tuning keys to their
365
+ default, policy keys to their most restrictive value, `CLINKX_ALLOWED_ROOTS`
366
+ to not-filled with a loud warning). A file-enabled flag whose required
367
+ companion is missing resolves to its restrictive value with a warning (e.g.
368
+ `CLINKX_ELARIS_ENABLED=true` from the file without a resolvable
369
+ `CLINKX_ELARIS_BASE_URL` fills `false`).
370
+
371
+ **One classifier, tolerant reads, lossless saves.** Loader and store share one
372
+ `classifySettingsDocument` pass (`clinkx-workflows/src/settings/schema.ts`):
373
+ a well-formed document with some invalid values still loads and still saves —
374
+ per-key tolerance, not all-or-nothing. A save never rewrites entries it does
375
+ not touch: unknown keys and untouched invalid values are persisted verbatim
376
+ (lossless), and a secret-class key inside `settings.json` is warned about,
377
+ never applied, never returned by the dashboard GET, and never re-serialized by
378
+ a save. Serialized documents above the one shared 256 KiB cap (the loader's
379
+ `MAX_SETTINGS_FILE_BYTES`) are rejected before anything is published.
380
+
381
+ **Classes and step-up.** `tuning`, `retention`, `feature` and `reader-first`
382
+ keys are dashboard-editable with a normal session. `policy` and `secret`
383
+ saves require a fresh passkey assertion (step-up) in the dashboard and are
384
+ audit-logged; the CLI may write every class — it runs with your local
385
+ filesystem authority (actor `cli`, auth `local-fs`) and is audited through the
386
+ same store.
387
+
388
+ **Restart-only.** Every settings change applies at the next server start;
389
+ there is no live reload of per-call knobs in v1. Each MCP server process
390
+ publishes a heartbeat file under `<settings-dir>/processes/` carrying its
391
+ loaded settings revision, secrets revision, and provenance, refreshed while
392
+ it runs. `clinkx settings processes` lists them (pid, entry, settings
393
+ state/revision, liveness) so you can see which servers still need a `/mcp`
394
+ reconnect after an edit; the dashboard Settings page surfaces the same list,
395
+ where a process is `current` only when its settings revision **and** digest
396
+ **and** secrets revision all match the store. A server prunes dead heartbeats
397
+ only from its own host, so a file from a host that starts no further server
398
+ stays, and that process's env overrides stay listed as "may no longer apply".
399
+ If the process is gone, confirm it on that host and delete its file from
400
+ `<settings-dir>/processes/`.
401
+
402
+ **Disabling.** `CLINKX_SETTINGS=off` disables settings loading entirely —
403
+ servers ignore the file, write no heartbeats, and the escape hatch applies
404
+ even when the file exists. Workflow children never re-read the ambient file:
405
+ they receive an explicit snapshot or a settings-off marker, so the child
406
+ environment cannot re-introduce scrubbed `CLINKX_*` values.
407
+
408
+ **Unreadable files.** A corrupt, shape-invalid, or unsupported `settings.json`
409
+ (an unparseable document, a bad envelope, or one over the 256 KiB cap) is
410
+ treated as *absent* with a loud warning; a server always starts for
411
+ settings-origin faults. **"Absent" means the shipped defaults — which are not
412
+ uniformly the safest choice**: four policy keys default permissively
413
+ (`CLINKX_CONTEXT_ALLOW_SECRETS=true`, `CLINKX_MAX_AGENT_DEPTH=2`,
414
+ `CLINKX_ELARIS_REDACT_AGGRESSIVE=false`, `CLINKX_APP_SERVER_STRICT_VERSION=false`),
415
+ unlike a single *invalid value*, which fills that key's restrictive value. The
416
+ per-process heartbeat reports the unreadable state, so the dashboard Settings
417
+ page shows an unreadable banner. A routine save refuses to overwrite unreadable
418
+ bytes — recover explicitly. Every recover requires a passkey step-up in the
419
+ dashboard (bearer/none modes show the CLI command
420
+ `clinkx settings recover --digest <sha256>` instead); recovery **copies** the
421
+ corrupt bytes to `settings.json.corrupt-<epochms>-<rand>` and then atomically
422
+ replaces the active path (never renames it). When the unreadable file cannot be
423
+ read at all (over the cap, a permission error, a non-regular file, or a
424
+ symlink), no backup can be made, so recover **refuses** — it reports
425
+ `settings_unreadable` ("no backup can be made — move it aside manually, then
426
+ save"), leaves the file untouched, and the CLI prints that message with a
427
+ nonzero exit instead of claiming preserved bytes. On the CLI, `clinkx settings
428
+ recover [--secrets] [--digest <sha256>]` prints the unreadable state and its
429
+ digest and exits 2 without `--digest` (settings), recovers with it, and
430
+ `--secrets` needs no digest. The same rules apply to `secrets.json`.
431
+
432
+ **Secrets.** Secret-class values (today `CLINKX_ELARIS_API_KEY`) live in a
433
+ separate 0600 `secrets.json` with its own revision, written only through
434
+ `clinkx settings secret set KEY` (value read from stdin, never echoed, never
435
+ printed by any command) or the dashboard's step-up secrets endpoint. Secret
436
+ values are never returned to the browser, never logged, never hashed into
437
+ DTOs, and never audited — `clinkx settings show` reports them as
438
+ `<set>`/`<unset>` only. A secrets file with group/other permission bits is
439
+ refused (treated as unset) until the next save rewrites it 0600.
440
+
441
+ **Reader-first warning.** The three `reader-first` flags keep their rollout
442
+ rule when set through the file: deploy capable readers first, enable producers
443
+ only with exact `true`, and on rollback disable producers first — disabling
444
+ never rewrites already-persisted bytes.
445
+
446
+ **Resume-fingerprint warning.** Keys marked *resume fingerprint* in the table
447
+ (`CLINKX_WORKFLOWS_LOG_LEVEL`, `CLINKX_WORKFLOWS_CHILD_*`) enter the workflow
448
+ resume fingerprint. Changing them can make unfinished resumable runs
449
+ non-resumable — inventory and drain resumable runs before editing them, the
450
+ same rule as for adapter edits.
451
+
452
+ #### `clinkx settings` command reference
453
+
454
+ ClinkX is an MCP server, and `clinkx settings` is an admin command on the same
455
+ entry point. When the first argument is `settings`, `dist/index.js` runs the
456
+ command and exits: no MCP server starts, and the startup settings overlay is
457
+ not applied to the command's own process. MCP clients never pass that argument,
458
+ so they are unaffected. It exists for work a server or the dashboard cannot do:
459
+ reading your MCP client configs, recovering a corrupt file when the dashboard
460
+ has no passkey step-up, and editing settings with no dashboard running.
461
+
462
+ Run it through whichever install you have:
463
+
464
+ ```bash
465
+ clinkx settings <command> # global install (npm install -g clinkx)
466
+ npx -p clinkx clinkx settings <command>
467
+ node dist/index.js settings <command> # source checkout, after npm run build:all
468
+ ```
469
+
470
+ It needs a build that includes the settings file. An older build has no
471
+ `settings` command, so it ignores the argument, starts as an MCP server and
472
+ waits on stdin, which looks like a hang.
473
+
474
+ | Command | What it does |
475
+ | --- | --- |
476
+ | `path` | Print the settings directory and where that location came from |
477
+ | `init` | Create the settings directory (`0700`) |
478
+ | `show` | Print the settings document's values |
479
+ | `show --effective` | Print every registry key's value and source (env, file or default) for the environment you run it from |
480
+ | `validate` | Check the settings and secrets documents |
481
+ | `set KEY VALUE` | Set a registry key; a bad value or unknown key exits `2` with the reason |
482
+ | `unset KEY` | Remove a key from the settings file |
483
+ | `secret set KEY` | Set a secret-class key; the value is read from stdin and never echoed |
484
+ | `secret unset KEY` | Remove a secret from `secrets.json` |
485
+ | `recover [--secrets] [--digest <sha256>]` | Recover an unreadable document; without `--digest` it prints the state and digest and exits `2` |
486
+ | `processes` | List live ClinkX process heartbeats |
487
+ | `import-clients [--dry-run\|--apply]` | Plan or apply a majority import of `CLINKX_*` env from MCP client configs; dry run by default |
488
+ | `trim-report --client <claude\|codex\|cursor\|zcode>` | Print one client's trim plan and trimmed config block |
489
+
490
+ `CLINKX_SETTINGS_DIR` and `CLINKX_SETTINGS=off` apply as they do for servers.
491
+ Changes reach a server when it next restarts. The CLI needs no passkey, even
492
+ for policy keys: the step-up guards browser saves, and anything that can run
493
+ the CLI can already write the file (see
494
+ [Dashboard settings authority](security.md#dashboard-settings-authority)).
495
+ Exit codes are listed under the guided trim below.
496
+
497
+ **Guided trim (moving client env into the file).** ClinkX never edits client
498
+ config files (`~/.claude.json`, `~/.cursor/mcp.json`,
499
+ `~/.zcode/cli/config.json`, `~/.codex/config.toml`). The migration is a
500
+ guided, two-step trim:
501
+
502
+ ```bash
503
+ clinkx settings path # where the file lives
504
+ clinkx settings import-clients --dry-run # majority plan across all clients
505
+ clinkx settings import-clients --apply # write majority values (+ secrets)
506
+ clinkx settings trim-report --client claude # per-entry plan + trimmed block
507
+ ```
508
+
509
+ `import-clients` scans every ClinkX entry it can find (claude user +
510
+ per-project scopes, cursor, zcode, and Codex via `codex mcp list --json` when
511
+ that subcommand exists — the TOML is never hand-parsed; a missing codex binary
512
+ is skipped with a note; Codex ≥ 0.166.0 nests the spawn spec under
513
+ `transport`, which is read alongside the older flat shape). For each registry
514
+ key it reports the **majority** value with per-entry vote counts and the
515
+ disagreeing entries by name; a tie is never imported, and minority values
516
+ stay as explicit overrides in their client entries. Within one entry a
517
+ canonical spelling beats a legacy alias — **one vote per entry per canonical
518
+ key**, so both spellings of one key never vote twice — and an entry whose env
519
+ sets `CLINKX_SETTINGS=off` or a `CLINKX_SETTINGS_DIR` different from the
520
+ CLI's resolved dir is counted as `override` for every key (that entry does
521
+ not read this settings file). Secret values are compared transiently for
522
+ equality only — never printed — and `--apply` writes the majority secret
523
+ straight into `secrets.json`; a partial settings-then-secrets import is
524
+ reported explicitly. Unknown keys (typos such as a missing trailing `D`) are
525
+ reported, never imported, and `trim-report` suggests the nearest registry
526
+ name for an unknown `CLINKX_*` name ("did you mean …?"; startup stays quiet).
527
+ `trim-report --client X` lists, per entry, keys that are **removable only
528
+ when the settings file holds an equal value** (the core invariant — nothing
529
+ is removable before `import-clients --apply`), keep-as-override keys with
530
+ both values shown, dead keys, unknown keys, and must-stay env-only keys, then
531
+ prints a trimmed block in that client's own format. Removability is decided
532
+ per **precedence group** (a canonical key plus its legacy aliases): if any
533
+ spelling in the group is not removable, every spelling is kept. Any kept
534
+ name that is not a non-secret registry key — unknown keys, env-only,
535
+ deployment-only, `*_API_KEY_ENV` indirection targets, the dashboard token —
536
+ renders as the `<unchanged — keep your existing value>` sentinel (paste your
537
+ existing value over it), because any of them may carry secret material. A
538
+ `CLINKX_ELARIS_API_KEY_ENV` that names a non-secret setting is refused at
539
+ runtime: it may name `CLINKX_ELARIS_API_KEY` (or another secret-class registry
540
+ key) or a variable that is not a ClinkX setting; naming any other settings key,
541
+ legacy alias, or exclusion-list name — including `CLINKX_ELARIS_API_KEY_ENV`
542
+ itself — fails config loading and key resolution with `InvalidParamsError`
543
+ before the value is read, because every consumer of a settings key treats its
544
+ value as non-secret. The CLI import/trim withholding and the settings-heartbeat
545
+ withholding described in this passage remain for a config left over from an
546
+ older build that predates the refusal. Rename the indirection (to
547
+ `CLINKX_ELARIS_API_KEY` or a variable of your own) before importing: an
548
+ import run before the rename can still see a forwarded designation it cannot
549
+ resolve. When
550
+ an entry's `CLINKX_ELARIS_API_KEY_ENV` names another variable (resolved from
551
+ that entry's own env block, trimmed — an indirection merely inherited from the
552
+ client's launch environment rather than set in the entry is not visible to the
553
+ CLI), that variable holds the
554
+ Elaris credential for that entry however the registry classifies it — unless
555
+ the target is itself a secret-class registry key (writing the documented
556
+ default `CLINKX_ELARIS_API_KEY` out explicitly), which keeps flowing through
557
+ the normal secret paths (secret import vote, `secrets.json` write, `secret_*`
558
+ trim decision) and is never reported as withheld. Otherwise, when the target
559
+ is actually set in the entry, it casts no import vote, is never printed, is
560
+ never written by `--apply`, is never classified removable, renders as the
561
+ sentinel, and is reported once by name as `withheld:
562
+ credential-indirection target of CLINKX_ELARIS_API_KEY_ENV` (other entries
563
+ may still set the same key normally; when the target is not set in the entry
564
+ nothing is withheld and the key votes and trims normally). Every other
565
+ spelling of that key in the same entry is kept as an override — never
566
+ removable — because the retained target spelling would then decide the
567
+ effective value. Each server's settings heartbeat withholds the key named by
568
+ that server's own `CLINKX_ELARIS_API_KEY_ENV`, recording neither its value
569
+ nor an env/file equality hint. When that key is set in the server's env, the
570
+ Settings UI's heartbeat-derived notices still name it as overridden by env, as
571
+ they do secret-class keys, but carry neither its value nor whether it matches
572
+ the file. `clinkx settings show
573
+ --effective` withholds only what the environment of the shell running it
574
+ designates, rendering `<withheld: credential-indirection target of
575
+ CLINKX_ELARIS_API_KEY_ENV>`; it cannot see an indirection set only in a
576
+ client entry, and it prints a value held in the settings file unless that
577
+ shell also sets the indirection. Plain `clinkx settings show` prints file
578
+ values as stored, so keep the credential out of `settings.json`. For
579
+ Codex the renderer emits `env = { … }` plus the original `env_vars = [ … ]`
580
+ array. Review and paste the blocks yourself, then reconnect the clients and
581
+ re-run `clinkx settings show --effective` to confirm provenance.
582
+
583
+ Exit codes: `0` ok, `2` usage/validation error (the registry's own message on
584
+ a bad value; also `recover` without `--digest`), `1` runtime failure
585
+ (unreadable documents, revision conflicts, filesystem errors), `3` a mutation
586
+ was published but its durability could not be confirmed
587
+ (`published_uncertain` — re-read before retrying, never blind-retry), `130`
588
+ the interactive secret prompt was interrupted (nothing was written).
589
+ Conflicting writers — the dashboard and the CLI share one lock and
590
+ compare-and-swap on the document revision — surface as a conflict you can
591
+ retry. A lock held from another host (or one recording no host) is never
592
+ reclaimed automatically: the error names the `.lock` path and the manual
593
+ `rm '<path>'` after you confirm no writer is running on that host. On the
594
+ dashboard a lock that could not be acquired is its own known outcome — the
595
+ wire error `settings_locked` (HTTP 409, nothing published), distinct from
596
+ `settings_conflict`, so the page shows the lock guidance instead of the
597
+ "another writer saved" dialog.
297
598
 
298
599
  ### Session-log tool arguments rollout
299
600
 
@@ -518,6 +819,27 @@ Shutdown closes all dashboard listeners before auth/gateway resources. All
518
819
  cleanup failures are retained in one listener-or-resource aggregate, and signal
519
820
  handling remains idempotent.
520
821
 
822
+ ## Browser agent preview
823
+
824
+ The dashboard's **agent** control opts one page into page-local WebMCP tools for an
825
+ AI agent working in that tab, in bearer, passkey, auth-disabled and hosted sessions.
826
+ Access starts disabled on every page load, needs a secure top-level document with
827
+ the native `document.modelContext.registerTool` API, and is never saved. An
828
+ unsupported browser keeps ordinary dashboard use.
829
+
830
+ The five tools report the visible view (`clinkx_get_context`), list run identifiers
831
+ (`clinkx_list_runs`), navigate the page (`clinkx_open_view`) and, while the council
832
+ builder's run-workflow target is active, read and conditionally patch the visible
833
+ draft (`clinkx_get_draft`, `clinkx_patch_draft`), which the builder keeps in browser
834
+ storage like the user's own edits. No browser tool reads results or logs, launches a
835
+ workflow, calls a provider or saves a preset; agents with the ClinkX MCP server should
836
+ use it for those. There is no configuration beyond the
837
+ opt-in.
838
+
839
+ See the [dashboard WebMCP guide](dashboard-webmcp.md) for inputs, outcomes, bounds and
840
+ compatibility, and the [qualification record](dashboard-webmcp-qualification.md) for
841
+ the exact consumers and builds tested, including earlier failures.
842
+
521
843
  ## Context Builder
522
844
 
523
845
  `context_builder` stores runs under environment-configured local state and uses the same adapter registry as `clink` only when delegate mode is explicitly enabled in the request. Without `delegate.enabled:true`, it uses deterministic local curation and does not invoke a CLI adapter.