@iowarp/clio-coder 0.4.9 → 0.5.0

package/docs/gui/workflow-coverage.md

@@ -0,0 +1,64 @@
+# Harness → GUI human workflow coverage
+
+> **Reference Design & Planning Blueprint**: This document is an architectural reference blueprint recovered from the deleted `apps/workbench` prototype. It specifies design doctrine, target parity, and inspection layouts for the early GUI preview (`apps/clio-coder-gui`), not verified runtime features of the core v0.5.0 terminal engine.
+
+Extracted from `apps/workbench/HARNESS_COVERAGE.md`. Original audit anchor: immutable harness commit `8874a3ff`, the 2026-08-29 `v0.3.9` sprint snapshot, GUI protocol version 4. The audit read Clio Coder's CLI registry, default settings schema, change classifier, ACP server, canonical event bus, and the GUI host/renderer protocol, and made no changes under root `src/`.
+
+The framing, verbatim: *"It is deliberately stricter than a feature wish list: every row names the authoritative public boundary that exists today, the UI coverage that actually exists, and the boundary that must be added before a truthful control or visualization can exist."*
+
+## Status vocabulary (6 values — keep these words, they are precise)
+
+| Status | Meaning |
+| --- | --- |
+| **Wired** | A real Clio Coder operation or fact crosses a validated GUI boundary and has a usable graphical surface. |
+| **Partial** | Part of the domain is real and graphical, but material controls, facts, or states are absent. |
+| **GUI-ready** | A public, structured Clio Coder interface exists; a GUI-only adapter and UI can be built without root edits. |
+| **Upstream boundary** | Clio Coder does not expose the required typed operation/fact to its ACP client; root harness work is required. |
+| **Separate surface** | Real functionality, but destructive, administrative, or developer-oriented enough to stay out of the core. |
+| **Not applicable** | The setting controls the terminal/TUI rather than an ACP client and should not be mirrored as a dead switch. |
+
+And the guard on "GUI-ready", verbatim: *"'GUI-ready' does not authorize parsing private state files. Prefer a documented JSON/JSONL command or a typed ACP extension over coupling the GUI to a durable store's internal layout."*
+
+**Note for the new app:** that guard was written for a browser-only client. `apps/clio-coder-gui/server/services/traces.ts` reads the trace store directly, and `server/services/` generally is a trusted local process. The guard's *spirit* — do not couple to an internal layout that will change without notice — still applies, but "prefer a documented command" is now a coupling-cost tradeoff rather than a security boundary. Decide per store, and write the decision down.
+
+## THE TABLE (33 rows)
+
+| # | Harness area | Current GUI | Status | Real boundary and next honest step |
+| -: | --- | --- | --- | --- |
+| 1 | Choose and remember project folders | Folder picker, recent projects, missing-folder recovery, guarded roots | **Wired** | GUI-local boundary; no Clio Coder change required. |
+| 2 | Bounded project files | Tree refresh, create file/folder, rename/move, version-aware confirmed delete | **Wired** | GUI-local boundary. Reading/editing file content remains Clio Coder tool work, not an embedded IDE. |
+| 3 | Interactive main-agent turn | Request composer; the Conversation projects each turn as Markdown prose, folded tool activity, reasoning, and outcome, with the Session Timeline as the card-by-card record; stop and terminal outcome | **Wired** | Standard ACP prompt/update plus strict presentation DTOs, now carrying per-frame agent attribution. Every live card names who produced it; a card Clio Coder did not attribute stays attributed to the product rather than guessed. |
+| 4 | Turn token output | Five exact fields on outcome cards and a visible-record Observatory comparison | **Wired** | Clio Coder terminal `_meta["clio-coder/usage"]`; **never converted to price or context pressure by the GUI.** |
+| 5 | Session lifecycle | New, list, resume/replay, close, rename, delete, truncation and unknown-state handling | **Wired** | ACP plus the versioned `clio-coder/session` extension. |
+| 6 | Session route | Bound target/model and next-turn target/model are distinguished | **Wired** | ACP session metadata plus safe settings extension. |
+| 7 | Working freedom | Bound-session autonomy and next-session default are distinguished; per-session change is explicit | **Wired** | ACP session autonomy plus safe settings extension. |
+| 8 | Configured targets | List, model ids, selected target, explicit probe result/latency/time | **Partial** | ACP target list/probe is real. Add/convert/remove/rename, capabilities, auth detail, fleet profiles, and richer model discovery are absent. |
+| 9 | Offline models and worker routing | Searchable model capability/limit/residency inventory plus worker profiles and agent bindings | **Wired** for read-only inventory; **Partial** for the wider domain | Fixed reads run **in parallel**: `models --json --offline`, `targets profile list --json`, `targets profile bindings --json`. **Offline residency is not health**; authoring, auth, live routing decisions, and activation events remain absent. |
+| 10 | Permissions | One-use allow/reject, expiry, cancellation semantics, locations, persistent banner, keyboard path | **Partial** | Standard ACP permission is wired. Policy rule, action class, posture, rejection hints, worker escalation provenance, and "why" need a sanitized upstream DTO. *(The DTO already exists in-process as `PermissionRequestedPayload` — see the event-bus artifact.)* |
+| 11 | Loop safety | Repeated-call count, per-turn block budget, disposition, interruption | **Wired** | The sole current `clio-coder/event` kind, `safety.loopBlocked`. *(STALE: the allowlist is 7 kinds now.)* |
+| 12 | Other safety | Tool-call soft/hard budgets, policy classifications/blocks/allows, run-abort source, budget alert | **Upstream boundary** | Typed bus facts exist but are not exposed over ACP. |
+| 13 | Context and compaction | Earlier session replay is visible and honestly marked | **Partial** | Status/init/refresh/wiki/reset/index, working-set state, pruning/recall, pressure, warnings, and compaction progress are not exposed to the ACP client. Several read-only CLI paths can seed later views. |
+| 14 | Prefix pre-warming | No GUI fact or control | **Upstream boundary** | `prewarm.enabled` exists at the audited harness commit, but safe settings and lifecycle outcomes do not cross ACP. **Never infer a cache hit from latency.** *(STALE key: it is `chat.prewarm` now.)* |
+| 15 | Agents and recipes | Searchable read-only cards for recipe, provenance, capability, latency, context tier, bindings, result contract, and budget, plus live agent attribution on the tool calls that spawned delegated runs | **Wired** for discovery and run observation; **Upstream boundary** for execution | A fixed `clio-coder agents --json` adapter projects a bounded inventory and drops native file paths. Observation is real: dispatch lifecycle events name the agent per run, and `clio-coder/agent` names it per tool call. Addressable execution, meaning the GUI asking for a run, still requires typed dispatch operations. |
+| 16 | Headless main-agent run | No separate GUI lab | **GUI-ready** | `clio-coder run --json` exposes a structured stream, but the main notebook already serves interactive ACP. Add only for reproducible batch studies, with explicit run/session semantics. |
+| 17 | Dispatch and fleet | Installation-wide admission aggregate, plus a live fleet strip of this session's dispatch runs with state, agent, node, attempt, progress count, outcome, duration, and reported tokens | **Wired** for the global aggregate and the live run lifecycle; **Partial** for the wider domain | `fleet status --json` supplies the installation aggregate. Live state arrives over the opt-in `clio-coder/event` stream as five sanitized dispatch DTOs. **The exact task never crosses**; only Clio Coder's own bounded, control-character-stripped preview does, and the untyped worker event stream is dropped in favour of a per-run progress count. Capacity, councils, gates, retry decisions, skill activation, and every mutation still require further typed events. |
+| 18 | Evidence artifacts | Usage records name the typed-listing gap; no evidence rows are fabricated | **Upstream boundary** for typed discovery | Public build/inspect/list commands exist, but `evidence list` is formatted text rather than a stable machine schema. The GUI does not scrape it. **STALE — `evidence inventory --json` now exists** (`src/cli/evidence.ts:24`), plus `src/cli/evidence-detail.ts`. This row is **resolved**. |
+| 19 | Evaluations | Usage records name the missing eval-discovery bridge; no suite or comparison surface | **GUI-ready** for a known eval; **Upstream boundary** for discovery | JSON reports exist after an eval ID is supplied, but no typed listing lets the GUI safely discover which project eval to open. Add that listing before building the Experiment index. **STALE — `eval inventory --json` now exists** (`src/cli/eval.ts:36`). This row is **resolved**. |
+| 20 | Scoped memory | No review inbox | **GUI-ready** for command orchestration; schema review needed | Public list/propose/promote/approve/reject/prune commands exist. **Approval and evidence linkage should become a deliberate review surface, never an automatic side effect of opening the GUI.** *(Still true. `src/cli/memory.ts` has zero `--json`, so the typed read is the blocker.)* |
+| 21 | Cross-session usage/economics | Project-scoped 30-day Usage record for sessions, dispatch receipts, exact token/cost totals, models, tools, skills, recipes, and safe opportunity counts | **Wired** for project-filtered aggregates; **Partial** for the wider domain | A fixed `usage report --repo <trusted-root> --days 30 --json` adapter validates bounded JSONL. It drops global audit/failure/memory/evidence rows plus raw prompts, suggestions, shapes, ids, paths, and diagnostics; **costs retain Clio Coder provenance.** |
+| 22 | Durable dispatch trace | Usage records name the project-filtering gap; no trace rows are fabricated | **Upstream boundary** for a project-safe listing | `trace runs --json` is global and includes raw requests. Add a bounded project selector and safe summary schema before a trace explorer; **never expose arbitrary SQL in the core GUI.** **STALE — `trace inspect --json` landed, and the new app reads the store server-side.** The "never arbitrary SQL" clause is the part that survives. |
+| 23 | Skills | Searchable installed inventory with scope, source, trust, precedence, invocation posture, and issue counts | **Wired** for inventory; **GUI-ready** for deeper read-only flows | A fixed `skills list --json` adapter omits bodies, hashes, native locations, and diagnostic text. Inspect/validate/eval remain candidates; install/update/sync need review and confirmation, and live activation needs upstream events. **STALE — the whole family moved under `library`.** |
+| 24 | Extensions | Searchable installed inventory with project/user scope, enabled state, effective precedence, resource kinds, versions, and issue counts | **Wired** for inventory; **GUI-ready** for reviewed mutations | `extensions list --all --json` projects scope, state, precedence, resource kinds, and issue counts while dropping paths and diagnostics. Install/enable/disable/remove still need supply-chain review, confirmation, progress, and recovery. |
+| 25 | Library | Searchable available-resource inventory with kind, category, version, origin, and audit state | **Wired** for inventory; **GUI-ready** for deeper read-only flows | A fixed `library list --json` adapter omits source URLs and requirements. Search can remain local over the bounded projection; use/sync/push/add need a separately reviewed resource flow. **STALE — `library` was rewritten into a 20-subcommand package manager. See the CLI-surface artifact; this is the marketplace the operator asked for and it is far more buildable than this row implies.** |
+| 26 | Project verifiers | Capability atlas names the missing typed interface; no verifier rows are fabricated | **Upstream boundary** for typed discovery | `verifiers discover` is formatted authoring output, not JSON. The GUI refuses to scrape it. Add a typed listing before checks become cards; **author/validate/dry-run/mutations must preserve exact argv/cwd/timeout/tags/authority.** **STALE — `verifiers inspect --json` now exists**; the argv-preservation rule still governs any authoring UI. |
+| 27 | Config provenance | Effective Clio Coder map plus four session-routing settings | **Wired** | A bounded host adapter runs fixed `clio-coder config inspect --json`, redacts values and unsafe paths, and projects provenance, trust, precedence, reload timing, context cost, and grouped issues into typed DTOs. |
+| 28 | Harness components and evolution manifests | No developer instrument | **Separate surface** | `components list --json`, snapshots/diffs, and `evolve manifest` are harness-development tools; keep them out of the primary research notebook. |
+| 29 | Portable share archives | No import/export flow | **Separate surface** | Public share inspect/import/export exists. **Import is a consequential resource mutation and needs diff, scope, conflict, and confirmation stages.** *(`/archive … --dry-run` now gives the diff stage for free.)* |
+| 30 | Doctor and paths | Settings includes a manual Recovery check with aggregate severity, fixed diagnostic categories, safe runtime versions, and resolved-root count | **Wired** for redacted diagnosis; **Partial** for repair | A fixed adapter runs `doctor --json` and `paths --json`, validates both reports, and drops finding names/details plus native paths, URLs, target/model/node/session ids, commands, and config errors. **It never passes `--fix`**; Clio Coder's documented doctor sweep **may refresh fleet eligibility facts** — disclose that side effect. Repair remains a separately reviewed action. |
+| 31 | Configure/auth/models | No setup wizard beyond selecting existing target/model | **Partial** | Full configure, target authoring, model search, and auth login/logout are not ACP operations. A first-run setup surface needs typed APIs or carefully isolated CLI workflows. **Never pass secrets through the renderer.** |
+| 32 | Upgrade/reset/uninstall | No GUI for Clio Coder's own reset, upgrade, or uninstall; the GUI's own install/upgrade/uninstall is `scripts/gui-lifecycle.ts` | **Separate surface** | Destructive or installation-level operations. If added, **resolve exact paths first, show recoverability, and require explicit confirmation outside the core notebook.** *(The GUI's own lifecycle is now `clio-coder gui`, `src/cli/gui.ts`.)* |
+| 33 | Docs | No embedded docs server | **Separate surface** | Link contextual help or launch the public docs surface; do not turn the main shell into a documentation browser. **STALE — the new app has `/api/docs/tree`, `/api/docs/page`, `/api/docs/search` and `client/pages/docs.tsx`, i.e. it deliberately did become a documentation browser.** Re-decide consciously; the old reason (don't dilute the shell) is a UX argument worth answering with navigation, not by removing the feature. |
+
+## Rows now resolved by harness work landed since the audit
+
+18 (evidence), 19 (evaluations), 22 (durable trace), 26 (verifiers) — all four upstream-boundary rows got their typed read. 23 and 25 moved rather than resolved. That leaves **10 (permissions), 12 (other safety), 13 (context), 14 (prewarm), 20 (memory)** as the genuine remaining upstream-boundary work, and every one of them already has a fully typed in-process payload waiting in `src/core/bus-events.ts`.

package/docs/guide/built-in-agents.md

@@ -275,7 +275,7 @@ Subagent runs that terminate with retryable outcomes are placed in an in-memory
 Scheduled retries use an exponential backoff state to calculate subsequent retry delays. Furthermore, targets that fail are subject to a cooldown period. The retry engine ensures that a retried task waits for the maximum of the exponential backoff delay or the remaining target cooldown duration. Retries are brand-new runs that must re-pass all admission checks. If target policies or budgets deny a retry, the task chain terminates as denied.
 
 ### 3. Concurrency Limits
-The setting `fleet.concurrency` restricts the number of concurrent subagent tasks. At this revision, `auto` resolves to the compiled default of four local workers; it does not probe the host dynamically.
+The setting `fleet.concurrency` restricts the number of concurrent subagent tasks. `auto` sizes the local node from usable CPUs, available memory, and any cgroup memory limit, up to eight workers; see [Fleet dispatch](fleet-dispatch.md#worker-limits-and-fleetconcurrency-auto).
 
 ### 4. Heartbeats and Reconciler
 For native subprocess workers, Clio uses a heartbeat mechanism. The reconciler monitors the active heartbeat timestamp. If a worker stops responding and updates no heartbeats, the reconciler terminates the stalled subprocess automatically.