@iowarp/clio-coder 0.4.2 → 0.4.3

package/docs/guide/proactive-memory.md

@@ -121,7 +121,7 @@ malformed response, or telemetry failure is silent and never blocks a tool.
 - `context.memory.cadenceToolCalls` (default `10`): Minimum completed-tool interval between background interventions.
 - `context.memory.trajectorySteps` (default `8`): Completed tool-trajectory window analyzed during background evaluation.
 - `context.memory.maxOutputTokens` (default `2000`): Bounds the rendered memory-bank context and the ordinary policy-model completion. An always-on-thinking model receives additional reasoning headroom, at least `4,000` tokens when its model cap permits, so it can still reach the strict envelope.
-- `context.memory.timeoutMs` (default `60000`): Wall-clock limit for one background memory-policy request. The step is detached, so this deadline never delays a turn, but it does hold a request slot on a real inference endpoint that your own turns and dispatched workers queue against. Raise it only after inspecting the timeout and hit-rate evidence for the selected route.
+- `context.memory.timeoutMs` (default `60000`): Wall-clock limit for one background memory-policy step, including its one permitted chat fallback attempt. The step is detached, so this deadline never delays a turn, but it does hold a request slot on a real inference endpoint that your own turns and dispatched workers queue against. Raise it only after inspecting the timeout and hit-rate evidence for the selected route.
 
 ## Trigger semantics
 
@@ -254,38 +254,48 @@ unexamined one:
   would not have been spent. The current 60-second deadline is the source-backed
   bound on what one optional call may hold a shared local server for, not a
   prediction of when a route answers.
-- A step that would run on the endpoint the chat target is streaming against is
-  skipped with reason `endpoint_busy`, and the skip is recorded. On a single-slot
-  llama.cpp router the alternative is queueing behind the operator's own decoding
-  or evicting the resident model, and neither is a cost an optional call may
-  impose.
-
-### What a background target costs on a shared local server
-
-If `context.memory.target` names the same server as `chat.target`, that
-server's slots are shared. On a llama.cpp router started with `--parallel 1`
-there is exactly one, and the memory step and the operator's turn contend for it.
-
-The consequence is worth stating plainly: a shared endpoint suppresses the model
-tier rather than merely delaying it. A step is started from the `turn_end` hook,
-which fires inside the streaming run at `agent_end`
-(`src/interactive/turn-runtime.ts`), while the chat loop still holds its
-foreground registration on that endpoint; the loop releases the hold afterwards,
-in the `finally` around the run (`src/interactive/chat-loop.ts`). Every boundary
-therefore finds the endpoint busy and records `dropped`/`endpoint_busy`. That is
-the intended trade: an optional call may not take the one slot the operator's own
-turn is using, and it may not make the server swap the resident model out. The
-`/memory` step list and `steps.jsonl` say so on every boundary, so the tier is
-visibly declining rather than quietly idle.
-
-The second mechanism is an `expected cold` stamp, for the case where a step did
-run on the chat endpoint. Its prompt is a trajectory rather than the chat prefix,
-so the next turn's prefill is expected to be cold; `/context` names
-`background_memory` as the reason instead of reporting an unexplained cold
-prefix.
-
-Pointing the background role at a second machine avoids both effects and is the
-arrangement the tier is designed for.
+- A step whose known endpoint occupancy exhausts the resolved request capacity is
+  skipped with reason `endpoint_busy`. The same gateway URL alone does not imply
+  a single request slot or a single physical model server.
+
+### Dedicated routing, chat fallback and endpoint capacity
+
+Clio prefers the explicitly configured memory target and model. If that route is
+known unavailable (missing target/runtime, down target, absent model in a known
+catalog, or a model reported unloaded/loading), Clio selects the active chat
+route for that step. A runtime client error on the dedicated route permits one
+chat attempt within the original remaining deadline. It does not retry after a
+timeout, cancellation, session/branch switch, malformed envelope, or a model's
+explicit silence. The fallback never falls back again. Both routes unavailable
+produce a visible `client_error` outcome. An unset memory role remains rules-only;
+chat fallback does not enable model-based memory by default.
+
+A runtime notice names the selected chat fallback and its reason. Routing stays
+session-local and does not edit saved settings. Each attempted call records its
+own known usage under its actual target/model and emits its own telemetry outcome;
+failed dedicated usage is retained alongside fallback usage. The final policy
+result describes the final attempt, without merging different provider identities.
+A generation change discards late content while preserving the original usage owner.
+
+Capacity follows the same existing evidence as dispatch: explicit target
+`maxConcurrentRequests`, current discovery, a valid discovery prior, then the
+conservative one-slot default for a local-native runtime. Known occupancy includes
+this process's foreground requests, active dispatch leases and held reservation
+waves. A two-slot endpoint with one foreground request can admit memory; a full
+one-slot endpoint skips it. Known dedicated saturation does not itself initiate
+chat fallback. Larger declared capacities work without a new constant.
+
+LiteLLM is a gateway protocol, so Clio does not invent a local one-slot limit for
+its URL. Distinct model routes such as dynamo, mini and zbook can share that URL;
+the gateway owns their physical routing and backend residency. An explicit or
+observed endpoint-wide bound still applies when present. Clio's process-local
+foreground holds and observed dispatch state are not a global scheduler for every
+client using the gateway. Slot holds are released on success, failure and abort.
+
+The existing `background_memory` expected-cold stamp remains keyed by endpoint
+URL. It records a possible shared-endpoint cache disturbance, including after a
+failed request, rather than proving that a different model behind the gateway
+actually evicted the chat prefix.
 
 ## Choosing a background model
 
@@ -294,9 +304,11 @@ does not need to be clever. A small non-reasoning model is the right choice, and
 Clio always requests the memory route with thinking off. Version 2 therefore
 has no configurable memory thinking-level key.
 
-That request reaches the wire wherever the runtime carries a thinking control:
+The off request depends on the resolved runtime and model metadata:
 llama.cpp reads `chat_template_kwargs.enable_thinking`, and LM Studio reads
-`reasoning_effort`, where `none` is the off value.
+`reasoning_effort`, with the off value selected by the model family. A gateway
+needs a recognized, unanimous upstream runtime declaration; unknown metadata
+does not establish a dialect. Requesting off does not prove server compliance.
 
 A model that reasons anyway still works. Some genuinely cannot be silenced, and
 the catalog records those as always-on so the level reads `forced` rather than
@@ -306,12 +318,11 @@ blocks are discarded and only the envelope is kept, and the output budget is
 sized to let a reasoning preamble run its course first. The cost is latency,
 which the detached step absorbs.
 
-One configuration is refused rather than degraded. If the background role names
-the same target and model as the orchestrator, and that model reasons, the LLM
-memory tier stays off and memory runs on its free deterministic tier. A single
-reasoning model already driving chat, workers, and shadow agents cannot also
-deliberate over memory steps without contending with the work the operator
-actually asked for.
+The active chat model may also serve memory, including a reasoning model, when
+request capacity permits. Memory still requests thinking off and uses its own
+bounded envelope and output budget. A dedicated small model is preferred for
+latency and resource use; sharing a model is a capacity decision rather than an
+unconditional refusal.
 
 This is a mix-and-match plane, not a local-only one. The background role resolves
 through the same target machinery as every other role, so the useful shapes are:
@@ -356,30 +367,30 @@ independent of the chat target and the fleet default. A running session owns
 its routing snapshot, while the saved
 selection becomes the default for new sessions.
 
-The reference topology separates chat from memory work:
+An example gateway topology keeps the three backend routes distinct:
 
 | Role | Target | Runtime and endpoint | Model | Capacity |
 | --- | --- | --- | --- | --- |
-| Chat | `dynamo` | LM Studio at `192.168.86.143:1234` | `qwen3.8-27b-dynamo` | Reported by the LM Studio probe |
-| Background memory | `mini` | llama.cpp router at `192.168.86.141:8080` | `ornith1.5-35b-moe` | 4 parallel slots, 262,144 context tokens per slot |
+| Chat and memory fallback | `dynamo` | LiteLLM at `http://gateway:4000` | `dynamo/qwen3.8-27b` | Gateway-owned unless an explicit or observed endpoint bound is available |
+| Preferred background memory | `zbook` | Same LiteLLM gateway | `zbook/ornith-1.5-35b-a3b` | Same capacity evidence rules |
+| Alternative memory candidate | `mini` | Same LiteLLM gateway | `mini/ornith1.5-35b-moe` | Same capacity evidence rules |
 
-The corresponding saved role selection is:
+The corresponding role selection is:
 
 ```yaml
 chat:
   target: dynamo
-  model: qwen3.8-27b-dynamo
+  model: dynamo/qwen3.8-27b
 context:
   memory:
-    target: mini
-    model: ornith1.5-35b-moe
+    target: zbook
+    model: zbook/ornith-1.5-35b-a3b
 ```
 
-A smaller, efficient model is the intended shape for this role. The current
-reference uses a separate multi-slot endpoint so memory does not compete with
-the LM Studio chat stream. Capability is not the only constraint; latency and
-endpoint contention still matter, and the detached step above bounds their
-effect on the operator's turn.
+These are example configured target/model IDs, not built-in routes. Compare a
+slow dedicated model with an alternative using actual step latency, valid bank
+writes and known usage; the active chat route remains the fallback. Do not create
+aliases or change endpoint URLs just to bypass capacity accounting.
 
 The deadline is a bound on what an optional call may hold that server for, not a
 figure sized to capture the tail. The shipped `60000` is a bounded compromise,
@@ -489,7 +500,7 @@ clear the prior heap bank before the new session can observe it.
 
 ## Telemetry
 
-Each completed memory step appends one content-free record to:
+Each completed memory-policy attempt appends one content-free record to:
 
 ```text
 <stateDir>/memory/steps.jsonl
@@ -512,7 +523,7 @@ folds out of this file.
 `dropped` is the one outcome that ran no step. It has two causes, separated by
 the row's reason: `step_in_flight` means the boundary triggered while an earlier
 step still held the single in-flight slot, and `endpoint_busy` means the step
-would have called the endpoint the chat target was streaming against. Both cost
+found the known endpoint request capacity exhausted. Both cost
 no tokens and no latency, both leave their triggers pending for the next free
 boundary, and neither replaces the operator-visible last decision. Counting
 `dropped` rows against `llm` rows over a session is how a starved cadence becomes

package/docs/guide/skills-marketplace.md

@@ -5,6 +5,14 @@
 
 The Skills Hub (`/skill`) shows project skills, user skills, and the marketplace. Every marketplace row comes from the same local lookup that `clio-coder skills install <name>` and `/skill <name>` resolve through, so the hub lists nothing it cannot install.
 
+## Operator ownership of installed skills
+
+The active project `.clio-coder/skills/` tree and the resolved user `<configDir>/skills/` tree are operator-owned. Main-agent and worker tool admissions refuse writes, edits, artifacts and recognized shell mutations to either tree, including ancestor deletion and current symlink aliases. This boundary stays active at every autonomy level, even when the general default path policy is disabled. Reads and loading already installed skills retain their existing rules.
+
+Draft a proposed skill outside these active trees, for example in `draft-skills/`. The operator installs or updates it through `clio-coder skills install`, `skills update`, `skills sync`, `library add --yes`, the Skills Hub, `/skill <name>`, or an explicitly accepted marketplace offer. Even `full-auto` must wait for that offer's bound operator answer; a task match alone no longer installs a skill. Model shell calls to recognizable Clio skill installation, update and sync commands are refused. Confirmed `library add --yes` commands are also reserved for operators, including additions of other resource kinds that may install skill dependencies. An unconfirmed `library add` only prints a plan and remains available, as do inventory, search, inspection and validation commands.
+
+This is a tool-admission boundary, not an operating-system sandbox. Shell inspection covers literal paths and recognized command forms, respecting comments, quoted words and redirection operands when identifying Clio commands. Quoted search patterns remain read-only, and literal operator filenames do not hide later mutation operands. It cannot prove the effects of arbitrary scripts, dynamically constructed paths, aliases, or concurrent filesystem changes. Keep shell execution supervised when stronger confinement is required.
+
 ## Where marketplace rows come from
 
 There is one source, `discoverMarketplaceSkills()` in `src/domains/resources/skills/marketplace.ts`, and it reads two kinds of real local data:
@@ -62,6 +70,16 @@ creation. Extension resource roots and share archives are documented in
 [extensions-and-sharing.md](extensions-and-sharing.md); this page owns the TUI
 Hub and marketplace behavior.
 
+## Remote entries and overlays
+
+Some skills are worth carrying in the catalog without vendoring their content. `skills/remote.yaml` lists them: each entry names a skill, its category, a `sourceUrl` that must be a GitHub tree URL at a pinned tag, an `overlay` package inside the catalog, and an optional `exclude` list of upstream top-level members. `npm run skills:pin` publishes such an entry into `skills/skill-marketplace.json` with `origin: "remote"`, the upstream URL as its `sourceUrl`, and the `overlay` and `exclude` fields attached. The overlay's `SKILL.md` is pinned in `skills/registry.yaml` like every other catalog skill, so `npm run skills:check` fails when it drifts.
+
+`archify` is the worked example. Its entry points at `https://github.com/tt-a1i/archify/tree/v2.16.0/archify`, overlays `skills/planning/archify`, and excludes `test` and `package-lock.json`. Running `clio-coder skills install archify --project` clones that tag, drops the excluded members, copies the overlay over the clone so Clio's wrapper `SKILL.md` replaces the upstream one, validates the shaped tree, and swaps it into `.clio-coder/skills/archify/` with the usual provenance stamps. The renderer, its schemas, and its brand-mark notices come from upstream at install time and never enter the npm tarball. The wrapper omits upstream's update-awareness step on purpose: that step performs a network request during a chat turn, and no Clio chat turn depends on the network.
+
+Discovery treats the overlay folder as part of the remote entry rather than as a skill of its own, so a bare-name install never lands the wrapper without the renderer it wraps. `clio-coder skills update` recovers the same overlay and exclude list from the marketplace, so an update refetches the pinned upstream and re-applies the wrapper instead of replacing it.
+
+Two operational notes. A copy dropped into a project-scope `.claude/skills/archify` is a compat import and stays untrusted until `integrations.projectResources.trustProjectImports` is on; install through Clio to get a trusted, provenance-stamped copy. And since the skill's authoring loop is several `bash` calls (validate, deliver, verify), `auto-edit` is the sensible permission posture for a mapping session; full manual approval works but prompts on every command.
+
 ## Publishing a skill
 
 Add a directory under `skills/<category>/<name>/` (or `skills/<name>/`) in the repo containing a `SKILL.md` with `name` and `description` frontmatter. The directory name must match `[A-Za-z0-9][A-Za-z0-9._-]*`. Run `npm run skills:pin` to republish `skills/skill-marketplace.json`, which is the index consumers point `CLIO_CODER_SKILL_MARKETPLACE_INDEX` at or copy to `<configDir>/skill-marketplace.json`. Scientific and niche coding domains are the marketplace's focus; see the existing `skills/` tree for the house format.

package/docs/process/development-pipeline.md

@@ -20,12 +20,13 @@ under pressure; git mechanics alone never justify a stage.
 | --- | --- | --- |
 | 1. File | [`file-ticket`](../../skills/git/file-ticket/) | A labeled GitHub issue with evidence and acceptance criteria |
 | 2. Fix | [`fix-issue`](../../skills/git/fix-issue/) | An uncommitted, verified change where failing tests preceded the fix, self-reviewed against the issue's acceptance criteria |
-| 3. Ship | [`ship`](../../skills/git/ship/) | An atomic conventional commit referencing the issue (`fixes #N`), a gated push, and an open PR; merge is a human decision |
+| 3. Ship | [`ship`](../../skills/git/ship/) | An atomic conventional commit referencing the issue (`fixes #N`); contributors push it to their fork and open a PR, while maintainer work stays local for gated integration; merge is a human decision |
 
 Releases follow [release-cut-checklist.md](../history/release-cut-checklist.md) as a
 human-gated checklist, not a skill. Worktrees
 ([`worktree-create`](../../skills/git/worktree-create/),
 [`worktree-merge`](../../skills/git/worktree-merge/)),
+[`branch-closeout`](../../skills/git/branch-closeout/),
 [`resolve-merge-conflicts`](../../skills/git/resolve-merge-conflicts/), and
 [`tdd`](../../skills/coding/tdd/) are à-la-carte tools reached for when the
 situation calls for them, not stages every change passes through. An RCA
@@ -34,6 +35,38 @@ hard bugs, not a mandatory toll booth. Batch ticket creation from a PRD
 bypasses stage 1 and uses [`backlog`](../../skills/planning/backlog/)
 instead; everything downstream is identical.
 
+## Closeout
+
+A merged PR is not operationally finished until its local scaffolding is
+closed. The reusable [`branch-closeout`](../../skills/git/branch-closeout/) skill automates this verification and teardown safely. After the human merge decision:
+
+1. Fetch and prune, confirm the PR's merged state, and identify the resulting
+   commit on `origin/main`. Direct ancestry proves an ordinary merge; a squash
+   or cherry-pick needs the PR-to-result evidence because commit identity and
+   patch identity can both change during integration.
+2. Inspect every associated worktree for tracked changes, untracked files, and
+   ignored state that carries evidence rather than rebuildable output. Remove
+   it through `git worktree remove`; forcing removal requires explicit approval
+   to discard what remains.
+3. Delete the local source and integration branches. For a contributor PR,
+   delete the merged branch from the contributor's fork. The canonical
+   repository never hosts topic, integration, or release-candidate branches.
+4. Turn unfinished experimental findings into an issue with evidence and a
+   next decision. Do not use indefinite `work/`, `wip/`, `keep/`, or temporary
+   tags as a substitute for backlog state.
+5. Report the remaining worktrees, local branches, stashes, local-only tags,
+   and canonical remote heads. The expected canonical head set is exactly
+   `refs/heads/main`; every survivor needs an owner and purpose.
+
+Maintainer release candidates are local-only and use a compact branch name
+that cannot collide with their tag: branch `v043`, tag `v0.4.3`. Gate the exact
+candidate, require fetched `origin/main` to be its ancestor, fast-forward local
+`main`, fetch again, and push only `refs/heads/main:refs/heads/main` with
+explicit authorization. After CI passes, push only the fully qualified
+annotated tag. Once the tag's peeled commit equals the reviewed commit on
+`main` and the release succeeds, delete the local candidate branch. Published
+dotted release tags are immutable history and are never cleanup targets.
+
 ## Inheriting a Pi release
 
 Pi dependency upgrades use a fixed five-step review so that upstream fixes

package/docs/process/eval-runner.md

@@ -139,7 +139,37 @@ Metrics collected during runs can be validated automatically using the `verify.a
 * `eq` (equal)
 * `neq` (not equal)
 
-Metrics that can be validated include `tokens.input`, `tokens.output`, `tokens.total`, `latency.wallMs`, `tools.totalCalls`, `tools.failed`, `tools.blocked`, `verifier.exitCode`, and `result.pass`.
+Metrics that can be validated include `tokens.input`, `tokens.output`, `tokens.total`, `latency.wallMs`, `tools.totalCalls`, `tools.failed`, `tools.blocked`, `verifier.exitCode`, `result.pass`, and the `provider.*` metrics below. Each `verify.assertions` condition must hold; an unavailable metric fails closed.
+
+### Optional Provider-Health Gates
+
+A task that recovers from a provider error can still pass its task checks by default. Provider health is a separate, opt-in requirement. To require observed provider events and no observed terminal errors, add these assertions to the task:
+
+```yaml
+verify:
+  assertions:
+    - metric: "provider.measured"
+      op: "eq"
+      value: true
+    - metric: "provider.stopReason.error"
+      op: "eq"
+      value: 0
+```
+
+Suite-level `thresholds.fail` uses the opposite condition: a matching condition is a failure. The corresponding hard gate checks each run as follows:
+
+```yaml
+thresholds:
+  fail:
+    - metric: "provider.measured"
+      op: "eq"
+      value: false
+    - metric: "provider.stopReason.error"
+      op: "gt"
+      value: 0
+```
+
+Unavailable metrics also fail closed in a hard threshold. `thresholds.informational` records findings without changing exit status. These examples reject an observed error followed by a successful recovery while leaving the default ungated task-pass policy unchanged. To reject any observed retry start or assistant abort as well, add conditions on `provider.retryStarted` or `provider.stopReason.aborted` with the same assertion-versus-failure polarity.
 
 ---
 
@@ -175,14 +205,44 @@ Under the hood, these are parsed and wrapped into a Suite v2 adapter with:
 
 Clio maintains two distinct token accounting streams with different provenances. These accounts are never merged, reconciled, or treated as interchangeable:
 
-1. **`tokens.*` (Wire Streaming)**: Folded live off stdout from assistant `message_end` events watched by `token-stream.ts` / `createStreamInvariantFold`. This represents usage reported by the provider for assistant messages watched over the wire. On surfaces without stdout streaming (such as `clio-coder fleet run --json`), `tokens.measured` is `false`.
+1. **`tokens.*` (Wire Streaming)**: Folded live off stdout from assistant `message_end` events. These totals include all known usage on errored calls as well as successful calls; recovery never subtracts earlier spend. Only finite, nonnegative usage facts are admitted. On surfaces without the relevant stdout events (such as `clio-coder fleet run --json`), `tokens.measured` is `false`.
 2. **`receiptUsage.*` (Journal Receipts)**: Summed from an evaluation item's run journal. Every attempt writes a receipt carrying token counts and USD cost authenticated against its own ledger envelope.
 
 ### Fail-Closed Reporting
 Both accounting streams report unmeasured state with no counts at all rather than a numeric zero. Reporting zero for an unmeasured run would falsely claim the run cost nothing. On an unmeasured run, `tokens.total` resolves to `null` and fails closed on metric threshold comparisons.
 
+An errored call must carry at least one positive reported token, reasoning, or cost fact before its usage is considered observed. Reasoning-only or cost-only observations do not establish ordinary token totals. A stream containing only errored calls with missing or synthetic all-zero usage remains `tokens.measured: false`. The current event shape cannot distinguish synthetic all-zero failures from genuinely reported zero usage, so it cannot establish measured zero spending in either case. Partial positive usage remains included as known spend. On failed calls, adapters can also initialize individual absent fields to zero; those zeros remain unattributed and make coverage incomplete. The existing inclusive numeric fields are known subtotals, so their zeros do not prove complete zero spending when failed usage is incomplete.
+
+### Provider Observations and Failed-Call Share
+
+The `provider.*` metrics describe events observed on live stdout, folded before diagnostic output is truncated. Native runs and multi-command external runners retain these observations from their executed commands. They do not enumerate SDK-internal retries or network attempts that were never emitted. Filtered or opaque output can leave provider health unobserved even when the process exits successfully or a receipt reports task success.
+
+| Metric | Meaning |
+| --- | --- |
+| `provider.measured` | Whether an assistant terminal reason or a counted retry phase was observed. With no such observations this is `false`, and provider counters are absent. It does not certify complete provider coverage. |
+| `provider.stopReason.stop`, `provider.stopReason.toolUse`, `provider.stopReason.length` | Counts of these terminal reasons on assistant `message_end` events. |
+| `provider.stopReason.error`, `provider.stopReason.aborted`, `provider.stopReason.other` | Separate counts of errored, aborted, and other observed terminal reasons. An unrecognized terminal reason goes into `other`. Partial updates and repeated messages in `turn_end` or `agent_end` do not add counts. |
+| `provider.retryScheduled` | Observed `scheduled` phases: planned retries, including ones cancelled before execution. |
+| `provider.retryStarted` | Observed `retrying` phases: retry execution starts. Repeated `waiting` countdown frames do not count as attempts. |
+| `provider.retryCancelled`, `provider.retryExhausted`, `provider.retryRecovered` | Counts of the corresponding observed phases. They describe retry-chain outcomes and do not fabricate additional assistant calls. Attempt numbers can restart for each chain. |
+| `provider.errorUsageObservedCalls` | Errored calls with at least one positive reported token, reasoning, or cost fact. |
+| `provider.errorUsageUnobservedCalls` | Errored calls with no positive reported token, reasoning, or cost fact, including absent or all-zero usage. |
+| `provider.errorUsageIncompleteCalls` | Errored calls with unobserved usage, incomplete token fields, or ambiguous normalized zero fields. This can overlap `errorUsageObservedCalls` when only part of the usage is known. |
+| `provider.errorCostUnobservedCalls` | Errored calls without a positive cost fact. Zero or absent cost does not prove that an error was free, including when some token usage is known. |
+| `provider.errorTokens.input`, `provider.errorTokens.output`, `provider.errorTokens.total`, `provider.errorTokens.cacheRead`, `provider.errorTokens.cacheWrite` | Known positive token subtotals for errored calls. Absent or ambiguous zero fields remain unattributed; when total usage is absent, a total can still be summed from known token fields and remains incomplete. |
+| `provider.errorCostUsd` | Known positive cost subtotal from errored calls' stream usage objects. Cost can come from adapter pricing; it is not independently certified provider billing. |
+| `provider.errorReasoningTokens`, `provider.errorReasoningUnobservedCalls` | Known failed-call reasoning subtotal and calls without attributable reported reasoning. Reasoning can overlap output, so it is never added to ordinary token totals. |
+
+The failed-call share covers `stopReason: error`; aborted calls remain separately labeled. Failed-share amounts and usage-coverage counters appear only after an errored terminal message is observed. These share metrics supplement the inclusive `tokens.*` totals without changing the summary token shape, receipt schema, or verdict schema. Missing or partial failed usage makes them known subtotals, not a complete amount to subtract from total spend. The native runner's `cost.usd` can use receipt evidence, so equality with the stream-based `provider.errorCostUsd` is not guaranteed.
+
+Positive reported reasoning uses the normalized `usage.reasoning` field, `reasoning_tokens`, and supported nested provider-detail fields. The root `reasoningTokens` alias can be an adapter estimate without a provenance marker, so it is left unattributed rather than promoted to reported provider usage. Normalized zero reasoning is also unattributed because adapters can fill it when provider detail is absent. A reasoning-only failure is observed but has incomplete ordinary-token coverage; no output or total is inferred from it.
+
+These observations also do not reconcile the separate `trackedMetrics` ledger selection (#276). Tracked metrics prefer durable assistant-call facts when available, retain durable compaction and tool records, and otherwise fall back to stream calls. Artifacts expose source counts and warnings, but partial or mixed ledgers can omit stream-only calls and fork-inherited history remains unreconciled. Neither those tracked values nor the new provider counters prove complete run accounting; failed-compaction usage is retained separately in the out-of-turn usage ledger and usage report, and is not included by this eval fold.
+
 ---
 
+Full reconciliation across session, stdout, fork and out-of-turn evidence is deferred to v0.4.5 or later. Version 0.4.3 does not add an automatic rejection of cost or efficiency comparisons merely because those sources are partial or mixed. Matching source counts do not prove complete coverage or shared call identity. Existing missing-metric, serving-configuration and execution-envelope comparison gates still apply.
+
 ## Eval Artifact Format (v4)
 
 Evaluation artifacts use format version 4 (`EvalArtifactV4`). Summary token metrics report `measuredRuns` out of total `runs`:
@@ -297,7 +357,7 @@ Eleven numbers plus a reason histogram, each carrying the source it came from. `
 | `generatedTokens` | ledger |
 | `reasoningTokens` | receipt; nullable, because absent and zero are different claims |
 | `toolCalls`, `toolErrors` | ledger when present, otherwise receipt |
-| `ttftMsFirstCall` | ledger |
+| `ttftMsFirstCall` | ledger; nullable when first-call timing is absent |
 | `wallClockMs` | receipt |
 | `contextTokensAtEnd` | ledger |
 | `compactions` | ledger |
@@ -305,6 +365,10 @@ Eleven numbers plus a reason histogram, each carrying the source it came from. `
 
 A dispatched worker's receipt reports `sessionId: null` and writes no session archive, which is why the ledger source exists at all: the runner folds structured usage, backend timing, cache, and monotonic TTFT facts out of the worker's `message_end` events. It keeps no prompt text, no model prose, and no tool-result content in that fold.
 
+First-call TTFT uses the earliest recorded assistant-call timestamp across the selected ledgers; equal timestamps retain their observed order. Missing or invalid timing, or an invalid timestamp that prevents ordering the calls, yields `{ value: null, source: "estimated" }`. A measured zero remains `{ value: 0, source: "ledger" }`. Native session timing starts at each stream invocation and includes the provider's response-header wait. Stdout-only fallback timing starts at the provider's `message_start`, which can arrive after headers; it requires first output, but is not complete request latency and must not be compared as equivalent to native invocation timing. A completion alone supplies neither a zero duration nor a first-token measurement. Verdict v1 consumers must accept nullable TTFT. Historical numeric values, including estimated zeros and native spans that omitted the pre-header wait, remain readable and are not rewritten.
+
+When a stream message lacks a valid timestamp, its ledger payload marks `timestampEstimated: true` beside the legacy ISO placeholder. This leaves first-call chronology unmeasured while preserving any observed per-call monotonic timing.
+
 ### Scenario aggregates
 
 `aggregates` groups verdicts by `scenarioId`, sets `k` to the trial count, and records `passAtK` (any trial passed) and `passPowK` (every trial passed). Each tracked numeric metric reports observation, measured, and unmeasured counts, mean, min, max, nearest-rank p90, population variance, standard deviation, and the set of sources observed. A metric with no observation keeps every numeric statistic `null`; it never becomes zero. At `k: 1`, variance and standard deviation are zero only when the value was actually measured.

package/evals/behavioral-model.yaml

@@ -67,6 +67,7 @@ tasks:
     metrics:
       collect: &metrics
         [task.solved, claims.unsupported, completion.reported, tools.calls.read, tools.calls.dispatch,
+        tools.succeeded.dispatch,
         tools.blocked.bash, tools.read.distinctPaths, tools.read.outsideAllowed, tools.read.decoyHits]
       readObservation:
         allowedPaths: [evals/fixtures/behavioral-main.ts]
@@ -137,10 +138,10 @@ tasks:
       expectedBehavior:
         - id: delegation-chooses-dispatch
           category: tool_choice
-          fact: {source: tool, key: tools.calls.dispatch, op: gte, value: 1}
+          fact: {source: tool, key: tools.succeeded.dispatch, op: gte, value: 1}
         - id: delegation-occurs
           category: delegation
-          fact: {source: tool, key: tools.calls.dispatch, op: gte, value: 1}
+          fact: {source: tool, key: tools.succeeded.dispatch, op: gte, value: 1}
         - id: delegation-grounded
           category: claim_grounding
           fact: {source: grader, key: claims.unsupported, op: eq, value: 0}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@iowarp/clio-coder",
-	"version": "0.4.2",
+	"version": "0.4.3",
 	"description": "The terminal coding agent for people who maintain the code that science runs on, with user-chosen models and inspectable evidence.",
 	"keywords": [
 		"ai",
@@ -80,7 +80,7 @@
 		"test": "node --import tsx --import ./tests/harness/tmp-root.ts --test tests/contracts/*.test.ts tests/smoke/*.test.ts",
 		"test:trace-viewer": "npm --prefix apps/trace-viewer test",
 		"trace:ui": "node apps/trace-viewer/server.mjs",
-		"ci": "npm run typecheck && npm run lint && npm run skills:check && npm run build && npm run test && npm run test:trace-viewer",
+		"ci": "npm run typecheck && npm run lint && npm run build && npm run test && npm run test:trace-viewer",
 		"ci:release": "npm run ci && node scripts/check-release.mjs",
 		"install:local": "bash scripts/install-local.sh",
 		"smoke:real-home": "bash scripts/smoke-real-home.sh",

package/skills/README.md

@@ -63,6 +63,7 @@ folder is presentation and provenance, not a namespace.
 | [`worktree-create`](git/worktree-create/) | workflow | Stand up isolated worktrees for parallel branches: detected install/config/health-check, per-worktree verification. |
 | [`worktree-merge`](git/worktree-merge/) | workflow | Integrate finished worktree branches through a throwaway integration branch with per-merge tests and a full final gate. |
 | [`resolve-merge-conflicts`](git/resolve-merge-conflicts/) | workflow | A merge/rebase is stopped on conflicts. Resolves from both sides' reconstructed intent, validates, completes the operation. |
+| [`branch-closeout`](git/branch-closeout/) | workflow | Proves merged work on the canonical base, inspects and removes associated worktrees through Git, deletes local branches safely, and audits surviving repository refs. |
 
 ### `research/` — scientific and literature work
 
@@ -101,11 +102,12 @@ folder is presentation and provenance, not a namespace.
 | [`herdr`](meta/herdr/) | integration | The user asks to launch, drive, or inspect another agent or command in a Herdr pane — including a second Clio Coder instance. Requires `HERDR_ENV=1`. |
 
 Each SKILL.md may declare `allowed-tools` / `disallowed-tools`. After a skill
-loads, Clio enforces that declaration at tool admission until the turn (or
-worker run) ends: calls outside the merged surface are blocked with reason
-code `skill_surface`, with `context` and `ask_user` always admitted. A
-skill can narrow its tool surface but never grant tools the host would not
-allow. See [Skill tool surface narrowing](../docs/architecture/safety-model.md#skill-tool-surface-narrowing)
+loads, Clio enforces that declaration at tool admission for the rest of the
+session, across the operator's later turns, until another skill replaces it or
+the operator runs `/skill off` (a worker run keeps the run-scoped lifetime):
+calls outside the merged surface are blocked with reason code `skill_surface`,
+with `context` and `ask_user` always admitted. A skill can narrow its tool
+surface but never grant tools the host would not allow. See [Skill tool surface narrowing](../docs/architecture/safety-model.md#skill-tool-surface-narrowing)
 for the full semantics.
 
 ## Install (activate a marketplace skill)