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.
- package/CHANGELOG.md +57 -0
- package/README.md +13 -6
- package/clinkx-workflows/dist/child-env.d.ts +3 -0
- package/clinkx-workflows/dist/child-env.js +11 -0
- package/clinkx-workflows/dist/child-env.js.map +1 -1
- package/clinkx-workflows/dist/dashboard/api-routes.d.ts +21 -0
- package/clinkx-workflows/dist/dashboard/api-routes.js +27 -0
- package/clinkx-workflows/dist/dashboard/api-routes.js.map +1 -1
- package/clinkx-workflows/dist/dashboard/auth/challenge-store.d.ts +13 -0
- package/clinkx-workflows/dist/dashboard/auth/challenge-store.js.map +1 -1
- package/clinkx-workflows/dist/dashboard/auth/controller.d.ts +27 -0
- package/clinkx-workflows/dist/dashboard/auth/controller.js +262 -23
- package/clinkx-workflows/dist/dashboard/auth/controller.js.map +1 -1
- package/clinkx-workflows/dist/dashboard/auth/settings-step-up.d.ts +62 -0
- package/clinkx-workflows/dist/dashboard/auth/settings-step-up.js +70 -0
- package/clinkx-workflows/dist/dashboard/auth/settings-step-up.js.map +1 -0
- package/clinkx-workflows/dist/dashboard/request-admission.d.ts +6 -0
- package/clinkx-workflows/dist/dashboard/request-admission.js +9 -0
- package/clinkx-workflows/dist/dashboard/request-admission.js.map +1 -1
- package/clinkx-workflows/dist/dashboard/server-factory.js +15 -1
- package/clinkx-workflows/dist/dashboard/server-factory.js.map +1 -1
- package/clinkx-workflows/dist/dashboard/settings-contract.d.ts +1806 -0
- package/clinkx-workflows/dist/dashboard/settings-contract.js +630 -0
- package/clinkx-workflows/dist/dashboard/settings-contract.js.map +1 -0
- package/clinkx-workflows/dist/dashboard/settings-process-reader.d.ts +48 -0
- package/clinkx-workflows/dist/dashboard/settings-process-reader.js +195 -0
- package/clinkx-workflows/dist/dashboard/settings-process-reader.js.map +1 -0
- package/clinkx-workflows/dist/dashboard/settings-routes.d.ts +87 -0
- package/clinkx-workflows/dist/dashboard/settings-routes.js +690 -0
- package/clinkx-workflows/dist/dashboard/settings-routes.js.map +1 -0
- package/clinkx-workflows/dist/dashboard-ui/assets/index-CX4FrhYN.js +122 -0
- package/clinkx-workflows/dist/dashboard-ui/assets/style-C5guUjwN.css +1 -0
- package/clinkx-workflows/dist/dashboard-ui/index.html +2 -2
- package/clinkx-workflows/dist/durable-file-core.d.ts +76 -0
- package/clinkx-workflows/dist/durable-file-core.js +146 -0
- package/clinkx-workflows/dist/durable-file-core.js.map +1 -0
- package/clinkx-workflows/dist/durable-file.d.ts +8 -64
- package/clinkx-workflows/dist/durable-file.js +14 -137
- package/clinkx-workflows/dist/durable-file.js.map +1 -1
- package/clinkx-workflows/dist/index.js +68 -2
- package/clinkx-workflows/dist/index.js.map +1 -1
- package/clinkx-workflows/dist/settings/audit.d.ts +101 -0
- package/clinkx-workflows/dist/settings/audit.js +318 -0
- package/clinkx-workflows/dist/settings/audit.js.map +1 -0
- package/clinkx-workflows/dist/settings/bootstrap.d.ts +35 -0
- package/clinkx-workflows/dist/settings/bootstrap.js +52 -0
- package/clinkx-workflows/dist/settings/bootstrap.js.map +1 -0
- package/clinkx-workflows/dist/settings/codec.d.ts +51 -0
- package/clinkx-workflows/dist/settings/codec.js +410 -0
- package/clinkx-workflows/dist/settings/codec.js.map +1 -0
- package/clinkx-workflows/dist/settings/durable-write.d.ts +48 -0
- package/clinkx-workflows/dist/settings/durable-write.js +31 -0
- package/clinkx-workflows/dist/settings/durable-write.js.map +1 -0
- package/clinkx-workflows/dist/settings/index.d.ts +20 -0
- package/clinkx-workflows/dist/settings/index.js +23 -0
- package/clinkx-workflows/dist/settings/index.js.map +1 -0
- package/clinkx-workflows/dist/settings/loader.d.ts +80 -0
- package/clinkx-workflows/dist/settings/loader.js +577 -0
- package/clinkx-workflows/dist/settings/loader.js.map +1 -0
- package/clinkx-workflows/dist/settings/lock.d.ts +108 -0
- package/clinkx-workflows/dist/settings/lock.js +344 -0
- package/clinkx-workflows/dist/settings/lock.js.map +1 -0
- package/clinkx-workflows/dist/settings/paths.d.ts +65 -0
- package/clinkx-workflows/dist/settings/paths.js +173 -0
- package/clinkx-workflows/dist/settings/paths.js.map +1 -0
- package/clinkx-workflows/dist/settings/process-heartbeat.d.ts +47 -0
- package/clinkx-workflows/dist/settings/process-heartbeat.js +305 -0
- package/clinkx-workflows/dist/settings/process-heartbeat.js.map +1 -0
- package/clinkx-workflows/dist/settings/registry.d.ts +178 -0
- package/clinkx-workflows/dist/settings/registry.js +1290 -0
- package/clinkx-workflows/dist/settings/registry.js.map +1 -0
- package/clinkx-workflows/dist/settings/schema.d.ts +404 -0
- package/clinkx-workflows/dist/settings/schema.js +415 -0
- package/clinkx-workflows/dist/settings/schema.js.map +1 -0
- package/clinkx-workflows/dist/settings/store.d.ts +157 -0
- package/clinkx-workflows/dist/settings/store.js +842 -0
- package/clinkx-workflows/dist/settings/store.js.map +1 -0
- package/clinkx-workflows/dist/stdio-entry.d.ts +2 -0
- package/clinkx-workflows/dist/stdio-entry.js +52 -0
- package/clinkx-workflows/dist/stdio-entry.js.map +1 -0
- package/dist/dashboard-cli.d.ts +11 -3
- package/dist/dashboard-cli.js +199 -33
- package/dist/dashboard-cli.js.map +1 -1
- package/dist/dashboard-companion/client.d.ts +14 -0
- package/dist/dashboard-companion/client.js +16 -0
- package/dist/dashboard-companion/client.js.map +1 -1
- package/dist/dashboard-companion/credential-expectation.d.ts +23 -0
- package/dist/dashboard-companion/credential-expectation.js +50 -0
- package/dist/dashboard-companion/credential-expectation.js.map +1 -0
- package/dist/dashboard-companion/host-channel.d.ts +36 -0
- package/dist/dashboard-companion/host-channel.js +78 -0
- package/dist/dashboard-companion/host-channel.js.map +1 -0
- package/dist/dashboard-companion/host-status.d.ts +179 -0
- package/dist/dashboard-companion/host-status.js +122 -0
- package/dist/dashboard-companion/host-status.js.map +1 -0
- package/dist/dashboard-companion/protocol.js +17 -0
- package/dist/dashboard-companion/protocol.js.map +1 -1
- package/dist/dashboard-companion/standalone-assets.d.ts +8 -0
- package/dist/dashboard-companion/standalone-assets.js +7 -1
- package/dist/dashboard-companion/standalone-assets.js.map +1 -1
- package/dist/dashboard-companion/standalone-entry.js +34 -13
- package/dist/dashboard-companion/standalone-entry.js.map +1 -1
- package/dist/dashboard-gateway/control-plane/contracts.d.ts +38 -38
- package/dist/dashboard-gateway/tunnel-http.js +20 -0
- package/dist/dashboard-gateway/tunnel-http.js.map +1 -1
- package/dist/desktop-host/child-env.d.ts +23 -0
- package/dist/desktop-host/child-env.js +70 -0
- package/dist/desktop-host/child-env.js.map +1 -0
- package/dist/desktop-host/daemon-entry.d.ts +2 -0
- package/dist/desktop-host/daemon-entry.js +50 -0
- package/dist/desktop-host/daemon-entry.js.map +1 -0
- package/dist/desktop-host/daemon-env.d.ts +12 -0
- package/dist/desktop-host/daemon-env.js +35 -0
- package/dist/desktop-host/daemon-env.js.map +1 -0
- package/dist/desktop-host/daemon-protocol.d.ts +210 -0
- package/dist/desktop-host/daemon-protocol.js +56 -0
- package/dist/desktop-host/daemon-protocol.js.map +1 -0
- package/dist/desktop-host/daemon.d.ts +50 -0
- package/dist/desktop-host/daemon.js +441 -0
- package/dist/desktop-host/daemon.js.map +1 -0
- package/dist/desktop-host/enrollment.d.ts +17 -0
- package/dist/desktop-host/enrollment.js +25 -0
- package/dist/desktop-host/enrollment.js.map +1 -0
- package/dist/desktop-host/import.d.ts +14 -0
- package/dist/desktop-host/import.js +95 -0
- package/dist/desktop-host/import.js.map +1 -0
- package/dist/desktop-host/profile.d.ts +130 -0
- package/dist/desktop-host/profile.js +176 -0
- package/dist/desktop-host/profile.js.map +1 -0
- package/dist/desktop-host/service.d.ts +6 -0
- package/dist/desktop-host/service.js +7 -0
- package/dist/desktop-host/service.js.map +1 -0
- package/dist/desktop-host/supervisor.d.ts +57 -0
- package/dist/desktop-host/supervisor.js +256 -0
- package/dist/desktop-host/supervisor.js.map +1 -0
- package/dist/desktop-host/view-state.d.ts +138 -0
- package/dist/desktop-host/view-state.js +27 -0
- package/dist/desktop-host/view-state.js.map +1 -0
- package/dist/elaris/config.d.ts +10 -0
- package/dist/elaris/config.js +27 -1
- package/dist/elaris/config.js.map +1 -1
- package/dist/elaris/tools.js +4 -1
- package/dist/elaris/tools.js.map +1 -1
- package/dist/index.d.ts +0 -31
- package/dist/index.js +41 -404
- package/dist/index.js.map +1 -1
- package/dist/lib.d.ts +17 -0
- package/dist/lib.js +17 -0
- package/dist/lib.js.map +1 -0
- package/dist/progress-report/lock.d.ts +17 -59
- package/dist/progress-report/lock.js +25 -329
- package/dist/progress-report/lock.js.map +1 -1
- package/dist/registry.d.ts +7 -0
- package/dist/registry.js +21 -7
- package/dist/registry.js.map +1 -1
- package/dist/server.js +75 -4
- package/dist/server.js.map +1 -1
- package/dist/settings-cli/clients.d.ts +137 -0
- package/dist/settings-cli/clients.js +1124 -0
- package/dist/settings-cli/clients.js.map +1 -0
- package/dist/settings-cli/commands.d.ts +67 -0
- package/dist/settings-cli/commands.js +726 -0
- package/dist/settings-cli/commands.js.map +1 -0
- package/dist/settings-cli/format.d.ts +34 -0
- package/dist/settings-cli/format.js +40 -0
- package/dist/settings-cli/format.js.map +1 -0
- package/dist/settings-cli/main.d.ts +18 -0
- package/dist/settings-cli/main.js +256 -0
- package/dist/settings-cli/main.js.map +1 -0
- package/dist/stdio-main.d.ts +73 -0
- package/dist/stdio-main.js +455 -0
- package/dist/stdio-main.js.map +1 -0
- package/docs/configuration.md +340 -39
- package/docs/security.md +150 -6
- package/docs/verification/README.md +28 -2
- package/docs/verification/workflow-handoff.md +86 -0
- package/package.json +3 -3
- package/clinkx-workflows/dist/dashboard-ui/assets/index-DRId2DVA.js +0 -119
- package/clinkx-workflows/dist/dashboard-ui/assets/style-CHAw57y5.css +0 -1
package/docs/configuration.md
CHANGED
|
@@ -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
|
-
| `
|
|
261
|
-
| `
|
|
262
|
-
| `
|
|
263
|
-
| `
|
|
264
|
-
| `
|
|
265
|
-
| `
|
|
266
|
-
| `
|
|
267
|
-
| `
|
|
268
|
-
| `
|
|
269
|
-
| `
|
|
270
|
-
| `
|
|
271
|
-
| `
|
|
272
|
-
| `
|
|
273
|
-
| `
|
|
274
|
-
| `
|
|
275
|
-
| `
|
|
276
|
-
| `
|
|
277
|
-
| `
|
|
278
|
-
| `
|
|
279
|
-
| `
|
|
280
|
-
| `
|
|
281
|
-
| `
|
|
282
|
-
| `
|
|
283
|
-
| `
|
|
284
|
-
| `
|
|
285
|
-
| `
|
|
286
|
-
| `
|
|
287
|
-
| `
|
|
288
|
-
| `
|
|
289
|
-
| `
|
|
290
|
-
| `
|
|
291
|
-
| `
|
|
292
|
-
| `
|
|
293
|
-
| `
|
|
294
|
-
| `
|
|
295
|
-
| `
|
|
296
|
-
| `
|
|
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,
|
|
184
|
-
session
|
|
185
|
-
|
|
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.
|
|
188
|
-
|
|
189
|
-
|
|
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,
|