clinkx 1.1.1 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,65 @@
 # Changelog
 
+## 1.2.0 — 2026-10-20
+
+### Upgrade notes
+
+- There is no automatic migration. Durable data now lives under `~/.clinkx`; data written by earlier builds stays under `~/.local/state/clinkx-workflows` and `~/.local/state/clinkx/context-builder/runs` until you act. Pick one path from [Migrating to `CLINKX_HOME`](docs/configuration.md#migrating-to-clinkx_home): start fresh and keep the old directories as an archive; copy workflow state and user configuration into `~/.clinkx` with producers stopped, merging rather than overwriting; or pin the old directories with `CLINKX_WORKFLOWS_STATE_DIR` and `CLINKX_CONTEXT_BUILDER_RUNS_DIR`. Do not move `context-builder/runs`.
+- Runs moved from the previous default stay non-resumable because the state path is part of their resume fingerprint. `CLINKX_HOME` itself is not part of that fingerprint.
+- A dashboard that still mounts or reads the old directories shows only runs written before the upgrade. Point it at the producers' current directories and recreate the dashboard companion or local stack.
+- `CLINKX_ALLOWED_ROOTS` entries that are dangling symlinks, inaccessible, or neither a directory nor a regular file now fail startup instead of being kept leniently. Fix or remove them before upgrading.
+
+### Added
+
+- `workflow_run_wait({run_id, expected_execution_id?})` observes a local workflow execution until its cleanup fence, for a fixed 30-second server-owned budget per call, and returns the metadata-only status projection plus `wait:{outcome, execution_id?, budget_ms, elapsed_ms}`. Outcomes are `settled`, `budget_elapsed`, `not_owned`, `orphaned`, `not_found`, `identity_changed` and `identity_unavailable`; they are observation outcomes, not new run statuses. Re-arm `budget_elapsed` with the same pin; cancelling a wait detaches only that observation.
+- Workflow executions carry an opaque `execution_id`: on the async `run_workflow` acknowledgement, and in one trailing identity block `{resolved_roster?, execution_id?}` on blocking `run_workflow` and `resume_workflow` results. It is a fence, not a capability. `workflow_run_status` accepts an optional `expected_execution_id`; a pinned read of a different or unprovable execution returns `isError` `identity_changed` / `identity_unavailable` with no result, and a persistently changing active state returns the retryable `state_read_unstable`. Unpinned calls are unchanged.
+- The execution id is persisted in `state.json` (optional `executionId`, `state_version` stays 1), so a pin settles from disk after a ClinkX restart or eviction from the 128-entry settled window when the run is terminal, stamped with that id, carries a matching `executionCompletedAt` witness, and its `run.lock` is released. A run last written by an older ClinkX (which carries the id forward without the witness) fails closed as `identity_unavailable` instead of settling on that build's outcome. Contract: `.ai/plans/workflow-completion-wait/CONTRACT.md`.
+
+### Changed
+
+- Durable ClinkX data now defaults to `~/.clinkx`, configurable with `CLINKX_HOME` (absolute; its canonical identity must not be a filesystem root, the effective home directory, or an ancestor of that home such as `/Users`). Workflow state moves from `~/.local/state/clinkx-workflows`; context-builder runs move from `~/.local/state/clinkx/context-builder/runs` to `~/.clinkx/context-builder/runs`; user adapters and rosters search `~/.clinkx/{adapters,rosters}` before the retained XDG config tier. Per-area overrides still take precedence, and temporary scratch paths are unchanged.
+- `XDG_STATE_HOME` no longer controls durable storage. Standalone workflow children receive resolved `CLINKX_HOME` and `CLINKX_WORKFLOWS_STATE_DIR` after environment scrubbing. The parent's context-run override is scrubbed; child context artifacts use `CLINKX_HOME/context-builder/runs`.
+- State and artifact roots remain automatically admitted even with an explicit workspace allowlist. Under the consolidated default, direct `clink` references can read adapters, rosters and context artifacts without context-builder secret filtering. Use a separate state override to keep configuration outside the automatic state grant. Deleting the whole ClinkX home also deletes user adapters and rosters.
+- `CLINKX_WORKFLOWS_STATE_DIR` and `CLINKX_WORKFLOWS_ARTIFACTS_DIR` reject a filesystem root or an alias of one at every entrypoint, including the standalone workflow server and an unset artifacts override whose TMPDIR-derived default resolves to one; before, only the root server rejected it. A relative `CLINKX_WORKFLOWS_ARTIFACTS_DIR` is now rejected instead of resolving against the process cwd. A value equal to the effective home, an alias of it, or an ancestor of it is still accepted, but both STDIO servers log one startup warning because it is auto-admitted as an artifact-only allowed root. Generic `CLINKX_ALLOWED_ROOTS` entries and `CLINKX_CONTEXT_BUILDER_RUNS_DIR` rules are unchanged. See the storage-root policy table in `docs/configuration.md`.
+- A `CLINKX_ALLOWED_ROOTS` entry that names an existing regular file is an exact-file grant: it resolves to the canonical file and admits only that file, not its siblings, name prefixes, or child paths. A dangling symlink, an inaccessible path (`EACCES`, `EPERM`, `ENOTDIR`, `ELOOP`), or an entry that is 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.` (`-32602` on tool paths). Nonexistent plain entries are still accepted. Automatically produced state and artifact roots stay directory-only.
+- The local and companion dashboard Compose files default the state and context-run bind sources to `${HOME}/.clinkx` and `${HOME}/.clinkx/context-builder/runs`. The workspace mount stays required, the sources must already exist, and the cloud file keeps explicit sources. One gateway deployment accepts one live companion; a second gets HTTP 409. `DASHBOARD_DEPLOYMENT_SLUG` only names Docker resources on one host.
+- When the adapter registry fails to load on a JSON syntax error, `provider_doctor` names the broken file by searching in registry order: `CLINKX_CONFIG_PATH` when set, otherwise `$CLINKX_HOME/adapters`, then the XDG config tier, then the packaged adapters. `scripts/verified-repair/qualify-installed.mjs` derives its state directory from `getStateDir()` instead of a fixed path.
+
+### Fixed
+
+- Home validation rejects symlink aliases to the effective home or filesystem root, including aliases in the default `.clinkx` path. Valid narrow symlinks and nonexistent first-run directories remain supported; accepted spelling is preserved for resume identity.
+- Individual workspace, state, artifact and context-run roots reject commas in supplied, canonical and prospective canonical paths before allow-root serialization. Relevant path checks run before reconciliation scheduling or context-directory creation. These checks are snapshots, not protection against later symlink retargeting.
+- A workflow context cache entry (`wfctx-*`) moved from another runs root no longer blocks its cache id. Its manifest names the old location, so it can never be admitted; eviction or a promotion conflict now renames it to `.stale-<runId>-<epochms>-<hex>`, the call rebuilds once, and the next identical call hits. Quarantined directories are deleted after the temp TTL (`min(cache TTL, 3600s)`). `wfpre-*`, `ctx_*` and named runs are not touched.
+
+## 1.1.2 — 2026-10-09
+
+### Added
+
+- Built-in `architecture-comparison` through `run_workflow`: two parallel authors receive the same bounded frozen packet, a fresh judge receives a separate semantic view with candidate aliases, and a deterministic reducer writes a strict owner-facing comparison record. References, output bounds, retained artifact digests, route bindings, and resume inputs are checked; incomplete evidence stays incomplete. The record preserves independent owner acceptance and states the limits of caller-declared source identity and free-text anonymity.
+- Native `workflow_verification_attach` re-inspects project proof with the owner's original expectations digest and retains a bounded, separately versioned inspection history on a workflow run. MCP status and dashboard detail expose inspected-at applicability, required coverage, check failures and safe digest references, with retention and owner acceptance kept separate. Progress-report test counts remain caller-reported.
+- Native MCP tools `provider_doctor`, `verification_run`, and `verification_inspect` work from an npm installation without a ClinkX clone or client shell access. Readiness is structured and authentication probes are explicit. Project verification runs reviewed argv commands within allowed roots, binds required checks to declared input and verifier identities, and retains private evidence for inspection with the owner's original expectations digest. The proposed standalone doctor/verifier npm CLI entry points were withdrawn before release. No Git or browser is required for project checks.
+- Packaged engineering-recipe wiring, verification overview, project-check guide, and example manifest. Recipe instructions remain in the separately installed companion `chief-of-staff` skill; ClinkX's dashboard and workflow-handoff regression fixtures remain source-only.
+- A source-checkout workflow-handoff verification procedure using the real YAML loader, MCP child session, workflow engine, validators, and artifact store. A host coverage evaluator checks frozen requirements and retained evidence; offline inspection requires the owner's original expectations digest and ignores cached success claims.
+- `scripts/provider-doctor.mjs` remains a source-checkout JSONL wrapper over the shared provider-doctor core. The MCP tool returns structured adapter readiness and a final verdict; all diagnostics are credential-redacted. Documented in `docs/configuration.md`.
+- A real-disk doctor (`clinkx-workflows/dashboard-ui/e2e/real-disk-doctor.mjs`) gates the dashboard real-disk e2e procedure: `preflight` checks node, dist freshness, chromium, the test-child seam, and an isolated `EVIDENCE_ROOT` before exercising the real fixture, `classify` maps a finished run to passed / blocked / not_run / harness_drift / failed_assertion / failed_fixture, and `identity` binds a run to its checkout and built artifacts. `docs/verification/dashboard-real-disk.md` documents the repeatable procedure.
+- A "Verified bug fix" recipe in `docs/engineering-recipes.md`.
+
+### Fixed
+
+- Dashboard-doctor Chromium preflight now removes only its owned profile and artifact directory, preserving other concurrent Playwright runs.
+- Provider-doctor interruption stops all concurrent version checks and cancels active authentication probes with their owned descendants before exiting.
+- Provider-doctor probes enforce their own 120-second cancellation deadline regardless of an adapter's timeout floor and require an exit-zero stdout or validated result-contract-file result with the exact trimmed `OK` answer before reporting authentication success.
+- Workflow-handoff inspection preserves independently observed execution, consumer, and cleanup failures when source/build identity has drifted.
+- Secret-redaction warnings deduplicate line numbers with a `Set`, preserving their ordering and bounded output without quadratic array scans.
+- `context_builder` opt-out secret redaction (`allow_secrets:false`) can no longer gut ordinary code: a quote inside a regex literal or a mid-value `key: quote` no longer opens a redaction span that runs to the end of the file, an in-place redaction that would move line breaks or span more than three lines omits the body fail-closed instead of shipping it redacted, and remaining redactions surface as one aggregate `content_secret_redacted` warning. `CONTEXT_DISCOVERY_ALGORITHM_VERSION` advances to 6.
+- A repeated SIGTERM no longer kills the dashboard, dashboard gateway, and server mid-shutdown: SIGTERM/SIGHUP handlers stay installed for repeats, teardown exits explicitly, and the dashboard and gateway close under an 8-second deadline that forces exit if closing stalls.
+- Codex app-server diagnostics now redact hyphenated vendor tokens (`sk-ant-`, `sk-proj-`, `sk-or-`) in stderr and recent-failure text.
+
+### Docs
+
+- Recipe wiring pins the merged three-recipe companion revision and records the completed evaluation and settled secret-policy decision.
+- The pstack integration evaluation for ClinkX (reports, three-arm evaluation protocol, and implementation plan under `.ai/plans/`), the dashboard verification runbook (`docs/verification/`), and the opt-out redaction bound in the context-builder notes.
+
 ## 1.1.1 — 2026-10-05
 
 ### Changed

package/README.md

@@ -60,9 +60,14 @@ ClinkX starts the Codex CLI, sends the prompt and the file references, and retur
 | `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. |
+| `provider_doctor` | Checks provider configuration, executables, and startup readiness. Optional explicit probes make real authentication calls. |
+| `verification_run` | Runs a reviewed project-check manifest and retains private evidence with a digest for later inspection. |
+| `verification_inspect` | Reassesses retained evidence using the original owner-held digest, without running project commands. |
+| `workflow_verification_attach` | Re-inspects proof with the original owner-held digest and records its historical coverage on a workflow run. |
 | `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. |
+| `workflow_run_status` | Reports persisted progress and results; optional `expected_execution_id` guards the selected local execution. |
+| `workflow_run_wait` | Observes local execution completion for up to 30 seconds without cancelling the worker when observation stops. |
 | `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. |
@@ -74,6 +79,13 @@ Two more tool groups are off by default:
 
 Each tool publishes its full input schema through MCP. MCP clients can show the schema with the tool description.
 
+Readiness and project verification are available through the same npm-installed
+MCP connection; no ClinkX checkout or client shell access is needed. See
+[provider readiness](docs/configuration.md#provider-readiness-doctor) and
+[project checks](docs/verification/project-checks.md) for tool calls, authorized
+project/evidence roots, and evidence limits. Project execution v1 supports
+macOS/Linux and runs trusted manifest commands with the server account's permissions.
+
 ## Supported CLIs
 
 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:
@@ -103,10 +115,11 @@ The `conf/adapters/hapi/` directory in the package holds optional templates that
 ClinkX reads adapter JSON files from these locations, in this order. ClinkX uses the first file with a given `name`.
 
 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.
+2. `${CLINKX_HOME:-~/.clinkx}/adapters/*.json`.
+3. `${XDG_CONFIG_HOME:-~/.config}/clinkx/adapters/*.json`.
+4. The `conf/adapters/` directory inside the installed package.
 
-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.
+To change an included adapter, copy its file to `${CLINKX_HOME:-~/.clinkx}/adapters/` (or `~/.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.
 
 To add a CLI that is not included, write a new file in the same directory. This example adapter returns the prompt unchanged:
 
@@ -127,10 +140,11 @@ These are the variables that most installations set. Every variable has a defaul
 
 | 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_ALLOWED_ROOTS` | Current directory of the server process | Comma-separated list of directories that tool calls can reference. An entry that is an existing file allows only that file. An entry that is a broken symlink, that ClinkX cannot access, or that is neither a directory nor a file stops the server at startup. 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_HOME` | `~/.clinkx` | Root directory for durable state, context-builder runs, user adapters and rosters. |
+| `CLINKX_WORKFLOWS_STATE_DIR` | `${CLINKX_HOME:-~/.clinkx}` | Directory for workflow runs, progress reports, and dashboard state. |
+| `CLINKX_CONTEXT_BUILDER_RUNS_DIR` | `${CLINKX_HOME:-~/.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. |
@@ -145,6 +159,10 @@ These are the variables that most installations set. Every variable has a defaul
 | `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_HOME` resolves to the explicit value, then `$HOME/.clinkx`, then the OS account home plus `/.clinkx` when `HOME` is unset or empty. It must be absolute and must not be a filesystem root, the home directory itself, or a parent of the home directory (for example `/Users`). The root server validates it at startup even when per-area overrides are set. `CLINKX_WORKFLOWS_STATE_DIR` and `CLINKX_WORKFLOWS_ARTIFACTS_DIR` must be absolute and must not be a filesystem root. If one of them is the home directory or a parent of it, the server starts but logs a warning.
+
+Earlier versions kept data in `${XDG_STATE_HOME:-~/.local/state}`. ClinkX does not move this data. To keep, copy, or pin the old data, see [Migrating to `CLINKX_HOME`](docs/configuration.md#migrating-to-clinkx_home).
+
 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
@@ -153,6 +171,8 @@ A workflow runs many CLI calls in stages and returns one result. A council workf
 
 | Workflow | Purpose |
 |---|---|
+| `architecture-comparison` | Compare two designs using frozen shared input and a fresh judge with candidate aliases. |
+| `verified-repair` | Repair declared existing files in place, reproduce the defect, and prove the fix through native checks and independent causal verification. |
 | `council-answer` | Answer one hard question. |
 | `council-code-review` | Review a change set. |
 | `council-debug` | Find the cause of a defect. |
@@ -161,7 +181,27 @@ A workflow runs many CLI calls in stages and returns one result. A council workf
 | `council-default` | General-purpose council. |
 | `plan-review-receipts` | Typed plan review that returns receipt candidates for an external approval process. |
 
-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`.
+Before the first stage, ordinary workflows run `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`. `verified-repair` uses its host-frozen declared inputs instead of this context preflight.
+
+Select `architecture-comparison` explicitly and provide `user_request`,
+`source_identity`, and optional `context_files` in `variables`. Its built-in
+templates and validators ship in the npm package. Two authors receive the same
+frozen packet; the independent judge receives a separate view with candidate
+aliases. The result reports comparison completeness and leaves owner acceptance
+unrecorded. See [engineering recipes](docs/engineering-recipes.md) for an example,
+route settings, bounds, and evidence limits.
+
+For a bug fix, invoke the companion `verified-repair` skill in Claude Code,
+Codex, or another connected MCP agent. It prepares the repair contract and
+native manifests, then calls `run_workflow` with
+`workflow: "verified-repair"`. The workflow needs three explicit provider routes
+and separate authorized project, evidence and verification-copy locations on
+the MCP host. It preserves unrelated changes and retains applied edits on
+failure; qualification never records owner acceptance. See the
+[paste-ready agent prompt and MCP calls](docs/engineering-recipes.md#using-verified-repair-from-an-agent-runtime)
+and [minimal contract and manifests](docs/verification/project-checks.md#native-verified-repair).
+The dashboard's **Verified repair** prompt-builder target prepares this caller
+skill invocation for copying; it does not execute the repair or authorize host paths.
 
 ### Roster presets
 
@@ -178,14 +218,58 @@ A roster preset names the members, the chairman, and the context delegate of a c
 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.
+2. `${CLINKX_HOME:-~/.clinkx}/rosters/*.json`.
+3. `${XDG_CONFIG_HOME:-~/.config}/clinkx/rosters/*.json`.
+4. 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.
+To write your own preset, copy `conf/rosters/default-council.json` to `${CLINKX_HOME:-~/.clinkx}/rosters/<name>.json` (or `~/.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.
+Pass `async: true` to `run_workflow` to get a `run_id` and an opaque
+`execution_id` immediately. Use the identity to wait for that execution:
+
+```json
+{
+  "run_id": "my-council-run",
+  "expected_execution_id": "<execution_id from launch>"
+}
+```
+
+Call `workflow_run_wait` with those arguments. It returns persisted status metadata
+and a `wait` block with `outcome`, optional `execution_id`, `budget_ms`, and
+`elapsed_ms`. On `budget_elapsed`, repeat the wait with the same identity. On
+`settled`, fetch `workflow_run_status` with the same arguments plus
+`include_result: true` to obtain the final result. The wait has a fixed server-owned
+30-second budget; it takes no caller timeout input, and `budget_ms` always reports
+that configured budget. Stopping a wait only detaches that observation. Use
+`cancel_workflow` to stop the worker.
+
+A blocking `run_workflow` and `resume_workflow` also return the `execution_id`, in
+a trailing content block `{resolved_roster?, execution_id?}`. Use the returned id
+as the pin. Leave the pin out of a first wait only when no id was returned; it then
+binds to the latest local execution and returns its identity. The id is a fence,
+not a capability: it only selects which execution a read must match.
+
+`settled` witnesses completion and cleanup in the owning server process, followed
+by an identity-checked persisted read. `not_owned`, `orphaned` and `not_found`
+return immediately. `not_owned` requires explicit persisted status recovery;
+`orphaned` and `not_found` require checking the run. A run that is still being
+admitted can briefly report `not_found` to an unpinned wait. A rejected start or
+resume never replaces an earlier execution's pin. Identity
+errors (`identity_changed` or `identity_unavailable`) must be surfaced without
+dropping the pin to fetch another execution's result. A pinned
+`workflow_run_status` can return `state_read_unstable` when the state file keeps
+changing during the read; retry it with the same pin after a short pause. The server retains up to 128
+settled metadata identities without active readers, without result text. Active
+executions are never evicted; active observations stay protected until their
+request ends. Eligible inactive settled entries are evicted FIFO. Each run's
+state also records its execution id, so after a restart or eviction a pinned
+wait or status still settles once that execution's state is terminal and its
+run lock is released. A pin on a run that is unfinished, or still locked (for
+example by a crashed owner on another host), reports `identity_unavailable`. Waits do not keep workers alive
+after server exit, and this tool does not promise unsolicited client wakeups.
+Completed runs stay on disk for the retention period given above.
 
 ## Context bundles
 
@@ -214,7 +298,7 @@ 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.
+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. If the dashboard shows only runs from before an upgrade, it still reads the old directories.
 
 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.
 

package/clinkx-workflows/dist/allowed-roots.js

@@ -1,5 +1,7 @@
 import { sep } from "node:path";
+import { assertRootRepresentable } from "./root-path-validation.js";
 export function artifactOnlyEnvEntry(root) {
+    assertRootRepresentable(root, "Allowed root");
     return root.endsWith(sep) ? `${root}.` : `${root}${sep}.`;
 }
 //# sourceMappingURL=allowed-roots.js.map

package/clinkx-workflows/dist/allowed-roots.js.map

@@ -1 +1 @@
-{"version":3,"file":"allowed-roots.js","sourceRoot":"","sources":["../src/allowed-roots.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAEhC,MAAM,UAAU,oBAAoB,CAAC,IAAY;IAC/C,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,GAAG,GAAG,CAAC;AAC5D,CAAC"}
+{"version":3,"file":"allowed-roots.js","sourceRoot":"","sources":["../src/allowed-roots.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAChC,OAAO,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AAEpE,MAAM,UAAU,oBAAoB,CAAC,IAAY;IAC/C,uBAAuB,CAAC,IAAI,EAAE,cAAc,CAAC,CAAC;IAC9C,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,GAAG,GAAG,CAAC;AAC5D,CAAC"}

package/clinkx-workflows/dist/architecture-comparison/admission.d.ts

@@ -0,0 +1,5 @@
+import type { NormalizedWorkflowDefinition } from "../definition-normalizer.js";
+export declare function materializeArchitectureRoutes(definition: NormalizedWorkflowDefinition, variables: Readonly<Record<string, unknown>>, available?: readonly string[], validateOverrides?: (cli: string, knobs: {
+    model?: string;
+    effort?: string;
+}) => void): NormalizedWorkflowDefinition;

package/clinkx-workflows/dist/architecture-comparison/admission.js

@@ -0,0 +1,50 @@
+import { getMaxPromptBytes } from "../config.js";
+import { DEFAULT_RESERVE_BYTES } from "../prompt-budget.js";
+import { ARCHITECTURE_WORKFLOW, MAX_JUDGE_BYTES, MAX_VIEW_BYTES, RouteSchema } from "./contract.js";
+const ROUTE_VARIABLES = { "candidates.author_a": "candidate_a", "candidates.author_b": "candidate_b", "judge.judge": "judge" };
+export function materializeArchitectureRoutes(definition, variables, available, validateOverrides) {
+    if (definition.name !== ARCHITECTURE_WORKFLOW)
+        return definition;
+    for (const name of ["user_request", "source_identity"]) {
+        const value = variables[name];
+        const cap = name === "user_request" ? 16 * 1024 : 2000;
+        if (typeof value !== "string" || value.trim() === "" || Buffer.byteLength(value, "utf8") > cap)
+            throw new Error(`${name} must be nonblank and at most ${cap} UTF-8 bytes`);
+    }
+    const contextFiles = variables["context_files"] ?? [];
+    if (!Array.isArray(contextFiles) || contextFiles.length > 32 || new Set(contextFiles).size !== contextFiles.length)
+        throw new Error("context_files must contain at most 32 distinct source files");
+    const judge = definition.stages.find((stage) => stage.id === "judge")?.calls[0];
+    const worstCase = MAX_VIEW_BYTES + MAX_JUDGE_BYTES + DEFAULT_RESERVE_BYTES + Buffer.byteLength(judge?.prompt ?? "", "utf8");
+    if (worstCase > getMaxPromptBytes())
+        throw new Error(`architecture worst-case judge input and response reserve (${worstCase} bytes) exceeds workflow prompt budget`);
+    const tokenLimit = variables["judge_prompt_token_limit"];
+    if (tokenLimit !== undefined && (!Number.isSafeInteger(tokenLimit) || tokenLimit < worstCase))
+        throw new Error(`judge_prompt_token_limit must cover the conservative byte-token upper bound ${worstCase}; shorten the contract or use a larger route`);
+    const materialized = {
+        ...definition,
+        stages: definition.stages.map((stage) => ({ ...stage, calls: stage.calls.map((call) => {
+                const prefix = ROUTE_VARIABLES[`${stage.id}.${call.id}`];
+                if (prefix === undefined)
+                    return call;
+                const cli = variables[`${prefix}_cli`];
+                const model = variables[`${prefix}_model`];
+                const effort = variables[`${prefix}_effort`];
+                const route = RouteSchema.parse({ cli_name: typeof cli === "string" ? cli.trim() : cli, ...(model !== undefined ? { model } : {}), ...(effort !== undefined ? { effort } : {}) });
+                if (!/^[A-Za-z0-9_-]+$/.test(route.cli_name))
+                    throw new Error(`invalid ${prefix}_cli`);
+                if (route.model !== undefined && !/^[^\s\u0000-][^\s\u0000]*$/.test(route.model))
+                    throw new Error(`invalid ${prefix}_model`);
+                if (route.effort !== undefined && !/^[a-z0-9][a-z0-9_-]*$/.test(route.effort))
+                    throw new Error(`invalid ${prefix}_effort`);
+                if (available !== undefined && !available.includes(route.cli_name))
+                    throw new Error(`${prefix}_cli ${route.cli_name} is not an available JSON-capable route`);
+                validateOverrides?.(route.cli_name, { ...(route.model !== undefined ? { model: route.model } : {}), ...(route.effort !== undefined ? { effort: route.effort } : {}) });
+                const { model: _model, effort: _effort, ...base } = call;
+                return { ...base, ...route, role: "json" };
+            }) })),
+    };
+    const judgeCli = String(variables["judge_cli"]);
+    return { ...materialized, stages: materialized.stages.map((stage) => ({ ...stage, calls: stage.calls.map((call) => call.reducer === undefined ? call : { ...call, cli_name: judgeCli }) })) };
+}
+//# sourceMappingURL=admission.js.map

package/clinkx-workflows/dist/architecture-comparison/admission.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"admission.js","sourceRoot":"","sources":["../../src/architecture-comparison/admission.ts"],"names":[],"mappings":"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"}