@iowarp/clio-coder 0.4.9 → 0.5.0

package/docs/guide/environment-variables.md

@@ -54,7 +54,6 @@ These names follow an upstream or operating-system convention. They are not subs
 | Variable or family | Controls |
 | --- | --- |
 | Provider credential variables | `src/engine/env-api-keys.ts` maps the selected provider to its conventional key, including `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `OPENROUTER_API_KEY`, `GEMINI_API_KEY`, `AWS_*` Bedrock credentials, and Google Vertex application credentials. `clio-coder auth` remains the preferred managed credential path. |
-| `OLLAMA_NUM_PARALLEL` | Fallback concurrency advertised for an Ollama Native target when the runtime does not provide a stronger slot fact (`src/domains/providers/runtimes/local-native/ollama-native.ts`). |
 | `VISUAL`, `EDITOR` | External editor command, with `VISUAL` taking precedence (`src/core/external-editor.ts`). |
 | `TERM`, `COLORTERM`, `TERM_PROGRAM`, `WT_SESSION` | Terminal capability, color-depth, keybinding, and desktop-notification adaptation. These variables describe the terminal rather than Clio policy. |
 | `SSH_CONNECTION`, `SSH_TTY`, `TMUX`, `STY` | Remote-session and terminal-multiplexer detection used by the adaptive stream-pacing policy (`src/interactive/stream-pacing-policy.ts`). |
@@ -96,6 +95,7 @@ Set by Clio for its own processes; not operator knobs.
 | Variable | Purpose |
 | --- | --- |
 | `AI_AGENT` | Clio sets this generic child-process attribution marker to `clio-coder` at both shipped entry points and reinforces it for bash tools, fleet workers, registered code steps, and command hooks. Child tooling may read it to identify the agent that launched it (`src/cli/index.ts`, `src/worker/entry.ts`, `src/core/bash-exec.ts`). |
+| `CDPATH` | Removed from bash-tool children, whether inherited or set by the login profile, because it sends a relative `cd` somewhere the command does not name and bash admission judges a `cd` by its text (`src/core/bash-exec.ts`). |
 | `CLIO_CODER_GIT_COMMITS_ENABLED` | Carries the effective `integrations.git.commitAttribution` setting to Clio-controlled child-process seams. It is set from validated settings and is not an operator override (`src/core/git-commit-attribution.ts`). |
 | `CLIO_CODER_COMMIT_ASSISTED`, `CLIO_CODER_COMMIT_AUTHORED`, `CLIO_CODER_COMMIT_DECISIONS` | Per-spawn inputs to the managed `prepare-commit-msg` hook, which also requires `AI_AGENT=clio-coder` and `CLIO_CODER_GIT_COMMITS_ENABLED=1`; normal external shells never receive this set. Only assistance, authorship, and the space-separated decision refs the spawn was made under cross the environment. Testing, review, and receipt trailers are composed in process by the fleet seam, so a child shell cannot forge them by exporting a variable (`src/core/git-commit-attribution.ts`). |
 | `CLIO_CODER_GIT_CONFIG_BASE_COUNT`, `CLIO_CODER_GIT_DEFAULT_HOOKS_EQUIVALENT` | Bookkeeping that lets each managed hook wrapper remove only Clio's command-scope `core.hooksPath` pair before chaining the repository's own hook of the same name. Existing `GIT_CONFIG_COUNT` entries remain in force; an explicit `core.hooksPath` is treated as composable only when it resolves exactly to the repository's default hooks directory (`src/core/git-commit-attribution.ts`). |

package/docs/guide/exit-codes-and-output.md

@@ -15,6 +15,7 @@ Clio Coder follows a deterministic exit code taxonomy across all commands:
 | **`0`** | **Success** | Successful command execution, clean run settlement, `--version`, `--help` invocation, or missing trace database notice without an explicit `--db` flag. |
 | **`1`** | **Operational Failure** | Execution error, model target unreachable, doctor diagnosis with unresolved issues, explicit `--db` path not found, or evaluation rubric failure (`fail` or `error` verdict). |
 | **`2`** | **Syntax / Usage Error** | Unknown subcommand, invalid flag, missing required positional arguments, global flag placed after subcommand, or data mutation SQL keyword passed to `clio-coder trace sql`. |
+| **`124`** | **Run Timeout** | `clio-coder run --timeout <seconds>` elapsed. The run took the coordinated shutdown path a SIGTERM takes: the turn was aborted, a running bash tool's process group was signalled, and the receipt was sealed with outcome `timed_out` and run status `failed`, the status a dispatched worker's `timed_out` receipt seals with. The code matches `timeout(1)`. An external SIGTERM still exits 143 with outcome `canceled`. A timeout that fires during boot, before the turn starts, exits 124 with no receipt. |
 | **`3`** | **Unmeasured / Harness State** | Specific to `clio-coder eval skill` (formerly `clio-coder skills eval`): rubric could not be evaluated due to unparseable judge output, timeout, or evidence archive write failure (distinct from a failure/regression). Package eval commands (`clio-coder eval run --package`) and suite evaluations return 1 on failure. |
 
 ---
@@ -47,7 +48,8 @@ In headless execution (`clio-coder run`):
    ```text
    clio-coder run cannot confirm permission requests; rerun interactively to approve this action.
    ```
-   The denial is delivered to the LLM as a tool result so the agent can adapt or report the limitation. If the run completes after the denial, the process exits `0` with the answer on `stdout`.
+   The denial is delivered to the model so it can recover through permitted work or report a limitation. An unresolved block with no successful write exits `1` with receipt outcome `failed` and `outcomeDetail: "noop"`; this does not require `--fail-on-noop`. A later substantive success of the same action class can resolve a block. A successful `limitation` call fails with detail `limitation`. `--fail-on-noop` also rejects runs whose attempted tools all failed without a block. See [Headless No-op Runs](commands-and-modes.md#headless-no-op-runs).
+4. **No-op Runs Under `eval run`**: `clio-coder eval run` fails a task whose `clio-coder run` sealed `noop: true`, with failure class `noop`, even when the task's verifier passes on the untouched workspace. The suite runner reads the main-agent receipt from the item's own state journal, matched to the run by the session id in its `--json` header, and does not pass `--fail-on-noop`, so a nonzero runner exit still reports `runner_failed`. The result carries `result.noop` (absent when no matching receipt records the flag), and `artifacts.failureReason` names the blocked tool calls and their reasons, or says no mutating tool call succeeded. `eval run` prints that reason as a `failure:` line, the JUnit report puts it in the failure body, and the verdict records `machinery: "ok"` with reason `noop`, because the harness worked and the agent changed nothing.
 
 ---
 

package/docs/guide/extensions-and-sharing.md

@@ -42,7 +42,7 @@ When inspecting skills discovered across native and foreign compatibility roots,
 1. **Trust-first collision resolution**: `compareSkillCandidates` compares **trusted status first** (`Number(a.trusted) - Number(b.trusted)`), then precedence level, then registry agent order (`interopSourceRank`), and finally file path. This ordering governs both canonical-file deduplication (`dedupeCanonicalSkillPaths`) and same-name collision resolution (`resolveSkillCollisions`). Crucially, trust-first ordering prevents an untrusted project compatibility copy (such as an unvetted `.claude/skills/my-skill` or `.agents/skills/my-skill`) from winning a collision against an admitted native library skill and then disappearing at model visibility time. The trusted native skill wins and remains active.
 2. **Canonical file deduplication**: If multiple scanned roots resolve to the exact same canonical `SKILL.md` path on disk (via symlinks), `dedupeCanonicalSkillPaths` sorts candidates with `compareSkillCandidates` and retains only the winning candidate, logging a diagnostic for the shadowed path.
 3. **Model visibility**: Only admitted skills passing `modelVisibleSkills` (`skill.trusted && !skill.disableModelInvocation`) are visible in `context(scope="skills")` or eligible for model invocation. Setting `disable-model-invocation: true` in skill YAML frontmatter keeps the skill in the catalog for manual operator slash command usage while withholding it from model context.
-4. **Foreign package trust vs unmanaged roots**: Foreign installed packages (carrying `origin: "import"` or `"interop"` and `trust: "foreign"`) are not automatically admitted just because they are installed at user scope. In `defaultSkillRoots`, plugin roots receive `trusted: root.trust !== "foreign" || trustProjectCompatRoots` regardless of install scope; the `integrations.projectResources.trustProjectImports` (`skills.trustProjectCompatRoots`) setting serves as the explicit trust gate for foreign package skills. Conversely, unmanaged user-scoped compatibility roots (`~/.claude/skills`, `~/.agents/skills`, `~/.codex/skills`) have native user trust, while unmanaged project-scoped compatibility roots (`.claude/skills`, `.agents/skills`) remain untrusted until that setting is enabled.
+4. **Foreign package trust vs unmanaged roots**: Skills and prompts discovered in other agents' user or project folders are inactive until explicitly imported into Clio. Imported foreign packages retain `trust: "foreign"` at either scope and additionally require `integrations.projectResources.trustProjectImports` (legacy control id `skills.trustProjectCompatRoots`). Enabling trust never imports or activates loose compatibility files.
 5. **Project-package shadowing**: Shadowing and disabling of entire packages operates through the managed package lifecycle (`state.json`), where a project-scoped package installation can shadow and disable an underlying user-scoped package of the same ID, rather than through an arbitrary filesystem switch on unmanaged files.
 
 ---
@@ -98,14 +98,7 @@ Submitting `/pkg:help` renders the template locally as an operator card in the t
 
 ### Foreign prompt roots
 
-A Claude Code slash command in `.claude/commands`, a Codex prompt in `.codex/prompts`, and an OpenCode command in `.opencode/command` are prompt templates Clio reads directly, at both user and project scope. A foreign prompt is text substituted into a message the operator typed, so it keeps the untrusted-by-project default that skills have and never gains an execution grant of its own.
-
-User-scope foreign prompts are trusted because they came from the operator's
-machine. A project-scope prompt lists in `/prompts` with an
-`untrusted` marker and refuses substitution until
-`integrations.projectResources.trustProjectImports: true` opts in. An untrusted
-template sends nothing to the model. A token naming neither a command nor a
-template reports `is not a command`.
+Claude, Codex, and OpenCode prompt folders are discovered at user and project scope, but their loose templates cannot expand. Explicitly adopt them with `clio-coder interop adopt <host>` or import a package with `clio-coder library import <path>`. Imported foreign prompts additionally require `integrations.projectResources.trustProjectImports: true`. Clio's own prompt roots remain usable. Discovery-only templates cannot shadow a trusted Clio template and send nothing to the model.
 
 ---
 
@@ -157,11 +150,7 @@ Recognized frontmatter fields:
 
 ### Trust and compatibility roots
 
-Shared user roots are model-visible by default, like the Clio user root. Project-local compatibility roots are discovered but **untrusted by default**: they appear in `/skill` with an `untrusted` marker, but they are excluded from the model-visible catalog and cannot be loaded through `context`. This prevents an unreviewed project checkout from injecting skills the model will act on.
-
-Opt in to model-visible project compatibility roots by setting `integrations.projectResources.trustProjectImports: true` in `settings.yaml`. `.clio-coder/skills` is always trusted as the Clio-native project root.
-
-### Loading with context and skill authoring
+Shared and other-agent user/project roots are discovery-only. Explicitly import the desired resources into Clio; then review and enable `integrations.projectResources.trustProjectImports` to use imported foreign packages. This setting applies to imported packages at either scope, despite its historical name. It never activates loose `.claude`, `.agents`, `.codex`, or other compatibility roots. Clio-native roots and trusted marketplace packages remain usable.
 
 `context(scope="skills")` lists model-visible skills when called with no `name`, or loads a pending skill body by `name`. It returns structured metadata (`name`, `description`, `path`, `base_dir`, `hash`, `source`, `scope`, `disable_model_invocation`, parsed tool policy fields, diagnostics, and frontmatter metadata) plus the body. Pass `include_tree: true` to list sibling files under the skill base directory, capped internally at 50 entries. The skills scope never executes bundled scripts and only resolves skills the model is allowed to see.
 

package/docs/guide/fleet-dispatch.md

@@ -3,15 +3,24 @@
 Clio Coder dispatches bounded worker agents. With a fleet configured, those
 workers run on remote machines over SSH while the orchestrator keeps every
 guarantee it makes locally: one admission path, one autonomy matrix, one
-receipt chain. This page covers the architecture, node setup, the doctor
-preflight, placement, topologies, failure semantics, and the residency
-default. For the end-to-end demo see
-[fleet-demo-runbook.md](../process/fleet-demo-runbook.md).
+receipt chain.
 
 Source of truth: `src/domains/dispatch/**`, `src/domains/scheduling/cluster.ts`,
 `src/tools/dispatch.ts`, `src/tools/monitor.ts`, and the contract tests under
 `tests/contracts/`.
 
+### Start here
+
+| If you want to | Go to |
+| --- | --- |
+| Add machines to the fleet | [Node setup](#node-setup), then [Doctor preflight](#doctor-preflight) |
+| Understand how work is placed and admitted | [Placement and process-safe admission](#placement-and-process-safe-admission) |
+| Choose a review, compete, or council shape | [Topologies](#topologies) |
+| Know what happens when a route fails | [Failure semantics](#failure-semantics), [Assignments, attempts, and failover](#assignments-attempts-and-failover) |
+| Watch or steer running work | [Operator visibility](#operator-visibility) |
+| Read what a run proved | [Receipts](#receipts) |
+| Run the end-to-end demo | [fleet-demo-runbook.md](../process/fleet-demo-runbook.md) |
+
 ## Architecture
 
 The worker protocol is transport-neutral: the orchestrator writes one
@@ -152,6 +161,38 @@ Placement and admission are separate, deterministic authorities:
 
 The durable capacity state file (`dispatch-admission.json`) uses schema version 2 and owns global and per-node leases, heartbeats, reservation transfer, retry rebinding, and the TTL-bounded operator drain (`DEFAULT_CAPACITY_DRAIN_TTL_MS` = 3,600,000 ms). A lease acts as durable expiring authority (`DEFAULT_CAPACITY_LEASE_TTL_MS` = 30,000 ms) and is reclaimed only with owner-liveness evidence when a process birth token cannot prove process death. A plan reserves its peak wave, and a retry rebinds the same assignment member to its actual node and cost bound so that an assignment retry belongs to its existing plan slot and cannot queue behind or outspend itself. Full leasing schema and locking protocols are specified in [capacity-and-scheduling.md](../architecture/capacity-and-scheduling.md).
 
+### Worker limits and `fleet.concurrency: auto`
+
+`fleet.concurrency` sets the global worker pool and the implicit local node's
+limit. SSH nodes always use their own `maxWorkers`. A number means exactly that
+many workers for both. The default is `auto`. An explicit value in
+`settings.yaml`, a number or `auto`, is kept as written.
+
+`auto` sizes the local node from the host it runs on. The limit is the smallest
+of four inputs:
+
+| Input | Rule |
+| --- | --- |
+| cpu | usable CPUs from `os.availableParallelism()`, which honors affinity masks such as a Slurm cpuset |
+| memory | (available memory minus a 2 GiB reserve) divided by 1 GiB per worker |
+| cgroup | the same formula over the headroom inside a cgroup memory limit, when one is set |
+| cap | 8 |
+
+The 1 GiB per-worker estimate is about four times the observed worker process
+(160 to 270 MB RSS), because workers run compilers, type checkers, and test
+suites. Under `auto` the global pool is the cap, so a small orchestrator host
+never shrinks work placed on SSH nodes. Host facts are sampled at most every 30
+seconds. Each sample records the host facts and active local worker count together.
+The sampler adds back the estimated memory of those workers, avoiding a capacity
+reduction caused solely by Clio's own workers while still observing changes in
+host pressure. Calls inside the sampling interval reuse that same paired sample.
+
+When a host input binds the limit, the `/settings` fleet row for `local` shows
+it after the busy count (`1/2 busy · memory-bound at 2`), and the footer worker
+chip names it while local demand exceeds the limit (`3 workers · memory-bound
+at 2`). `clio-coder configure` shows what `auto` resolves to on the current
+host.
+
 Use `clio-coder fleet drain [--json]` before maintenance to close that shared
 admission authority. Existing workers continue, but new plans and every new
 execution start—including a retry or a previously reserved member—fail closed.
@@ -265,6 +306,55 @@ application never merges and reports the branch. A detached task applies when it
 Admission refuses a non-git checkout, a read-only agent, compete mode, or an
 explicit cwd outside the parent checkout with a named reason.
 
+`fleet.worktrees.root` chooses where the working tree is created:
+
+| Value | Location |
+| --- | --- |
+| `disk` (default) | The location above, under the project root. |
+| `tmpfs` | A per-user, per-checkout directory, mode 0700, under `$XDG_RUNTIME_DIR` when that is a tmpfs mount and under `/dev/shm` otherwise. |
+| `auto` | The `tmpfs` behavior when such a mount exists, quietly falling back to disk when none does. |
+| An absolute path | That directory, provided Clio owns it outright. A directory on a shared mount that Clio does not own outright is refused. |
+
+Before creating a worktree off disk, Clio compares the mount's free space with
+twice the size of the tracked tree plus 256 MiB and falls back to disk, with a
+`[clio-coder:dispatch] task worktree root` notice, when it is short. A tmpfs is
+RAM: what a worker builds inside its worktree counts against it, and uncommitted
+files there do not survive a reboot.
+
+Only the working tree moves. Git objects, the index, the branch, and the
+ownership claim stay with the repository. The setting applies to local placement
+only: when `fleet.nodes` is non-empty a run may be placed on another host, which
+reaches the worktree by the project-root path, so task worktrees stay on disk.
+Compete candidates always stay under the project root.
+
+Each task worktree is claimed by `.clio-coder/worktrees/<runId>.task-owner.json`,
+which always stays under the project root and records the working tree's path,
+the branch, the base commit, the apply mode, and a lease on the Clio process
+that created it (host, PID, and a PID-reuse-resistant start identity). A run that
+ends and keeps its worktree marks the claim `settled`.
+
+`clio-coder doctor` lists every task worktree that outlived its run with its
+branch, age, and the git commands to inspect or drop it.
+
+<details>
+<summary>What crash recovery removes, preserves, and refuses to touch</summary>
+
+At the next start in the same checkout, a claim that is still `active` while its
+owner is gone is a crash.
+
+A worktree with no commit beyond its base and no modified, staged, or untracked
+file is removed with its branch, and so is one whose tmpfs working tree a reboot
+took, after its stale git metadata is pruned. Its commits, if any, keep it.
+
+One that holds work is kept, marked `abandoned`, and named once on stderr as
+`[dispatch] task worktree recovery preserved <runId>: ...`. It is never merged
+and never deleted.
+
+A live owner, an owner on another host, a claim written before recovery existed,
+and anything git cannot inspect are left alone.
+
+</details>
+
 ### Typed intent and host-run verification
 
 The singular request and every object in `tasks` accept an optional `intent`:
@@ -446,24 +536,39 @@ its own prior answer. Each briefing is limited to 8 KiB and carries an explicit
 truncation marker when necessary. A failed peer contributes a labelled failure
 marker and no answer text.
 
-`synthesis: "none"` returns the final member answers directly. `vote` performs
-a deterministic majority tally over structured `verdict` fields without a
-model call. A vote council asks each member for that verdict: the member's task
-carries the ballot directive and the member's run seals a `council-ballot`
-postcondition, `{"verdict":"...","text":"..."}`, in place of the seated
-recipe's own result contract. The seated agent, its persona, and its read-only
-tool profile are unchanged, so any recipe can be voted with. The verdict is a
-single line of at most 64 bytes and is lower-cased before the tally, so members
-who reach the same conclusion land on the same key; the reasoning belongs in
-`text`, which is what the council report shows as the member's answer. A member
-that seals no conforming ballot fails its own run and is reported as a failed
-member rather than dropping silently out of the count. A vote with no majority
-reports `no_majority`, and a vote whose final members all failed reports
-`no_verdict_field`. `judge` runs one additional read-only judge against all final
-answers. Every member run seals a receipt. A judge receipt points backward to
-every final member receipt through gate provenance. The approval artifact names
-each member's label, target, model, thinking level, node, color, round count,
-and synthesis mode, so the plan hash binds the whole council contract.
+Three synthesis modes are available:
+
+| `synthesis` | What it does | Model call |
+| --- | --- | --- |
+| `none` | Returns the final member answers directly. | No |
+| `vote` | Deterministic majority tally over structured `verdict` fields. | No |
+| `judge` | Runs one additional read-only judge against all final answers. | Yes, one |
+
+Every member run seals a receipt, a judge receipt points backward to every final
+member receipt through gate provenance, and the approval artifact names each
+member's label, target, model, thinking level, node, color, round count, and
+synthesis mode, so the plan hash binds the whole council contract.
+
+<details>
+<summary>How a vote council collects ballots and what it reports without a majority</summary>
+
+A vote council asks each member for that verdict: the member's task carries the
+ballot directive and the member's run seals a `council-ballot` postcondition,
+`{"verdict":"...","text":"..."}`, in place of the seated recipe's own result
+contract. The seated agent, its persona, and its read-only tool profile are
+unchanged, so any recipe can be voted with.
+
+The verdict is a single line of at most 64 bytes and is lower-cased before the
+tally, so members who reach the same conclusion land on the same key. The
+reasoning belongs in `text`, which is what the council report shows as the
+member's answer.
+
+A member that seals no conforming ballot fails its own run and is reported as a
+failed member rather than dropping silently out of the count. A vote with no
+majority reports `no_majority`, and a vote whose final members all failed reports
+`no_verdict_field`.
+
+</details>
 
 ### ExecutionPlan and plan approval
 
@@ -484,17 +589,20 @@ rolls the whole reservation back.
 
 A reservation holds three scarce things and nothing else: a global concurrency
 slot, a per-node slot, and a budget upper bound. It never pins route identity.
+
 Capacity and budget are checked for the plan as a unit at approval time, per
-wave, so a three-step sequential plan holds one slot rather than three and N
+wave, so a three-step sequential plan holds one slot rather than three, and N
 parallel tasks whose individual estimates each fit but whose sum breaches the
-ceiling are denied together with the aggregate figure. A member is consumed
-once by its assignment and released once when that assignment settles; a retry
-that lands on a different node or a differently priced route rebinds the member
-atomically and fails closed if the new node has no free slot or the new
-estimate breaches the ceiling. Reservations owned by a dead process are
-reclaimed at startup, with a TTL as the backstop, and live sibling processes'
-reservations are preserved. Execution consumes the
-same pins, including each expanded builder/reviewer/candidate/judge role and
+ceiling are denied together with the aggregate figure.
+
+A member is consumed once by its assignment and released once when that
+assignment settles. A retry that lands on a different node or a differently
+priced route rebinds the member atomically and fails closed if the new node has
+no free slot or the new estimate breaches the ceiling. Reservations owned by a
+dead process are reclaimed at startup, with a TTL as the backstop, and live
+sibling processes' reservations are preserved.
+
+Execution consumes the same pins, including each expanded builder/reviewer/candidate/judge role and
 the SSH node's transport kind and host. A placement, host, capability, or
 cost-ceiling change fails before launch rather than silently choosing an
 unapproved alternative. Full-auto skips the stop and seals the
@@ -728,6 +836,55 @@ the correct and sufficient bound. A retry denied at admission settles the
 assignment failed, reports the reason on stderr, and records it in the
 assignment's `outcomeDetail`.
 
+A retry that excludes the target, which a target-attributed failure does under
+`automatic` failover, moves to the first configured route on another target
+that can serve the request. The route must resolve to that target, carry every
+capability in the request's `requiredCapabilities`, and have a breaker that is
+neither open nor probing. When no other route qualifies, placement chooses
+again, which usually lands on the failed route after backoff; the admission
+capability gate still applies to whatever it picks.
+
+The cooldown is a per-route circuit breaker, keyed by target, runtime, and wire
+model, held in memory by the running process. It moves through three states:
+
+| State | How it is entered | What dispatches see |
+| --- | --- | --- |
+| Closed | Start, or a success resets the consecutive-failure count. | Normal admission. |
+| Open | Consecutive target-attributed failures reach `fleet.retry.breakerThreshold` (default `1`, so the first failure trips it). Lasts `fleet.retry.routeCooldownMs`. | Reroute when the failover mode allows it, refusal otherwise. |
+| Half-open | The cooldown expired. | The next new dispatch is admitted as the only probe; every other dispatch still sees the route as cooling until that probe finishes. |
+
+The failures that count are `target-auth`, `target-rate-limit`,
+`target-transient`, and `worker-runtime`. A probe success closes the route and
+resets the backoff. A probe failure reopens it with the cooldown doubled, up to
+five minutes, or the configured cooldown if that is longer. A probe that ends
+for a reason that says nothing about the target, or never starts, frees the slot
+for the next dispatch to probe.
+
+The breaker is not persisted. `clio-coder targets` and `clio-coder doctor` run in
+their own processes and cannot see it, so the session's `/settings` targets rows
+are where an open, half-open, or probing route shows with its remaining cooldown.
+
+<details>
+<summary>Why context overflow and rejected schemas do not trip the breaker</summary>
+
+A provider's context-overflow error and a response schema the server rejects are
+verdicts on the request, not on the route, so they never count against it.
+
+A rejected schema ends the attempt without a retry.
+
+A context overflow is retried once, and only onto a route whose effective context
+window is strictly larger than the failed route's. The route is chosen like a
+target-excluding retry, except that another model on the same target also
+qualifies, and under `approved` failover it must be in the approved envelope. The
+retry counts against `fleet.retry.maxRetries`, and the attempt's retry reason in
+the assignment lineage reads `context-overflow: 8192 -> 32768 on big/qwen`.
+
+An overflow is not retried under `none` failover, when the failed attempt was
+itself an overflow retry, or when no eligible route has a larger window. The
+assignment then settles failed with an `outcomeDetail` that names the reason.
+
+</details>
+
 Assignment status, attempt ids, and terminal run id are stored separately in
 `assignments.json` while each attempt keeps its own strict v20 receipt.
 Pipelines and batches await assignment terminals, so downstream stages consume
@@ -826,20 +983,22 @@ In particular, verified integrity cannot validate claims, known provenance
 cannot establish correctness, and a review verdict cannot establish
 authorship.
 
-Gate references point backward: a reviewer references the builder it
-reviewed, a revise builder references the reviewer whose findings it
-received, and a judge references every candidate. Because a worker receipt
-seals before the coordinator parses its final verdict, terminal pass/fail,
-exhaustion, winner, and confirmation outcomes are append-only integrity-
-covered gate-decision artifacts under the state directory. Evidence builds
-discover them from linked receipt ids and export `gate-decisions.json`.
+Gate references point backward: a reviewer references the builder it reviewed, a
+revise builder references the reviewer whose findings it received, and a judge
+references every candidate.
+
+Because a worker receipt seals before the coordinator parses its final verdict,
+terminal pass/fail, exhaustion, winner, and confirmation outcomes are append-only
+integrity-covered gate-decision artifacts under the state directory. Evidence
+builds discover them from linked receipt ids and export `gate-decisions.json`.
+
 Reviewer and judge terminal output first crosses an integrity-covered
 write-ahead boundary under `state/gate-decisions/pending/`, before the caller
-waits for the final receipt. Restart recovery verifies the receipt, applies
-the same verdict/winner parser, materializes the final artifact idempotently,
-and only then clears the pending record. Missing receipts, tampering, or a
-conflicting artifact fail closed and leave the journal and any compete
-worktrees available for inspection.
+waits for the final receipt. Restart recovery verifies the receipt, applies the
+same verdict/winner parser, materializes the final artifact idempotently, and
+only then clears the pending record. Missing receipts, tampering, or a
+conflicting artifact fail closed and leave the journal and any compete worktrees
+available for inspection.
 
 Protected-artifact hard blocks follow compete work into candidate worktrees:
 Clio mirrors every applicable parent-checkout path into each admitted worker
@@ -985,12 +1144,39 @@ fleet execution is not hidden inside deterministic CI.
 
 ## Bounded result delivery
 
-Documenter and Coder use a structured report (`mutation-report`). Explicit recipe selections remain in force. For a read-only explanation, its `summary` carries the requested explanation and citations, with `mutatedPaths` empty. The inline `summary` allows up to 16,384 UTF-8 bytes by default, configurable up to a ceiling of 32,768 UTF-8 bytes via recipe `maxSummaryBytes` or dispatch `result_summary_max_bytes`. In batch dispatches, a top-level `result_summary_max_bytes` default is inherited by mutating tasks and safely ignored by non-mutation steps; setting an explicit per-task `result_summary_max_bytes` on a non-mutation step fails validation before model dispatch. Authored `commitMessage` and `architect-plan` authorship remain bounded at 1,000 UTF-8 bytes. Coder and Documenter explanations have no global 15-line limit. If worker output exceeds the sealed output bound, capture fails explicitly naming the bound rather than reporting an ambiguous JSON syntax error. If the requested answer cannot fit within the summary allowance or cannot be grounded, the summary must state the specific limitation. A longer artifact requires authorization to write it; a shortened answer or validation log does not satisfy an unmet length requirement.
+Documenter and Coder use a structured report (`mutation-report`). Explicit recipe
+selections remain in force. For a read-only explanation, its `summary` carries
+the requested explanation and citations, with `mutatedPaths` empty.
+
+| Field | Bound |
+| --- | --- |
+| Inline `summary` | 16,384 UTF-8 bytes by default, raised up to 32,768 by recipe `maxSummaryBytes` or dispatch `result_summary_max_bytes`. |
+| Internal helper results | 32,768 bytes (`STRUCTURED_HELPER_RESULT_MAX_BYTES`), the same acceptance and receipt-capture ceiling. |
+| Authored `commitMessage` and `architect-plan` authorship | 1,000 UTF-8 bytes. |
+
+Coder and Documenter explanations have no global 15-line limit. In batch
+dispatches, a top-level `result_summary_max_bytes` default is inherited by
+mutating tasks and safely ignored by non-mutation steps; an explicit per-task
+`result_summary_max_bytes` on a non-mutation step fails validation before model
+dispatch.
+
+If worker output exceeds the sealed output bound, capture fails and names the
+bound rather than reporting an ambiguous JSON syntax error. If the requested
+answer cannot fit within the summary allowance or cannot be grounded, the summary
+must state the specific limitation. A longer artifact requires authorization to
+write it; a shortened answer or validation log does not satisfy an unmet length
+requirement.
 
 Documenter exposes no arbitrary shell commands; it relies on declared verifier checks or grounded source reads. In validation reporting, unexecuted checks must never be recorded as failures (`passed: false` applies only to checks that actually ran and failed). Unexecuted checks or execution limitations belong in the `summary` deliverable as stated limitations.
 
+Eligible native HTTP shadow/internal workers with tool support finish through the worker-local `clio_submit_result` tool. Its arguments are the existing contract payload, not a second model-authored envelope. The host validates the payload and grounding, seals `output.structured = {version: 1, kind, data}`, and retains canonical JSON in `output.text` for older consumers. A valid handoff ends generation without another narration round. During synthesis or repair only the terminal handoff remains available; mixed work/handoff batches are rejected and repairs remain bounded. Strict JSON text fallback is validated through the same contract. Other transports retain their existing output path, and Wiki Writer retains its scoped artifact workflow.
+
+Dispatch and `monitor(mode="collect")` expose successful sealed payloads in `details.runs[].helperResult`, with compact text and a receipt lookup. Failed integrity, failed runs, partial/truncated output, or failed contract conformance do not become consumable typed results. `quality=unmeasured` remains unmeasured. Typed data never grants write authority or authorizes Scout split continuation by itself.
+
+For an independent helper task, use `detach:true` and continue useful work; collect the batch when its result is needed. This uses the existing durable detached-run mechanism. The TUI announces helper start and settlement in its notice area even for internal invocations without a transcript island.
+
 The Scout recipe instructs the model to return structured findings with source paths and exact lines checked against live reads. A search hit alone does not establish a citation. On repair, unsupported findings should be removed rather than moved to convenient range endpoints. Inline delivery and schema conformance do not establish semantic citation accuracy.
 
-Ordinary dispatcher, council, and wiki planning time and tool estimates are advisory during execution rather than automatic aborts. Enforced bounds are explicit caller deadlines (`timeout_ms`), operator cancellation, contract output bounds, and capacity rules. The fleet tool-call cap limits tool use. The `fleet.limits.internalRunTimeoutMs` setting bounds internal CLI dispatch; it does not impose a wall-clock deadline on ordinary TUI dispatch workers.
+Ordinary dispatcher, council, and wiki planning time and tool estimates are advisory during execution rather than automatic aborts. Enforced bounds are explicit caller deadlines (`timeout_ms`), operator cancellation, contract output bounds, and capacity rules. In ordinary advisory dispatch, `fleet.limits.toolCallsPerRun` is a recorded baseline, not an enforced cutoff, despite the legacy `hardCap` field name. Repetition guards still apply; legacy enforced budget envelopes retain their tool-call cap. The `fleet.limits.internalRunTimeoutMs` setting bounds internal CLI dispatch; it does not impose a wall-clock deadline on ordinary TUI dispatch workers.
 
 A pipeline stops before admitting a dependent when a completed step reports failed quality. Execution success, result conformance, and deliverable quality remain separate facts. An independent recovery has its own receipt and does not replace the failed pipeline result. When delivery is missing or incomplete, report the terminal result and limitation; a successful process exit alone does not establish the requested deliverable.

package/docs/guide/glossary.md

@@ -115,7 +115,7 @@ This document defines the 50 core architectural concepts and terminology used th
 - **Owning Type**: `ResourceSourceInfo` in `src/domains/resources/collision.ts`.
 
 ### 28. Trust Gate
-- **Definition**: A security boundary requiring explicit operator opt-in via `integrations.projectResources.trustProjectImports` before prompt templates or skills from project-scope foreign roots can execute or expand.
+- **Definition**: A security boundary requiring explicit operator opt-in via `integrations.projectResources.trustProjectImports` before explicitly imported foreign skills or prompt templates can be used at either scope. Loose compatibility roots remain discovery-only even when enabled.
 - **Owning Type**: `PromptTemplate` in `src/domains/resources/prompts/loader.ts`.
 
 ### 29. Fleet

package/docs/guide/installation-and-lifecycle.md

@@ -2,10 +2,8 @@
 
 Clio Coder installs from the npm registry as `@iowarp/clio-coder` using npm,
 pnpm, or Bun, or from a source checkout using the pinned pnpm workflow. The
-[README installation guide](../../README.md#install) covers global installs,
-cached runners (npm exec/npx, pnpm dlx, bunx, and Yarn dlx), release tarballs,
-and manager-specific update and removal commands. All routes require Node.js
-`>=22.19.0`, including installations managed by Bun.
+[README quick start](../../README.md#get-started) covers installing and first
+run. All routes require Node.js `>=22.19.0`, including installations managed by Bun.
 
 Repository development uses pnpm 10.34.5 and `pnpm-lock.yaml`. Registry
 consumers install the built package and do not need the repository toolchain.
@@ -17,7 +15,8 @@ lifecycle operations.
 | Task | Command | Result |
 | --- | --- | --- |
 | Set up a new installation | `clio-coder configure` | Quick Connect: endpoint, key if needed, model, Connect; then start `clio-coder`. |
-| Change a connection | `clio-coder configure --section targets` | Add or edit endpoints, credentials, and models; choose role defaults. |
+| Change a connection | `clio-coder configure --section targets` | Open Connections to add or edit endpoints, credentials, and available models. |
+| Choose models for each role | `clio-coder configure --settings` | Open Chat, Fleet, or Context & Memory to choose the target and model used for that work. |
 | Change any setting or repair YAML | `clio-coder configure --edit` | Edit a draft, validate, and save with a backup. |
 | Diagnose the installation | `clio-coder doctor` | Read-only diagnosis. `clio-coder doctor --fix` repairs structure and permissions, and records fleet preflight results. |
 | Finish a package-manager update | `clio-coder upgrade --post-install` | Apply local migrations and installation checks. |
@@ -128,6 +127,7 @@ The core files are created automatically during the first run. `credentials.yaml
 | **Config** | `credentials.yaml.lock` | Lockfile used during credentials updates to prevent file corruption. | Ephemeral | Auto-removed. |
 | **State** | `install.json` | Install metadata: Clio version, node, platform, `installedAt` (written once at first install) or `repairedAt` (when metadata is reconstructed over a preexisting config, data, or state root), `upgradedAt` and `upgradedFrom` (stamped on a version change), and `noticedVersion` (the version whose one-time upgrade notice the interactive launch has shown). | Writer/umask default | Removed by uninstall / `reset --state`. |
 | **State** | `migrations.json` | Log of successfully applied schema/state migrations. | Writer/umask default | Removed by uninstall / `reset --state`. |
+| **State** | `gui/docs-server.json`, `gui/docs-server.log` | The record and log of the background documentation server started by `clio-coder docs`. The record holds the private launch token, so it is written with mode 0600. | 0600 record | Removed by uninstall / `reset --state`; `clio-coder docs --stop` removes the record. The log stays until the next launch or purge. |
 | **Data** | `memory/records.json` | Long-term learning memories (up to 500 records) proposed/approved from runs. | Writer/umask default | Removed by uninstall / `reset --data`. |
 | **Data** | `tools/<id>/<version>/` | One pinned external program Clio downloaded on request (`clio-coder tools install <id>`), with its upstream license text and a `clio-install.json` recording url, sha256, platform and install time. Binaries `0o755`, documents `0o644`. Only the pinned version is kept: a successful install prunes the versions it supersedes. | `0o755` dir | `clio-coder tools remove <id>` deletes every version of one tool; removed by uninstall / `reset --data`. |
 | **State** | `audit/YYYY-MM-DD.jsonl` | Daily safety audit logs showing allowed/blocked tool actions. | Writer/umask default | Removed by uninstall / `reset --state`. |
@@ -441,17 +441,26 @@ clio-coder configure --quick
 clio-coder configure --settings
 ```
 
-**Settings** contains the nine advanced sections:
+**Settings** uses the same organization as the TUI `/settings` overlay:
 
-1. **Targets & Auth**: manage providers, endpoints, credentials, and models.
-2. **Models & Thinking**: default models, thinking levels, model favorites, cycle set.
-3. **Chat Defaults**: smooth streaming, terminal progress, token limits, compaction.
-4. **Fleet**: concurrency, retries, tool call caps, worker timeouts, profiles.
-5. **Permissions & Autonomy**: autonomy level, worker permissions, cost limits, review watchdog.
-6. **Panes & Layout**: terminal panes capability, dock layout, TUI display mode, notifications.
-7. **Skills & Extensions**: trust project imports, external ACP agents, plugins, library sync.
-8. **Diagnostics**: version information, resolved directories, doctor check, raw settings inspection.
-9. **All Settings**: validated file editor for the complete settings schema.
+1. **Connections**: providers, endpoints, credentials, and available models.
+2. **Chat**: chat model, thinking, favorites, response length, and retries.
+3. **Fleet**: worker models, profiles, routing, concurrency, retries, and run limits.
+4. **Context & Memory**: compaction, working set, context limits, and proactive memory.
+5. **Permissions & Limits**: autonomy, worker approvals, external-agent governance, spending, and safety review.
+6. **Appearance**: display, streaming, notifications, panes, and keyboard shortcuts.
+7. **Integrations**: project skills, external agents, plugins, library, and Git attribution.
+8. **Advanced**: diagnostics, configuration files, and the validated full-file editor.
+
+Configure puts common actions first and offers **All controls in this section**
+for the shared settings catalog, with descriptions, defaults, validation, and
+explicit save review. Collections accept JSON; the full-file editor remains
+available in Advanced. The launcher also keeps its Diagnostics shortcut.
+
+This menu reorganization preserves the version-2 settings schema, file paths,
+credentials, and defaults. It needs no new data migration or reset. Older
+version-1 installations still use the existing migration through
+`clio-coder upgrade --post-install`, which backs up the original settings.
 
 Every section header indicates the exact settings file path being modified
 (`Source: ~/.config/clio-coder/settings.yaml`), prints the current active values,
@@ -460,7 +469,9 @@ parent menu remembers your selected row. Dumb terminals use numbered menus
 with `b` for Back and `q` to quit.
 
 The `--section <name>` flag jumps directly into any section (e.g.,
-`clio-coder configure --section models` or `clio-coder configure --section fleet`).
+`clio-coder configure --section chat` or `clio-coder configure --section fleet`).
+Previous names such as `models`, `permissions`, `panes`, and `skills` remain
+accepted aliases. `--section diagnostics` opens diagnostics directly.
 The `--json` flag emits user settings with defaults in formatted JSON for scripting.
 `--edit` opens a temporary settings draft in `VISUAL`/`EDITOR`, validates it before
 saving, and keeps the previous file as `settings.yaml.bak`. It can repair a file

package/docs/guide/interop.md

@@ -29,7 +29,7 @@ claude plugin marketplace add ./path/to/clio-coder
 claude plugin marketplace add "$(npm root -g)/@iowarp/clio-coder"
 ```
 
-The marketplace publishes 34 entries: the 33 curated skill packages and the
+The marketplace publishes 35 entries: the 34 curated skill packages and the
 `materio` bundle. What each entry becomes on the Claude Code side:
 
 | Source layout | What Claude Code loads |
@@ -75,7 +75,7 @@ own `.agents/skills` links straight at the canonical trees:
 .agents/skills/materio     -> ../../library/plugins/materio/skills
 ```
 
-A Codex session started anywhere in a clone therefore sees all 33 curated skills
+A Codex session started anywhere in a clone therefore sees all 34 curated skills
 and Materio's 6 portable skills under their canonical names, with no install step
 and no copied `SKILL.md`. To get the same catalog in every repository, link the
 canonical directories into your user skills root: