clinkx 1.0.0 → 1.1.1

package/docs/configuration.md

@@ -0,0 +1,426 @@
+# Configuration
+
+ClinkX is config-driven: you define one or more **CLI adapters** as JSON files. At runtime, ClinkX loads adapters into a registry and resolves `cli_name` from each `tools/call` request.
+
+## Config Discovery Order
+
+ClinkX discovers adapter JSON files in this order:
+
+1. `CLINKX_CONFIG_PATH` (file or directory) — **replaces** the search path entirely; shipped adapters are not loaded
+2. `${XDG_CONFIG_HOME:-~/.config}/clinkx/adapters/*.json`
+3. Packaged `conf/adapters/*.json` relative to the installed package (`import.meta.url`), **not** `process.cwd()`
+
+If the same adapter name appears more than once, ClinkX uses **first-wins**: the higher-precedence source (discovered earlier in the order above) is kept, and any later file with the same name is skipped with a log line naming the kept and skipped paths. ClinkX does not fail on a duplicate name. A leftover XDG file that fails schema validation aborts the whole load; with default-on workflow preflight that is a fatal `ConfigError`.
+
+## Adapter JSON Reference
+
+Minimal adapter:
+
+```json
+{
+  "name": "agy",
+  "command": "agy"
+}
+```
+
+Full field reference:
+
+| Field | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `name` | string | (required) | Adapter name used as `cli_name`. Must be unique. |
+| `command` | string | (required) | Executable to spawn. Uses `shell:false`. |
+| `runner` | string | (optional) | Reserved for future compatibility; unused by v1. |
+| `args` | string[] | `[]` | Safe args always included. |
+| `unsafe_args` | string[] | `[]` | Always merged with `args` at runtime. Use for permission-bypass flags needed by non-interactive subprocesses. |
+| `env` | record<string,string> | `{}` | Env injected into subprocess. |
+| `env_allowlist` | string[] | `[]` | Additional env keys copied from the ClinkX process. |
+| `timeout_seconds` | number | `600` | Per-call timeout (can be overridden by request `timeout_seconds`). |
+| `parser` | enum | `"text"` | One of: `text`, `json_extract`, `codex_jsonl`, `claude_json`, `claude_stream_json`, `agy_stream_json`. |
+| `tolerate_nonzero_exit_for_parse` | boolean | `false` | If true: a non-zero exit is treated as non-error when a valid payload is parsed. |
+| `capabilities_hint` | string | (optional) | Inserted into the prompt to reflect the CLI agent’s capabilities. |
+| `roles` | record<string,Role> | `{}` | Role prompts selected by request `role` (default: `"default"`). |
+| `supports_images` | boolean | `false` | Informational (v1 does not inline image bytes). |
+| `requires_tty` | boolean | `false` | If true: ClinkX rejects the call (PTY/TTY not supported in v1). |
+| `result_contract` | object | `{ enabled:false, filename:"RESULT.md" }` | Optional file-based result extraction from the run dir. |
+| `prompt_mode` | enum | `"stdin"` | One of: `stdin`, `arg`, `file`. Controls how the assembled prompt is delivered. |
+| `prompt_file_flag` | string | (optional) | Flag starting with `-`, valid only with `prompt_mode:"file"`; delivery emits the flag and generated path together. |
+| `invocation_overrides` | object | (optional) | Strict adapter consent block for per-call `model` and `effort`. Each knob declares an exactly two-token `args` template; effort also requires `allowed_values`. Load-time validation rejects a knob flag that exactly equals any `unsafe_args` token, `prompt_file_flag`, `native_output_file_flag`, or `stdin_placeholder_arg`. Collisions with base `args` / role `extra_args` remain legal (replacement targets). Not supported on `backend:"app_server"`. |
+
+> **Migration note (breaking): `gemini_json` parser removed.** The `gemini` adapter and its `gemini_json` parser were removed in favor of the `agy` (Google Antigravity CLI) adapter. `gemini_json` is no longer a valid `parser` value, so any adapter config still declaring `parser: "gemini_json"` — in this repo or in your `~/.config/clinkx/adapters/*.json` — now fails `CliAdapterConfigSchema` validation when the adapters are loaded, which aborts server startup (independent of the workflow-context preflight, though preflight-enabled mode likewise hard-requires a valid registry). The server will not start until it is fixed. If you have a custom adapter using `parser: "gemini_json"` that is not emitting agy stream-json, rename it and set `parser: "text"`. Shipped agy uses `parser: "agy_stream_json"` with `--output-format stream-json`.
+
+Role object (`roles.<roleName>`):
+
+| Field | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `inline_prompt` | string | (optional) | Inline role instruction inserted at top of prompt. |
+| `prompt_file` | string | (optional) | Path (relative to the adapter config) to a prompt file, resolved into `inline_prompt` at load time; `inline_prompt` wins if both are set. |
+| `parser` | enum | (optional) | Per-role parser override; falls back to the adapter-level `parser` when unset. |
+| `extra_args` | string[] | `[]` | Extra args appended after the adapter `args` for this role (CLI last-wins semantics). |
+
+## Per-call model and effort
+
+`clink` accepts independently optional `model` and `effort` values. Omitting both preserves the complete argv, including the CLI's configured defaults. Callers cannot supply flags or templates. Models are trimmed, nonblank identifiers of 1–128 characters with no whitespace, NUL (U+0000), or leading `-`. Effort is trimmed, 1–32 characters, matches `^[a-z0-9][a-z0-9_-]*$`, and must belong to the resolved adapter's allowlist.
+
+An adapter opts in explicitly, for example:
+
+```json
+"invocation_overrides": {
+  "model": { "args": ["--model", "{value}"] },
+  "effort": {
+    "args": ["-c", "model_reasoning_effort={value}"],
+    "allowed_values": ["none", "minimal", "low", "medium", "high", "xhigh", "max"]
+  }
+}
+```
+
+Templates contain exactly two nonempty tokens: a literal flag starting with `-` and containing no `{value}`, then a token containing `{value}` exactly once. A static value prefix is supported, including a dash-leading prefix such as `--model={value}`. Model and effort templates may share a flag only when their static prefixes are disjoint: neither prefix may start with the other. Equal prefixes and an empty prefix shared with any other prefix are rejected; different suffixes after `{value}` do not disambiguate them. Different flags may use overlapping prefixes. Unknown keys inside the block and invalid templates fail adapter loading. A custom adapter with overlapping same-flag templates now fails registry loading instead of silently losing an override; none of the nine shipped subprocess adapters has this conflict.
+
+| CLI | Model | Effort | Allowed effort values |
+| --- | --- | --- | --- |
+| Claude / GLM | `--model <value>` | `--effort <value>` | `low`, `medium`, `high`, `xhigh`, `max` |
+| Grok | `--model <value>` | `--effort <value>` | `low`, `medium`, `high`, `xhigh` |
+| agy | `--model <value>` | `--effort <value>` | `low`, `medium`, `high` |
+| Codex | `--model <value>` | `-c model_reasoning_effort=<value>` | `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max` |
+
+The same declarations apply to the shipped hapi templates. A declaration describes argv support, not provider acceptance of a model or proof that the provider honors effort. GLM effort honoring remains best-effort unless independently qualified. Some agy model IDs already encode effort (`…-high`, `…-low`); passing both knobs can fail at spawn with a provider error even when the effort value is in `allowed_values`.
+
+Replacement is key-aware across adapter `args` and role `extra_args`: scan the original arguments once, remove every matching requested `[flag, value]` pair, then append model followed by effort before `unsafe_args`, native output, and prompt delivery. Matching uses the exact template flag and complete value shape: both the static prefix and suffix must match, and the candidate must be long enough for those static fragments not to overlap. Suffixes participate in ownership of a particular pair, but still do not disambiguate two same-flag knob declarations during load-time validation. Both declared templates identify pairs, even when only one override is requested: a recognized nonrequested pair remains intact, and its value is not interpreted as another flag. Newly rendered values are never scanned for removal. Thus `-c model_reasoning_effort=high` is replaced while `-c sandbox_mode=read-only` survives; a template `-c model={value}.json` owns `-c model=old.json` but preserves `-c model=old.txt` as unrelated. Aliases are not matched: `-m` is not `--model`. A nonempty prefix can own a dash-leading value; an empty prefix only owns a non-dash value. A requested empty-prefix bare flag is removed alone without consuming an unrecognized following flag. A requested nonempty-prefix flag followed by a dash-leading token that does not match its complete value shape is left intact so the follower is not orphaned. Unrelated arguments remain unchanged. Load-time validation rejects a declared invocation flag that collides with `unsafe_args`, `prompt_file_flag`, `native_output_file_flag`, or `stdin_placeholder_arg`. Collisions with base `args` / role `extra_args` remain legal replacement targets. `unsafe_args` is still not pin-swept at render time. `_debug` reports `requested_model` / `requested_effort` (the request), not argv. To witness the effective argv, set `CLINKX_LOG_LEVEL=debug` and read the stderr pino record `spawning subprocess` (`command` / `args`). Do not claim `_debug.argv` exists.
+
+Unsupported knobs, malformed values, and effort outside the allowlist return MCP `-32602` before spawning. Root-hosted workflows validate effective calls before mutex/state creation for both sync and async requests; standalone workflows without the registry hook reject at dispatch as a permanent, non-retryable error. Context-builder delegates reject unsupported knobs under both `fail` and `fallback` policies, before run state. Delegate `InvalidParamsError` is never converted into fallback success, including an unknown provider CLI discovered at dispatch when no knobs were requested. A syntactically valid but unknown provider model can still fail at runtime.
+
+The GLM `[1m]` suffix and `CLAUDE_CODE_AUTO_COMPACT_WINDOW` are adapter-level choices. A per-call model without `[1m]` selects the 200k route; the override does not rewrite companion environment settings. Keep the model and configured context window compatible.
+
+### Invocation audit V2 writer activation
+
+Invocation-audit readers are always V1/V2-capable, but every V2 persistence surface is disabled by default. Set `CLINKX_INVOCATION_AUDIT_V2_PERSISTENCE_ENABLED=true` (exact lowercase value) on producers only after all dashboards/readers have been upgraded. Unset, empty, `false`, `TRUE`, `1`, and whitespace-padded values are disabled: workflow `state_version: 1` call entries omit `invocation`, direct activity state is exact `ActivityStateV1` without `invocation`, and context-builder delegate calls do not update `invocation-audit.json`. A disabled sidecar update leaves any existing bytes untouched.
+
+With exact `true`, root-hosted workflow calls persist their derived V2 audit, direct activities use `ActivityStateV2` when audit evidence exists, and curator/finalizer calls update the V2 sidecar. Standalone workflows still have no adapter registry/audit derivation capability, so their calls omit `invocation` even when the control is enabled. For rollback, disable producers first and retain V2-capable readers until all previously written V2 workflow state, activities, and sidecars have expired; disabling the control does not delete or downgrade existing V2 bytes.
+
+**XDG migration and resume:** first-wins remains whole-file; a user override file must declare the block itself. Editing a referenced adapter (stage calls plus an enabled context delegate's curator and an effectively enabled finalizer) changes the fingerprint of runs using an explicit child config; unreferenced adapter JSON does not. Before any repo or XDG adapter edit, inventory unfinished resumable generic runs (`running`, `pending`, `failed`, and `cancelled`) and drain, resume to completion, or explicitly abandon them. Generic failed/cancelled status does not itself prohibit resume. Pre-edit runs become non-resumable across the fingerprint boundary; repeat the inventory for rollback. Unfinished resumable runs can also become non-resumable across a ClinkX upgrade that changes fingerprint composition (enabled context curator/finalizer refs), even if adapter JSON is unchanged — inventory/drain/abandon before deploying such a build, not only before adapter edits. Configs that omit both new keys retain their old normalized fingerprint shape. XDG edits and configured MCP restarts require separate authorization.
+
+### Observed invocation writer activation
+
+`ObservedInvocationV1` is a sibling persistence surface to the V2 audit — observed runtime telemetry, not another V2 provenance. Its writer gate is `CLINKX_OBSERVED_INVOCATION_PERSISTENCE_ENABLED` (exact lowercase `true` only), independent of `CLINKX_INVOCATION_AUDIT_V2_PERSISTENCE_ENABLED`, and off by default: unset, empty, `false`, `TRUE`, `1`, and whitespace-padded values write nothing. Readers always accept `ObservedInvocationV1` regardless of the control. Rollback mirrors the V2 sequence — disable writers first; disabling never scrubs already-persisted bytes. Observed values must never be baked into adapter JSON, run fingerprints, or `wfctx` cache keys. Authoritative observation sources are the `claude_stream_json` `system/init` `model` and the app-server `thread/start` `model` plus a string `reasoningEffort`; Codex exec JSONL and agy remain unknown (the dashboard renders unknown as "CLI default").
+
+## Examples
+
+### agy (Google Antigravity CLI, stream-json)
+
+Shipped ClinkX uses `parser: "agy_stream_json"` with `--output-format stream-json`. Prompt delivery stays on stdin. Adapter `args` do not include `--print`. This is **not** Claude/Codex compatible. Grok still uses `claude_stream_json` because Grok's `streaming-messages-json` is Anthropic-shaped.
+
+The stream-json discriminator is `event` (`init`, `step_update`, `result`). Canonical extract is `result.response`. `result.error` is a string present on failure. `tool_info.error` is `{type, message}`. Statuses include `SUCCESS`, `ERROR`, and `CANCELED` (one L). An empty SUCCESS `response` is a valid empty result. `ERROR`/`CANCELED` with an empty `response` is `isError`; `result.error` is carried as extract `metadata.agy_error` and as invalid-path extract content, and appears in the dashboard session log and in `_debug.parse_metadata` when `debug:true`. The default `clink` error body reports the rejection reason and does not reprint `result.error`. A present non-string `response` fails closed when it is the first result; a later malformed result is ignored after a nonempty string has already won. Session-log Timeline shows the concatenated partial transcript only when the stream ends without a terminal `result` event.
+
+```json
+{
+  "name": "agy",
+  "command": "agy",
+  "args": ["--print-timeout", "3600s", "--output-format", "stream-json"],
+  "parser": "agy_stream_json",
+  "prompt_mode": "stdin",
+  "timeout_seconds": 3600,
+  "idle_timeout_startup_seconds": 180,
+  "idle_timeout_seconds": 0,
+  "result_contract": {
+    "enabled": false,
+    "filename": "RESULT.md"
+  }
+}
+```
+
+agy 1.1.22+ requires `--print` to take the prompt *text*. A valueless `--print` followed by another flag is an error (`--print took "--print-timeout" as its prompt`), and `--print <path>` is that path string as the user message — the CLI does not read the file. Do not put `--print` in `args`. Headless ClinkX delivers the prompt on stdin without `--print`; agy lists stdin as a native prompt source. Keep `--print-timeout` in `args` so a later `--print` still has a bounded wait; `timeout_seconds` is the subprocess ceiling. The shipped adapter uses a 1-hour print timeout (`--print-timeout 3600s` with `timeout_seconds: 3600`). stream-json normally emits `init` early, so `idle_timeout_startup_seconds` is `180` (text/json were silent until idle). Early-failure paths such as an invalid `--model` may emit only the terminal `result` with no `init`. Direct `clink` session logs are retained for this structured parser when `CLINKX_DIRECT_SESSION_LOGS_ENABLED` is on (default).
+
+### agy via the hapi gateway (optional template)
+
+`conf/adapters/hapi/agy.json` is an unverified **template**, not a ready-to-use adapter. It runs `agy` through a `hapi` gateway (`"command": "hapi"`, with `agy` as the first arg) and ships a placeholder `HAPI_API_URL` of `https://your.domain.com`. To use it you must supply a real `HAPI_API_URL` and a `hapi` gateway that actually proxies `agy`. It is optional and not needed for the direct `agy` adapter above.
+
+### Codex (JSONL output, tail-heavy)
+
+```json
+{
+  "name": "codex",
+  "command": "codex",
+  "args": ["--output", "jsonl"],
+  "parser": "codex_jsonl",
+  "prompt_mode": "stdin"
+}
+```
+
+### Grok (Grok Build CLI 1.0.x)
+
+Shipped as `conf/adapters/grok.json` (`command: "grok"`). Headless `grok` does **not** read stdin, so `prompt_mode` is `file` and `prompt_file_flag` is `--prompt-file`. The runner appends this flag and its generated path together after `unsafe_args`; do not leave a bare prompt-file flag in `args`. The adapter uses `parser: "claude_stream_json"` because `--output-format streaming-messages-json` is Anthropic Messages compatible. `result_contract` is disabled. `unsafe_args` is empty; `--always-approve` lives in `args`. The adapter does not pin `-m`.
+
+```json
+{
+  "name": "grok",
+  "command": "grok",
+  "args": [
+    "--always-approve",
+    "--no-auto-update",
+    "--verbatim",
+    "--output-format",
+    "streaming-messages-json"
+  ],
+  "unsafe_args": [],
+  "env_allowlist": ["XAI_API_KEY"],
+  "parser": "claude_stream_json",
+  "prompt_mode": "file",
+  "prompt_file_flag": "--prompt-file",
+  "result_contract": {
+    "enabled": false,
+    "filename": "RESULT.md"
+  }
+}
+```
+
+Local auth is OAuth via `~/.grok/auth.json` (`HOME` is in the sanitized baseline). `XAI_API_KEY` is the extra allowlist entry.
+
+### GLM (Claude Code harness on Z.ai)
+
+Shipped as `conf/adapters/glm.json` (`command: "claude"`). The optional template `conf/adapters/hapi/glm.json` uses `hapi` + `--yolo` instead of `claude` + `--permission-mode acceptEdits`; copy that file over `~/.config/clinkx/adapters/glm.json` if you spawn through hapi, then fill `ANTHROPIC_AUTH_TOKEN` and `HAPI_API_URL`.
+
+The hapi template has `result_contract.enabled: true` (prompt-honor `RESULT.md` in the run dir, no `native_output_file_flag`) so long `--verbose stream-json` council seats can bypass capture-truncation fidelity hard-fails when the file is actually written. Shipped `conf/adapters/glm.json` (`command: claude`, `--permission-mode acceptEdits`) keeps `result_contract.enabled: false`: a 2026-08-28 overflow probe completed exit 0 with stdout truncated and never created `RESULT.md` under `${TMPDIR}/clinkx/runs`. Enabling it would fall through to the parser and still hard-fail context-producing workflow seats. Live XDG `~/.config/clinkx/adapters/glm.json` first-wins over shipped `glm.json` (no merge). A hapi live overlay must set `enabled: true` itself; flipping only the packaged claude glm.json does not affect a hapi XDG override.
+
+Z.ai's Anthropic-compatible API plus Claude Code's 1M default is a known overflow shape (`API Error: The model has reached its context window limit`). The shipped spawn pins the official 1M Coding Plan route:
+
+- `--model glm-5.3[1m]` and `ANTHROPIC_DEFAULT_{SONNET,OPUS}_MODEL=glm-5.3[1m]` (Haiku → `glm-4.7`)
+- `CLAUDE_CODE_AUTO_COMPACT_WINDOW=1000000` (Z.ai's documented companion to the `[1m]` suffix; not the `--autocompact` CLI flag)
+
+`--verbose` + `--output-format stream-json` are load-bearing for `parser: "claude_stream_json"`. Do not switch json roles to `--output-format json`.
+
+If `glm-5.3[1m]` 404s, fall back to the 200k pin: drop the `[1m]` suffix, set `CLAUDE_CODE_DISABLE_1M_CONTEXT=1`, and `CLAUDE_CODE_AUTO_COMPACT_WINDOW=200000`. Do not mix the two pins.
+
+## Environment Variables
+
+| Variable | Purpose | Default |
+| --- | --- | --- |
+| `CLINKX_CONFIG_PATH` | Override adapter config file/directory. Replaces XDG + packaged builtins entirely. | unset |
+| `CLINKX_ALLOWED_ROOTS` | Comma-separated allow-roots for `absolute_file_paths` / `images`. Fatal at startup only when cwd is filesystem root and this is unset. | `process.cwd()` |
+| `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 |
+| `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` |
+| `CLINKX_TIMEOUT_SECONDS` | Default timeout (seconds) | `600` |
+| `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` |
+| `CLINKX_MAX_CONCURRENT` | Concurrent subprocess limit (fail-fast) | `5` |
+| `CLINKX_MAX_PROMPT_BYTES` | Max prompt bytes written/passed to subprocess | `1048576` |
+| `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` |
+| `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` |
+| `CLINKX_STRICT_FIDELITY` | When `true`, standalone clink returns `isError: true` if capture-layer truncation is detected on stdout-extracted (non-result-contract) calls. | `false` |
+| `CLINKX_MAX_RESPONSE_CHARS` | Max chars returned in tool result (post-parse) | `20000` |
+| `CLINKX_LOG_LEVEL` | Logger verbosity | `info` |
+| `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 fail at startup. | See precedence below. |
+| `XDG_STATE_HOME` | Absolute fallback base for workflow state when `CLINKX_WORKFLOWS_STATE_DIR` is unset or empty. Relative values fail at startup. | unset |
+| `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` |
+| `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` |
+| `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` |
+| `CLINKX_WORKFLOWS_PROGRESS_REPORT_OVERRIDE_DIR` | Optional absolute, non-root parent directory for dashboard-private sidecars: `progress-report-status-overrides.json` and `prompt-builder-library.json`. Unset/empty keeps them beside `progress-reports/` under the workflow state directory. Containers pin it to the independent writable `/data/dashboard-overrides` volume so those files survive a read-only producer-state mount. Neither file is an execution input. | `${CLINKX_WORKFLOWS_STATE_DIR}` |
+| `CLINKX_WORKFLOWS_DASHBOARD_RP_NAME` | WebAuthn RP display name shown by the authenticator. | `ClinkX Dashboard` |
+| `CLINKX_WORKFLOWS_DASHBOARD_SESSION_TTL_SECONDS` | Absolute, non-sliding passkey session lifetime in seconds. | `43200` |
+| `CLINKX_WORKFLOWS_DASHBOARD_MAX_STATE_BYTES` | Maximum admitted `state.json` bytes per run. Strict integer range `1048576..67108864`. | `16777216` |
+| `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)_ |
+| `CLINKX_WORKFLOWS_DASHBOARD_UI_ORIGIN` | Cloud dashboard canonical HTTPS origin. Passkey mode requires the same origin as the API. | _(unset → local)_ |
+| `CLINKX_WORKFLOWS_RETAIN_SUCCEEDED_DAYS` | Retention for ordinary synchronous successes after `run.lock` release. `0` keeps indefinitely. | `1` |
+| `CLINKX_WORKFLOWS_RETAIN_ASYNC_DAYS` | Retention for successful detached runs. `0` keeps indefinitely. | `1` |
+| `CLINKX_WORKFLOWS_RETAIN_FAILED_DAYS` | Retention for failed runs. `0` keeps indefinitely. | `30` |
+| `CLINKX_WORKFLOWS_RETAIN_CANCELLED_DAYS` | Retention for cancelled runs. `0` keeps indefinitely. | `30` |
+| `CLINKX_WORKFLOWS_RETAIN_DEBUG_DAYS` | Retention for debug-kept runs. `0` keeps indefinitely. | `7` |
+| `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` |
+| `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` |
+| `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` |
+| `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` |
+| `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. | `${XDG_STATE_HOME:-~/.local/state}/clinkx/context-builder/runs` |
+| `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` |
+| `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` |
+
+### Session-log tool arguments rollout
+
+`CLINKX_SESSION_LOG_TOOL_ARGUMENTS_PERSISTENCE_ENABLED` defaults off and enables
+extended writes only for the exact value `true`. It is read once when
+`createProviderSessionLogProducer()` is created; changing the environment does
+not change an existing producer. Disabled producers emit no `arguments`, no new
+argument-derived summaries, and no `redaction.coverage`: Claude keeps
+`"Tool invocation"`, while Codex/agy keep their legacy summaries. Redaction
+pattern hardening remains active independently of this flag and `allow_secrets`.
+
+Backend and browser readers always accept legacy and extended events. Deploy
+every capable reader first, then enable producers. Rollback disables producers
+first and keeps capable readers until extended journals age out; flag-off does
+not make previously written gate-on journals old-reader-safe. The optional
+`redaction.coverage: "pattern_best_effort"` describes the redaction method, not
+cleanliness; absence is legacy metadata. Neither `no_matches` nor a positive
+match count proves safety.
+The native projection persists nothing and is independent of this gate.
+
+### STDIO server lifetime
+
+Both STDIO entrypoints monitor the parent captured at startup and request normal
+shutdown with reason `parent-died` when that parent disappears. This covers
+parent death without a stdin EOF, including the macOS socketpair failure mode.
+Permission errors from the parent probe are not evidence of death. The parent
+must own the MCP connection: a wrapper that exits while deliberately handing the
+connection to another process is not a supported lifetime handoff. A server
+already started under PID 1 cannot recover its previous parent's identity.
+
+Structured diagnostics use Node's stderr stream and stop after a stderr error.
+They are best-effort when the peer disconnects; teardown does not synchronously
+flush an asynchronous Pino destination, which could otherwise block exit on a
+closed macOS pipe. Failed diagnostic writes cannot recursively trigger more
+shutdown logging.
+
+Idle shutdown is disabled by default to preserve healthy but silent MCP sessions.
+Set `CLINKX_SERVER_IDLE_TIMEOUT_SECONDS=1800` on the server process to opt into a
+30-minute idle lifetime. Unset, empty, or `0` disables it. Explicit values must
+be finite decimal seconds from `0` through `2147483.647`; invalid values fail
+startup instead of silently disabling the watchdog or overflowing Node's timer.
+Inbound messages and completed work refresh activity;
+active tool handlers, admitted workflows, active Codex turns (including pending
+approvals), and response delivery prevent idle shutdown. Idle expiry uses reason
+`server_idle_orphan_timeout`. Parent death still triggers cleanup during active
+work; the idle exemption does not keep an orphan alive.
+
+Enable idle shutdown only where the host can reconnect and recover sessions.
+Restart loses process-local continuation/session aliases and in-memory event
+logs; Codex resume using a raw `thread_id` is the restart-safe path. Idle time
+alone cannot distinguish an abandoned connection from a healthy quiet client.
+These controls do not change adapter authentication, remove duplicate host MCP
+registrations, or replace host-side connection teardown. They apply to the STDIO
+executables, not to importing the workflow library or to the dashboard server.
+
+Workflow state resolves in this order: nonempty `CLINKX_WORKFLOWS_STATE_DIR`,
+nonempty `XDG_STATE_HOME` plus `/clinkx-workflows`, then nonempty `HOME` (or the
+OS account home when `HOME` is absent or empty) plus
+`/.local/state/clinkx-workflows`. Every selected root or base must be absolute;
+the OS account-home fallback must also be nonempty and non-root. Older relative
+configurations that resolved against the dashboard's cwd now fail explicitly.
+Migrate a relative override by expanding it before launch:
+
+```sh
+export CLINKX_WORKFLOWS_STATE_DIR="$(pwd)/.clinkx-state"
+```
+
+Dashboard passkey challenges use protected capacities of 96 login and 32
+registration entries, plus 8 concurrent verifications. Saturation returns 503
+`auth_busy` with `Retry-After: 1`; live challenges are not evicted. Local
+session/challenge cookie names include the browser-facing port, while the RP ID
+remains bare `localhost`. Cloud cookie prefixes are unchanged.
+
+Shutdown closes all dashboard listeners before auth/gateway resources. All
+cleanup failures are retained in one listener-or-resource aggregate, and signal
+handling remains idempotent.
+
+## Context Builder
+
+`context_builder` stores runs under environment-configured local state and uses the same adapter registry as `clink` only when delegate mode is explicitly enabled in the request. Without `delegate.enabled:true`, it uses deterministic local curation and does not invoke a CLI adapter.
+
+Minimal request:
+
+```json
+{
+  "task": "Collect context for the server tool registration",
+  "roots": ["/path/to/workspace"],
+  "focus_paths": ["src/server.ts"]
+}
+```
+
+Accepted anchor fields and scan filters:
+
+- `focus_paths`: bounded file or directory paths resolved under one configured root
+- `search_terms`: nonblank literal terms searched in eligible text files
+- `include_globs`: selective root-relative include patterns that narrow scanning when combined with `focus_paths` or `search_terms`; they do not select context alone
+- `allow_secrets`: optional boolean (default `true`) controlling whether secret material is included; see "Context builder secret material" below
+
+The response is one minified JSON text block. The important handoff field is:
+
+```json
+{
+  "recommended_clink": {
+    "absolute_file_paths": [
+      "/.../artifacts/bundle.md",
+      "/.../manifest.json"
+    ]
+  }
+}
+```
+
+Pass those paths as the `absolute_file_paths` field in a later `clink` call. Do not rely on the receipt to contain source text; source-derived context lives in the persisted artifacts. The handoff remains `artifacts/bundle.md` plus `manifest.json` for deterministic, approved delegate, and fallback delegate runs.
+
+Delegate request shape:
+
+```json
+{
+  "task": "Collect context for the server tool registration",
+  "roots": ["/path/to/workspace"],
+  "focus_paths": ["src/server.ts"],
+  "delegate": {
+    "enabled": true,
+    "curator": {
+      "cli_name": "<curator-cli>",
+      "role": "<curator-role>"
+    },
+    "finalizer": {
+      "cli_name": "<finalizer-cli>",
+      "role": "<finalizer-role>",
+      "min_score": 8.5
+    },
+    "failure_policy": "fallback",
+    "timeout_seconds": 120,
+    "max_response_chars": 20000
+  }
+}
+```
+
+Delegate fields:
+
+| Field | Required | Notes |
+| --- | --- | --- |
+| `delegate.enabled` | yes | `true` runs curator/finalizer orchestration; omitted or `false` keeps deterministic local curation. |
+| `delegate.curator.cli_name` / `role` | yes when enabled | Must name an adapter and role configured in the existing adapter registry. There is no provider default. |
+| `delegate.finalizer.cli_name` / `role` | yes when enabled | Must name an adapter and role configured in the existing adapter registry. There is no provider default. |
+| `delegate.finalizer.min_score` | no | Defaults to the implementation policy threshold and is schema-validated in the range `0..10`. |
+| `delegate.failure_policy` | no | `"fallback"` publishes deterministic local selection as a partial v2 run after delegate failure; `"fail"` returns a tool error and does not publish `manifest.json`. |
+| `delegate.timeout_seconds` | no | Per delegate-call hard timeout. Omitted values use the implementation default; the schema caps accepted values. |
+| `delegate.max_response_chars` | no | Per delegate-call response cap. Omitted values use the implementation default; the schema caps accepted values. |
+
+Delegate provider output is not source authority. The server accepts only strict
+JSON, validates candidate IDs and ranges against local discovery, reconstructs
+source content locally, reapplies budgets and secret checks, and omits raw
+provider output from receipts, manifests, summaries, and artifacts.
+
+### Context builder mutation-lock recovery
+
+Ordinary per-run mutation locking uses the existing exclusive-create main lock;
+fresh and live contention does not invoke recovery. For an eligible stale main
+lock, a remover must first create the sibling `.recovery` gate exclusively. While
+holding that gate it authoritatively re-observes stale qualification, caller
+admission, fingerprint identity, and removal, and removes only the unchanged
+admitted main-lock incarnation. The `.recovery` gate is never stale-recovered.
+
+This is an operational rollout boundary. A crash while holding the gate can wedge
+stale recovery until operator cleanup. Quiesce old workers before a mixed-version
+rollout against the same runs directory. The lock protocol assumes a cooperative,
+trusted local filesystem with reliable exclusive create; it provides no NFS or
+hostile-writer conditional-unlink guarantee.
+
+### Context-run detail refresh
+
+The dashboard resolves detail generation from the current observed row, then the
+retained selection authority, then the request-start expectation. A
+same-generation list response overlays a detail only when its completion epoch is
+newer than that detail request, and terminal state remains monotonic across list
+omission. Generation, terminal-audit, and recoverable-404 triggers share one
+selection-scoped automatic reload; ordinary polls stay list-only. Each explicit
+Retry performs at most one non-recursive detail read after refreshing the list.
+An authoritative 404 clears pending obligations and can be escaped only by a
+matching row from a genuinely later completed list or deliberate route re-entry.
+The detail view does not offer Retry for `auth_expired`, `connection_changed`, or
+`not_found` states.
+
+### Context builder secret material
+
+The `context_builder` secret filter is **non-blocking and default-on**. By default (`allow_secrets:true`), secret material — API keys, SSH/private keys, tokens, and files like `.env`, `.pem`, `id_rsa`, `credentials.json` — is included verbatim in curated bundles, delegate packets, and any downstream council member CLIs / upstream providers. Set the off-switch to restore fail-closed omission/redaction. There are three controls, resolved in this precedence (highest wins):
+
+| Scope | Control | Where |
+| --- | --- | --- |
+| Per-call | `allow_secrets` (boolean) | standalone `context_builder` and `refine_context_run` request input |
+| Per-workflow | `cb_allow_secrets` (boolean) | `run_workflow` variable; a context OVERRIDE variable (not an anchor) in `list_workflows` metadata |
+| Environment | `CLINKX_CONTEXT_ALLOW_SECRETS` | environment variable (see the table above) |
+
+Effective default when none is set: `true`. Both the standalone and workflow paths honor the env var. Allowing secrets into bundles does **not** affect log redaction, subprocess environment scrubbing, Elaris remote-session redaction, or path/allowed-root safety — see `docs/security.md`.