@bjoernrochel/sevro 0.1.0-rc.7 → 1.0.0

package/docs/codex-host.md

@@ -20,21 +20,13 @@ The bounded JSONL stream is retained per trial as the private
 `sevro.codex.events` host artifact. Its file URL and digest appear in trial
 evidence and are available to extension grading; the stream bytes stay out of
 the run JSON.
-The host also retains a bounded `sevro.codex.skill-reads` observation. It
-records the first verified mounted skill and ordered skill names, without
-commands or skill bodies. A completed direct `cat` of one mounted `SKILL.md`,
-alone or alongside literal documentation paths, counts only when the command
-output contains that file's exact body. Batched reads naming multiple
-`SKILL.md` files or more than 64 paths remain partial. Direct
-`sed -n` pages count after their verified line ranges cover the whole body. An
-exact `cat` wrapped by `lean-ctx -c` is accepted only when its reported output
-still contains the full body; a compressed summary cannot prove the read. An
-attempted indirect, malformed, or incomplete read makes the observation
-partial. This is a host observation; an extension decides what selection means
-for its case.
-The same check accepts skill files below the exact installed plugin roots from
-Codex's installation receipts. It does not infer activation from arbitrary
-files in the private plugin cache.
+Skill activation uses the common `sevro.host.skill-activations` observation
+from passive hooks in the request's private Codex home. The collector matches
+prepared skill bodies in returned tool content without interpreting shell
+syntax or recovering command output from native sessions. See
+[skill activation evidence](native-hosts.md#skill-activation-evidence) for the
+scope, limits, privacy boundaries, and incomplete collection states.
+
 The `sevro.codex.native-calls` capability retains allowlisted direct goal and
 agent control calls from the native session bound to the completed thread. Its
 observation contains only call names, namespaces, and source ordinals, plus the
@@ -59,33 +51,10 @@ only when plaintext is readable. It retains neither message nor prompt bytes.
 For a second prompt, `sevro.codex.continuation` retains the last validated
 native-session ordinal before resume. Extensions can compare later call
 ordinals with that boundary without reading private arguments.
-The host also retains separate `sevro.codex.initial-skill-reads` and
-`sevro.codex.follow-up-skill-reads` observations. Each applies the same exact
-mounted-skill read check to one completed turn, so an extension can grade read
-order or a missing repeat read without inferring it from the combined list.
-
-It also checks native parent command records for exact mounted skill bodies,
-including sessions with no spawn request. The bounded diagnostic distinguishes
-no read from an incomplete read without claiming skill activation.
-It retains the skill name and native ordinal when verified reads complete a
-whole body. Repeated complete reads produce separate receipts; paged reads
-produce one receipt when their ranges first cover the body. An incomplete
-later reread makes the diagnostic partial. Extensions can compare these
-ordinals with an accepted owner boundary without retaining commands or output.
-Earlier yielded output can complete a read only when its process and unique
-call identity bind it to that actor's native command completion. Completed
-literal command calls use a bounded TypeScript parser; conditional or ambiguous
-code cannot establish that binding. Recovery verifies the exact mounted bytes
-and recomputes completeness for the matching CLI command. Private commands,
-submitted code and recovered skill bodies stay out of public observations.
-For accepted spawns, it also checks up to eight child thread rollouts and
+For accepted spawns, the host checks up to eight child thread rollouts and
 reports whether each is available, unavailable, ambiguous, or partial, with an
-explicit truncation flag. An available rollout includes bounded diagnostics for
-native child commands: the number of commands and skill read attempts, whether
-the exact mounted `SKILL.md` body was read, and whether the check was complete
-or truncated. A rollout with no read differs from a missing or malformed
-rollout. These diagnostics do not establish skill activation or task completion
-by themselves and retain no child prompt, command, or output.
+explicit truncation flag. Child rollout metadata describes delegation and
+completion; skill activation remains in the common hook observation.
 An available child rollout also reports whether one nonempty final assistant
 message matches a later native completion event for the same turn. This proves
 a returned turn, not the accuracy of the child's work, and retains no message
@@ -101,12 +70,18 @@ discarded. Extensions interpret task names and decide whether a nested reader
 satisfies their policy.
 The record proves an invocation attempt, not its success. A missing, ambiguous,
 unreadable, oversized, or malformed session is unavailable or partial, so its
-absence cannot prove that a control was unused. Calls made through submitted
-code are not classified by this first observation.
+absence cannot prove that a control was unused. Code Mode submissions now have
+separate bounded `execCalls` inspection receipts, described in the
+[native control contract](native-controls.md). Direct native call ordinals and
+acceptance receipts keep their original meaning; submitted requests do not
+acquire direct native acceptance receipts.
 For an explicitly declared `$plugin:skill`, the host verifies that the installed
 skill exists and that the exact token occurs once in the delivered prompt. A
-completed turn yields `sevro.codex.explicit-invocation` with the owner first and
-verified supporting reads after it. Incomplete reads make that receipt partial.
+completed turn yields a complete `sevro.codex.explicit-invocation` naming the
+dispatched skill. This receipt proves verified dispatch and contains no
+`observedSkills` list. Activation checks require the common hook observation;
+missing hook evidence cannot be repaired by a dispatch receipt or native
+transcript. Failed execution cannot yield a complete dispatch receipt.
 The `sevro.codex.repository-invocation` capability supports an explicitly
 declared `$skill` from `.agents/skills/<skill>/SKILL.md`. The host checks that
 the repository mount is a bounded regular file with no symlink components and
@@ -122,7 +97,11 @@ symlinks, and installs it with `codex plugin marketplace add` followed by
 `codex plugin add`. It checks each installation receipt against the private
 plugin cache. Candidate commands can read that cache, while the rest of the
 private Codex home, including authentication and configuration, remains denied.
-It refuses fixture-local `.codex` configuration, unsupported enforced
+With the [Codex state opt-in](runtime-v1.md#candidate-codex-configuration-and-user-skills),
+commands may read generated configuration and write actual non-system user skills;
+graders retain read-only access to that request's original paths. Fixture-local
+configuration is accepted as inert represented input on this route. Otherwise,
+the host refuses fixture-local `.codex` configuration. It also refuses unsupported enforced
 conditions, unreadable or oversized auth files, malformed event streams, and
 incomplete turns. The host bounds output and runtime, kills its process group
 on timeout or cancellation, and removes private state after the turn. It is
@@ -144,14 +123,18 @@ explicit workspace rule, denies all other filesystem roots except minimal
 runtime files and the selected executable's install directories, and
 specifically denies protected roots and the private Codex home. An executable
 inside a protected root is rejected. The profile also disables command
-network access and clears inherited command environment variables. The Codex
+network access by default and clears inherited command environment variables.
+The runtime [local HTTP option](runtime-v1.md#local-http-test-servers) enables
+Codex's managed network proxy and local binding for socket-using tests.
+The Codex
 parent can read authentication before it starts sandboxed commands. Tests
 invoke the installed `codex sandbox` CLI to prove fixture access, denied
 source/auth reads, and executable access. The process adapter verifies these
 properties in one sandbox invocation before each fresh host request, with a
 60-second bounded startup deadline. The combined probe still requires readable
 private command storage, denied project listing, denied authentication and
-configuration reads, and a successful native executable `--version`. Continuation
+configuration reads (unless configuration access was explicitly enabled), and a
+successful native executable `--version`. Continuation
 turns reuse the same isolated state. The longer deadline accommodates observed
 native policy startup; it is not counted as a performance saving.
 
@@ -162,12 +145,135 @@ wrappers additionally embed that request's runtime, sandbox profile, and receipt
 paths. Replaying an old installation receipt cannot establish a new installed
 path. Sevro therefore retains native marketplace/plugin installation and receipt
 verification, fresh credentials/configuration, hook rewriting, preflight, and
-invocation evidence for every request. See the [startup measurements](evidence/runtime-startup-30/README.md)
+invocation evidence for every request. See the [startup measurements](https://github.com/BjRo/sevro/blob/main/docs/evidence/runtime-startup-30/README.md)
 for measured boundaries, copy-on-write assessment, and limitations.
 
+## Retired skill-read evidence
+
+The current host no longer emits `sevro.codex.skill-reads`,
+`sevro.codex.initial-skill-reads`, `sevro.codex.follow-up-skill-reads`, or native
+parent/child read diagnostics. Migrate activation checks to
+`sevro.host.skill-activations`; old required evidence remains unavailable rather
+than silently receiving a different meaning. Existing retained run evidence
+keeps its original interpretation.
+
+[Issue #70 representative retests](https://github.com/BjRo/sevro/blob/main/docs/evidence/skill-reads-70/results.json) retain
+separate task, activation, and phase-read outcomes from the private candidate,
+plus its source fingerprints and test-first regression results. Private native
+transcripts remain outside the repository.
+
+<details>
+<summary>Historical command-pattern and read-recovery contract</summary>
+
+The following describes the retired collector before the hook migration.
+These rules are preserved for interpreting older evidence; they do not describe
+the current host.
+
+The host also retains a bounded `sevro.codex.skill-reads` observation. It
+records the first verified mounted skill and ordered skill names, without
+commands or skill bodies. A `cat` or `sed -n` attempt counts only when its path
+resolves to a mounted skill or a skill below an installed plugin root verified
+by Codex's installation receipt. Missing targets outside a mounted skill
+directory, listings, and other harmless mentions of `SKILL.md` do not make the
+observation partial. A missing `SKILL.md` target does not count as a read just
+because its parent directory belongs to a mounted skill; an existing mounted
+target that fails or produces incomplete bytes remains partial. A completed direct
+`cat` of one mounted `SKILL.md`, alone or alongside literal documentation
+paths, counts only when the command output contains that file's exact body.
+Batched reads naming more than 64 paths remain partial, as do failed,
+malformed, or incomplete recognized reads. Direct
+`sed -n` pages count after their verified line ranges cover the whole body. An
+exact `cat` wrapped by `lean-ctx -c` is accepted only when its reported output
+still contains the full body; a compressed summary cannot prove the read.
+The same exact-body check accepts a literal read followed by one literal `rg`
+command, separated by a semicolon or newline. It also accepts a single-file
+literal `cat` of the skill followed by one or more literal `cat` reads of
+non-skill files, then one literal `rg` command, with the same separators. For
+example:
+
+```sh
+cat .agents/skills/darrow-guide/SKILL.md; cat docs/specs/repository-guide.md; rg -n -i 'offline|\bsla\b|service.level|guarantee|deployment' --glob '*.md' --glob '!docs/research/**' --glob '!**/SKILL.md' .
+```
+
+This sequence uses the shared stream and native read check. Quoted separators
+remain part of their literal operand. The ordered file bodies must match the
+retained output, so documentation or search output cannot replace an altered
+or incomplete skill read. Literal `cat` commands may read multiple mounted
+skills and documentation, before or after skills, with or without a terminal
+search. Multiple literal terminal `rg` commands are accepted within the command
+bound. Each verified skill receives its own ordered receipt. Documentation
+must resolve within the workspace or a receipt-bound installed plugin root;
+each file is bounded to 1 MiB. Aliases of mounted skills without a literal
+`SKILL.md` operand remain unsupported.
+The 64-operand bound applies across all reads in the sequence. Shell expansions,
+including unquoted glob and tilde operands, are unsupported in this form.
+
+The bounded composed-read grammar also accepts `unset` with literal variable
+names, `pwd` or `pwd -P`, `git rev-parse --show-toplevel` (optionally with
+`-C "$PWD"`), `printenv` with literal variable names, and `rg --files` with
+literal arguments before the reads. Prefix `printenv` requires the reads to
+end the command, so environment output cannot replace missing read bytes.
+Literal `printenv` commands may follow reads without prefix `printenv`.
+The fixed pair `repo=$(git -C "$PWD" rev-parse --show-toplevel)` and
+`cd "$repo" && pwd -P` is supported only with absolute read operands. Other
+assignments, substitutions, directory changes, or control flow remain
+unsupported. Prefix and environment output cannot supply skill frontmatter;
+ambiguous repeated output cannot establish an attributable read.
+
+The check also accepts a chain of literal
+`cat` fallbacks with `2>/dev/null` and `||`, ending in `true` followed by a newline
+and one literal `rg` discovery command. A fallback chain must resolve to one
+canonical file across all its read operands; absent alternate targets do not
+invalidate the read. Each fallback `cat` names one literal file. Multiple
+existing targets, including unmounted copies,
+cannot establish an attributable read. The total read operands remain bounded
+at 64. The complete command must succeed and expose the mounted file's entire
+exact body. `cat` accepts literal file operands and the optional `--` delimiter;
+other options cannot prove an unchanged read. Substitutions, pipelines, other shell control flow, and dynamic
+search arguments cannot establish a compound read through this check.
+Unrecognized commands remain partial when their output contains the identifying
+`name: <skill>` line from a mounted or receipt-bound installed-plugin skill.
+This is a host observation; an extension decides what selection means for its
+case.
+The same check accepts skill files below the exact installed plugin roots from
+Codex's installation receipts. It does not infer activation from arbitrary
+files in the private plugin cache.
+The host also retains separate `sevro.codex.initial-skill-reads` and
+`sevro.codex.follow-up-skill-reads` observations. Each applies the same exact
+mounted-skill read check to one completed turn, so an extension can grade read
+order or a missing repeat read without inferring it from the combined list.
+For `app-server`, the verified same-thread feedback boundary separates the
+initial phase from the follow-up phase, including subsequent native goal turns.
+Absent, duplicated, foreign-thread, or failed boundaries do not yield phase
+receipts.
+
+It also checks native parent command records for exact mounted skill bodies,
+including sessions with no spawn request. The bounded diagnostic distinguishes
+no read from an incomplete read without claiming skill activation.
+It retains the skill name and native ordinal when verified reads complete a
+whole body. Repeated complete reads produce separate receipts; paged reads
+produce one receipt when their ranges first cover the body. An incomplete
+later reread makes the diagnostic partial. Extensions can compare these
+ordinals with an accepted owner boundary without retaining commands or output.
+Earlier yielded output can complete a read only when its process and unique
+call identity bind it to that actor's native command completion. Completed
+literal command calls use a bounded TypeScript parser; conditional or ambiguous
+code cannot establish that binding. Recovery verifies the exact mounted bytes
+and recomputes completeness for the matching CLI command. Private commands,
+submitted code and recovered skill bodies stay out of public observations.
+For accepted spawns, it also checks up to eight child thread rollouts and
+reports whether each is available, unavailable, ambiguous, or partial, with an
+explicit truncation flag. An available rollout includes bounded diagnostics for
+native child commands: the number of commands and skill read attempts, whether
+the exact mounted `SKILL.md` body was read, and whether the check was complete
+or truncated. A rollout with no read differs from a missing or malformed
+rollout. These diagnostics do not establish skill activation or task completion
+by themselves and retain no child prompt, command, or output.
 Native read diagnostics retain at most 64 `recoverySources` entries. Each
 records its native ordinal, whether the native completion had output, the
 yielded chunk count, and separate `completedCall` and `literalCommandCall`
 flags. These facts distinguish recovery sources without retaining commands,
 submitted code, or skill bodies. The diagnostic's completeness and truncation
 fields still determine whether its read evidence can support grading.
+
+</details>

package/docs/contracts.md

@@ -7,6 +7,7 @@ Read these human contracts and their schemas together:
 - [Report v1](report-v1.md): summaries and comparison limitations.
 - [Identity v1](identity-v1.md): versioned comparison dimensions and hashing.
 - [Runtime configuration v1](runtime-v1.md): environment, tools, private state, goals, and hooks.
+- [Run settings v1](run-settings-v1.md): recurring evaluation selections and CLI overrides.
 - [Built-in graders v1](builtin-graders-v1.md): output, shell, Git HEAD, and semantic checks.
 - [Schemas](../schemas/): machine-readable public forms.
 
@@ -15,4 +16,4 @@ Read these human contracts and their schemas together:
 [TypeScript quality contract](typescript-quality.md) defines source inventories,
 development checks, and coverage policy.
 [Architecture](architecture.md) explains implementation context;
-[historical validation](evidence.md) records past observations. Return to the [hub](README.md).
+[historical validation](https://github.com/BjRo/sevro/blob/main/docs/evidence.md) records past observations. Return to the [hub](README.md).

package/docs/creating-cases.md

@@ -4,18 +4,25 @@ Start with a direct case for a prompt, fixture, and built-in success criteria.
 Copy [the basic graded case](../examples/basic/graded.json), give it a stable
 ID, and replace the prompt/check. Read [built-in graders](builtin-graders-v1.md)
 for regex, JSON, and bounded schema assertions. No criteria means `not_assessed`.
+For complete coding, repository-skill, runtime, semantic and extension projects,
+follow the [runnable recipes](recipes.md), including their deliberate failures.
 
 Run it with the [CLI](running-evaluations.md). Direct cases follow `ResolvedCase`
 in [the engine](../src/engine.ts). Fixtures can provide inline files, generated
 Git history, or a declared clean repository. The [CLI reference](development-cli.md)
 owns required source roots/maps; an arbitrary returned path does not grant access.
 
+Selecting `--project-root` identifies the project; it does not copy its contents
+into a participant fixture. Declare the files or repository source the participant
+should receive. The [run defaults reference](development-cli.md#run-defaults)
+explains how project identity, fixtures and CLI path resolution interact.
+
 ## Evaluate your repository skills
 
 Start with one representative task, your actual skill, and observable success
 criteria. This example evaluates a documentation guide's answer with Codex.
 Use [Sevro from `PATH`](installing.md#make-the-command-available).
-Live runs require the [native host prerequisites](native-hosts.md), macOS
+Live runs require the [native host prerequisites](native-hosts.md), supported
 isolation, an authenticated Codex installation, and your chosen model.
 They consume that account's model quota.
 
@@ -109,7 +116,7 @@ prepares skill mounts and interprets complete native host evidence. The
 [extension protocol](extension-protocol-v1.md) defines repository and plugin
 invocations; the checkout's [guide evals](guide-evaluation.md) demonstrate the
 approach. Check those capabilities against your exact installed release:
-this checkout contains [changes beyond published `rc.2`](installing.md#published-package-and-checkout).
+this checkout can contain [changes beyond its published version](installing.md#published-package-and-checkout).
 
 ## Reusable project policy
 

package/docs/development-cli.md

@@ -8,14 +8,107 @@ grading, evidence, and extension lifecycle.
 [versioned report contract](report-v1.md). It emits Markdown by default or
 `sevro.report.v1` with `--json`.
 
+`sevro prune` [removes older retained results](reading-results.md#prune-retained-results)
+and maintains the latest report index. Bare pruning keeps the newest ten results;
+`--keep`, `--older-than`, and `--latest` select explicit retention policies.
+
 Examples assume [Sevro and Bun are on `PATH`](installing.md#make-the-command-available).
 For a contributor checkout, use `bun src/cli.ts` in place of `sevro`.
 
+Use `sevro --help`, `sevro run --help`, `sevro report --help`, or
+`sevro prune --help` for examples,
+required options, and defaults without preparing a run. `sevro --version` prints
+the installed package version. Invocation and configuration diagnostics go to
+stderr in both output modes; `--json` keeps one `sevro.cli-result.v1` document
+on stdout. Invalid case diagnostics name the input file and offending field.
+
+<a id="run-defaults-in-this-checkout"></a>
+
+## Run defaults
+
+`sevro demo` owns a deterministic case, fixture and adapter. It needs no model
+credentials and immediately prints an assessed verdict plus an evidence path in
+`.sevro/results` beneath the invoking directory. Its temporary project and
+configuration are independent of the caller's files and runtime policy.
+
+An ordinary run needs a case source and candidate route. For example:
+
+```sh
+sevro run --case-file ./case.json --adapter-module ./host-adapter.ts
+```
+
+| Setting                                                     | Default                                                                                                                 |
+| ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| Condition                                                   | `passive`                                                                                                               |
+| Trial count                                                 | `1`                                                                                                                     |
+| Pass threshold                                              | `1`: all assessed trials must pass; any unassessed trial prevents a pass                                                |
+| Parallel trial limit (`--jobs`)                             | `3`                                                                                                                     |
+| Project root                                                | Invoking current directory                                                                                              |
+| Results root                                                | `<project-root>/.sevro/results`                                                                                         |
+| Configuration root                                          | Project root                                                                                                            |
+| Run-state root                                              | Results root                                                                                                            |
+| Runtime policy                                              | Discover `sevro.json` at project root; none when absent                                                                 |
+| Native binary                                               | Resolve only the explicitly selected `codex` or `claude` from `PATH`; `--codex-bin` / `--claude-bin` override it        |
+| Native execution timeout                                    | `600000` ms (10 minutes); Codex accepts `--codex-timeout-ms`                                                            |
+| Codex entrypoint                                            | `exec`; a native-goal runtime policy selects `app-server`                                                               |
+| Codex agent concurrency                                     | `agents.max_concurrent_threads_per_session` from `.codex/config.toml` at configuration root, otherwise the host default |
+| Shell-check expected exit                                   | `0` unless the check declares `expectedExitCode`                                                                        |
+| Shell-check timeout                                         | `30000` ms unless the check declares `timeoutMs` (maximum `120000`)                                                     |
+| Shell isolation, dry preparation, host diagnostic retention | Off                                                                                                                     |
+
+Every run file/directory option accepts a relative path based on the invoking
+current directory, including adapter modules, extension source files, native
+binary overrides and protected roots. Sevro resolves them to canonical absolute
+paths before constructing protection lists; missing output-directory suffixes
+resolve through their nearest existing parent. A different `--project-root`
+does not change that base. The default results directory is relative to the
+selected project root. Paths inside runtime policy files retain their
+[runtime-specific resolution rules](runtime-v1.md).
+Extension command JSON still requires an absolute executable argv; arbitrary
+argv entries are not treated as CLI path options.
+
+Sevro prints a whitelist of effective run settings and routes on stderr before
+candidate execution, including resolved storage paths, native executables,
+timeouts and concurrency. JSON stdout remains one result document. The preview
+does not print credential bytes, runtime environment values or native diagnostics.
+The resolved executable is retained as `sevro.host.executable` in each used native
+role's redacted host configuration; selecting a different path changes that
+configuration's identity.
+
+Use `sevro init` with `--template response`, `coding` or
+`repository-skill` and `--directory <new-path>`. It refuses existing destinations
+and writes runnable assertions, a manifest and template instructions. Follow the
+[demo-to-iteration workflow](evaluation-workflow.md) for preparation, execution
+and negative controls. Repository-skill requires explicit native model, effort
+and authentication; dry preparation does not establish dispatch.
+
+Actual preparation, candidate, grading and evidence-retention stage events use
+stderr. Human completion includes each trial's separate states, failed-check
+reasons, measured candidate time, known/unknown usage and retained paths. JSON
+stdout remains one result. Each retained CLI run writes `result.json` beside run
+evidence and `<results-root>/latest.json`. `sevro report --latest` reads the current
+directory's default results root; add `--results-root <path>` for another root.
+Dry and failed runs can be latest.
+
+Project root identifies the evaluated project and extension discovery. It does
+not populate the participant workspace: declare inline files, generated history
+or a repository source in the case's fixture. See [case authoring](creating-cases.md).
+Keep `.sevro/` out of Git. Results and run-state paths are excluded from project
+snapshots and untracked Git identity; tracked source changes still count.
+
+## Explicit run settings
+
+To repeat these selections, use the versioned [saved run settings](run-settings-v1.md)
+with `--run-manifest-file ./evaluation.json`. Built-in defaults are replaced by
+saved settings, then by explicit CLI options. `sevro.json` keeps its separate
+runtime scope. Saved file paths use the manifest's directory; explicit CLI
+paths use the invoking directory.
+
 An installed package records its name, version, and a digest of its packaged
 runtime and public contract files without reading runner Git metadata. The CLI
 derives the project digest from its revision and dirty patch, or from a bounded
 content snapshot when the project has no Git revision. Result and run-state
-directories are excluded from that snapshot. When running this source checkout
+directories are excluded from that snapshot and untracked Git identity. When running this source checkout
 for coordinated development, pass `--runner-checkout-root` with the absolute
 path to this checkout. Sevro verifies that it is the code actually running and
 records its revision and dirty-patch digest instead of package provenance.
@@ -60,6 +153,53 @@ Codex route, including semantic and advisory roles, and to both `exec` and
 `app-server` entrypoints. For a 20-minute app-server evaluation, add
 `--codex-entrypoint app-server --codex-timeout-ms 1200000` to the Codex command
 above. The option requires a Codex host route; invalid values fail before a run.
+For `app-server`, this is the only deadline for the whole session, including
+startup requests such as `thread/start`. If it expires while a request is
+unanswered, the failure names that request, for example
+`App-server evaluation time bound reached awaiting thread/start`.
+
+### Retain native host diagnostics
+
+Add `--retain-host-diagnostics` to a failing invocation to retain private
+diagnostics from bundled Codex and Claude hosts. The switch defaults to off,
+applies to every selected native role, and is independent of runtime
+`nativeTranscripts`. It does not enable transcript access or change the
+candidate's permissions.
+
+For example, add the switch to the Codex command above:
+
+```sh
+sevro run --json \
+  --case-file /absolute/path/case.json \
+  --host codex --codex-bin /absolute/path/codex \
+  --codex-auth-file /absolute/path/auth.json \
+  --model <model> --effort medium \
+  --project-root /absolute/path/project \
+  --results-root /absolute/path/results \
+  --condition passive --trials 1 --threshold 1 \
+  --retain-host-diagnostics
+```
+
+Failed preparation or execution retains `sevro.host.diagnostics`, including
+when no native session or final response exists. Its private JSON records the
+failing stage, original error/cause chain, and recent subprocess receipts.
+Receipts contain actual exit code or signal, monotonic duration, bounded
+stdout/stderr prefixes, and truncation markers. App-server protocol failure is
+separate from its process exit code.
+
+The CLI's failure diagnostic names the artifact's file URL when it fits the
+diagnostic length limit. The result's `evidencePath` and each trial's
+`artifactPath` always lead to retained artifact references; semantic and
+advisory artifacts carry their existing role prefixes. Files have private
+permissions and are persisted before native state cleanup. The
+[results contract](results-v1.md#native-host-diagnostics) defines the format,
+bounds, redaction, and failure semantics.
+
+Enabled native roles record `sevro.host.retain-diagnostics: true` in redacted
+host configuration. This changes configuration identity, so a diagnostic rerun
+is not an exact-repeat comparison with an invocation that omitted the switch.
+Injected adapters own their diagnostic behavior; the CLI switch configures the
+bundled native routes.
 
 ### Trial concurrency
 
@@ -130,22 +270,45 @@ sevro run --json \
 The route reuses existing Claude authentication. An explicit
 `--claude-credential-file` takes precedence over inherited credentials. Otherwise,
 it forwards `ANTHROPIC_API_KEY` and `CLAUDE_CODE_OAUTH_TOKEN` when present, leaving
-their relative precedence to Claude Code. With neither variable present, it
-copies `.credentials.json` from `CLAUDE_CONFIG_DIR` or `~/.claude`, then falls back
-to the macOS Keychain if the saved file is absent. An unreadable, empty or
-oversized selected file fails rather than falling back to another login.
-Only credentials enter private per-turn state; user rules, settings and hooks
-remain excluded. The host denies both authentication variables to sandboxed
+their relative precedence to Claude Code. With neither variable present, it uses
+the saved login where Claude Code keeps it for `CLAUDE_CONFIG_DIR` or `~/.claude`.
+On macOS that is the configuration's Keychain item, then `.credentials.json` in
+that directory when the item is absent or unreadable. On Linux it is that file.
+An unreadable, empty, oversized or non-login selected file fails rather than
+falling back to another login. Pass `--claude-credential-file` with an absolute
+path to select a separate saved login; Sevro refreshes and updates only that file.
+
+A saved login never enters per-turn state. Each turn receives only its access
+token as `CLAUDE_CODE_OAUTH_TOKEN`, so Claude Code in the trial cannot refresh or
+rotate the login. The parent refreshes when the remaining token lifetime cannot
+cover the execution budget: the Claude timeout for each turn, including a
+declared follow-up, plus five minutes. It holds Claude Code's own
+`.oauth_refresh.lock` in the login's configuration directory and reads the login
+again. It then runs `claude auth login` with Claude Code's documented
+`CLAUDE_CODE_OAUTH_REFRESH_TOKEN` in a disposable configuration. Sevro writes the
+rotated tokens back to the original Keychain item or file, preserving other fields.
+It reads that store again to verify them before a turn starts, and leaves a login
+that changed during the refresh untouched. Refresh requires Claude Code 2.1.284 or
+later; an older release fails before its refresh token is used.
+
+If the store cannot be updated, the run fails and Sevro keeps the rotated tokens in
+its private native-state directory. The next run restores them once the store is
+writable. If Claude Code cannot refresh the login, run `claude` and `/login`.
+A token that expires or is revoked during a turn fails that turn's
+authentication; the trial never refreshes it. This lifecycle is covered with a
+synthetic Claude CLI and token ledger, not against Anthropic's live endpoint.
+
+Only the access token enters private per-turn state; user rules, settings and
+hooks remain excluded. The host denies both authentication variables to sandboxed
 commands and enables Claude Code's subprocess credential scrubbing. Credential
-values are excluded from retained evidence and configuration digests. Pass
-`--claude-credential-file` with an absolute path to select a separate saved login.
+values are excluded from retained evidence and configuration digests.
 It accepts declared Claude
 plugin directories and explicit skill invocations from extension preparation.
 It runs candidate tools under Claude Code's native sandbox with private,
 source, and result paths denied. The route disables hooks by default and does not expose
 the Write tool. It currently supports passive candidate turns only. Use
 `--protected-root` to exclude additional private paths from the candidate's
-filesystem access. Configure shared host tools, private caches, goals, and selected
+filesystem access. Configure shared host tools, private or reusable caches, goals, and selected
 plugin hooks with [`sevro.json` or `--runtime-config-file`](runtime-v1.md).
 The same policy reaches isolated checks and native grading hosts.
 
@@ -174,9 +337,10 @@ Without that option, the host does not advertise
 `sevro.claude.repository-invocation` and refuses explicit repository dispatch
 before launching Claude. This avoids recording an unknown command as a usable
 repository-skill route.
-The host reads only bounded Skill metadata from completed child Agent sessions
-in its temporary private configuration, then removes those session files. A
-missing or inconsistent graph leaves `sevro.claude.nested-skills` partial.
+The host collects successful `Skill` calls through the existing structured
+stream as [skill activation evidence](native-hosts.md#skill-activation-evidence).
+It uses the same collector for parent and nested actors. Missing or unmatched
+results remain partial; separate transcript-based skill detectors are retired.
 
 A case's `followUpPrompt` starts a UUID-bound session and resumes that same
 session after a complete successful initial result. Both results must name
@@ -195,7 +359,8 @@ For cases with `sevro.semantic` checks, also pass
 explicit second `HostAdapter` for grading. Alternatively, select the bundled
 Codex route with `--semantic-host codex --semantic-model <model>
 --semantic-effort <effort>`. That route also requires `--codex-bin` and
-`--codex-auth-file`, shared with a Codex candidate route when present. The two
+`--codex-auth-file`, shared with a Codex candidate route when present. The binary
+defaults to the explicitly selected `codex` on `PATH`. The two
 semantic route options are exclusive. The candidate and semantic routes are
 recorded separately in evidence and evaluation identity. The semantic adapter
 runs after a complete candidate response in its own empty workspace; missing
@@ -249,7 +414,7 @@ verdict and rejects unsolicited recommendations.
 
 If the extension needs configuration, supply both
 `--extension-configuration-file` and
-`--extension-redacted-configuration-file` as absolute paths to JSON objects.
+`--extension-redacted-configuration-file` as paths to JSON objects.
 The latter replaces secret values for the retained configuration digest. Keep
 secrets out of the command argv and the redacted file.
 
@@ -279,7 +444,13 @@ isolated shell checks receive `.git/fixture-bin` on `PATH`. Host adapters
 receive `fixtureBinDir` and must add it to their native tool environment; the
 bundled Codex adapter also preserves it across login shells. A negotiated
 fixture setup command may then prepare the clone before the host runs.
-Repository submodules and preparation artifacts targeting `.git/` are refused.
+Repository fixtures preserve committed `.gitmodules` files and submodule gitlink
+revisions. Trial clones leave submodules uninitialized and do not fetch their
+contents, even when the source has initialized submodules. A fixture that needs
+those contents must initialize them during its negotiated setup. Modified or
+untracked files and revision changes in initialized source submodules are
+refused, including when Git's submodule ignore settings hide them. Preparation
+artifacts targeting `.git/` are refused.
 
 A direct case or extension can declare a generated Git fixture:
 
@@ -371,6 +542,3 @@ Claude also advertises `sevro.host.native-goal`. Its observer binds one persiste
 transcript to the original successful native session and retains goal status
 and objective length. Missing, ambiguous, malformed or oversized evidence is
 unavailable; an unavailable observation cannot prove goal absence.
-
-These additions require the `0.1.0-rc.2` candidate. The published `rc.1` lacks
-the app-server selector and native goal observations.

package/docs/documentation-quality.md

@@ -14,6 +14,12 @@ Local checks need no network. Run `bun run test:docs-examples` for the exact
 marked tutorial commands in fresh consumer/contributor directories, including
 expected verdicts and saved evidence. Candidate and released-package runs are
 reported separately. These commands create and clean temporary directories.
+The [recipe verifier](../scripts/documentation-recipes.ts) runs the new packaged
+projects separately from the current published version. It executes actual
+isolated tool/check positive and negative controls and both native hosts' dry
+preparation; authenticated model, plugin-hook and goal behavior remain
+unexecuted by that check. Its [prerequisites](recipes.md#prepare-a-recipe-project)
+are mandatory, including UV and mise's declared Node installation.
 
 `package.json.version` is the authoritative current version. `bun run docs:sync`
 updates only the marked [Current release](installing.md#current-release) section
@@ -25,6 +31,10 @@ stale output. Run synchronization after a version bump and include the resulting
 documentation change. Link installation and update instructions to this section.
 Keep historical versions, licensing transitions, and minimum supported versions
 fixed and explain their purpose beside each reference.
+Link to the current-release section instead of repeating the current Sevro
+version elsewhere. Describe features for the latest version, using the installed
+`sevro` command in user workflows. Keep source-checkout instructions in contributor
+guidance and omit notes about feature unavailability in older releases.
 
 ## External links
 
@@ -38,8 +48,8 @@ make a network job green. External success does not establish a claim's truth.
 
 - Can a new user reach installation, first success, results, troubleshooting,
   architecture, and contributing without the guide?
-- Are supported environments, credentials, side effects, and current versus
-  released behavior explicit beside the relevant commands?
+- Are supported environments, credentials, side effects, and prerequisites
+  explicit beside the relevant commands?
 - Do descriptive links, meaningful headings, source order, readable tables,
   image alternatives, and words rather than color support accessibility?
 - Are current contracts, accepted choices, research, and past evidence distinct?