@evolvingmachines/evolve 0.0.65 → 0.0.67-train-harness-wave-2026-09-25.20260926.e00a8a6d

package/skills/evolve-evals/references/core-concepts/multi-step.md

@@ -0,0 +1,93 @@
+---
+title: "Multi-step tasks"
+description: "Give the agent a sequence of instructions while preserving its files."
+---
+
+A multi-step task runs ordered instructions in one shared environment. Files persist between steps; each step starts a fresh agent conversation and receives its own verification result.
+
+```mermaid
+%%{init: {"flowchart": {"nodeSpacing": 16, "rankSpacing": 20, "padding": 10, "subGraphTitleMargin": {"top": 8, "bottom": 24}}, "themeVariables": {"fontSize": "14px", "fontFamily": "Google Sans Flex, sans-serif"}}}%%
+flowchart TB
+  subgraph shared["One shared environment"]
+    A["1. Start environment"] --> B["2. Step 1<br/>New conversation"]
+    B --> C["3. Verify step 1"]
+    C -->|"Threshold met"| D["4. Step 2<br/>New conversation · same files"]
+    D --> E["5. Verify step 2"]
+  end
+  E --> F["6. Select trial reward<br/>mean or final"]
+  C -->|"Threshold missed<br/>Skip step 2"| F
+```
+
+This two-step example uses the same environment for both agent steps and their verifiers. Reward thresholds and failure rules decide whether later steps run.
+
+## Directory layout
+
+- migrate-then-test/
+  - task.toml
+  - environment/
+    - Dockerfile
+  - tests/
+    - test.sh
+  - steps/
+    - 01-migrate/
+      - instruction.md
+      - tests/
+        - test.sh
+      - workdir/
+        - setup.sh
+    - 02-test/
+      - instruction.md
+      - tests/
+        - test.sh
+
+The root `tests/` folder can hold shared verifier files. Each step can include optional `workdir/` files and a `setup.sh` inside that folder.
+
+Each step needs an instruction and a test script, either its own or the shared root `tests/test.sh`. Step test files override shared files with the same path.
+
+## Declare the order
+
+```toml task.toml
+multi_step_reward_strategy = "mean"
+
+[[steps]]
+name = "01-migrate"
+min_reward = 0.5
+
+[[steps]]
+name = "02-test"
+
+[steps.agent]
+timeout_sec = 600
+```
+
+Every declared step must have a matching directory, and every step directory must be declared. There is no root instruction for this layout.
+
+Before a step starts, its optional `workdir/` files are copied into the working directory and `setup.sh` runs if present.
+
+## Rewards and stopping
+
+| Setting | Meaning |
+| --- | --- |
+| `mean` | Average each metric across steps with a verifier result; a missing metric counts as `0`. This is the default |
+| `final` | Use the last executed step's result, including a step that stopped the trial early |
+| `min_reward = 0.5` | Require the `reward` key to be at least `0.5`; a missing key also stops the trial |
+| `min_reward = { accuracy = 0.8 }` | Require each named metric to meet its threshold; a missing metric also stops the trial |
+
+A setup or healthcheck failure stops the remaining steps. A step error with no verifier result also stops the trial. An agent error alone can still continue when verification returns a result and the reward thresholds pass. Infrastructure failures stop the trial.
+
+The trial exposes individual outcomes in `step_results`. A retry starts again at step 1.
+
+## Current limits
+
+| Supported per step | Set once for the whole task |
+| --- | --- |
+| Instruction and tests | Environment image and agent user |
+| Agent and verifier timeouts | Network policies |
+| Verifier environment variables | Shared verifier mode |
+| Healthcheck | Sandbox provider |
+
+Multi-step tasks require shared verification. Compose, separate verification, per-step agent users, per-step network policies, per-step verifier environments, and per-step collection hooks are rejected. Verifiers run as root. These trials cannot be regraded.
+
+`steps.artifacts` does not create a separate snapshot after each step. Save intermediate outputs under distinct paths when you need to inspect them later.
+
+To seed the first conversation on Claude Code or Codex, put an ATIF `trajectory.json` inside the first step’s directory, beside its `instruction.md`. A root trajectory or a trajectory in a later step is rejected. Later steps start fresh conversations.

package/skills/evolve-evals/references/core-concepts/rewardkit.md

@@ -0,0 +1,341 @@
+---
+title: "Reward Kit"
+description: "Combine reusable checks, custom Python, and model judges into reward scores."
+---
+
+Reward Kit is the `harbor-rewardkit` Python package. It discovers checks in `tests/`, runs them against the agent's workspace, and writes a reward plus detailed findings.
+
+This guide uses the published **0.2.1** package.
+
+| Use | For |
+| --- | --- |
+| Built-in checks | Files, commands, JSON, CSV, databases, HTTP, and images |
+| Custom Python | Rules specific to your task |
+| Model judges | Criteria that need a written assessment |
+
+## Build a deterministic verifier
+
+Start with [your first task](/getting-started/first-task). Keep its instruction, `task.toml`, and solution. Replace the environment Dockerfile and test files with these four files.
+
+This example uses shared verification and requires the exact answer, including its final newline.
+
+- hello-world/
+  - environment/
+    - Dockerfile
+  - tests/
+    - test.sh
+    - checks.py
+    - reward.toml
+
+### environment/Dockerfile
+
+Install Reward Kit when the image builds. Python 3.12 or newer is required; no package download is needed during verification.
+
+```dockerfile
+FROM python:3.12-slim
+RUN pip install --no-cache-dir \
+    'harbor-rewardkit==0.2.1'
+WORKDIR /app
+```
+
+### tests/checks.py
+
+Combine a built-in file check with one custom criterion.
+
+```python
+from pathlib import Path
+import rewardkit as rk
+
+rk.file_exists("answer.txt")
+
+@rk.criterion
+def exact_answer(
+    workspace: Path,
+) -> bool:
+    path = workspace / "answer.txt"
+    if not path.is_file():
+        return False
+    expected = "Hello, world!\n"
+    actual = path.read_text()
+    return actual == expected
+```
+
+### tests/reward.toml
+
+Require both checks in `checks.py` to pass.
+
+```toml
+[scoring.checks]
+aggregation = "all-pass"
+```
+
+### tests/test.sh
+
+Run the installed package against `/app` and write the standard reward file.
+
+```bash
+#!/bin/bash
+set -euo pipefail
+python3 -m rewardkit /tests \
+  --workspace /app \
+  --output \
+  /logs/verifier/reward.json
+```
+
+The exact answer scores `1`. A missing file, different text, or missing final newline scores `0`.
+
+Reward Kit also writes `reward-details.json` beside `reward.json`, with the individual checks and their results. Use the [first-task workflow](/getting-started/first-task#2-validate-the-metadata) to validate, publish, check, and evaluate this version.
+
+## Write your own checks
+
+A criterion receives `workspace: Path` and returns a boolean or number. The example's function has no other arguments, so `@rk.criterion` registers it automatically.
+
+For reusable criteria with additional arguments, register each check through `rk`:
+
+```python tests/lines.py
+from pathlib import Path
+import rewardkit as rk
+
+@rk.criterion
+def has_lines(
+    workspace: Path,
+    count: int,
+) -> bool:
+    path = workspace / "answer.txt"
+    if not path.is_file():
+        return False
+    lines = path.read_text().splitlines()
+    return len(lines) >= count
+
+rk.has_lines(5, weight=2.0)
+rk.has_lines(10, weight=1.0)
+```
+
+Handle expected failures by returning `False` or `0`. An unhandled exception aborts the verifier; it does not become a failed criterion automatically.
+
+**Note:**
+
+`file_matches()` ignores leading and trailing whitespace. Use a custom check, as above, when exact whitespace matters.
+
+## Built-in criteria
+
+Call these through `rk`. File, data, and image paths resolve from `--workspace`; absolute paths stay absolute. All checks also accept `weight=1.0`, a custom `name`, and `isolated=False`.
+
+### Files and text
+
+- `file_exists(path)` and `file_not_exists(path)`: test whether a path exists. Directories count too.
+
+- `file_contains(path, text)`: find a literal substring.
+
+- `file_contains_regex(path, pattern)`: find a Python regular-expression match.
+
+- `file_matches(path, expected)`: compare text after trimming both ends.
+
+- `files_equal(path1, path2)`: compare two text files after trimming both ends.
+
+- `diff_ratio(path, expected)`: return a text-similarity ratio from `0` to `1`, after trimming both ends.
+
+### Commands
+
+All four take `cmd`, optional `cwd`, and `timeout=30` seconds. The default working directory is the workspace.
+
+- `command_succeeds(cmd)`: require exit code `0`.
+
+- `command_output_contains(cmd, text)`: find a substring in stdout.
+
+- `command_output_matches(cmd, expected)`: compare stdout after trimming both ends.
+
+- `command_output_matches_regex(cmd, pattern)`: search stdout with a Python regular expression.
+
+Output checks inspect stdout regardless of the exit code. A timeout fails the check.
+
+### JSON, tables, and databases
+
+- `json_key_equals(path, key, expected)`: compare a top-level JSON object key.
+
+- `json_path_equals(path, json_path, expected)`: follow dot-separated keys and list indices, such as `items.0.name`. This is not JSONPath syntax.
+
+- `csv_cell_equals(path, row, col, expected)`: compare a string cell. Indices start at `0`. A named column treats the first row as a header; an integer column counts that header as row `0`.
+
+- `xlsx_cell_equals(path, cell, expected, sheet=None)`: compare a cell such as `A1`. Defaults to the active sheet and reads cached formula values. Requires the `documents` extra.
+
+- `sqlite_query_equals(db_path, query, expected)`: compare the first column of the first result row.
+
+### HTTP and images
+
+- `http_status_equals(url, status=200)`: send a GET request and compare its status, including HTTP error statuses.
+
+- `http_response_contains(url, text)`: find text in a GET response body. Request errors fail the check. Both HTTP criteria accept `timeout=10` seconds and require network access to the URL.
+
+- `image_size_equals(path, width, height)`: compare pixel dimensions.
+
+- `image_similarity(path1, path2)`: return the fraction of exactly matching RGBA pixels; different dimensions score `0`. Both image criteria require the `image` extra.
+
+### Agent trajectories
+
+Supply an ATIF JSON file in the verifier sandbox and pass its `path`. Do not assume an exported trial trace is already present there.
+
+- `trajectory_tool_used(tool_name, min_count=1)`: require at least this many calls with the matching function name.
+
+- `trajectory_tool_not_used(tool_name)`: require no matching calls.
+
+- `trajectory_turn_count(max_turns)`: score `1` within the agent-turn limit, then decrease linearly to `0` at twice the limit. Use a positive limit.
+
+All three accept `path`; the package default is `/logs/agent/trajectory.json`. A missing trajectory fails the check, including `trajectory_tool_not_used`.
+
+`isolated=True` needs working overlayfs support in the verifier environment. Installing Reward Kit alone does not provide that capability.
+
+## Combine scores
+
+Each Python file that registers checks and each judge TOML produces a score. Criteria use a weighted mean by default, with weight `1` each.
+
+| Configuration | Controls |
+| --- | --- |
+| `[scoring.checks]` in `reward.toml` | Criteria in `checks.py` |
+| `[scoring]` in a judge TOML | Criteria in that judge file |
+| Named `[[reward]]` in root `reward.toml` | Combined output score |
+
+| Aggregation | Result |
+| --- | --- |
+| `weighted-mean` | Weighted average |
+| `weighted-sum` | Sum of score × weight, without normalization |
+| `all-pass` | `1` when every score is greater than `0` |
+| `any-pass` | `1` when any score is greater than `0` |
+| `threshold` | `1` when the weighted mean reaches `threshold`, default `0.5` |
+| `required-pass` | `1` when every non-optional criterion scores above `0`; requires at least one |
+
+With only files directly under `tests/`, Reward Kit combines their scores into `reward`. A judge file can set `[judge].weight`; otherwise each file has equal weight.
+
+### Keep separate dimensions and a primary reward
+
+Subfolders expose separate score keys. For example, use this layout to keep correctness and quality visible:
+
+- tests/
+  - test.sh
+  - reward.toml
+  - correctness/
+    - checks.py
+  - quality/
+    - judge.toml
+
+In the root `tests/reward.toml`, add a named aggregation:
+
+```toml
+[[reward]]
+name = "reward"
+aggregation = "weighted-mean"
+
+[reward.weights]
+correctness = 3
+quality = 1
+```
+
+This keeps the two dimensions and adds their weighted mean under `reward`.
+
+Evolve reads `reward` as the primary score, or the only value in a one-key result. Multiple dimensions without `reward` remain available as metrics but have no primary score.
+
+Keep the primary score within `[0, 1]`. Reward Kit does not clamp custom numbers or `weighted-sum` results; an out-of-range primary score becomes `SCORING_ERROR` on Evolve.
+
+## Add a model judge
+
+For a task that produces `/app/report.md`, a judge can assess the explanation. Install Reward Kit in the image as above, then add this file beside the programmatic checks:
+
+```toml tests/judge.toml
+[judge]
+judge = "anthropic/claude-sonnet-4-6"
+files = ["/app/report.md"]
+timeout = 120
+
+[[criterion]]
+name = "clear-conclusion"
+description = """
+Does the report state a clear conclusion?
+"""
+type = "binary"
+
+[[criterion]]
+name = "supports-conclusion"
+description = """
+How well does the report support
+its conclusion with evidence?
+"""
+type = "likert"
+points = 5
+weight = 2.0
+```
+
+Give the verifier enough time and request the judge credential in `task.toml`. Update the existing `[verifier]` table rather than adding a second one:
+
+```toml task.toml
+[verifier]
+environment_mode = "shared"
+timeout_sec = 180
+
+[verifier.env]
+ANTHROPIC_API_KEY = "${ANTHROPIC_API_KEY}"
+```
+
+Write the template literally. Evolve supplies a scoped gateway credential and base URL at verification time; you do not place a provider key in the task. Judge calls incur usage and can reach the gateway under `no-network`.
+
+Automatic credential detection reads judge TOMLs at the root of a flat `tests/` folder, or one level below it when subfolders exist. Reward Kit itself discovers deeper layouts; keep the explicit credential request above when using them.
+
+| Judge value | Managed support |
+| --- | --- |
+| `anthropic/<model>` | Anthropic-family LLM judge |
+| `openai/<model>` | OpenAI-family LLM judge; request `OPENAI_API_KEY` instead |
+| `claude-code` or `codex` | Agent judge; also set `model` and provide its CLI in the verifier image |
+
+Use [separate verification](/core-concepts/task-verifiers#separate-verification) when the verifier needs its own image. Declare the report in `artifacts` so it reaches that sandbox. The managed judge path does not provide verifier MCP tools or arbitrary provider credentials.
+
+### Judge options
+
+| Option | Behavior |
+| --- | --- |
+| `type = "binary"` | Yes/no becomes `1`/`0` |
+| `type = "likert"`, `points = 5` | A 1–5 rating becomes a score in `[0, 1]` |
+| `type = "numeric"`, `min`, `max` | Normalize the chosen numeric range to `[0, 1]` |
+| `[judge].mode = "individual"` | Grade each criterion separately; allows per-criterion `files` for LLM judges |
+
+The default mode is `batched`. A criterion without its own files uses `[judge].files`.
+
+### Additional judge and criterion options
+
+In `[judge]`:
+
+| Option | Meaning |
+| --- | --- |
+| `timeout` | Response limit in seconds; default `300` |
+| `reasoning_effort` | LLM reasoning setting; default `medium` |
+| `reference` | File or directory supplied as reference material to an LLM judge |
+| `atif-trajectory` | Path to an ATIF file available inside the verifier |
+| `prompt_template` | `.txt` or `.md` path relative to the judge TOML; must contain `{criteria}` |
+| `weight` | This judge file's weight when combined with other files; default `1` |
+| `cwd` | Agent judge's working directory; defaults to the workspace |
+| `version` | Agent CLI version to use |
+| `isolated` | Agent workspace isolation; default `false`, requires overlayfs support |
+
+In each `[[criterion]]`, `name` identifies the result and `description` defines the check. `weight` defaults to `1`. `negate = true` changes the score to `1 - score`. `optional = true` excludes that criterion from `required-pass`; other aggregations still include it.
+
+Keep the task's verifier timeout long enough for the judge. Agent CLIs must be available in the verifier environment; a blocked runtime installer cannot supply them under `no-network`.
+
+For a per-job override, use `--ve REWARDKIT_JUDGE=<judge>` with `evolve run`. `--ve REWARDKIT_MODEL=<model>` selects the model for an agent judge. These are the only two job-level verifier environment overrides; request the matching provider credential family in the task.
+
+## Dependencies and network access
+
+| Need | Install in the verifier's image |
+| --- | --- |
+| Core checks and text judges | `harbor-rewardkit==0.2.1` |
+| PDF, DOCX, PPTX, or XLSX support | `harbor-rewardkit[documents]==0.2.1` |
+| Image criteria | `harbor-rewardkit[image]==0.2.1` |
+
+Evolve stages an offline Reward Kit bundle for judge-enabled runs, not for every deterministic verifier. It contains the base package and dependencies, not optional extras. The bundled `uvx --from harbor-rewardkit...` path cannot fetch a Reward Kit version or extra absent from that bundle.
+
+Installing the package in the image and using `python3 -m rewardkit` makes the dependency choice explicit. HTTP checks and other external calls still need [network access](/core-concepts/task-config#network-access) to their destinations.
+
+**[Verifier environments](/core-concepts/task-verifiers)**
+
+Choose shared or separate verification and transfer the required files.
+
+**[Reward Kit skill](/cli-reference/skills)**
+
+Load `evolve skills get rewardkit` for an agent authoring a verifier.

package/skills/evolve-evals/references/core-concepts/sandboxes.md

@@ -0,0 +1,73 @@
+---
+title: "Sandboxes"
+description: "Choose a cloud provider and understand how task requirements affect placement."
+---
+
+Each trial runs in its own cloud sandbox. Use `-e` to request E2B, Daytona, or Modal; the default is Daytona.
+
+```bash
+evolve run -d harbor-examples@1.0 -i hello-world \
+  -a codex -m gpt-5.6-luna -e modal \
+  --max-trial-spend 1 --max-retries 0 --watch
+```
+
+## Task requirements come first
+
+Evolve checks the requested provider against the task's image, resources, network policy, Compose services, and GPUs.
+
+```mermaid
+%%{init: {"flowchart": {"nodeSpacing": 16, "rankSpacing": 20, "padding": 10}, "themeVariables": {"fontSize": "14px", "fontFamily": "Google Sans Flex, sans-serif"}}}%%
+flowchart TB
+  A["1. Check requested<br/>provider"] -->|"Fits task"| B["2. Use it"]
+  A -->|"Does not fit"| C["2. Check alternatives<br/>E2B → Modal<br/>→ Daytona"]
+  C -->|"Match"| D["3. Use fallback"]
+  C -->|"No match"| E["3. Reject"]
+```
+
+A fallback is recorded as `sandbox_provider_degrade` on the trial. The requested provider on the job and the actual provider on a trial can differ.
+
+If no provider can satisfy the task, Evolve rejects the configuration.
+
+```bash
+evolve dataset show harbor-examples@1.0
+```
+
+Inspect the per-task provider verdicts before starting a larger run. A compatible declaration does not guarantee immediate provider capacity.
+
+## Supported configurations
+
+| Capability | E2B | Daytona | Modal |
+| --- | --- | --- | --- |
+| Single-container tasks | Yes | Yes | Yes |
+| Docker Compose | Yes | Yes | No |
+| GPUs | No | Subject to live quota and GPU type | Yes |
+| Compose with GPUs | No | No | No |
+| Compose with `no-network` | No | No | No |
+
+Network allowlist kinds and resource ceilings also differ. The live [`meta()` document](/sdk-reference/meta) publishes these constraints. Daytona disk and GPU limits depend on the platform's live provider quota.
+
+**Note:**
+
+A temporary capacity shortage can put a trial back in the queue even with `--max-retries 0`. Capacity waits are bounded and separate from ordinary retry attempts.
+
+## Images and startup
+
+Dataset publication prepares task images. A provider may also need to prepare its own cached image or snapshot before the first trial. That first start can take longer than later trials using the cache.
+
+Resources come from the task's `task.toml`. See [task configuration](/core-concepts/task-config) for defaults and how to request CPUs, memory, disk, and GPUs.
+
+## GPU costs
+
+GPU compute is shown as an estimate, separate from model spend:
+
+| Location | Field |
+| --- | --- |
+| Trial | `gpu_cost` |
+| Job totals | `stats.gpu_cost_usd` |
+| CLI trial view | `gpu compute (est.)` |
+
+An unavailable estimate includes `unpriced_reason`. Do not add this estimate to the metered model cost and present it as the same charge.
+
+## Analysis and checks
+
+These operations also use sandboxes. Choose their provider with `-e` on `evolve analyze` or `evolve check`, or `--analyze-provider` for analysis attached to a run. Their default is Daytona unless the platform operator configures another provider; the [SDK defaults](/sdk-reference/analyses#read-current-defaults) expose the resolved setting.

package/skills/evolve-evals/references/core-concepts/secrets.md

@@ -0,0 +1,86 @@
+---
+title: "Secrets"
+description: "Store a credential once and attach it to evaluation jobs by name."
+---
+
+Secret values are write-only. Reads return metadata, and jobs store references to the selected secret rows.
+
+```text
+1. Store the secret
+   GITHUB_TOKEN
+         ↓
+2. Attach its reference
+   --secret GITHUB_TOKEN
+         ↓
+3. Run the trial
+   Value enters agent environment
+```
+
+## Store a value
+
+```bash
+printf %s "$GITHUB_TOKEN" | evolve secrets set GITHUB_TOKEN --delivery direct
+```
+
+Piping keeps the value out of the command text. Use `--label staging` to store a labeled variant; the default label is `default`.
+
+Eval jobs support **direct** delivery: the value enters the agent sandbox. Brokered secrets are supported by other Evolve surfaces but are rejected for managed evals.
+
+## Attach it to a job
+
+```bash
+evolve run -d my-dataset@1.0 -a codex -m gpt-5.6-luna \
+  --secret GITHUB_TOKEN@staging \
+  --max-trial-spend 1 --max-retries 0 --watch
+```
+
+| Attachment | Meaning |
+| --- | --- |
+| `GITHUB_TOKEN` | Use the default label, or the only available label |
+| `GITHUB_TOKEN@staging` | Select the `staging` value |
+| `GITHUB_TOKEN@staging=GH_TOKEN` | Expose it as `GH_TOKEN` inside the sandbox |
+
+If several labels exist and none is `default`, select one explicitly. Every arm receives the attachment. Reserved routing names and the `EVOLVE_` prefix cannot be overwritten.
+
+## Request it from a task
+
+```toml task.toml
+[environment.env]
+GITHUB_TOKEN = "${GITHUB_TOKEN}"
+```
+
+The template matches the attached environment name. A missing required attachment rejects the job. For a non-secret fallback, use `"${NAME:-fallback}"`.
+
+Task literals belong in `[environment.env]`. Managed eval jobs do not accept arbitrary `agent_env` values through `--ae`.
+
+## List, replace, or remove
+
+```bash
+evolve secrets list
+evolve secrets delete GITHUB_TOKEN --label staging
+```
+
+A different value under an existing name and label is rejected with `secret_exists`. Use a new label, or delete the old row before storing its replacement. Removing or disabling a secret needed by an unfinished job can cause its later trials to fail.
+
+### Save and attach in one request
+
+The SDK accepts both references and inline values in a job's `secrets` list:
+
+```json
+{
+  "secrets": [
+    {"name": "GITHUB_TOKEN", "label": "staging"},
+    {"name": "SERVICE_TOKEN", "value": "VALUE", "delivery": "direct"}
+  ]
+}
+```
+
+An inline value is saved before the job stores its reference. Repeating the same value and delivery resolves to the existing row; a conflicting value is rejected. The CLI equivalent is `--secret-inline NAME[@LABEL]:DELIVERY=VALUE`.
+
+**[Secret commands](/cli-reference/secrets)**
+
+Storage, labels, and delivery options.
+
+**[Secret SDK](/sdk-reference/secrets)**
+
+Manage secrets from Python or TypeScript.

package/skills/evolve-evals/references/core-concepts/sharing.md

@@ -0,0 +1,81 @@
+---
+title: "Sharing"
+description: "Give someone read access to a job, check, or managed-agent session."
+---
+
+Share a run you created by email or by an unlisted link. Both can be enabled at the same time.
+
+| Method | Who can open it? | Sign-in |
+| --- | --- | --- |
+| Email | The account using that address. | Required. |
+| Link | Anyone holding the link. | Not required. |
+
+### By email
+
+```bash
+evolve job share "$JOB_ID" --email teammate@example.org
+```
+
+This sends an email with the run's address. An eligible new recipient also receives a signup link. The run appears under their shared work after sign-in.
+
+### By link
+
+```bash
+evolve job share "$JOB_ID" --link
+```
+
+The command prints an unlisted URL. Keep using that URL until you revoke it.
+
+Only the creator can share or revoke a share. Read access does not grant cancellation, retry, analysis, or deletion permission. A recipient who is already a team member retains their separate membership permissions.
+
+## Inspect or revoke access
+
+```bash
+evolve job shares "$JOB_ID"
+evolve job unshare "$JOB_ID" --email teammate@example.org
+evolve job unshare "$JOB_ID" --link
+```
+
+Revoking a link disables it immediately. Enabling link sharing later produces a new link.
+
+The same commands apply to other run types:
+
+| Run | Commands |
+| --- | --- |
+| Job | `evolve job share`, `unshare`, `shares` |
+| Check | `evolve check share`, `unshare`, `shares` |
+| Managed-agent session | `evolve session share`, `unshare`, `shares` |
+
+## What a link shows
+
+| Run | Readable content |
+| --- | --- |
+| Job | Summary, trials, traces, and available permitted logs and files. |
+| Check | Report, task-check results, and downloadable check archive. |
+| Session | Transcript and trace download. Browser replay and session filesystem are not included. |
+
+Sharing a run does not make its dataset public. Task-file access still follows the underlying dataset rules.
+
+## In the dashboard
+
+### 1. Open a run you created
+
+Open the job, check, or session, then choose **Share**.
+
+### 2. Choose the audience
+
+Enter an email address and invite, or enable **Anyone with the link**.
+
+### 3. Review access later
+
+Return to the same dialog to inspect recipients or disable the link.
+
+Email-shared runs appear in **Shared with me** under your personal workspace's Traces page.
+
+**[Share commands](/cli-reference/job)**
+
+Exact flags and share-state output.
+
+**[Teams](/core-concepts/teams)**
+
+Access through workspace membership.