clinkx 1.0.0 → 1.1.1

package/CHANGELOG.md

@@ -1,5 +1,100 @@
 # Changelog
 
+## 1.1.1 — 2026-10-05
+
+### Changed
+
+- The npm package now ships `docs/configuration.md` and `docs/security.md`, and the README is rewritten as a self-contained, install-facing page in Simplified Technical English. `package.json` `homepage` points at the npm package page and `bugs` is removed, because the source repository is private.
+
+### Fixed
+
+- `context_builder` secret scanning (`allow_secrets:false`) on large bodies is 6-8x faster on Node 24: comment masking now returns the input string when nothing is masked, so memo lookups no longer compare a distinct but equal copy of the whole body. Output is unchanged.
+- npm publish confirmation now waits up to about eight minutes for npm to expose the new version instead of failing after a few seconds; 1.1.0's automated publish succeeded but failed confirmation and needed a manual re-run to go green.
+
+## 1.1.0 — 2026-10-03
+
+### Upgrade notes
+
+- Adapter files stay whole-file first-wins. An overlay in `~/.config/clinkx/adapters/` keeps its 1.0.0 argv and parser and does not get the shipped changes below, including `invocation_overrides` (required for per-call `model`/`effort`) and the agy stream-json parser. Re-copy from the packaged `conf/adapters/` or `conf/adapters/hapi/` to adopt them. (#26, #44)
+- Shipped `agy` now sends the prompt on stdin without `--print` and passes `--output-format stream-json`, which needs an agy build that emits stream-json (1.1.8+). (#26, #44)
+- Shipped `glm` and the `hapi/glm` template pin `--model glm-5.3[1m]`, Opus/Sonnet defaults `glm-5.3[1m]`, Haiku `glm-4.7`, and `CLAUDE_CODE_AUTO_COMPACT_WINDOW=1000000`. 1.0.0 used `glm-5`.
+- A finalizer `model`, `effort`, or explicit `min_score` on an effectively disabled finalizer (`finalizer.enabled` omitted under a profile that defaults it off) is now rejected `-32602` by `run_workflow` and `context_builder` before any state or spawn. 1.0.0 accepted and ignored it. Set `finalizer.enabled:true` or drop the knob. (#52)
+- The six `council-*` workflows default to `context_external_gap_policy: degrade`. When the finalizer reports evidence it could not obtain, the run proceeds with `context_quality:"degraded"`, health reason `context_external_gaps`, and a `## Known missing evidence` bundle block instead of failing. An explicit `cb_delegate` with `external_gap_policy:"fail"` keeps the failure. `plan-review-receipts` is unchanged. (#55)
+- `review_deep` delegate `timeout_seconds` defaults to 300 (was 180). (#55)
+- Context-builder default excludes add `.worktrees/**` and vendor trees (`Pods`, `.cxx`, `.gradle`, `DerivedData`). `exclude_globs:[]` / `cb_exclude_globs:[]` cannot remove them. (#45, #55)
+- The workflow context cache (`wfctx-*`) goes cold once: the delegate prompt and discovery algorithm versions changed. (#55)
+- Drain, finish, or abandon unfinished resumable workflow runs before upgrading. Child-config fingerprints now cover override declarations and the enabled curator/finalizer adapters, and shipped adapter JSON changed, so resume across the upgrade can be rejected. Runs that do resume replay their persisted snapshot and keep external-gap policy `fail`. (#26, #55)
+- `progress_report_start`, `progress_report_update`, `progress_report_get`, and `progress_report_list` are always advertised. (#51)
+- New flags, off by default. Only exact `true` enables `CLINKX_INVOCATION_AUDIT_V2_PERSISTENCE_ENABLED`, `CLINKX_OBSERVED_INVOCATION_PERSISTENCE_ENABLED`, and `CLINKX_SESSION_LOG_TOOL_ARGUMENTS_PERSISTENCE_ENABLED`; `CLINKX_SERVER_IDLE_TIMEOUT_SECONDS` defaults to `0`. Readers always accept the new formats, so enable writers only once every dashboard reading the same state runs 1.1.0. With the audit flag off, the dashboard shows model/effort as not recorded. (#24, #28, #40, #57)
+- New runtime dependency: `@letta-ai/trajectory`, pinned to `0.4.3`. (#57)
+
+### Added
+
+- Per-call `model` and `effort` on `clink`, generic workflow calls, council `members[]`, `chairman_model` / `chairman_effort`, and the `context_builder` / `cb_delegate` curator and finalizer, when the resolved adapter declares `invocation_overrides`. Every shipped subprocess adapter declares both; Codex effort renders as `-c model_reasoning_effort=<value>`. Unsupported values fail `-32602` before spawn. `plan-review-receipts`, the Codex app-server tools, and Elaris are unchanged. (#26)
+- Invocation evidence: a pre-dispatch audit (requested value, applied value, provenance) for workflow calls, direct `clink` activity, and context curator/finalizer calls, plus the model/effort a child reports (Claude `system/init`, app-server `thread/start`). The dashboard shows both in the call inspector and on run-detail stage rows. Persistence is behind the flags above. (#28, #40, #53)
+- `run_workflow.roster`: named council presets carrying members, chairman, and the context delegate. Discovery is first-wins across `CLINKX_ROSTERS_PATH`, `${XDG_CONFIG_HOME:-~/.config}/clinkx/rosters/`, and built-in `conf/rosters/` (ships `default-council`). A roster cannot be combined with `members`, `chairman`, `chairman_model`, `chairman_effort`, or a non-empty `cb_delegate`. (#52)
+- `list_workflows` adds `available_clis` (per-adapter model/effort support) and `available_rosters`. Council runs report `resolved_roster` on the async ack, the sync result, and `workflow_run_status`. (#52)
+- `workflow_run_status` adds `context.delegate.finalizer` `{effective_enabled, execution_status, score?}` and, while preflight is still scanning, a top-level `context_progress` block. (#52)
+- Progress-report tools `progress_report_start` / `_update` / `_get` / `_list`: patch-only writes, `expected_revision` compare-and-swap, `request_id` replay, server-owned ids and timestamps. Reports live under `<state dir>/progress-reports/` and show on the dashboard. (#51)
+- Delegate `external_gap_policy: "fail" | "degrade"` (default `fail`) on `context_builder` and `cb_delegate`. Finalizer-reported `external_gaps` are classified; rejected gaps fail under either policy, accepted ones carry provenance. (#55)
+- `CLINKX_SERVER_IDLE_TIMEOUT_SECONDS`: opt-in idle lifetime for both STDIO servers. Active tools, workflows, Codex turns, and response delivery hold it off. (#24)
+- Dashboard: prompt builder at `/prompt-builder` for `run_workflow` and chief-of-staff prompts, validated against live adapter capabilities. Its library persists in a private `prompt-builder-library.json` sidecar. Copy is its only action.
+- Dashboard: `CLINKX_WORKFLOWS_DASHBOARD_AUTH_MODE=none` for loopback-only testing. Host and origin checks stay enforced; remote and gateway modes reject it. (#47)
+- Dashboard: session-log conversations tail in place. Tool rows can show bounded, redacted tool arguments when `CLINKX_SESSION_LOG_TOOL_ARGUMENTS_PERSISTENCE_ENABLED=true`, and Find searches them. (#57)
+- Dashboard: `CLINKX_WORKFLOWS_PROGRESS_REPORT_OVERRIDE_DIR` moves the status-pin sidecar off a read-only state directory.
+- Automatic npm publishing after main CI passes. A PR that bumps the root
+  version (stable, ahead of the base and npm `latest`, with `CHANGELOG.md` in the
+  same diff) releases on merge; PRs and main pushes that leave the version
+  unchanged never publish or read the registry and ship with the next bump. A
+  failed or incomplete publication is recovered only by a manual run on main,
+  which rebuilds from current main and publishes that source under the version
+  if it is still unpublished. One tarball is verified across the Node matrix
+  and published with OIDC, a single `npm publish` write, bounded registry
+  reconciliation, and no rebuild in the publisher. The publisher parses the tarball itself instead of using system
+  `tar`, accepts only the ustar regular-file layout `npm pack` emits under
+  `package/` with exactly one `package/package.json` (name and prefix fields
+  NUL-padded to their ends, an empty linkname, a terminated checksum, no
+  base-256 numbers, no entry path that is also another entry's directory), and
+  rejects a manifest that declares `publishConfig` or a top-level `tag`; the
+  expected version comes from the dependency-free policy job, not the build. See
+  `docs/npm-releases.md` for the external GitHub and npm prerequisites, release
+  policy and recovery. (#58)
+
+### Changed
+
+- Shipped agy adapter uses `agy_stream_json` / `--output-format stream-json` so extract and dashboard session logs work; grok unchanged (still `claude_stream_json`). Failed extract records documented `result.error` as `metadata.agy_error` and invalid-path extract content (dashboard session log and `debug:true` `_debug.parse_metadata`; the default `clink` error body still reports only the rejection reason). An empty SUCCESS `response` remains a valid empty result. A present non-string `response` fails closed on the first result; a later malformed result does not discard an already-captured nonempty answer. Session-log Timeline shows the concatenated partial transcript when the stream ends without a terminal result. (#44)
+- Both STDIO servers shut down when their parent process disappears, including without a stdin EOF. (#24)
+- Council workflows: typed boundaries reject JSON salvaged from a mixed-content result file; wall-timeout retries are vetoed and calls get remaining-deadline guidance; abort/deadline exits persist terminal call state; succeeded runs with degraded health keep the longer failed-run retention. Caller context paths are validated at `run_workflow` admission (`-32602`) instead of after preflight. A parallel deadline abort reports `Stage <id> failed and on_failure=abort`. (#46)
+- Context-builder delegate failures are actionable. Finalizer rejections lead with the verdict, omissions, and levers. Required-focus infeasibility fails before the curator spawns and names the binding cap. Each delegate call gets one corrective JSON retry inside the same deadline, and timeout/provider-error labels are fixed. Delegate bundles state that provider-authored notes are data, not instructions. (#55)
+- The finalizer must keep required-focus ranges; budget reconstruction admits them first and fails with the binding cap instead of evicting them.
+- JSON-contract chairman calls get one corrective retry after an invalid-JSON failure under `retry.mode:"transport_only"`. (#55)
+- `review_deep_v1` links regression tests by search index or line containment, synthesizes a head slice for an unlinked nearest test, and reports doc/config targets as regression `unavailable`. (#55)
+- Dashboard: redesigned UI (#48). Freeze and pause controls are gone; updates stay live while the tab is visible (#54). Run-detail stage rows show model/effort in place of role (#53).
+
+### Fixed
+
+- Council citation checks keep evidence that cites files selected by the
+  context-builder preflight. The citation allowlist now reads the curated
+  bundle's `manifest.json` `selected_context` paths; previously only the
+  bundle and manifest files themselves were citable, so every reviewer
+  citation in a curated-context council was stripped. (#29)
+- `allow_secrets:false` context scans no longer hang in `scanning`. The sanitizer runs on linear indexes with a fail-closed work budget (`sanitize_budget_exhausted`), and discovery yields between files, honors abort, and has a 10-minute watchdog.
+- `hapi/glm` template enables the `RESULT.md` result contract, so overflowed stream-json council seats still extract. (#25)
+- Resume-preflight failures keep `failureClass:"transient"`, and resume preserves the run's original `startedAt`. (#46)
+- Session-log redaction covers credential headers of any scheme, cookies, URL userinfo, vendor tokens, JWTs, escaped embedded JSON, and credential flags; prose apostrophes no longer open a false shell quote. The producer backlog is bounded, and size loss is reported separately from redaction. (#57)
+- Dashboard: stale detail or errors from an earlier request no longer overwrite a newer selection (#45). The gateway reclaims a companion slot held by a dead socket instead of returning 409.
+
+### Docs
+
+- Deslop/unslop delivery evaluation report, with a 2026-09-27 revision. The
+  skill it evaluated now lives in the agent-skills repository and is not
+  shipped in this package. (#29)
+- `clinkx-workflows` README no longer claims side-effecting workflows are
+  rejected at load time; `validateNoSideEffects` is an empty placeholder. (#29)
+- `docs/configuration.md` documents the GLM 1M pin, STDIO server lifetime,
+  and per-call override templates (#24, #26). README documents roster
+  presets (#52).
+
 ## 1.0.0 — 2026-08-17
 
 First npm release of the work that landed after `0.3.0`. The previous registry `latest` is still `clinkx@0.3.0` (published 2026-06-15).

package/README.md

@@ -1,121 +1,114 @@
 # ClinkX
 
-An MCP STDIO server with local tools for CLI delegation and workflow orchestration.
+ClinkX is an MCP server that connects your AI coding assistant to other command-line AI agents. It runs Codex, Claude Code, agy, GLM, or Grok as child processes and returns their output as MCP tool results. You can send one task to one agent. You can run a council of many agents on one question. You can also build a context bundle for a later task.
 
-- `clink` runs a configured CLI adapter (agy, Codex, Claude, Grok, or anything you add) as a subprocess and returns the output.
-- `context_builder` writes a persisted context bundle from allowed local roots. Selection is deterministic by default. You can also run explicit curator and finalizer adapters, then the server validates and materializes locally.
-- `list_workflows`, `resume_workflow`, and `run_workflow` run multi-stage workflows.
+ClinkX uses MCP over STDIO. It works with any MCP client that can start a local command.
 
-Adapters come from config. There is no hardcoded CLI allowlist. Field-level PAL compatibility is intentional.
+## Requirements
 
-## Quick start
+- Node.js 24.0.0 or later.
+- At least one of these command-line tools on your `PATH`: `codex`, `claude`, `agy`, or `grok`. The `glm` adapter also uses the `claude` command.
+- The `codex` command, if you run workflows. Workflows use Codex to select repository context before the first stage. See [Workflows](#workflows) for the opt-out switch.
 
-Node.js >= 24, plus at least one CLI adapter.
+## Installation
 
-```bash
-npm install
-npm run build:all
-node dist/index.js
-```
+Add ClinkX to the MCP server list of your client. The exact file and format depend on the client. This is the common JSON shape:
 
-stdout is MCP JSON-RPC only (one JSON object per line). Logs go to stderr.
+```json
+{
+  "mcpServers": {
+    "clinkx": {
+      "command": "npx",
+      "args": ["-y", "clinkx@latest"],
+      "env": {
+        "CLINKX_ALLOWED_ROOTS": "/path/to/your/workspace",
+        "CLINKX_WORKFLOWS_WORKSPACE_ROOT": "/path/to/your/workspace"
+      }
+    }
+  }
+}
+```
 
-## Local workflow dashboard
+Set the two paths to the directory that tool calls can reference. Use absolute paths.
 
-After `npm run build:all`:
+To install ClinkX globally, run this command. Then set `"command": "clinkx"` with no `args`:
 
 ```bash
-node dist/dashboard-cli.js --port 0
+npm install -g clinkx
 ```
 
-Passkey auth is the default. The process binds `127.0.0.1` and `::1` on the same port and prints `http://localhost:<port>`. An empty credential store also prints one enrollment code. Register a passkey with that code, then sign in as a separate step. Credentials live under `CLINKX_WORKFLOWS_DASHBOARD_CREDENTIAL_DIR` (default `${CLINKX_WORKFLOWS_STATE_DIR}/dashboard/webauthn`). Sessions die on restart.
-
-Screens: Runs, Single Calls, Context Runs, Workflows, Adapters, Artifacts. They show retained workflow state, direct-call lifecycle, standalone/refine context-builder lifecycle, persisted pre-dispatch workflow input, final outputs and errors, validated JSON artifacts, and the launch-time workflow/adapter catalogs. Runs, Single Calls, and Context Runs have their own path routes. The persisted-call inspector is an overlay that still shows up as a nested route in history.
-
-Workflow-call, activity, and context-run detail pages also have local session logs (observability only). Timeline and Conversation are chronological; order comes from the log sequence. Each lane is fenced to one immutable parent generation (run, activity, or context) plus the matching attempt, turn, or curator/finalizer execution. Pages are at most 500 events. A lane stops at 100,000 events. Events are normalized and pattern-redacted. They are not raw provider payloads, a session browser, or a live tail.
-
-The dashboard has no SSE, filesystem watch, worker-health inference, cross-process cancellation, or run-creation form. Session logs cannot replay, approve, cancel, or otherwise control a run. Copied action objects are MCP tool handoffs, not JSON-RPC requests.
-
-Point the dashboard at the same `CLINKX_WORKFLOWS_STATE_DIR` as the workflow process or you will see a different (often empty) run set. Successful sync and async runs are kept for one day by default so you can inspect them. `CLINKX_WORKFLOWS_RETAIN_SUCCEEDED_DAYS=0` or `CLINKX_WORKFLOWS_RETAIN_ASYNC_DAYS=0` means keep that class forever, which can fill the disk.
-
-Workflow and activity session logs follow retention of that exact parent generation. Context session logs follow the parent context-run/manual lifecycle. There is no separate context-run pruner yet.
-
-Persisted inputs, outputs, errors, and artifact bytes can be sensitive. Access is loopback-only and passkey-gated. That is a shared-account boundary, not isolation from other processes as the same OS user. Redaction strips high-confidence credentials and user-home paths before write. Prompts, outputs, tool summaries, and reasoning can still be sensitive after that. Per-run state admission defaults to 16 MiB (configurable 1–64 MiB via `CLINKX_WORKFLOWS_DASHBOARD_MAX_STATE_BYTES`). Raw result/call reads use smaller fixed caps.
-
-For local Docker, `compose.dashboard-local.yml` runs the real UI + API over plain HTTP. Caddy publishes on `127.0.0.1` and `::1`. The browser uses `http://localhost:<port>`. Caddy shares the dashboard network namespace and proxies IPv4 to Node at `127.0.0.1:4180`. The same Node process also listens on `::1:4180`. See `docs/dashboard-local-compose.md`.
+Restart your MCP client after you change its configuration. To control when upgrades happen, replace `clinkx@latest` with a fixed version.
 
-Hosted passkey topology is one UI+API service behind Traefik on a private Docker network. See `deploy/dashboard-cloud/README.md`. The older gateway/companion and split-origin paths exist only as a temporary bearer rollback until local and live cloud passkey ceremonies pass the proof-gated cutover.
+## First call
 
-To build the local CLI as one host-native executable, use an official Node 25.5+ runtime with SEA support:
+Ask your assistant to use the `clink` tool. This is the smallest valid request:
 
-```bash
-npm run build:dashboard:standalone -- \
-  --node-executable /absolute/path/to/official-node \
-  --output ./artifacts/clinkx-dashboard
+```json
+{
+  "cli_name": "codex",
+  "prompt": "Summarize the module boundaries in this project. Do not edit files.",
+  "absolute_file_paths": ["/path/to/your/workspace/src/server.ts"]
+}
 ```
 
-The binary embeds the dashboard UI, bundled configuration, workflows, and templates. At runtime it still reads state, context runs, and the inspected workspace from the usual environment paths.
+ClinkX starts the Codex CLI, sends the prompt and the file references, and returns the final answer. You can run many `clink` calls at the same time, up to the concurrency limit.
 
-## Configuration
+## Tools
 
-Adapter JSON is discovered in this order:
+| Tool | Function |
+|---|---|
+| `clink` | Runs one task on one configured CLI and returns the result. |
+| `context_builder` | Selects a bounded set of files from permitted roots and writes a reusable context bundle to disk. |
+| `refine_context_run` | Makes a new bundle from an earlier one. You can add, remove, promote, or demote files, or set their slices. |
+| `list_workflows` | Lists the available workflows, CLIs, and roster presets. |
+| `run_workflow` | Starts a multi-stage workflow. Runs in blocking mode by default, or in the background with `async: true`. |
+| `workflow_run_status` | Reports the progress and result of a workflow run. |
+| `resume_workflow` | Continues a workflow run that stopped before completion. |
+| `cancel_workflow` | Cancels a workflow run. |
+| `progress_report_start`, `progress_report_update`, `progress_report_get`, `progress_report_list` | Keep a live progress report that the dashboard shows. |
 
-1. `CLINKX_CONFIG_PATH` (file or directory). This replaces the whole search path. Shipped adapters are not loaded.
-2. `${XDG_CONFIG_HOME:-~/.config}/clinkx/adapters/*.json`. First-wins on `name`.
-3. Packaged `conf/adapters/*.json` next to the installed package (`import.meta.url`). Not `process.cwd()`.
+Two more tool groups are off by default:
 
-A `conf/adapters/*.json` file in the current working directory is ignored unless `CLINKX_CONFIG_PATH` points at it. Full reference: `docs/configuration.md`.
+- `clink_agent_run` and `clink_agent_manage` control a stateful Codex app-server session with approvals. Set `CLINKX_APP_SERVER_ENABLED=true` to publish them.
+- `clink_elaris_run` and `clink_elaris_manage` start remote Elaris agent sessions over HTTPS. Set `CLINKX_ELARIS_ENABLED=true` and the Elaris connection variables to publish them.
 
-Dashboard deployment controls:
+Each tool publishes its full input schema through MCP. MCP clients can show the schema with the tool description.
 
-| Setting | Contract |
-|---|---|
-| `CLINKX_WORKFLOWS_DASHBOARD_CREDENTIAL_DIR` | Optional absolute, non-root credential directory. Host default: `${CLINKX_WORKFLOWS_STATE_DIR}/dashboard/webauthn`. Compose pins the writable `/data/dashboard-credentials` volume. |
-| `DASHBOARD_DEPLOYMENT_SLUG` | Required Compose identity, `^[a-z][a-z0-9-]{0,31}$`. Local and cloud names keep distinct stack-kind prefixes. |
-| `DASHBOARD_CREDENTIAL_BOOTSTRAP_MODE` | Required Compose state assertion. First start is `bootstrap`. Flip to `existing-enrolled` right after enrollment, before restart. |
+## Supported CLIs
 
-Passkey challenge capacity is 96 login slots and 32 registration/add-passkey slots, with 8 concurrent verifications. Saturation returns 503 `auth_busy` and `Retry-After: 1`. Live challenges are not evicted. Local session and challenge cookie names are port-scoped. WebAuthn still uses the shared bare `localhost` RP ID.
+An adapter file tells ClinkX how to start one CLI, how to pass the prompt, and how to read the output. These adapters are included:
 
-On browser startup, a valid same-origin passkey status beats provisional bearer state. The only bearer fallback is the split-origin static server's exact no-store 404 `{"error":{"code":"not_found"}}`. Malformed or ambiguous status, and uncertain logout, fail closed. Bearer is the explicit tested rollback.
+| `cli_name` | Command (short form) | Notes |
+|---|---|---|
+| `codex` | `codex exec --json` | Default curator and finalizer for workflow context. |
+| `claude` | `claude -p --output-format stream-json` | |
+| `agy` | `agy --output-format stream-json` | Use an agy build that emits stream-json (1.1.8 or later). |
+| `glm` | `claude -p ... --model glm-5.3[1m]` | Runs GLM through the Claude Code CLI. |
+| `grok` | `grok --output-format streaming-messages-json` | |
 
-Dashboard shutdown closes listeners first, then auth/gateway resources. Cleanup failures are aggregated across both.
+All included adapters accept the optional `model` and `effort` fields on each call:
 
-## Context bundles
+```json
+{ "cli_name": "codex", "prompt": "...", "model": "gpt-5.4", "effort": "low" }
+```
+
+If you omit a field, ClinkX uses the adapter setting or the CLI default. If the adapter does not declare the field or the value, ClinkX returns MCP error `-32602` and does not start the process.
 
-Use `context_builder` when a later `clink` call needs curated repo context and you do not want that source inlined in the first tool response. You must pass a bounded anchor: at least one `focus_paths` entry or a nonblank `search_terms` entry. `include_globs` only narrows the scan when those anchors exist. It does not select context by itself.
+The `conf/adapters/hapi/` directory in the package holds optional templates that start each CLI through a `hapi` gateway. These templates are not ready to use. You must set the gateway URL and credentials in your copy.
 
-The tool writes a durable run directory (`manifest.json`, `artifacts/bundle.md`) and returns one minified JSON receipt. The receipt includes `recommended_clink.absolute_file_paths`. Pass those as `absolute_file_paths` on a later `clink` call. The handoff files are the persisted `artifacts/bundle.md` and `manifest.json`.
+## Configuration
 
-Delegate mode needs an explicit request shape and explicit providers:
+### Adapter files
 
-```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
-  }
-}
-```
+ClinkX reads adapter JSON files from these locations, in this order. ClinkX uses the first file with a given `name`.
 
-There are no built-in curator or finalizer provider defaults. Provider output is advisory. The server checks strict JSON, rebuilds accepted content from local candidates, reapplies budgets and secret checks, and does not persist raw provider output. `failure_policy:"fallback"` publishes deterministic local selection as a partial v2 run if delegate curation fails. `failure_policy:"fail"` returns an error and does not publish a manifest.
+1. `CLINKX_CONFIG_PATH`, a file or a directory. When you set it, ClinkX reads only this location and does not load the included adapters. The location must also contain a `codex` adapter with a `json` role, or you must set `CLINKX_WORKFLOWS_CONTEXT_PREFLIGHT_ENABLED=false`.
+2. `${XDG_CONFIG_HOME:-~/.config}/clinkx/adapters/*.json`.
+3. The `conf/adapters/` directory inside the installed package.
 
-### Adding an adapter
+To change an included adapter, copy its file to `~/.config/clinkx/adapters/` and edit the copy. The copy replaces the included file completely. ClinkX does not merge the two files. After you upgrade ClinkX, compare your copy with the new included file. Copy the new file again if necessary.
 
-Put the JSON in `${XDG_CONFIG_HOME:-~/.config}/clinkx/adapters/`. Or set `CLINKX_CONFIG_PATH` to a directory that also contains every shipped adapter you still need. That env var replaces the search path.
+To add a CLI that is not included, write a new file in the same directory. This example adapter returns the prompt unchanged:
 
 ```json
 {
@@ -128,56 +121,135 @@ Put the JSON in `${XDG_CONFIG_HOME:-~/.config}/clinkx/adapters/`. Or set `CLINKX
 }
 ```
 
-## MCP client config
+### Environment variables
+
+These are the variables that most installations set. Every variable has a default.
+
+| Variable | Default | Function |
+|---|---|---|
+| `CLINKX_ALLOWED_ROOTS` | Current directory of the server process | Comma-separated list of directories that tool calls can reference. Set it so path checks do not depend on the directory in which the client starts ClinkX. |
+| `CLINKX_WORKFLOWS_WORKSPACE_ROOT` | Current directory of the server process | Workspace for workflows. Set it to the same directory as the allowed root. |
+| `CLINKX_WORKFLOWS_STATE_DIR` | `${XDG_STATE_HOME:-~/.local/state}/clinkx-workflows` | Directory for workflow runs, progress reports, and dashboard state. |
+| `CLINKX_CONTEXT_BUILDER_RUNS_DIR` | `${XDG_STATE_HOME:-~/.local/state}/clinkx/context-builder/runs` | Directory for `context_builder` runs and bundles. |
+| `CLINKX_CONFIG_PATH` | not set | Replaces the adapter search path. See [Adapter files](#adapter-files). |
+| `CLINKX_ROSTERS_PATH` | not set | Replaces the roster-preset search path. See [Workflows](#workflows). |
+| `CLINKX_MAX_CONCURRENT` | `5` | Maximum number of `clink` processes at one time. ClinkX returns an error when the limit is reached. It does not queue requests. |
+| `CLINKX_TIMEOUT_SECONDS` | `600` | Default time limit for one child process. |
+| `CLINKX_MAX_RESPONSE_CHARS` | `20000` | Maximum number of characters in one tool result. |
+| `CLINKX_LOG_LEVEL` | `info` | Log level. Logs go to stderr. |
+| `CLINKX_CONTEXT_ALLOW_SECRETS` | `true` | When `true`, `context_builder` copies secret material into bundles as written. See [Safety](#safety). |
+| `CLINKX_WORKFLOWS_CONTEXT_PREFLIGHT_ENABLED` | `true` | Set to `false` to run workflows without the Codex context step. |
+| `CLINKX_WORKFLOWS_RETAIN_SUCCEEDED_DAYS` | `1` | Days to keep completed blocking workflow runs on disk. `0` keeps them without limit. |
+| `CLINKX_WORKFLOWS_RETAIN_ASYNC_DAYS` | `1` | Days to keep completed background workflow runs on disk. `0` keeps them without limit. |
+| `CLINKX_SERVER_IDLE_TIMEOUT_SECONDS` | `0` | Seconds of inactivity after which the server exits. `0` disables the timer. Active tool calls, workflows, and Codex turns reset it. |
+| `CLINKX_APP_SERVER_ENABLED` | `false` | Set to `true` to publish the Codex app-server tools. |
+| `CLINKX_ELARIS_ENABLED` | `false` | Set to `true` to publish the Elaris tools. |
+
+ClinkX writes only MCP JSON-RPC to stdout. All logs go to stderr. The server detects the exit of its parent process and stops.
+
+## Workflows
+
+A workflow runs many CLI calls in stages and returns one result. A council workflow asks each member for an independent answer. The members then review each other. A chairman writes the final answer. These workflows are included:
+
+| Workflow | Purpose |
+|---|---|
+| `council-answer` | Answer one hard question. |
+| `council-code-review` | Review a change set. |
+| `council-debug` | Find the cause of a defect. |
+| `council-discover` | Inspect a codebase or a design space. |
+| `council-plan-review` | Review a plan document. |
+| `council-default` | General-purpose council. |
+| `plan-review-receipts` | Typed plan review that returns receipt candidates for an external approval process. |
 
-The exact shape depends on the client.
+Before the first stage, the workflow runs `context_builder` with Codex as curator and finalizer. This step selects the repository files that the members receive. The `codex` command must be on your `PATH`. To skip this step, set `CLINKX_WORKFLOWS_CONTEXT_PREFLIGHT_ENABLED=false`.
 
-Via npx (recommended):
+### Roster presets
+
+A roster preset names the members, the chairman, and the context delegate of a council in one file. Pass the preset name as `roster` in place of `members`, `chairman`, and `cb_delegate`:
 
 ```json
 {
-  "mcpServers": {
-    "clinkx": {
-      "command": "npx",
-      "args": ["-y", "clinkx@latest"],
-      "env": {
-        "CLINKX_ALLOWED_ROOTS": "/path/to/your/workspace",
-        "CLINKX_WORKFLOWS_WORKSPACE_ROOT": "/path/to/your/workspace"
-      }
-    }
-  }
+  "workflow": "council-default",
+  "roster": "default-council",
+  "variables": { "user_request": "Compare the three approaches and pick one." }
 }
 ```
 
-From a local clone:
+The included `default-council` preset uses Codex, Claude, and GLM as members and Codex as chairman. ClinkX reads these locations in this order and uses the first file with a given name:
+
+1. `CLINKX_ROSTERS_PATH`, a file or a directory. When you set it, ClinkX reads only this location.
+2. `${XDG_CONFIG_HOME:-~/.config}/clinkx/rosters/*.json`.
+3. The `conf/rosters/` directory inside the installed package.
+
+To write your own preset, copy `conf/rosters/default-council.json` to `~/.config/clinkx/rosters/<name>.json` and edit the copy. The file name is the preset name. The preset name must match `^[a-z0-9][a-z0-9_-]{0,63}$`. A request that gives `roster` together with `members`, `chairman`, `chairman_model`, `chairman_effort`, or a non-empty `cb_delegate` returns error `-32602` and starts no run.
+
+### Background runs
+
+Pass `async: true` to `run_workflow` to get a `run_id` immediately. Call `workflow_run_status` with that `run_id` to see the stage progress. Pass `include_result: true` to get the final result. Use `cancel_workflow` to stop a run. Completed runs stay on disk for the retention period given above.
+
+## Context bundles
+
+Use `context_builder` when a later call needs a selected part of the repository. Then the first tool result does not contain that content. You must give at least one anchor: a `focus_paths` entry or a non-blank `search_terms` entry.
 
 ```json
 {
-  "mcpServers": {
-    "clinkx": {
-      "command": "node",
-      "args": ["/path/to/clink-mcp/dist/index.js"],
-      "env": {
-        "CLINKX_ALLOWED_ROOTS": "/path/to/your/workspace",
-        "CLINKX_WORKFLOWS_WORKSPACE_ROOT": "/path/to/your/workspace"
-      }
-    }
-  }
+  "task": "Collect context for the server tool registration",
+  "roots": ["/path/to/your/workspace"],
+  "focus_paths": ["src/server.ts"],
+  "search_terms": ["ListToolsRequestSchema"]
 }
 ```
 
+The tool writes the bundle to the context-runs directory and returns a short JSON receipt. The receipt contains `recommended_clink.absolute_file_paths`. Pass that list as `absolute_file_paths` on the next `clink` call.
+
+By default the selection is deterministic. You can also set `delegate.enabled: true` and name a curator and a finalizer CLI. The curator makes a selection and the finalizer scores it. ClinkX checks the selection and rebuilds the bundle from local files. It applies the budgets again and writes only content that it checked itself. Provider output is an input that ClinkX checks, not a result.
+
+## Dashboard
+
+The package includes a local, read-only web dashboard. It shows workflow runs, single calls, context runs, progress reports, the workflow catalog, the adapter catalog, and the saved artifacts. Start it with the second command that the package installs:
+
+```bash
+npx -p clinkx clinkx-workflows-dashboard --port 4180
+```
+
+The dashboard listens on `127.0.0.1` and `::1` and prints `http://localhost:<port>`. Passkey sign-in is the default. On the first start, the dashboard prints one enrollment code. Register a passkey with that code, then sign in. For local tests only, `CLINKX_WORKFLOWS_DASHBOARD_AUTH_MODE=none` disables sign-in.
+
+Point the dashboard at the same `CLINKX_WORKFLOWS_STATE_DIR` as the ClinkX server. If the two directories differ, the dashboard shows a different run set, often an empty one. If you set `CLINKX_CONTEXT_BUILDER_RUNS_DIR` for the server, set the same value for the dashboard.
+
+The dashboard does not start, cancel, or approve anything. The data that it shows can contain prompts, outputs, and file contents from your workspace. Access is local and needs a passkey, but any process that runs as the same OS user can read the state directory.
+
 ## Safety
 
-ClinkX validates request paths, environment variables, and argument policy. It does not sandbox the spawned process.
+ClinkX checks request paths and passes only a small set of environment variables to the child process. It does not sandbox the child process.
+
+**WARNING: A child process has the same permissions as the user who started ClinkX.** The included adapters start each CLI with no sandbox and with approval prompts turned off or set to accept file edits. The child process can edit and delete files in your workspace and can run commands. Give each prompt clear limits. Do not run ClinkX as root or as an administrator.
+
+**WARNING: `context_builder` copies secrets by default.** The default is `allow_secrets: true`. With this default, ClinkX copies API keys, private keys, tokens, and files such as `.env` and `id_rsa` into bundles. The CLIs that receive the bundle also receive the secrets. To make ClinkX omit or redact common secret forms, set one of these:
+
+- `allow_secrets: false` on the `context_builder` call.
+- `cb_allow_secrets: false` on the `run_workflow` call.
+- `CLINKX_CONTEXT_ALLOW_SECRETS=false` in the server environment.
 
-`CLINKX_ALLOWED_ROOTS` limits which file paths the tool accepts. Default is `process.cwd()`. It is required only if the MCP host starts ClinkX with cwd at `/`. Set it anyway so path admission does not depend on whatever cwd the host chose. The subprocess has the same permissions as whoever started ClinkX.
+This filter is a best-effort check, not a security boundary.
 
-Set `CLINKX_WORKFLOWS_WORKSPACE_ROOT` to the same workspace. If you omit it, workflows use `process.cwd()` and warn on stderr.
+`CLINKX_ALLOWED_ROOTS` limits the paths that tool calls can reference. It does not limit the child process. Set it in all installations so that the limit does not depend on the start directory of the client.
 
-`context_builder` validates roots and blocks symlink escapes. Secret material (API keys, private keys, tokens, `.env` / `.pem` / `id_rsa` / `credentials.json`) is included as written by default (`allow_secrets:true`) so delegates can probe. Opt out with `allow_secrets:false`, `cb_allow_secrets:false`, or `CLINKX_CONTEXT_ALLOW_SECRETS=false`. Bundle artifacts are not a sandbox and not an access-control boundary.
+Only the `council-plan-review` and `plan-review-receipts` prompts tell the members not to edit files. This is an instruction to the model, not a mechanical control. The other workflows give no such instruction.
 
-See `docs/security.md`.
+## Documentation
+
+The installed package contains these files. After `npm install clinkx`, find them in `node_modules/clinkx/`.
+
+| File | Content |
+|---|---|
+| `docs/configuration.md` | Reference for adapter files, invocation overrides, and environment variables. |
+| `docs/security.md` | Trust boundaries, redaction scope, and the limits of each safety control. |
+| `CHANGELOG.md` | Changes, upgrade notes, and new flags for each release. |
+
+Read the upgrade notes before you upgrade a server that has unfinished workflow runs.
 
 ## License
 
-Copyright (c) 2026 jim380. All rights reserved. Proprietary package (`license: UNLICENSED`). See `LICENSE`.
+Copyright (c) 2026 jim380. All rights reserved.
+
+ClinkX is free to use but not open source. You may install and run the published npm package for your own use. You may not copy, change, redistribute, or sell it. The `package.json` license field is `UNLICENSED`. See the `LICENSE` file in the package for the full text.

package/clinkx-workflows/dist/chairman-knobs.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Shared chairman invocation-knob resolution.
+ *
+ * Provider change (caller chairman is set AND differs from the static
+ * cli_name) drops inherited model/effort; only explicit chairman knobs apply.
+ * Same provider keeps unspecified static pins and overlays supplied knobs.
+ */
+export interface ChairmanCallPins {
+    readonly cli_name: string;
+    readonly model?: string | undefined;
+    readonly effort?: string | undefined;
+}
+export interface ResolveEffectiveChairmanCallInput {
+    readonly staticCall: ChairmanCallPins;
+    readonly chairmanCliName: string | undefined;
+    readonly chairmanModel: string | undefined;
+    readonly chairmanEffort: string | undefined;
+}
+export interface EffectiveChairmanCall {
+    readonly cli_name: string;
+    readonly model?: string;
+    readonly effort?: string;
+}
+export declare function resolveEffectiveChairmanCall(input: ResolveEffectiveChairmanCallInput): EffectiveChairmanCall;

package/clinkx-workflows/dist/chairman-knobs.js

@@ -0,0 +1,27 @@
+/**
+ * Shared chairman invocation-knob resolution.
+ *
+ * Provider change (caller chairman is set AND differs from the static
+ * cli_name) drops inherited model/effort; only explicit chairman knobs apply.
+ * Same provider keeps unspecified static pins and overlays supplied knobs.
+ */
+export function resolveEffectiveChairmanCall(input) {
+    const { staticCall, chairmanCliName, chairmanModel, chairmanEffort } = input;
+    const providerChanged = chairmanCliName != null && chairmanCliName !== staticCall.cli_name;
+    const model = chairmanModel !== undefined
+        ? chairmanModel
+        : providerChanged
+            ? undefined
+            : staticCall.model;
+    const effort = chairmanEffort !== undefined
+        ? chairmanEffort
+        : providerChanged
+            ? undefined
+            : staticCall.effort;
+    return {
+        cli_name: chairmanCliName ?? staticCall.cli_name,
+        ...(model !== undefined ? { model } : {}),
+        ...(effort !== undefined ? { effort } : {}),
+    };
+}
+//# sourceMappingURL=chairman-knobs.js.map

package/clinkx-workflows/dist/chairman-knobs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chairman-knobs.js","sourceRoot":"","sources":["../src/chairman-knobs.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAqBH,MAAM,UAAU,4BAA4B,CAC1C,KAAwC;IAExC,MAAM,EAAE,UAAU,EAAE,eAAe,EAAE,aAAa,EAAE,cAAc,EAAE,GAAG,KAAK,CAAC;IAC7E,MAAM,eAAe,GACnB,eAAe,IAAI,IAAI,IAAI,eAAe,KAAK,UAAU,CAAC,QAAQ,CAAC;IACrE,MAAM,KAAK,GAAG,aAAa,KAAK,SAAS;QACvC,CAAC,CAAC,aAAa;QACf,CAAC,CAAC,eAAe;YACf,CAAC,CAAC,SAAS;YACX,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC;IACvB,MAAM,MAAM,GAAG,cAAc,KAAK,SAAS;QACzC,CAAC,CAAC,cAAc;QAChB,CAAC,CAAC,eAAe;YACf,CAAC,CAAC,SAAS;YACX,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC;IAExB,OAAO;QACL,QAAQ,EAAE,eAAe,IAAI,UAAU,CAAC,QAAQ;QAChD,GAAG,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACzC,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC5C,CAAC;AACJ,CAAC"}

package/clinkx-workflows/dist/clink-client.d.ts

@@ -14,6 +14,7 @@
  */
 import type { ClinkBackend, ToolCallResult } from "./backend.js";
 import type { SessionLogOwnerV1 } from "./dashboard/session-log-contract.js";
+import { type ObservedInvocationV1 } from "./dashboard/invocation-contract.js";
 /** Parsed result from a clink call. */
 export interface ClinkCallResult {
     /** Primary output text (for storage/threading/hashing). */
@@ -50,3 +51,12 @@ export declare function callClink(session: ClinkBackend, input: Record<string, u
     stageId: string;
     callId: string;
 }, timeoutMs?: number, sessionLogOwner?: SessionLogOwnerV1): Promise<ClinkCallResult>;
+/**
+ * Extract a runtime-observed invocation record from a child `_debug` block.
+ *
+ * Best-effort telemetry: returns undefined when the block is absent, the
+ * `observed_invocation` key is missing, or the payload does not satisfy
+ * ObservedInvocationV1Schema. Never throws — malformed observed telemetry
+ * must not affect call success/failure handling.
+ */
+export declare function extractObservedInvocation(debug: Record<string, unknown> | null): ObservedInvocationV1 | undefined;