clinkx 1.3.0 → 1.4.1

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 (179) hide show
  1. package/CHANGELOG.md +57 -0
  2. package/README.md +13 -6
  3. package/clinkx-workflows/dist/child-env.d.ts +3 -0
  4. package/clinkx-workflows/dist/child-env.js +11 -0
  5. package/clinkx-workflows/dist/child-env.js.map +1 -1
  6. package/clinkx-workflows/dist/dashboard/api-routes.d.ts +21 -0
  7. package/clinkx-workflows/dist/dashboard/api-routes.js +27 -0
  8. package/clinkx-workflows/dist/dashboard/api-routes.js.map +1 -1
  9. package/clinkx-workflows/dist/dashboard/auth/challenge-store.d.ts +13 -0
  10. package/clinkx-workflows/dist/dashboard/auth/challenge-store.js.map +1 -1
  11. package/clinkx-workflows/dist/dashboard/auth/controller.d.ts +27 -0
  12. package/clinkx-workflows/dist/dashboard/auth/controller.js +262 -23
  13. package/clinkx-workflows/dist/dashboard/auth/controller.js.map +1 -1
  14. package/clinkx-workflows/dist/dashboard/auth/settings-step-up.d.ts +62 -0
  15. package/clinkx-workflows/dist/dashboard/auth/settings-step-up.js +70 -0
  16. package/clinkx-workflows/dist/dashboard/auth/settings-step-up.js.map +1 -0
  17. package/clinkx-workflows/dist/dashboard/request-admission.d.ts +6 -0
  18. package/clinkx-workflows/dist/dashboard/request-admission.js +9 -0
  19. package/clinkx-workflows/dist/dashboard/request-admission.js.map +1 -1
  20. package/clinkx-workflows/dist/dashboard/server-factory.js +15 -1
  21. package/clinkx-workflows/dist/dashboard/server-factory.js.map +1 -1
  22. package/clinkx-workflows/dist/dashboard/settings-contract.d.ts +1806 -0
  23. package/clinkx-workflows/dist/dashboard/settings-contract.js +630 -0
  24. package/clinkx-workflows/dist/dashboard/settings-contract.js.map +1 -0
  25. package/clinkx-workflows/dist/dashboard/settings-process-reader.d.ts +48 -0
  26. package/clinkx-workflows/dist/dashboard/settings-process-reader.js +195 -0
  27. package/clinkx-workflows/dist/dashboard/settings-process-reader.js.map +1 -0
  28. package/clinkx-workflows/dist/dashboard/settings-routes.d.ts +87 -0
  29. package/clinkx-workflows/dist/dashboard/settings-routes.js +690 -0
  30. package/clinkx-workflows/dist/dashboard/settings-routes.js.map +1 -0
  31. package/clinkx-workflows/dist/dashboard-ui/assets/index-CX4FrhYN.js +122 -0
  32. package/clinkx-workflows/dist/dashboard-ui/assets/style-C5guUjwN.css +1 -0
  33. package/clinkx-workflows/dist/dashboard-ui/index.html +2 -2
  34. package/clinkx-workflows/dist/durable-file-core.d.ts +76 -0
  35. package/clinkx-workflows/dist/durable-file-core.js +146 -0
  36. package/clinkx-workflows/dist/durable-file-core.js.map +1 -0
  37. package/clinkx-workflows/dist/durable-file.d.ts +8 -64
  38. package/clinkx-workflows/dist/durable-file.js +14 -137
  39. package/clinkx-workflows/dist/durable-file.js.map +1 -1
  40. package/clinkx-workflows/dist/index.js +68 -2
  41. package/clinkx-workflows/dist/index.js.map +1 -1
  42. package/clinkx-workflows/dist/settings/audit.d.ts +101 -0
  43. package/clinkx-workflows/dist/settings/audit.js +318 -0
  44. package/clinkx-workflows/dist/settings/audit.js.map +1 -0
  45. package/clinkx-workflows/dist/settings/bootstrap.d.ts +35 -0
  46. package/clinkx-workflows/dist/settings/bootstrap.js +52 -0
  47. package/clinkx-workflows/dist/settings/bootstrap.js.map +1 -0
  48. package/clinkx-workflows/dist/settings/codec.d.ts +51 -0
  49. package/clinkx-workflows/dist/settings/codec.js +410 -0
  50. package/clinkx-workflows/dist/settings/codec.js.map +1 -0
  51. package/clinkx-workflows/dist/settings/durable-write.d.ts +48 -0
  52. package/clinkx-workflows/dist/settings/durable-write.js +31 -0
  53. package/clinkx-workflows/dist/settings/durable-write.js.map +1 -0
  54. package/clinkx-workflows/dist/settings/index.d.ts +20 -0
  55. package/clinkx-workflows/dist/settings/index.js +23 -0
  56. package/clinkx-workflows/dist/settings/index.js.map +1 -0
  57. package/clinkx-workflows/dist/settings/loader.d.ts +80 -0
  58. package/clinkx-workflows/dist/settings/loader.js +577 -0
  59. package/clinkx-workflows/dist/settings/loader.js.map +1 -0
  60. package/clinkx-workflows/dist/settings/lock.d.ts +108 -0
  61. package/clinkx-workflows/dist/settings/lock.js +344 -0
  62. package/clinkx-workflows/dist/settings/lock.js.map +1 -0
  63. package/clinkx-workflows/dist/settings/paths.d.ts +65 -0
  64. package/clinkx-workflows/dist/settings/paths.js +173 -0
  65. package/clinkx-workflows/dist/settings/paths.js.map +1 -0
  66. package/clinkx-workflows/dist/settings/process-heartbeat.d.ts +47 -0
  67. package/clinkx-workflows/dist/settings/process-heartbeat.js +305 -0
  68. package/clinkx-workflows/dist/settings/process-heartbeat.js.map +1 -0
  69. package/clinkx-workflows/dist/settings/registry.d.ts +178 -0
  70. package/clinkx-workflows/dist/settings/registry.js +1290 -0
  71. package/clinkx-workflows/dist/settings/registry.js.map +1 -0
  72. package/clinkx-workflows/dist/settings/schema.d.ts +404 -0
  73. package/clinkx-workflows/dist/settings/schema.js +415 -0
  74. package/clinkx-workflows/dist/settings/schema.js.map +1 -0
  75. package/clinkx-workflows/dist/settings/store.d.ts +157 -0
  76. package/clinkx-workflows/dist/settings/store.js +842 -0
  77. package/clinkx-workflows/dist/settings/store.js.map +1 -0
  78. package/clinkx-workflows/dist/stdio-entry.d.ts +2 -0
  79. package/clinkx-workflows/dist/stdio-entry.js +52 -0
  80. package/clinkx-workflows/dist/stdio-entry.js.map +1 -0
  81. package/dist/dashboard-cli.d.ts +11 -3
  82. package/dist/dashboard-cli.js +199 -33
  83. package/dist/dashboard-cli.js.map +1 -1
  84. package/dist/dashboard-companion/client.d.ts +14 -0
  85. package/dist/dashboard-companion/client.js +16 -0
  86. package/dist/dashboard-companion/client.js.map +1 -1
  87. package/dist/dashboard-companion/credential-expectation.d.ts +23 -0
  88. package/dist/dashboard-companion/credential-expectation.js +50 -0
  89. package/dist/dashboard-companion/credential-expectation.js.map +1 -0
  90. package/dist/dashboard-companion/host-channel.d.ts +36 -0
  91. package/dist/dashboard-companion/host-channel.js +78 -0
  92. package/dist/dashboard-companion/host-channel.js.map +1 -0
  93. package/dist/dashboard-companion/host-status.d.ts +179 -0
  94. package/dist/dashboard-companion/host-status.js +122 -0
  95. package/dist/dashboard-companion/host-status.js.map +1 -0
  96. package/dist/dashboard-companion/protocol.js +17 -0
  97. package/dist/dashboard-companion/protocol.js.map +1 -1
  98. package/dist/dashboard-companion/standalone-assets.d.ts +8 -0
  99. package/dist/dashboard-companion/standalone-assets.js +7 -1
  100. package/dist/dashboard-companion/standalone-assets.js.map +1 -1
  101. package/dist/dashboard-companion/standalone-entry.js +34 -13
  102. package/dist/dashboard-companion/standalone-entry.js.map +1 -1
  103. package/dist/dashboard-gateway/control-plane/contracts.d.ts +38 -38
  104. package/dist/dashboard-gateway/tunnel-http.js +20 -0
  105. package/dist/dashboard-gateway/tunnel-http.js.map +1 -1
  106. package/dist/desktop-host/child-env.d.ts +23 -0
  107. package/dist/desktop-host/child-env.js +70 -0
  108. package/dist/desktop-host/child-env.js.map +1 -0
  109. package/dist/desktop-host/daemon-entry.d.ts +2 -0
  110. package/dist/desktop-host/daemon-entry.js +50 -0
  111. package/dist/desktop-host/daemon-entry.js.map +1 -0
  112. package/dist/desktop-host/daemon-env.d.ts +12 -0
  113. package/dist/desktop-host/daemon-env.js +35 -0
  114. package/dist/desktop-host/daemon-env.js.map +1 -0
  115. package/dist/desktop-host/daemon-protocol.d.ts +210 -0
  116. package/dist/desktop-host/daemon-protocol.js +56 -0
  117. package/dist/desktop-host/daemon-protocol.js.map +1 -0
  118. package/dist/desktop-host/daemon.d.ts +50 -0
  119. package/dist/desktop-host/daemon.js +441 -0
  120. package/dist/desktop-host/daemon.js.map +1 -0
  121. package/dist/desktop-host/enrollment.d.ts +17 -0
  122. package/dist/desktop-host/enrollment.js +25 -0
  123. package/dist/desktop-host/enrollment.js.map +1 -0
  124. package/dist/desktop-host/import.d.ts +14 -0
  125. package/dist/desktop-host/import.js +95 -0
  126. package/dist/desktop-host/import.js.map +1 -0
  127. package/dist/desktop-host/profile.d.ts +130 -0
  128. package/dist/desktop-host/profile.js +176 -0
  129. package/dist/desktop-host/profile.js.map +1 -0
  130. package/dist/desktop-host/service.d.ts +6 -0
  131. package/dist/desktop-host/service.js +7 -0
  132. package/dist/desktop-host/service.js.map +1 -0
  133. package/dist/desktop-host/supervisor.d.ts +57 -0
  134. package/dist/desktop-host/supervisor.js +256 -0
  135. package/dist/desktop-host/supervisor.js.map +1 -0
  136. package/dist/desktop-host/view-state.d.ts +138 -0
  137. package/dist/desktop-host/view-state.js +27 -0
  138. package/dist/desktop-host/view-state.js.map +1 -0
  139. package/dist/elaris/config.d.ts +10 -0
  140. package/dist/elaris/config.js +27 -1
  141. package/dist/elaris/config.js.map +1 -1
  142. package/dist/elaris/tools.js +4 -1
  143. package/dist/elaris/tools.js.map +1 -1
  144. package/dist/index.d.ts +0 -31
  145. package/dist/index.js +41 -404
  146. package/dist/index.js.map +1 -1
  147. package/dist/lib.d.ts +17 -0
  148. package/dist/lib.js +17 -0
  149. package/dist/lib.js.map +1 -0
  150. package/dist/progress-report/lock.d.ts +17 -59
  151. package/dist/progress-report/lock.js +25 -329
  152. package/dist/progress-report/lock.js.map +1 -1
  153. package/dist/registry.d.ts +7 -0
  154. package/dist/registry.js +21 -7
  155. package/dist/registry.js.map +1 -1
  156. package/dist/server.js +75 -4
  157. package/dist/server.js.map +1 -1
  158. package/dist/settings-cli/clients.d.ts +137 -0
  159. package/dist/settings-cli/clients.js +1124 -0
  160. package/dist/settings-cli/clients.js.map +1 -0
  161. package/dist/settings-cli/commands.d.ts +67 -0
  162. package/dist/settings-cli/commands.js +726 -0
  163. package/dist/settings-cli/commands.js.map +1 -0
  164. package/dist/settings-cli/format.d.ts +34 -0
  165. package/dist/settings-cli/format.js +40 -0
  166. package/dist/settings-cli/format.js.map +1 -0
  167. package/dist/settings-cli/main.d.ts +18 -0
  168. package/dist/settings-cli/main.js +256 -0
  169. package/dist/settings-cli/main.js.map +1 -0
  170. package/dist/stdio-main.d.ts +73 -0
  171. package/dist/stdio-main.js +455 -0
  172. package/dist/stdio-main.js.map +1 -0
  173. package/docs/configuration.md +340 -39
  174. package/docs/security.md +150 -6
  175. package/docs/verification/README.md +28 -2
  176. package/docs/verification/workflow-handoff.md +86 -0
  177. package/package.json +3 -3
  178. package/clinkx-workflows/dist/dashboard-ui/assets/index-DRId2DVA.js +0 -119
  179. package/clinkx-workflows/dist/dashboard-ui/assets/style-CHAw57y5.css +0 -1
@@ -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. 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}` |
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. 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` |
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
 
package/docs/security.md CHANGED
@@ -180,16 +180,160 @@ context without it must reauthenticate. Cloud passkey behavior remains
180
180
  cookie-only and its login response remains `{"verified":true}`.
181
181
 
182
182
  The first enrollment code is printed only when no credential exists. After the
183
- first durable credential is registered, recovery requires an authenticated
184
- session to add another passkey; losing every enrolled passkey requires backed-up
185
- re-enrollment into deliberately empty state. Cloud deployment is limited
183
+ first durable credential is registered, adding another passkey requires a live
184
+ session **plus a verified assertion from an already-enrolled passkey**
185
+ (`POST /api/auth/register/assert/{options,verify}`; `register/options` fails
186
+ closed with `403 passkey_assertion_required`). The reason: every enrolled
187
+ credential also passes every settings step-up, so a session that could enroll
188
+ its own authenticator could mint its own step-up authority. Deliberate
189
+ consequence: an owner who lost every enrolled authenticator but still has a
190
+ session cannot add a passkey and must use backed-up re-enrollment into
191
+ deliberately empty state. Cloud deployment is limited
186
192
  to one replica because session and challenge state are process-local and the
187
- credential writer is single-owner. Credential state belongs on a narrow
188
- independent read-write volume; operator progress-report status pins belong on
189
- a second independent read-write volume. All other dashboard input mounts remain
193
+ credential writer is single-owner. The dashboard deployment has exactly three
194
+ writable surfaces, each narrow and purpose-built: passkey credential state on an
195
+ independent read-write volume (`/data/dashboard-credentials`); operator
196
+ progress-report status pins and the prompt-builder library on a second
197
+ read-write volume (`/data/dashboard-overrides`); and — since the Settings page
198
+ (owner decision 2026-11-03, `.ai/plans/dashboard-settings/DECISIONS.md` #1) —
199
+ the settings directory, mounted as a read-write **host bind** at
200
+ `/data/settings` rather than a named volume, so host-side producers and
201
+ `clinkx settings …` see the same documents (`create_host_path: false`: run
202
+ `clinkx settings init` first; on Linux a host/container UID mismatch surfaces
203
+ as 503 `settings_unavailable` on save). All other dashboard input mounts remain
190
204
  read-only. Deployment preflight classifies strict-v1 absent/zero/nonzero state
191
205
  only; store open remains the sole RP-ID authority.
192
206
 
207
+ ### Dashboard settings authority
208
+
209
+ The dashboard Settings page **writes an execution input by design** (owner
210
+ decision 2026-11-03): every ClinkX server process reads the same
211
+ `~/.config/clinkx/settings/settings.json` at startup (env override
212
+ `CLINKX_SETTINGS_DIR`; `CLINKX_SETTINGS=off` disables loading entirely). This
213
+ deliberately reverses the earlier "the dashboard writes nothing any execution
214
+ path reads" rule for this one surface; adapters, rosters, and the two
215
+ dashboard-private sidecars keep their old constraints. Five routes exist:
216
+ `GET /api/settings`, `GET /api/settings/processes`, and the three POSTs
217
+ `/api/settings/save`, `/api/settings/secrets/save`, `/api/settings/step-up`.
218
+
219
+ **Auth matrix (OQ-7).** Tuning, retention, feature-gate, and reader-first keys
220
+ save with a normal session and are allowed in passkey, bearer, and none auth
221
+ modes (POST Origin enforcement stays with the server factory). Any op touching
222
+ a **policy** or **secret** key requires a *fresh passkey step-up*: the class of
223
+ change is computed **server-side from the registry** (`opsTouchElevatedClass`),
224
+ so the client cannot downgrade a policy save to tuning. **Every `recover` save
225
+ requires a step-up regardless of its ops** — recovering an unreadable document
226
+ is always elevated, and the intent digest additionally binds the
227
+ recovery fact (`recover:true` plus the `expectedDigest` sha256 of the corrupt
228
+ bytes), so a recovery ceremony cannot be replayed against an ordinary save (or
229
+ vice versa). The ceremony binds the assertion to the save it authorizes: the
230
+ server computes an intent digest (sha256 over the secret-free projection
231
+ `{target, expected_revision, recover?, expected_digest?, ops:[{key, action,
232
+ value-if-not-secret}]}` — secret values never enter the digest), mints a
233
+ challenge bound to `{sessionId, intentDigest}` with a **120 s TTL**, and the
234
+ save request must carry `{challengeId, assertion}`; verification recomputes the
235
+ digest from *this* request, checks the session binding, requires
236
+ `userVerification:"required"`, and **consumes the challenge once** with the
237
+ write attempt. Step-up challenges live in a dedicated store, purpose-checked on
238
+ consume: a login challenge can never satisfy a step-up (or vice versa), and a
239
+ step-up never mints a session. Bearer and none modes have no session to bind a
240
+ challenge to, so policy/secret intents — including step-up option requests and
241
+ recover — fail 403 `step_up_unavailable` there; the UI then shows the
242
+ `clinkx settings recover --digest <sha256>` CLI command instead. A passkey
243
+ deployment with no enrolled credential fails the same way.
244
+
245
+ **Audit log.** Every save (all classes) appends a **pending** line to
246
+ `audit.jsonl` *before* anything is published and an outcome line after
247
+ (0600, `O_APPEND|O_CREAT|O_NOFOLLOW`, fsynced per line, ≤4 KiB per line with a
248
+ `keysOmitted` marker when truncated, rotated once at 1 MiB). A failed pending
249
+ append is a clean 503 with **nothing published**; a failed outcome append —
250
+ the bytes are already live — surfaces as `settings_published_uncertain` (HTTP
251
+ 500, the landed revision in the body), never a clean rejection. A line carries
252
+ `{schema_version, at, actor, auth, keys, classes, action, revisionBefore,
253
+ revisionAfter, digestAfter, outcome}` — **key names, classes, revisions, and a
254
+ document digest, never values**. `digestAfter` (sha256 of the settings bytes) is
255
+ omitted for secrets saves: hashing the secrets document would hash secret
256
+ material into the log.
257
+
258
+ **Secrets.** Secret-class keys (v1: `CLINKX_ELARIS_API_KEY`) live only in a
259
+ separate `secrets.json`, mode `0600`, with its own revision under the same
260
+ lock. The browser sees write-only state: set/unset plus `updated_at`, never the
261
+ value; values are never returned, logged, hashed into DTOs, or audited. A
262
+ secrets file whose mode allows group/other access is refused — reads treat it
263
+ as unset with a warning and the next save rewrites it 0600. A secret-class key
264
+ inside the (0644, world-readable) `settings.json` is dropped loudly: it never
265
+ applies from the shared document, is never re-serialized by a save, and is
266
+ **filtered out of `GET /api/settings` `values` by the response schema** — a
267
+ secret can never round-trip through the read path.
268
+
269
+ **What the step-up does not protect.** Filesystem-write parity: anything that
270
+ can write `$HOME` (any process running as the user, any editor, any
271
+ unsandboxed CLI the user runs) can edit or replace the settings documents
272
+ directly. The passkey ceremony protects only the *dashboard write path*; it is
273
+ an authority control on the UI, not a filesystem boundary. Symmetrically,
274
+ `settings.json` is 0644 by design (the dashboard container reads it as another
275
+ user), so non-secret settings are not confidential. External edits are
276
+ *detected*, not prevented: the store's `read()` compares the sha256 of the
277
+ current bytes against the last audited `digestAfter` and reports the mismatch
278
+ as `externalEdit` (the audit log is the oracle; the dashboard GET wire does not
279
+ yet project the flag).
280
+
281
+ **Hosted path.** The hosted topology (gateway → tunnel → companion) forwards
282
+ exactly three settings POST literals — `/api/settings/save`,
283
+ `/api/settings/secrets/save`, `/api/settings/step-up` — with byte tiers
284
+ matching the dashboard's own route caps: 64 KiB for saves (a WebAuthn assertion
285
+ plus at most 64 ops) and 16 KiB for step-up options (intent projection only,
286
+ never secret values). The literals are pinned locally in
287
+ `src/dashboard-companion/protocol.ts` and `src/dashboard-gateway/tunnel-http.ts`
288
+ (closed transport graphs) and pinned against the settings contract by tests.
289
+
290
+ **WebMCP.** Settings are never exposed through WebMCP tools: the only
291
+ settings-related surface is the `clinkx_open_view` navigation `{kind:"settings"}`,
292
+ which carries no settings data; no WebMCP tool reads or writes settings.
293
+
294
+ **Failure behavior.** A settings-origin fault never prevents startup. A whole
295
+ document that is unreadable (corrupt JSON, bad shape, unsupported
296
+ `schema_version`, over the 256 KiB cap, symlink, or non-regular) is treated as
297
+ **absent** with loud warnings — no fills at all, and the per-process heartbeat
298
+ reports the unreadable state so the dashboard shows a banner (the shipped
299
+ defaults are not uniformly the safest choice; see `docs/configuration.md`
300
+ "Unreadable files"). A routine save refuses to overwrite it; recovery is an
301
+ explicit `recover` save — always step-up-gated, bound to the digest of the
302
+ corrupt bytes — which **copies** them to `settings.json.corrupt-<epochms>-<rand>`
303
+ through the durable writer and atomically replaces the active path (it never
304
+ renames the active path, and never deletes). A per-key *invalid* value follows
305
+ the registry policy: tuning keys are
306
+ not filled (the consumer default applies) with a warning; policy keys are filled
307
+ with their most-restrictive value (e.g. `CLINKX_CONTEXT_ALLOW_SECRETS` →
308
+ `false`, `CLINKX_MAX_AGENT_DEPTH` → `1`); `CLINKX_ALLOWED_ROOTS` is never filled
309
+ from an invalid file value (the no-config `cwd()` default applies, loudly).
310
+ Unknown keys warn and are ignored, so mixed code versions can share one file —
311
+ and a save persists unknown and untouched invalid entries verbatim.
312
+ Apply is **restart-only**: each server heartbeats its loaded settings revision,
313
+ secrets revision, and provenance to `<settingsDir>/processes/` (the process id
314
+ is the boot nonce, so restarts never alias), and the dashboard's processes view
315
+ lists which servers run the current revision, which are stale, and which keys
316
+ take their value from env (names only, even with no file value); a row that
317
+ fails validation is skipped with a warning and never fails the whole response.
318
+ See `docs/configuration.md` ("Settings file") and the Settings ADR in
319
+ `docs/architecture.md`.
320
+
321
+ **Writer exclusion.** The dashboard and the CLI share one cross-process lock
322
+ over the settings directory. A lock held from **another host, or one recording
323
+ no hostname at all, is never reclaimed automatically** — no staleness
324
+ heuristic can distinguish a dead foreign holder from a suspended one, so the
325
+ acquire deadline expires and the error names the `.lock` path, the recorded
326
+ host/pid, and the manual step ("confirm no writer runs on `<host>`, then
327
+ `rm '<lockPath>'`"); on the dashboard this surfaces as the wire error
328
+ `settings_locked` (HTTP 409) — a known nothing-published outcome, distinct
329
+ from the `settings_conflict` revision-CAS rejection. The lock body is published
330
+ atomically (`O_EXCL` temp +
331
+ `link`), so a partial or empty `.lock` can never exist to wedge every future
332
+ save. Only a same-host dead PID is reclaimed, serialized behind a second
333
+ `O_EXCL` `.lock.steal` file with the body re-observed under it before any
334
+ unlink. The same core (in `clinkx-workflows/src/settings/lock.ts`) backs the
335
+ progress-report session lock; the two surfaces cannot drift.
336
+
193
337
  Bearer mode remains a transitional rollback path until both a real local
194
338
  platform-passkey ceremony and a live same-origin Traefik ceremony have passed.
195
339
  The authenticated dashboard response path must not log enrollment codes,