@bjoernrochel/sevro 0.1.0-rc.7 → 1.0.0

package/docs/runtime-v1.md

@@ -1,8 +1,7 @@
 # Runtime configuration v1
 
-Configure access to existing host tools, private writable caches, native goals,
-and selected plugin hooks in `<project-root>/sevro.json`. This interface is
-available in `0.1.0-rc.3` and later.
+Configure access to existing host tools, private state, reusable caches, native goals,
+and selected plugin hooks in `<project-root>/sevro.json`.
 
 `--runtime-config-file /absolute/path/runtime.json` selects a replacement file.
 Sevro reads exactly one file before execution, including dry runs. It does not
@@ -14,6 +13,17 @@ non-symlink files of at most 64 KiB.
 
 The [JSON schema](../schemas/runtime-v1.schema.json) has format
 `sevro.runtime.v1`. All properties except `format` are optional.
+Start with the smallest file:
+
+```json
+{ "format": "sevro.runtime.v1" }
+```
+
+Then add `environment.inherit: ["PATH"]` for installed tools. Follow the
+[runnable runtime recipes](recipes.md#add-host-tool-access-one-capability-at-a-time)
+to add Node, Python/UV, mise, goals and selected plugin hooks separately.
+The following composed example is for a workflow that already needs all these
+capabilities:
 
 ```json
 {
@@ -26,7 +36,13 @@ The [JSON schema](../schemas/runtime-v1.schema.json) has format
     }
   },
   "runtime": {
-    "seedDirectories": [{ "source": "./public-uv-cache", "target": "uv-cache" }]
+    "sharedCacheDirectories": [
+      {
+        "source": "../public-uv-cache",
+        "target": "uv-cache",
+        "roles": ["candidate", "hooks"]
+      }
+    ]
   },
   "hooks": {
     "nativeGoal": true,
@@ -35,7 +51,7 @@ The [JSON schema](../schemas/runtime-v1.schema.json) has format
 }
 ```
 
-Create the example's `public-uv-cache` directory beside the configuration, or
+Prepare the example's `public-uv-cache` directory outside the project, or
 omit `runtime` when no prepared cache is needed. Selected plugin names must be
 present in the case's prepared mounts; remove names that the case does not mount.
 `DARROW_CACHE_DIR` is an ordinary explicit variable in this example, not a
@@ -102,6 +118,10 @@ Existing directory paths and symlink targets are canonicalized. Reads under
 the real home are allowed only through bounded runtime grants. Source and
 configuration worktrees, evaluator inputs, credentials, results, run ownership
 state, and peer fixtures remain protected. A conflicting or broad grant fails.
+Managed workspaces share a private parent that protects sibling workspaces,
+including those created after launch. Independently prepared workspaces require
+explicit protection for other private inputs. Claude hosts require Claude Code
+2.1.257 or later for managed-workspace isolation; see [checked versions](typescript-quality.md#environment-and-ci).
 
 Use `filesystem.optionalReadOnlyRoots` for supporting directories that may not
 be installed on every host, with the same path rules as `readOnlyRoots`:
@@ -140,8 +160,80 @@ minimal system read tree such as `/usr` or `/etc`, Sevro retains its explicit de
 the native preflight may refuse that overlapping setup rather than expose home
 contents.
 
+## Local HTTP test servers
+
+Sevro supports local HTTP servers in isolated Codex candidate
+commands and `sevro.shell` graders through an explicit operator selection:
+
+```json
+{
+  "format": "sevro.runtime.v1",
+  "network": { "localHttp": true }
+}
+```
+
+Add this property to the selected `sevro.json`, or select a replacement with
+`--runtime-config-file`. Declare the existing Node/Python installations through
+the environment and filesystem options above. The selection is snapshotted and
+enters evaluation identity. Absent or `false` preserves existing permissions.
+Hooks and semantic/advisory hosts keep their existing network permissions; this
+option applies to Codex candidates and shell grading.
+
+On macOS, shell isolation permits IP socket binding, loopback inbound traffic,
+and outbound connections to loopback addresses. Wildcard listeners such as
+Node's `server.listen(0)` work with loopback clients. Other outbound IP traffic
+remains denied. On Linux, shell checks retain their private network namespace
+with usable loopback and no external route.
+
+Codex uses its managed command network proxy with `allow_local_binding = true`,
+upstream proxy chaining disabled, and only `localhost`, `127.0.0.1`, and `::1`
+allowlisted. Its native sandbox permits local binding and loopback traffic while
+refusing direct outbound TCP. The native proxy may permit DNS queries; public
+HTTP destinations are not allowlisted. The candidate can reach other services
+on the available loopback interface, so choose this option for evaluations
+that need that access. It does not provide a separate per-trial loopback service
+namespace on macOS.
+
+The supported host boundary is the native Codex sandbox and its experimental
+`network_proxy` feature, documented in the [OpenAI permission reference](https://learn.chatgpt.com/docs/permissions).
+Setting `allow_local_binding` while leaving command networking disabled still
+denies `listen()` on macOS. Integration tests execute the installed native
+Codex sandbox, a wildcard HTTP listener and loopback client, and an outbound TCP
+denial probe. Host versions and actual upstream evaluation outcomes belong in
+[validation evidence](https://github.com/BjRo/sevro/blob/main/docs/evidence.md), rather than being inferred from a profile's
+text. An unsupported host must not be interpreted as a passing behavior test.
+
+## macOS ancestor metadata
+
+Sevro's macOS outer sandbox for isolated shell checks and authorized command
+hooks permits metadata reads on the exact ancestor paths of existing validated
+grants. This includes declared read-only support trees, private writable
+runtimes, and bounded transcript, candidate artifact, and managed workspace
+access. The permissions are derived automatically from those grants; no
+additional configuration is required. They let libc `realpath()` canonicalize
+paths inside a permitted subtree.
+
+Ancestor directory metadata, such as existence, type, ownership, permissions,
+and timestamps, is visible. Directory listings, ancestor file contents, and
+ungranted sibling metadata and contents remain denied under protected roots.
+Writes remain limited by the existing writable grants; read-only grants stay
+read-only. This metadata exception does not grant access to an ancestor subtree
+or change network isolation.
+
 ## Private writable state
 
+Codex candidate commands can write the isolated fixture's `.git` directory,
+including its index, refs, objects, and task-owned admission locks. Sevro grants
+that exact path explicitly because Codex's workspace permission otherwise keeps
+Git metadata read-only. Real commits and publication to a fixture-local remote
+need no additional runtime option. This grant does not authorize writes to
+source repositories, grading inputs, host authentication or configuration, or
+peer trials. Command network access remains disabled unless the operator selects
+the [local HTTP option](#local-http-test-servers).
+An existing fixture `.git` must be a physical directory. Symlinks and Git
+directory pointer files are refused before launch because their metadata may
+belong to a protected source repository rather than the isolated trial.
+
 `runtime.seedDirectories` copies prepared public dependencies into a private
 slot for each execution role. `source` uses the filesystem path rules above;
 `target` is a single lowercase slot name, up to 64 characters, with letters,
@@ -149,10 +241,12 @@ digits, and hyphens. `home` and `tmp` are reserved. Targets must be unique.
 An optional nonempty `roles` array selects any of `candidate`, `checks`, `hooks`,
 `semantic`, and `advisory`. For example, `"roles": ["candidate", "checks", "hooks"]`
 keeps dependency slots out of semantic and advisory runtimes. Without `roles`,
-execution and artifact-grading roles retain the existing selection. Response-only
+candidate, hook, artifact semantic, and advisory roles receive private copies.
+Shell checks require explicit `"checks"` selection; a non-UV grader receives no
+implicit UV/Python cache. Existing configurations whose shell checks need seeded
+dependencies must add `"checks"` to `roles`. Response-only
 semantic grading omits implicit seeds; include `"semantic"` explicitly in `roles`
-when that route needs dependencies. Artifact semantic grading and executable
-shell checks keep their declared tools and default seed selection.
+when that route needs dependencies. Declared host tools remain available to shell checks.
 
 Each source tree is bounded to 16,384 entries and 512 MiB. Escaping symlinks,
 directory cycles, dangling links, and special files are refused. File content
@@ -168,21 +262,67 @@ retaining large policies can retain up to the configured per-seed byte bounds.
 Source caches are never a writable runtime. Use prepared public caches rather
 than credential-bearing homes or evaluator directories.
 
+### Reuse a shared dependency cache
+
+`runtime.sharedCacheDirectories` opts into persistent writable caches without
+copying or hashing their contents for each trial. Each entry requires `source`,
+`target`, and a nonempty `roles` array drawn from the same five roles above.
+The source must already be an owned, readable, writable directory. Relative paths
+resolve beside the runtime file. Sevro resolves declaration symlinks to their
+canonical source and revalidates that directory before execution.
+Targets use the seed slot rules and must be unique across seeds and shared caches.
+Sources cannot overlap each other, private seed sources, declared read-only
+inputs, evaluated project/source trees, results, credentials, or native private state.
+
+Select only roles that actually use UV, for example `"roles": ["candidate", "hooks"]`.
+If a grader also uses UV, add `"checks"` to that same entry; both roles use the
+same cache. Each selected private slot aliases the original directory, with a
+narrow sandbox write grant. Other roles receive no slot or source grant.
+Shared content survives successful, failed, and cancelled trials and later runs.
+Sevro removes only disposable role state, never the declared shared source.
+
+Prepare UV packages once outside evaluation, point `UV_CACHE_DIR` at
+`{{sevro.runtime}}/uv-cache`, and reuse the existing Python installation through
+declared read-only tool roots. Set `UV_PYTHON_DOWNLOADS=never` to require that
+installation. Sevro keeps `UV_OFFLINE=1`; a missing dependency fails rather than
+downloading during a trial. Project virtual environments and temporary files
+remain disposable; UV's install/link mode can still allocate files in a virtual
+environment. The shared option removes the full cache copy per trial.
+
+Shared caches are mutable across trials, roles, and runs. Use them only for public
+dependencies and accept that a participant can change them for later participants.
+Use isolated seeds when dependency independence is required. Configuration identity
+binds the source, slot, and roles, but excludes mutable cache contents; equal
+identities therefore do not prove identical shared-cache bytes. Sevro does not
+age-delete shared caches. Manage their size between evaluations with the cache
+tool, such as `uv cache prune --cache-dir /absolute/public-uv-cache`.
+
 `{{sevro.runtime}}` in an environment value resolves to that role's writable
-root. Sevro supplies private `HOME` and temporary storage and sets `UV_OFFLINE=1`
-and `PYTHONDONTWRITEBYTECODE=1`. Candidate, hook, checker, semantic, and advisory
+root. Codex commands receive a `TMPPREFIX` inside their private `TMPDIR`,
+so zsh here-documents use their existing private temporary storage while shared
+host temporary directories remain denied. `TMPPREFIX` is runner-owned and cannot
+be inherited or set through runtime configuration.
+Sevro supplies private `HOME` and temporary storage and sets `UV_OFFLINE=1`
+and `PYTHONDONTWRITEBYTECODE=1`. Fixture setup uses the candidate commands'
+private `HOME`, so `$HOME` paths initialize the same state the candidate will
+use. Its temporary directory stays disposable.
+Candidate, hook, checker, semantic, and advisory
 state are separate. With a runtime policy, native candidate, semantic, and
 advisory roots live in a unique runner-owned host directory outside the Git
-fixture. The root contains `home`, `tmp`, and declared seed slots; plugins can
+fixture. The root contains `home`, `tmp`, private seed slots and selected shared-cache links; plugins can
 use paths such as `~/.darrow/reviews` without creating repository-local review
 state. Command runtime directories are separate from host authentication,
-configuration, and live transcript sources. Checker and hook caches also live
-outside candidate-controlled workspace state. Private roots survive native
+configuration, and live transcript sources. Checker and hook private state also lives
+outside candidate-controlled workspace state. Shared sources remain at their declared locations. Private roots survive native
 continuation turns and children, then are removed with their owning trial or
-host state after owned hooks terminate. Runs without a selected runtime policy
+host state after owned hooks terminate. Checker home, temporary storage, and copied
+seeds are removed after grading even when the fixture is retained after failure
+or cancellation. Results and evidence are preserved. Opted-in candidate artifact runtimes
+remain alive through grading as described below. Runs with neither fixture setup
+nor a selected runtime policy
 retain their previous writable-state locations.
 
-Claude runtime policies refuse a private namespace overlapping the native CLI's
+Claude refuses managed workspace or runtime namespaces overlapping its
 implicit `/tmp/claude` or `/private/tmp/claude` write roots, including canonical
 symlink targets. A conflicting `TMPDIR` placement fails before native launch;
 choose a temporary base outside those cache trees.
@@ -192,6 +332,142 @@ checks, and native semantic/advisory hosts. Candidate plugin-hook authority is
 not forwarded to grading hosts. Injected adapters receive the policy as request
 data and remain trusted code responsible for their own execution boundary.
 
+## Candidate artifact access
+
+Use `runtime.artifactDirectories` to let graders read selected artifacts in the
+candidate's private home after execution.
+
+```json
+{
+  "format": "sevro.runtime.v1",
+  "runtime": {
+    "artifactDirectories": [{ "name": "reviews", "path": ".darrow/reviews" }]
+  }
+}
+```
+
+The example permits only the `~/.darrow/reviews` subtree, which may be initialized
+by trusted fixture setup or created by the candidate.
+Its original absolute path reaches isolated shell checks and native
+semantic/advisory commands as `SEVRO_CANDIDATE_ARTIFACT_REVIEWS`. Graders keep
+their own private `HOME`; use the supplied variable to read candidate evidence.
+For each declared name, the variable is `SEVRO_CANDIDATE_ARTIFACT_` followed by
+the name in uppercase. Artifact content is untrusted candidate evidence.
+
+At most 16 directories may be declared. Names are unique, contain lowercase
+letters, digits and underscores, start with a letter, and are at most 64
+characters. Paths are relative to candidate home, are at most 4,096 characters,
+and cannot contain empty, `.` or `..` components, backslashes or control
+characters. Whole-home and absolute grants are refused. Each subtree is bounded
+to 16,384 entries, including its root. Missing directories, symlinked ancestors,
+descendant symlinks, hardlinks and special files make grading an error; missing
+evidence cannot produce a pass.
+
+Initialize an empty directory or seed prior Review state in the extension's
+trusted `fixtureSetup` command before the candidate starts. For example:
+
+```sh
+mkdir -p "$HOME/.darrow/reviews"
+printf '%s\n' '{"verdict":"passed"}' > "$HOME/.darrow/reviews/prior.json"
+```
+
+Setup and candidate commands share this private trial home, including when no
+artifact grants or runtime file are selected. Graders keep their own homes and
+receive only declared read-only artifact grants. To test missing reports or
+absence of new artifacts, initialize the directory without writing a report;
+an empty safe directory reaches ordinary task checks. Missing required reports
+can then fail those checks, while negative cases can assert the directory is
+empty. Sevro does not automatically create declared artifact directories: if
+setup and candidate both leave one absent, or replace it with an unsafe path,
+grading still errors. Setup state is temporary and is removed with its trial,
+including setup failure, cancellation, and dry runs.
+
+The grant permits reads and denies writes, creation, deletion and renaming.
+Credentials, other home contents and peer role/trial state stay protected.
+Ordinary `filesystem.readOnlyRoots` cannot select this private-state exception.
+Artifact grants and native transcript access are independent opt-ins.
+
+The trial allocates the retained runtime before fixture setup and
+removes it after grading, advisory review and evidence persistence, including
+failure and cancellation paths. Review state remains outside the Git fixture.
+These artifacts are temporary; declaring access does not copy their bytes into
+retained run evidence. Failed-fixture retention does not retain this runtime.
+Standalone bundled-host calls retain their immediate cleanup behavior.
+
+Trusted injected adapters receive a runner-owned `candidateRuntimeRoot` on the
+candidate request and a named `candidateArtifactRoots` path map on grading
+requests. Candidate adapters opting into this feature must put their private
+runtime at the supplied root. The lifetime binding is process-local; bundled
+hosts validate it before use. Grading adapters must preserve the read-only
+boundary. The directory declarations enter runtime configuration identity;
+per-trial absolute paths do not.
+
+## Candidate Codex configuration and user skills
+
+Set top-level `"codexState": true` to expose the bundled Codex candidate's actual
+isolated configuration and user-skill state. This opt-in is independent of
+`nativeTranscripts` and ordinary
+candidate-home artifact declarations:
+
+```json
+{
+  "format": "sevro.runtime.v1",
+  "codexState": true
+}
+```
+
+Candidate commands receive the real isolated `CODEX_HOME`. They may read its
+`config.toml` and write non-system skills below `CODEX_HOME/skills`. The native
+process's separate user-skill directory is available as
+`SEVRO_CODEX_AGENT_SKILLS`; it names that process's `HOME/.agents/skills`.
+Bundled `CODEX_HOME/skills/.system` skills remain read-only. Authentication,
+other private siblings, evaluator inputs and peer requests remain denied.
+Configuration remains read-only, and the preflight still checks credential denial.
+
+A physical fixture-local `.codex` directory is accepted only with this opt-in.
+Sevro marks the isolated project untrusted in its generated Codex configuration,
+so project-local configuration, hooks and rules remain represented inputs rather
+than effective host settings. The fixture is preserved. Diagnose the absolute
+`CODEX_HOME/config.toml`, not the checkout's `.codex/config.toml`. The runner's
+selected concurrency limit is written into the private config; an omitted limit
+still means the native host default, not a fabricated configured capacity.
+CLI model/effort and vetted-hook overrides keep their existing precedence; the
+file alone does not establish every effective native default or child route.
+
+After execution, isolated shell and native semantic/advisory graders receive
+read-only bindings to these original candidate paths:
+
+| Environment variable                            | Original candidate path                    |
+| ----------------------------------------------- | ------------------------------------------ |
+| `SEVRO_CANDIDATE_ARTIFACT_CODEX_CONFIG`         | Native `CODEX_HOME/config.toml` (one file) |
+| `SEVRO_CANDIDATE_ARTIFACT_CODEX_SKILLS`         | Native `CODEX_HOME/skills`                 |
+| `SEVRO_CANDIDATE_ARTIFACT_AGENT_SKILLS`         | Native process `HOME/.agents/skills`       |
+| `SEVRO_CANDIDATE_ARTIFACT_COMMAND_AGENT_SKILLS` | Command `HOME/.agents/skills`              |
+| `SEVRO_CANDIDATE_ARTIFACT_COMMAND_CODEX_SKILLS` | Command `HOME/.codex/skills`               |
+
+Native and command homes are separate. The runner initializes these actual
+skill locations before the candidate starts and retains their resulting state;
+it does not create replacement empty directories for grading. Graders keep their
+own homes and must use these bindings. To assert absence, require every selected
+directory to exist, then search for `SKILL.md`, excluding only the native Codex
+root's read-only `.system` subtree. Missing evidence is an error. Do not search
+the grader's home or retired fixture state.
+
+The five artifact names are reserved. Each binding belongs to one active trial
+and one native request; reuse by another host request is refused. The same
+canonical ancestor, entry-limit, symlink, hardlink and special-file checks as
+ordinary artifacts apply. Configuration cannot be replaced by a directory grant.
+The native home is retained through grading and removed with its trial, including
+failure and cancellation paths. Standalone host calls clean up immediately.
+These grants do not persist native files in run evidence; private absolute paths
+do not enter identity, while the `codexState` selection does. Other candidate
+hosts cannot supply this Codex evidence and fail grading when it is requested.
+
+For the Darrow doctor and undefined-skill cases, select this configuration with
+`--runtime-config-file`, preserve the doctor fixture's checkout value `99`, and
+replace the retired-state absence check with the four skill-directory bindings
+above. Keep the original repository, no-commit, activation and semantic checks.
+
 ## Goals and plugin hooks
 
 `hooks.nativeGoal` enables Claude's native goal Stop-hook path while preserving
@@ -216,6 +492,17 @@ instead of being skipped. The wrapper denies network access and protected
 roots and owns asynchronous hook cleanup. Native timeout/cancellation stops
 owned hook descendants before private state is removed.
 
+Prepared native plugin projections live outside the fixture in the current
+host request's private native state. Curated hook read grants validate the
+canonical projection layout, ownership, private state permissions, and binding
+to that request. Only the selected plugin subtree is readable; it stays
+read-only, and credentials, private siblings, and peer requests remain denied.
+Ordinary filesystem declarations cannot select this exception. Codex validates
+and filters installed plugins before enabling its runner-owned skill collector,
+including requests without a runtime policy. Plugin command handlers still
+require explicit hook authority. Projections are removed with their owning host
+request.
+
 Auxiliary `.mcp.json` and `.lsp.json` files and plugin mods are unsupported under
 hook authority. Manifest MCP/LSP declarations are removed from curated mounts.
 
@@ -283,7 +570,7 @@ run evidence. Extensions and external benchmarks consume the
 ## Evidence and compatibility
 
 `configuration.redacted.runtimePolicy` retains the selected environment,
-canonical read roots, seed digests, and hook declaration. The engine snapshots
+canonical read roots, seed digests, shared-cache declarations, and hook declaration. The engine snapshots
 this input once; it participates in `configurationDigest` and evaluation
 identity. Symbolic runtime placeholders remain symbolic in identity, while
 execution uses per-role paths. This binds declared setup and seed contents;
@@ -297,7 +584,8 @@ file contents do not. The same discovery and skip evidence reaches
 `sevro.host.runtime` observations.
 
 Bundled hosts supply `sevro.host.runtime` with the applied policy digest, role,
-environment names, read roots, and seed slots. `sevro.host.hooks` records source
+environment names, read roots, seed slots, and selected shared-cache declarations.
+Shared entries contain no content digest. `sevro.host.hooks` records source
 and effective plugin digests plus observed executions and their exit codes.
 An empty execution list does not prove hook activation. Partial lifecycle
 evidence remains partial. Cases can require these observations; missing required
@@ -307,7 +595,8 @@ task verdict.
 `--toolchain-bin-dir` and `--claude-uv-cache-dir` are deprecated. They keep their
 previous behavior with a warning when no runtime file is selected. Combining
 them with a runtime file fails before execution. Migrate to `environment`,
-`filesystem`, and private seed slots; removal is no earlier than `0.2.0`.
+`filesystem`, and either private seed slots or shared-cache declarations; removal
+is no earlier than `0.2.0`. The deprecated UV option continues to copy privately.
 See the [CLI reference](development-cli.md), [native hosts](native-hosts.md),
 and [identity contract](identity-v1.md).
 

package/docs/troubleshooting.md

@@ -3,18 +3,18 @@
 Start with execution, grading, task states, and stderr. A documented possible
 cause is not a diagnosis of your machine.
 
-| Symptom                                   | Check and next step                                                                                                                                       |
-| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Command cannot run                        | Use Bun 1.3.13 and verify the local package/version. Read [installation](installing.md).                                                                  |
-| Project snapshot contains a symbolic link | Use a separate evaluated project directory as in [the tutorial](getting-started.md); do not include installed dependencies in a plain-directory snapshot. |
-| Exit 0 but no passing task                | Prompt-only/dry runs are `not_assessed`. Read [results](reading-results.md).                                                                              |
-| Exit 64 before execution                  | Check absolute paths, exclusive route options, configuration, and capabilities in the [CLI reference](development-cli.md).                                |
-| Grading unavailable                       | Inspect required evidence/completeness in [results v1](results-v1.md).                                                                                    |
-| Native authentication fails               | Check the exact release and private credential route. Read [native hosts](native-hosts.md).                                                               |
-| Native or shell isolation fails           | Verify macOS and `sandbox-exec`. Other platforms are unverified.                                                                                          |
-| Extension protocol fails                  | Return one matching stdout response; diagnostics use stderr. Read [protocol v1](extension-protocol-v1.md).                                                |
-| Schema freshness fails                    | Run `bun run schemas:generate`, then `bun run schemas:check`, from a checkout.                                                                            |
-| External links fail                       | Follow [network failure triage](documentation-quality.md#external-links).                                                                                 |
+| Symptom                                   | Check and next step                                                                                                                                                                     |
+| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Command cannot run                        | Use Bun 1.3.13 and verify the local package/version. Read [installation](installing.md).                                                                                                |
+| Project snapshot contains a symbolic link | Use a separate evaluated project directory as in [the tutorial](getting-started.md); do not include installed dependencies in a plain-directory snapshot.                               |
+| Exit 0 but no passing task                | Prompt-only/dry runs are `not_assessed`. Read [results](reading-results.md).                                                                                                            |
+| Exit 64 before execution                  | Check absolute paths, exclusive route options, configuration, and capabilities in the [CLI reference](development-cli.md).                                                              |
+| Grading unavailable                       | Inspect required evidence/completeness in [results v1](results-v1.md).                                                                                                                  |
+| Native authentication fails               | Check the exact release and private credential route. Read [native hosts](native-hosts.md).                                                                                             |
+| Native or shell isolation fails           | On macOS, verify `sandbox-exec`; on Ubuntu 24.04 x64, verify `bubblewrap` and Claude's `socat`. See [validated scope](native-hosts.md#validated-platform-scope). Windows is unverified. |
+| Extension protocol fails                  | Return one matching stdout response; diagnostics use stderr. Read [protocol v1](extension-protocol-v1.md).                                                                              |
+| Schema freshness fails                    | Run `bun run schemas:generate`, then `bun run schemas:check`, from a checkout.                                                                                                          |
+| External links fail                       | Follow [network failure triage](documentation-quality.md#external-links).                                                                                                               |
 
 ## The repository guide is missing