outerloop-science 0.5.0__tar.gz → 0.6.0__tar.gz

outerloop_science-0.6.0/.claude-plugin/marketplace.json

@@ -0,0 +1,14 @@
+{
+  "name": "outerloop",
+  "owner": {
+    "name": "Outerloop"
+  },
+  "plugins": [
+    {
+      "name": "outerloop",
+      "source": "./plugins/outerloop",
+      "category": "Productivity"
+    }
+  ],
+  "description": "Set up and operate Outerloop from your coding agent."
+}

{outerloop_science-0.5.0 → outerloop_science-0.6.0}/CHANGELOG.md

@@ -6,6 +6,46 @@ Versions follow [SemVer](https://semver.org).
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-10-26
+
+### Upgrading
+
+No operator action is needed before upgrading; details in each entry.
+
+What changes for runs in flight: runs started before the upgrade have no
+trajectory until their next recorded event, and their earlier session events
+count as author sessions. The first run to end creates the attestation key
+`trajectory_attest.key`, owner-only, beside the operator settings file. On
+macOS without an image, sessions, evaluations and panel lenses now run under
+the Seatbelt profile, which allows outbound connections only to TCP port 443,
+DNS and local ports.
+
+Before rolling back: if you switched the author to a Claude subscription
+token, switch back to an API key, since older kernels send the token as
+`ANTHROPIC_API_KEY`. Older kernels ignore `trajectory.jsonl`, the attestation
+key and `OUTERLOOP_AUTHOR_EFFORT`, and pending ledger records are unchanged.
+
+### Changes
+
+- `OUTERLOOP_AUTHOR_EFFORT` sets the author's effort level (`low`, `medium`, `high`, `xhigh` or `max`) on every backend: Claude Code's `--effort` (the pinned 2.1.285 has the flag), Codex's `model_reasoning_effort` as a kernel-owned `-c` setting, and Hermes's `agent.reasoning_effort`. For Hermes the setting is written to the seeded `config.yaml`, and the capture wrapper also hands it to the agent, because `run_agent.main` builds its agent without a reasoning config and would otherwise ignore it. Unset keeps each harness's default. Panel judges and the steward ignore it, so a cheaper author does not change how its work is reviewed. Start, the tick and each wake refuse an unknown level. The setting is read when each session starts and is not stored in run records.
+- Run endings append one `attest` trajectory event: an HMAC-SHA256 over the run id and chain head with a deployment key created owner-only beside the operator settings file, and `outerloop trajectory --verify` reports `attested` or `attestation mismatch`. Older kernels ignore the event; no ledger or PR-body change.
+- The PR body gains a report-only Number check that lists values in the author's report matching no `measure` event or Experiments result when rounded to the report's decimals; nothing is blocked and no trajectory event is added.
+- Session end records each tool call from the retained Claude or Codex log as a `tool.call` trajectory event, once per call even when a session resumes. `outerloop trajectory` and a new Process section in the PR body show counts by tool. Older kernels ignore these events.
+- `outerloop status` shows a run's priced session cost as a lower bound when some legs are unpriced (a wake killed mid-turn leaves no usage event), for example `session-cost>=$4.2000 (1 unpriced)`, instead of hiding the priced part behind `unknown`; the status row and JSON gain the priced-leg count (#516).
+- The pre-PR panel accepts a composite change — a PR that carries several changes — when the report gives each component's isolated measurement and the combination's under the same protocol and the combination is what the kernel measured. A bundle without those isolated measurements stays blocked (#489).
+- Claude sessions can use a subscription token from `claude setup-token` (`sk-ant-oat...`). The harness sends it as `CLAUDE_CODE_OAUTH_TOKEN`, not `ANTHROPIC_API_KEY`, and `init` accepts it. A panel judge on a token runs `claude --safe-mode`, because `--bare` cannot read OAuth tokens. Both modes ignore the checkout's CLAUDE.md, hooks, plugins and MCP servers. The pinned Claude Code release (2.1.285) has `--safe-mode`.
+- A session now hears once when a live sibling states a new or changed hypothesis (#360). The note names the sibling, quotes its hypothesis, and points to `siblings` for its launches and score. It is sent only when `channels.siblings` is on. Upgrading: the note uses the existing `note` kind, so an older kernel shows it as ordinary inbox text.
+- A skills-only plugin for Claude Code and Codex sets up Outerloop, writes and validates the contract, and operates runs from the agent (#562). Install it with `/plugin marketplace add outerloop-science/outerloop` or `codex plugin marketplace add outerloop-science/outerloop`. Its setup skill offers a Claude subscription token from `claude setup-token` as the author credential.
+- `outerloop trajectory <run-id>` now ends with the run's refusal count and its author models, for release canary comparisons; the agent-text inventory includes operator notes (#487, part 3). Session events record `role` (`author` or `judge`). Upgrading: session events written before this kernel have no `role` and count as author sessions.
+- On macOS without an image, sessions, evaluations and panel lenses run under a packaged Seatbelt profile (`sandbox-exec`, #292): they write only the workspace and a scratch directory, read only system and toolchain paths, and connect out only to TCP port 443, DNS and local ports. Linux and Apptainer runs are unchanged.
+- Kernel events now append to a per-run `trajectory.jsonl` with sequence numbers and a SHA-256 chain. `outerloop trajectory <run-id> [--verify] [--json]` reads it without changing run state. Operational files and their formats are unchanged; older kernels ignore the new file. Upgrading: runs started before this kernel have no trajectory and read as "no trajectory" until their next recorded event. No backfill is attempted.
+- `measure` trajectory events carry provenance: the ledger's ruler digest (the same value a pending submission computes), the container image digest when an image is configured, and refs to the evaluation result files the kernel read. Self-reported measures record the ruler alone. Pending ledger records now ignore fields this kernel does not know, so a later release can add one without breaking this release's ledger read. Upgrading: no action needed; older kernels ignore the trajectory, and pending records are unchanged.
+- Add a printable agent-text inventory and protocol wording lint, with clearer refusal recovery guidance (#487, parts 1–2).
+- `BENCHMARKS.md` shows `—` instead of "provenance unknown" in the main-commit column of a baseline row that nothing has improved on yet, as on a freshly seeded repository.
+- The README and the getting-started guide link to the quickstart repository. It runs two CPU benchmarks with the local forge and local compute, and needs no GitHub account or cluster (#563). The docs and the startup warning no longer say an uncontained session runs in a sandbox: on Linux without an image, it gets a scrubbed environment and its own home, but can read any file the account can.
+- The advisory review covers exactly the head its triggering event named (`REVIEW_HEAD_SHA`, #462). If the PR has moved off that head, nothing is reviewed or posted. Otherwise the diff is read between fixed commits, every envelope records the reviewed `head_sha`, and the review is attached to that commit. When GitHub refuses its inline comments, the fallback is a body-only review on the same commit, never an unpinned comment (#569). The summarizer skips clean when its lenses read different heads. For a fork PR (`REVIEW_CHECKOUT_BASE=1`) the brief says the tree is the base branch and the change is only in the diff. Upgrading: envelopes without `head_sha` (from an older reviewer ref) still post; callers that do not pass REVIEW_HEAD_SHA behave as before.
+- When check runs cannot be read on a token deployment, the warning now says the token cannot read them (fine-grained tokens have no checks permission) instead of asking for an App permission.
+
 ## [0.5.0] - 2026-10-23
 
 ### Upgrading

{outerloop_science-0.5.0 → outerloop_science-0.6.0}/CITATION.cff

@@ -13,5 +13,5 @@ authors:
 repository-code: "https://github.com/outerloop-science/outerloop"
 url: "https://outerloop.science"
 license: Apache-2.0
-version: 0.5.0
-date-released: "2026-10-23"
+version: 0.6.0
+date-released: "2026-10-26"

{outerloop_science-0.5.0 → outerloop_science-0.6.0}/CONTRIBUTING.md

@@ -61,6 +61,19 @@ uv run pytest
   `uv lock`; CI checks the lock.
 - Docs are plain prose. Short sentences, no metaphors, no internal jargon.
 
+New agent-facing text must be reachable from `outerloop.agent_text.inventory()`.
+Keep text with its renderer and add a representative rendering to the inventory;
+review it with `python -m outerloop.agent_text`. The fast lint in
+`tests/test_agent_text.py` checks protocol terms, syscall names, and refusal recovery
+guidance. Keep refusals inline: the inventory reads explicit AST constructs listed in
+`REFUSAL_CONSTRUCTS`, rendering f-string expressions as `{}`. Input constraints
+use category `validation` and need no redundant next step. The syscall CLI mixes
+constraints and state refusals in `ToolError`; `CLI_REFUSALS` identifies the latter
+by function and call ordinal, so update it when adding or reordering those calls. Delivery reasons composed into a
+refusal use category `reason`; the enclosing refusal carries recovery guidance.
+Kernel refusals require a next step; any exception needs a specific reason beside
+the lint rule.
+
 ## Tests
 
 | Tier | Marker | Runs |

{outerloop_science-0.5.0 → outerloop_science-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: outerloop-science
-Version: 0.5.0
+Version: 0.6.0
 Summary: Autonomous research agents that improve the benchmark you point them at, one verified pull request at a time
 Project-URL: Homepage, https://outerloop.science
 Project-URL: Repository, https://github.com/outerloop-science/outerloop
@@ -41,6 +41,11 @@ change, runs the experiment on your cluster, and opens a pull request only
 when your benchmark actually improves. Every attempt ends in a short
 written report, including the attempts that failed.
 
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/outerloop-science/outerloop/main/docs/assets/loop-dark.svg">
+  <img alt="One attempt: an agent proposes a change, runs the experiment on your GPUs, the kernel re-measures it against the base, judges review the claim, and a pull request opens with a written report. Without a real gain the attempt ends in a report and the next hypothesis starts." src="https://raw.githubusercontent.com/outerloop-science/outerloop/main/docs/assets/loop.svg" width="880">
+</picture>
+
 You run it yourself, with your own keys, your own compute and your own
 repositories, and nothing reports back to us. It is built and used every
 day by the [Agentic Learning AI Lab](https://agenticlearning.ai) at NYU,
@@ -48,7 +53,24 @@ where it co-develops our research codebases.
 
 ## Get started
 
-Three commands and one file. You need a repo with a benchmark command, an
+To see a run first, the [quickstart](https://github.com/outerloop-science/quickstart)
+runs two CPU benchmarks on your own machine, with no GitHub account and no
+cluster. You need Python 3.12 or later, [uv](https://docs.astral.sh/uv/), Git
+2.38 or later and an Anthropic API key:
+
+```bash
+pip install outerloop-science
+outerloop init --forge local --compute local --no-image --target me/quickstart \
+  --forge-source https://github.com/outerloop-science/quickstart
+outerloop start
+```
+
+On macOS, sessions and evaluations run under a Seatbelt profile: they write their
+workspace and a scratch directory, read system and toolchain paths, and cannot read
+the rest of your home. On Linux without a container they can read any file your
+account can. Either way, use a spend-capped API key.
+
+For your own repository: three commands and one file. You need a repo with a benchmark command, an
 API key for the model that will write the code, and a Slurm cluster or one
 machine with a GPU.
 
@@ -60,8 +82,10 @@ outerloop init     # where the loop runs, which repo, which model and its key, y
 The wizard asks for a GitHub identity for the agents to open pull requests
 as. Pick `app` and it walks you through creating a GitHub App under your
 account and installing it on the repo. Pick `pat` if you already have a
-token, and it writes the config and the key files either way. Then add one
-file, `.outerloop.yaml`, to the repo you want improved:
+token, and it writes the config and the key files either way. To try it
+without GitHub, `outerloop init --forge local` keeps the repository and its
+pull requests in a git repository on the same machine. Then add one file,
+`.outerloop.yaml`, to the repo you want improved:
 
 ```yaml
 benchmarks:
@@ -128,8 +152,8 @@ build. See [the reviewer guide](https://docs.outerloop.science/reviewer/).
   output are rendered to the agent as fenced data, not instructions, which
   lowers the risk of injected text being followed without guaranteeing it.
   A contained session gets no GitHub credential in its environment and
-  cannot read the operator's key files; an uncontained local session runs
-  as your user and can read any file you can, key files included.
+  cannot read the operator's key files. Without a container, a macOS session
+  runs under Seatbelt; a Linux session can read any file you can, key files included.
 - **Budgets in code.** Launches, GPU-hours, and runs per week are enforced
   by the kernel, not left to the agent.
 - **No model lock-in.** Claude Code, Codex, and hermes-agent are wired

{outerloop_science-0.5.0 → outerloop_science-0.6.0}/README.md

@@ -17,6 +17,11 @@ change, runs the experiment on your cluster, and opens a pull request only
 when your benchmark actually improves. Every attempt ends in a short
 written report, including the attempts that failed.
 
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/outerloop-science/outerloop/main/docs/assets/loop-dark.svg">
+  <img alt="One attempt: an agent proposes a change, runs the experiment on your GPUs, the kernel re-measures it against the base, judges review the claim, and a pull request opens with a written report. Without a real gain the attempt ends in a report and the next hypothesis starts." src="https://raw.githubusercontent.com/outerloop-science/outerloop/main/docs/assets/loop.svg" width="880">
+</picture>
+
 You run it yourself, with your own keys, your own compute and your own
 repositories, and nothing reports back to us. It is built and used every
 day by the [Agentic Learning AI Lab](https://agenticlearning.ai) at NYU,
@@ -24,7 +29,24 @@ where it co-develops our research codebases.
 
 ## Get started
 
-Three commands and one file. You need a repo with a benchmark command, an
+To see a run first, the [quickstart](https://github.com/outerloop-science/quickstart)
+runs two CPU benchmarks on your own machine, with no GitHub account and no
+cluster. You need Python 3.12 or later, [uv](https://docs.astral.sh/uv/), Git
+2.38 or later and an Anthropic API key:
+
+```bash
+pip install outerloop-science
+outerloop init --forge local --compute local --no-image --target me/quickstart \
+  --forge-source https://github.com/outerloop-science/quickstart
+outerloop start
+```
+
+On macOS, sessions and evaluations run under a Seatbelt profile: they write their
+workspace and a scratch directory, read system and toolchain paths, and cannot read
+the rest of your home. On Linux without a container they can read any file your
+account can. Either way, use a spend-capped API key.
+
+For your own repository: three commands and one file. You need a repo with a benchmark command, an
 API key for the model that will write the code, and a Slurm cluster or one
 machine with a GPU.
 
@@ -36,8 +58,10 @@ outerloop init     # where the loop runs, which repo, which model and its key, y
 The wizard asks for a GitHub identity for the agents to open pull requests
 as. Pick `app` and it walks you through creating a GitHub App under your
 account and installing it on the repo. Pick `pat` if you already have a
-token, and it writes the config and the key files either way. Then add one
-file, `.outerloop.yaml`, to the repo you want improved:
+token, and it writes the config and the key files either way. To try it
+without GitHub, `outerloop init --forge local` keeps the repository and its
+pull requests in a git repository on the same machine. Then add one file,
+`.outerloop.yaml`, to the repo you want improved:
 
 ```yaml
 benchmarks:
@@ -104,8 +128,8 @@ build. See [the reviewer guide](https://docs.outerloop.science/reviewer/).
   output are rendered to the agent as fenced data, not instructions, which
   lowers the risk of injected text being followed without guaranteeing it.
   A contained session gets no GitHub credential in its environment and
-  cannot read the operator's key files; an uncontained local session runs
-  as your user and can read any file you can, key files included.
+  cannot read the operator's key files. Without a container, a macOS session
+  runs under Seatbelt; a Linux session can read any file you can, key files included.
 - **Budgets in code.** Launches, GPU-hours, and runs per week are enforced
   by the kernel, not left to the agent.
 - **No model lock-in.** Claude Code, Codex, and hermes-agent are wired

{outerloop_science-0.5.0 → outerloop_science-0.6.0}/RELEASING.md

@@ -43,21 +43,24 @@ wording does not reach a parked run unless its deduplication key changes.
    run with an open PR, a run whose PR merged, and an ended run. A dev or rc pre-release still bumps the version (PyPI never
    accepts a version twice, so the next one is `.dev1`, `rc2`, ...) but leaves
    `[Unreleased]` in place until the final release.
-3. `git tag vX.Y.Z && git push origin vX.Y.Z`. The `release` workflow builds
+3. Pre-release canary runs report `refusals` per run by author model from
+   `outerloop trajectory <run-id>`. If refusals per run rise against the previous
+   release, explain why in the release PR before shipping.
+4. `git tag vX.Y.Z && git push origin vX.Y.Z`. The `release` workflow builds
    and publishes `outerloop-science` to PyPI through Trusted Publishing; the
    one-time PyPI setup is described at the top of
    `.github/workflows/release.yml`.
-4. Once the `release` workflow run for the tag is green (`gh run watch` on
+5. Once the `release` workflow run for the tag is green (`gh run watch` on
    it), `pip install outerloop-science==X.Y.Z` in a fresh venv, then
    `outerloop --help`. This comes before the GitHub release: publishing it is
    what Discord announces, so nothing is announced that did not install.
-5. `gh release create vX.Y.Z --generate-notes`, with `--prerelease` for a dev
+6. `gh release create vX.Y.Z --generate-notes`, with `--prerelease` for a dev
    or rc tag.
    For a final release, also move the `v0` tag that external callers of the
    reusable workflows track: `git tag -f v0 vX.Y.Z && git push -f origin v0`.
    Dev and rc tags never move it. This tag alias is the one force-push the
    repository allows; branches are never force-pushed.
-6. Announce. Discord's `#announcements` gets the release from the GitHub
+7. Announce. Discord's `#announcements` gets the release from the GitHub
    webhook on its own (docs/community.md). For a final release, also write
    the post for X (`@outerloop_sci`) and Bluesky (`@outerloop.science`): one
    or two sentences on what changed for the reader, the install line, the

outerloop_science-0.6.0/docs/assets/loop-dark.svg

@@ -0,0 +1,86 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 880 210" width="880" height="210" role="img" aria-label="One Outerloop attempt: an agent proposes a change, runs the experiment on your GPUs, the kernel re-measures it against the base, judges review the claim, and a pull request opens with a written report. Without a real gain the attempt ends in a report and the next hypothesis.">
+<style>
+  svg { --fg: #e4e7eb; --muted: #9aa5b1; --line: #3e4c59; --card: #161b22; --accent: #6ea2ff; --good: #4cc38a; }
+  text { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif; fill: var(--fg); }
+  .title { font-size: 15px; font-weight: 600; }
+  .sub { font-size: 12px; fill: var(--muted); }
+  .node { fill: var(--card); stroke: var(--line); stroke-width: 1.5; }
+  .edge { stroke: var(--line); stroke-width: 1.5; fill: none; }
+  .back { stroke: var(--line); stroke-width: 1.5; fill: none; stroke-dasharray: 5 5; }
+  .head { fill: var(--line); }
+  .dot { fill: var(--accent); }
+  .score { font-size: 12px; font-variant-numeric: tabular-nums; fill: var(--fg); }
+  .ok { fill: var(--good); font-weight: 600; }
+  .pr { fill: var(--accent); font-weight: 600; font-size: 12px; }
+
+  .n1 { animation: lit1 12s infinite; } .n2 { animation: lit2 12s infinite; }
+  .n3 { animation: lit3 12s infinite; } .n4 { animation: lit4 12s infinite; }
+  .n5 { animation: lit5 12s infinite; }
+
+  @keyframes lit1 { 0%, 11% { stroke: var(--accent); stroke-width: 2.5; } 13%, 100% { stroke: var(--line); stroke-width: 1.5; } }
+  @keyframes lit2 { 0%, 15% { stroke: var(--line); stroke-width: 1.5; } 16%, 31% { stroke: var(--accent); stroke-width: 2.5; } 33%, 100% { stroke: var(--line); stroke-width: 1.5; } }
+  @keyframes lit3 { 0%, 35% { stroke: var(--line); stroke-width: 1.5; } 36%, 53% { stroke: var(--accent); stroke-width: 2.5; } 55%, 100% { stroke: var(--line); stroke-width: 1.5; } }
+  @keyframes lit4 { 0%, 57% { stroke: var(--line); stroke-width: 1.5; } 58%, 71% { stroke: var(--accent); stroke-width: 2.5; } 73%, 100% { stroke: var(--line); stroke-width: 1.5; } }
+  @keyframes lit5 { 0%, 75% { stroke: var(--line); stroke-width: 1.5; } 76%, 96% { stroke: var(--accent); stroke-width: 2.5; } 98%, 100% { stroke: var(--line); stroke-width: 1.5; } }
+
+  @media (prefers-reduced-motion: reduce) {
+    .n1, .n2, .n3, .n4, .n5 { animation: none; }
+  }
+</style>
+
+<!-- edges between the five steps -->
+<g>
+  <line class="edge" x1="172" y1="68" x2="186" y2="68"/><polygon class="head" points="192,68 184,64 184,72"/>
+  <line class="edge" x1="344" y1="68" x2="358" y2="68"/><polygon class="head" points="364,68 356,64 356,72"/>
+  <line class="edge" x1="516" y1="68" x2="530" y2="68"/><polygon class="head" points="536,68 528,64 528,72"/>
+  <line class="edge" x1="688" y1="68" x2="702" y2="68"/><polygon class="head" points="708,68 700,64 700,72"/>
+</g>
+
+<!-- the steps -->
+<g>
+  <rect class="node n1" x="20" y="36" width="152" height="64" rx="10"/>
+  <text class="title" x="96" y="63" text-anchor="middle">Propose</text>
+  <text class="sub" x="96" y="83" text-anchor="middle">agent edits the solver</text>
+
+  <rect class="node n2" x="192" y="36" width="152" height="64" rx="10"/>
+  <text class="title" x="268" y="63" text-anchor="middle">Experiment</text>
+  <text class="sub" x="268" y="83" text-anchor="middle">jobs on your GPUs</text>
+
+  <rect class="node n3" x="364" y="36" width="152" height="64" rx="10"/>
+  <text class="title" x="440" y="63" text-anchor="middle">Measure</text>
+  <text class="sub" x="440" y="83" text-anchor="middle">Outerloop re-measures</text>
+
+  <rect class="node n4" x="536" y="36" width="152" height="64" rx="10"/>
+  <text class="title" x="612" y="63" text-anchor="middle">Review</text>
+  <text class="sub" x="612" y="83" text-anchor="middle">judges read the claim</text>
+
+  <rect class="node n5" x="708" y="36" width="152" height="64" rx="10"/>
+  <text class="title" x="784" y="63" text-anchor="middle">Pull request</text>
+  <text class="sub" x="784" y="83" text-anchor="middle">with a written report</text>
+</g>
+
+<!-- the attempt moving through -->
+<circle class="dot" cx="96" cy="22" r="6">
+  <animateTransform attributeName="transform" type="translate" dur="12s" repeatCount="indefinite"
+    values="0 0; 0 0; 172 0; 172 0; 344 0; 344 0; 516 0; 516 0; 688 0; 688 0"
+    keyTimes="0; 0.10; 0.16; 0.30; 0.36; 0.52; 0.58; 0.70; 0.76; 1"/>
+</circle>
+
+<!-- what the measure step reports -->
+<g class="readout" opacity="0">
+  <animate attributeName="opacity" dur="12s" repeatCount="indefinite"
+    values="0; 0; 1; 1; 0" keyTimes="0; 0.39; 0.42; 0.94; 1"/>
+  <text class="score" x="440" y="124" text-anchor="middle">base 9,472 steps → candidate 7,808</text>
+  <text class="score ok" x="440" y="142" text-anchor="middle">more than run-to-run noise</text>
+</g>
+<g class="badge" opacity="0">
+  <animate attributeName="opacity" dur="12s" repeatCount="indefinite"
+    values="0; 0; 1; 1; 0" keyTimes="0; 0.78; 0.81; 0.94; 1"/>
+  <text class="pr" x="784" y="124" text-anchor="middle">opened for a human to merge</text>
+</g>
+
+<!-- no gain: report and try again -->
+<path class="back" d="M 440 154 L 440 176 L 96 176 L 96 108"/>
+<polygon class="head" points="96,102 92,110 100,110"/>
+<text class="sub" x="268" y="196" text-anchor="middle">no real gain: the report says why, and the next hypothesis starts</text>
+</svg>

outerloop_science-0.6.0/docs/assets/loop.svg

@@ -0,0 +1,86 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 880 210" width="880" height="210" role="img" aria-label="One Outerloop attempt: an agent proposes a change, runs the experiment on your GPUs, the kernel re-measures it against the base, judges review the claim, and a pull request opens with a written report. Without a real gain the attempt ends in a report and the next hypothesis.">
+<style>
+  svg { --fg: #1f2933; --muted: #616e7c; --line: #c4cdd5; --card: #ffffff; --accent: #3c81f7; --good: #1f8a4c; }
+  text { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif; fill: var(--fg); }
+  .title { font-size: 15px; font-weight: 600; }
+  .sub { font-size: 12px; fill: var(--muted); }
+  .node { fill: var(--card); stroke: var(--line); stroke-width: 1.5; }
+  .edge { stroke: var(--line); stroke-width: 1.5; fill: none; }
+  .back { stroke: var(--line); stroke-width: 1.5; fill: none; stroke-dasharray: 5 5; }
+  .head { fill: var(--line); }
+  .dot { fill: var(--accent); }
+  .score { font-size: 12px; font-variant-numeric: tabular-nums; fill: var(--fg); }
+  .ok { fill: var(--good); font-weight: 600; }
+  .pr { fill: var(--accent); font-weight: 600; font-size: 12px; }
+
+  .n1 { animation: lit1 12s infinite; } .n2 { animation: lit2 12s infinite; }
+  .n3 { animation: lit3 12s infinite; } .n4 { animation: lit4 12s infinite; }
+  .n5 { animation: lit5 12s infinite; }
+
+  @keyframes lit1 { 0%, 11% { stroke: var(--accent); stroke-width: 2.5; } 13%, 100% { stroke: var(--line); stroke-width: 1.5; } }
+  @keyframes lit2 { 0%, 15% { stroke: var(--line); stroke-width: 1.5; } 16%, 31% { stroke: var(--accent); stroke-width: 2.5; } 33%, 100% { stroke: var(--line); stroke-width: 1.5; } }
+  @keyframes lit3 { 0%, 35% { stroke: var(--line); stroke-width: 1.5; } 36%, 53% { stroke: var(--accent); stroke-width: 2.5; } 55%, 100% { stroke: var(--line); stroke-width: 1.5; } }
+  @keyframes lit4 { 0%, 57% { stroke: var(--line); stroke-width: 1.5; } 58%, 71% { stroke: var(--accent); stroke-width: 2.5; } 73%, 100% { stroke: var(--line); stroke-width: 1.5; } }
+  @keyframes lit5 { 0%, 75% { stroke: var(--line); stroke-width: 1.5; } 76%, 96% { stroke: var(--accent); stroke-width: 2.5; } 98%, 100% { stroke: var(--line); stroke-width: 1.5; } }
+
+  @media (prefers-reduced-motion: reduce) {
+    .n1, .n2, .n3, .n4, .n5 { animation: none; }
+  }
+</style>
+
+<!-- edges between the five steps -->
+<g>
+  <line class="edge" x1="172" y1="68" x2="186" y2="68"/><polygon class="head" points="192,68 184,64 184,72"/>
+  <line class="edge" x1="344" y1="68" x2="358" y2="68"/><polygon class="head" points="364,68 356,64 356,72"/>
+  <line class="edge" x1="516" y1="68" x2="530" y2="68"/><polygon class="head" points="536,68 528,64 528,72"/>
+  <line class="edge" x1="688" y1="68" x2="702" y2="68"/><polygon class="head" points="708,68 700,64 700,72"/>
+</g>
+
+<!-- the steps -->
+<g>
+  <rect class="node n1" x="20" y="36" width="152" height="64" rx="10"/>
+  <text class="title" x="96" y="63" text-anchor="middle">Propose</text>
+  <text class="sub" x="96" y="83" text-anchor="middle">agent edits the solver</text>
+
+  <rect class="node n2" x="192" y="36" width="152" height="64" rx="10"/>
+  <text class="title" x="268" y="63" text-anchor="middle">Experiment</text>
+  <text class="sub" x="268" y="83" text-anchor="middle">jobs on your GPUs</text>
+
+  <rect class="node n3" x="364" y="36" width="152" height="64" rx="10"/>
+  <text class="title" x="440" y="63" text-anchor="middle">Measure</text>
+  <text class="sub" x="440" y="83" text-anchor="middle">Outerloop re-measures</text>
+
+  <rect class="node n4" x="536" y="36" width="152" height="64" rx="10"/>
+  <text class="title" x="612" y="63" text-anchor="middle">Review</text>
+  <text class="sub" x="612" y="83" text-anchor="middle">judges read the claim</text>
+
+  <rect class="node n5" x="708" y="36" width="152" height="64" rx="10"/>
+  <text class="title" x="784" y="63" text-anchor="middle">Pull request</text>
+  <text class="sub" x="784" y="83" text-anchor="middle">with a written report</text>
+</g>
+
+<!-- the attempt moving through -->
+<circle class="dot" cx="96" cy="22" r="6">
+  <animateTransform attributeName="transform" type="translate" dur="12s" repeatCount="indefinite"
+    values="0 0; 0 0; 172 0; 172 0; 344 0; 344 0; 516 0; 516 0; 688 0; 688 0"
+    keyTimes="0; 0.10; 0.16; 0.30; 0.36; 0.52; 0.58; 0.70; 0.76; 1"/>
+</circle>
+
+<!-- what the measure step reports -->
+<g class="readout" opacity="0">
+  <animate attributeName="opacity" dur="12s" repeatCount="indefinite"
+    values="0; 0; 1; 1; 0" keyTimes="0; 0.39; 0.42; 0.94; 1"/>
+  <text class="score" x="440" y="124" text-anchor="middle">base 9,472 steps → candidate 7,808</text>
+  <text class="score ok" x="440" y="142" text-anchor="middle">more than run-to-run noise</text>
+</g>
+<g class="badge" opacity="0">
+  <animate attributeName="opacity" dur="12s" repeatCount="indefinite"
+    values="0; 0; 1; 1; 0" keyTimes="0; 0.78; 0.81; 0.94; 1"/>
+  <text class="pr" x="784" y="124" text-anchor="middle">opened for a human to merge</text>
+</g>
+
+<!-- no gain: report and try again -->
+<path class="back" d="M 440 154 L 440 176 L 96 176 L 96 108"/>
+<polygon class="head" points="96,102 92,110 100,110"/>
+<text class="sub" x="268" y="196" text-anchor="middle">no real gain: the report says why, and the next hypothesis starts</text>
+</svg>

outerloop_science-0.6.0/docs/design/trajectory.md

@@ -0,0 +1,67 @@
+# Run trajectory
+
+The kernel alone writes `runs/<run-id>/trajectory.jsonl`, outside the session's
+workspace and writable sandbox mounts. Operational state, launch ledgers,
+inbox/outbox and session records continue unchanged. The trajectory is a
+best-effort timeline, not a replacement for those recovery records.
+
+Each line is a JSON object with sorted keys: `seq` (starting at zero), `ts`
+(Unix seconds), `type`, `actor`, `data`, `refs`, and `prev`. `prev` is SHA-256
+of the previous event's exact bytes excluding its newline; the first event
+uses SHA-256 of the UTF-8 run id. Actors use `kernel`, `author:<agent-id>`,
+`judge:<name>`, or `human:<login>`; these kernel actions use `kernel`.
+Refs contain run-relative `path` and `sha256` fields. Native session logs are
+hashed once at session end, and the report is hashed at ending.
+
+Events cover session start/end, syscall acceptance/refusal, launch submission
+and results, gate results, acknowledged inbox delivery, wakes, PR opening
+(including reconciliation of an already opened PR), and endings. Inbox events
+contain sequence ranges, kinds and origins, never message bodies. Session start
+may have an empty id until the backend returns one. Exceptions produce a session
+end outcome when the host can catch them; process death can leave an unmatched
+start. Measurement credit describes the gate decision, not publication or merge.
+
+A sibling `trajectory.lock` serializes appenders with exclusive `flock`. A torn
+last line is preserved and separated by a newline; the chain continues from
+the last parseable event. Verification reports malformed lines even after
+recovery. A complete JSON event missing only its newline is retained and its
+newline repaired on the next append. No old bytes are rewritten. Writes stop
+at 4 MB and warn once per file per kernel process; I/O failures warn without
+failing a tick. Events are not transactional with the operational files, so a
+crash or write failure can leave missing events or retries.
+
+`outerloop trajectory <run-id> --verify` checks sequence gaps and byte hashes;
+`--json` emits events (and verification problems when requested). Missing legacy
+files read as an empty history and verification says "no trajectory". No history
+is reconstructed from older operational files. Older kernels ignore this file.
+The chain detects internal edits and missing lines, but without a trusted
+external anchor cannot detect a rewritten chain or removal of its tail.
+Verification checks the event chain, not the contents of referenced artifacts.
+
+`measure` events carry provenance. They record the ledger's ruler digest (the
+measurement signature plus the non-solver tree entries, the value a pending
+submission also computes), the container image digest when one is configured,
+and refs to the evaluation result files the kernel read under the run
+directory. Self-reported measures record the ruler alone: they have no
+evaluation image or result files. A pending submission does not yet name the
+trajectory head: kernels before this one reject unknown pending fields, so the
+pending reader now ignores them, and a later release can add the field without
+breaking this one. Session end also appends one `tool.call` event per tool call
+found in the retained, redacted native log: Claude project transcripts and Codex
+rollout JSONL are parsed host-side, bounded to 500 calls per session, and Hermes
+or unknown formats yield nothing. Each event carries the tool name, repo-relative
+files, a bounded shell command and, when the log has them, the exit code and
+outcome — never file contents or tool output. `outerloop trajectory` counts them
+by tool and the PR body summarizes the top tools. The PR body also runs a
+report-only number check: numbers on report lines that mention the metric,
+baseline or candidate are compared with every `measure` event's values and the
+Experiments result cells, after rounding to the report's decimals, and the
+unmatched ones are listed under "## Number check". Nothing is blocked and no
+event is written for it. At the end of a run the kernel appends one `attest`
+event carrying an HMAC-SHA256 over the run id and the chain head. Its 32-byte
+key is created owner-only beside the operator settings file
+(`trajectory_attest.key`). `--verify` reports `attested` when the last attest
+event matches that key and `attestation mismatch` otherwise, which shows the
+deployment's own chain was not altered after ending but is not a public proof:
+anyone holding the key can recompute it, and a missing event or key proves
+nothing.

{outerloop_science-0.5.0 → outerloop_science-0.6.0}/docs/getting-started.md

@@ -1,16 +1,46 @@
 # Getting started
 
-This page walks you through one Outerloop run end to end: install the package, declare a contract in your repository, run guided setup, and watch the loop make its first climb. You need one machine, a GitHub repository you administer, and Anthropic API keys for the author and the review judges.
+This page walks you through one Outerloop run end to end: install the package, declare a contract in your repository, run guided setup, and watch the loop make its first climb. You need one machine, a GitHub repository you administer, and separate Anthropic credentials for the author and the review judges: API keys, or subscription tokens from `claude setup-token`.
 
 The tutorial uses the simplest supported setup: everything runs on your machine. [Install](install.md) covers Slurm clusters, upgrades and the other deployment shapes.
 
+To watch a run before you write a contract, the [quickstart repository](https://github.com/outerloop-science/quickstart) has two CPU benchmarks and runs without GitHub or a cluster; its README has the three commands.
+
+## Use from your coding agent
+
+Install the skills-only Outerloop plugin in Claude Code:
+
+```text
+/plugin marketplace add outerloop-science/outerloop
+/plugin install outerloop@outerloop
+```
+
+Or in Codex:
+
+```bash
+codex plugin marketplace add outerloop-science/outerloop
+codex plugin add outerloop@outerloop
+```
+
+Both use the repository's `.claude-plugin/marketplace.json` and the same skills;
+Codex also supports this marketplace layout. Open a new agent session in your
+target repository and say "use outerloop on this repo". The setup skill installs
+`outerloop-science`, helps validate a contract, and offers local forge with local
+or Slurm compute. On a laptop, the plugin runs CPU benchmarks locally without
+needing GitHub or a cluster. For GPU benchmarks, SSH to the cluster's login node
+and run your coding agent there; the resident loop submits all work to Slurm.
+Model access is still needed;
+enter secrets only in the CLI's private prompts. Setup does not start the loop.
+Ask separately to start, inspect, message or stop a run. The plugin drives the
+CLI; budgets, measurement and forbidden paths remain enforced by the kernel.
+
 ## Before you start
 
 - Python 3.12 or later on a Linux machine, or any machine you can leave a terminal open on.
 - `uv` on PATH. Install it with `curl -LsSf https://astral.sh/uv/install.sh | sh` and check `uv --version`. Every evaluation runs through `uv run`, and `outerloop start` refuses to launch without it.
 - A GitHub repository you administer, so you can install a GitHub App on it and merge pull requests.
 - A benchmark command in that repository that prints a JSON metric, such as `{"success_rate": 0.42}`.
-- An Anthropic API key for the author model, and a second key for the review judges. Spend-capped keys are recommended.
+- An Anthropic credential for the author model and a separate one for the review judges: an API key, or a subscription token from `claude setup-token`. Spend-capped keys are recommended.
 
 The loop opens pull requests, comments and pushes branches as a GitHub identity that is not yours. On the way you create that identity with `outerloop init`.
 
@@ -89,7 +119,7 @@ The wizard asks for the deployment settings and writes `~/.config/outerloop/.env
 - Enter for the author backend, keeping `claude`.
 - Enter for the author model to take the backend's default, or name one.
 - The model ID your key serves for the Claude model.
-- Your Anthropic key when it asks for the author's key. The prompt hides it.
+- Your Anthropic API key or `claude setup-token` token when it asks for the author's key. The prompt hides it.
 - Enter for `app` at the auth prompt.
 
 On Linux with [Apptainer](https://apptainer.org) installed, init also offers to download the agent image, about 200 MB, so sessions run contained. Accept unless you have a reason not to. Without an image, on macOS for example, runs stay uncontained and the verification panel is off, and a pull request opened without a panel says so.

{outerloop_science-0.5.0 → outerloop_science-0.6.0}/docs/index.md

@@ -6,6 +6,9 @@ request when the kernel's own measurement shows the benchmark improved. Every
 attempt ends in a written report, including the ones that failed. You run
 Outerloop yourself, with your own keys, compute and repositories.
 
+![One attempt: an agent proposes a change, runs the experiment on your GPUs, the kernel re-measures it against the base, judges review the claim, and a pull request opens with a written report.](assets/loop.svg#only-light)
+![One attempt: an agent proposes a change, runs the experiment on your GPUs, the kernel re-measures it against the base, judges review the claim, and a pull request opens with a written report.](assets/loop-dark.svg#only-dark)
+
 - [Getting started](getting-started.md) takes one repository through a first
   run on a single machine.
 - [Guides](install.md) cover installing Outerloop, operating runs, writing a

{outerloop_science-0.5.0 → outerloop_science-0.6.0}/docs/install.md

@@ -9,8 +9,8 @@ Outerloop is self-hosted. You run it, with your keys, on your compute, against y
 - Python 3.12 or later.
 - `uv` on PATH, or in the directory its installer uses. Evaluations and launches run through `uv run`, and `outerloop start` stops with a message when it cannot find it.
 - A GitHub repository you administer.
-- An API key for the author's model, and separate keys for the judges.
-- For contained runs, Linux with [Apptainer](https://apptainer.org). macOS has no Apptainer, so runs there stay uncontained.
+- An API key for the author's model, or for Claude a subscription token from `claude setup-token`, and separate credentials for the judges.
+- For contained runs, Linux with [Apptainer](https://apptainer.org). macOS uses Seatbelt through `/usr/bin/sandbox-exec` without a VM.
 
 The orchestrator is CPU-only and makes outbound connections only. Anywhere that can reach GitHub and your model provider works.
 
@@ -46,7 +46,7 @@ With `OUTERLOOP_COMPUTE=local`, or with no `sbatch` on PATH, `outerloop start` r
 
 Local compute has no lanes, so GPU benchmarks need no GPU partition: evaluations and the author's launches run on the machine's own GPUs, shared first come first served. Launch arrays run their tasks in parallel as GPUs become available, and `OUTERLOOP_LOCAL_GPUS` overrides automatic detection through `nvidia-smi` (`0` disables GPU allocation). The pool also follows the loop's own `CUDA_VISIBLE_DEVICES`: start each deployment with its own list (for example `0,1` and `2,3`) to give it its own GPUs. The author's session itself starts with `CUDA_VISIBLE_DEVICES` empty, so an experiment that needs a GPU goes through the author's `launch` syscall, where it is recorded and metered against `gpu_hours_per_run`. Uncontained, that is a default the session could reset; containment is what keeps the GPU out of the session, which is one more reason to run with the image.
 
-Without a container image, sessions run under the harness's own sandbox and evaluations run bare on your machine with your keys, and the loop says so once at start. The verification panel is off in this mode unless you set `OUTERLOOP_PANEL_UNCONTAINED=1`, because an uncontained judge holds a shell next to its own key file. A pull request opened without a panel says so. A Codex or Hermes author needs the image in every mode. For priorities, walltime accounting, or several machines, use Slurm.
+Without a container image, sessions and evaluations run as your account on your machine, and the loop says so once at start. On macOS a Seatbelt profile (`/usr/bin/sandbox-exec`) confines them: they write only the workspace and a scratch directory, read only system and toolchain paths, and connect out only to TCP port 443, DNS and local ports (a local model endpoint). If `sandbox-exec` is missing, the loop warns and runs them uncontained. The profile does not open the keychain, but a subscription token from `claude setup-token` works as a Claude credential because it travels as an environment variable. It shares your plan's usage limits with your own Claude use and cannot be spend-capped. A judge on a token runs with `--safe-mode` instead of `--bare`. On Linux they get a scrubbed environment and their own home but can read any file your account can, keys included. Use a spend-capped key. The verification panel is off in this mode unless you set `OUTERLOOP_PANEL_UNCONTAINED=1`, because an uncontained judge holds a shell next to its own key file. A pull request opened without a panel says so. A Codex or Hermes author needs the image in every mode. For priorities, walltime accounting, or several machines, use Slurm.
 
 ### One machine as its own Slurm cluster
 
@@ -208,13 +208,13 @@ GPU jobs request at least 8 cores and 64 GB of host memory per GPU. On nodes wit
 
 ## The agent image
 
-On a cluster, evals and launches run inside the Apptainer image at `OUTERLOOP_IMAGE` (default `~/outerloop-images/agent-py312.sif`), in a jail that binds only the checked-out tree. An eval that needs data must fetch it into the tree. The published image lives at [huggingface.co/outerloop-science/agent-image](https://huggingface.co/outerloop-science/agent-image), built from `containers/agent-py312.def`. On Linux with Apptainer installed, `outerloop init` downloads it (about 200 MB), verifies its published checksum and records it. `--image` points at your own, and `--no-image` keeps runs uncontained even when an image is on disk by writing `OUTERLOOP_IMAGE=`.
+On a cluster, evals and launches run inside the Apptainer image at `OUTERLOOP_IMAGE` (default `~/outerloop-images/agent-py312.sif`), in a jail that binds only the checked-out tree. An eval that needs data must fetch it into the tree. The published image lives at [huggingface.co/outerloop-science/agent-image](https://huggingface.co/outerloop-science/agent-image), built from `containers/agent-py312.def`. On Linux with Apptainer installed, `outerloop init` downloads it (about 200 MB), verifies its published checksum and records it. `--image` points at your own, and `--no-image` skips Apptainer even when an image is on disk (macOS still uses Seatbelt when available) by writing `OUTERLOOP_IMAGE=`.
 
 Only the local loop falls back to running uncontained on its own. On Slurm the tick does not service a target without an image, and its log names the setting below, so a lost image never silently drops containment. Codex and Hermes authors need the image in every mode.
 
 ### Running a cluster without a container
 
-A Slurm cluster with no container runtime sets `OUTERLOOP_UNCONTAINED=1` in `~/.config/outerloop/.env`. Sessions and evaluations then run as local mode does without an image, but as Slurm jobs on your account. Sessions run under the harness's own sandbox. Evaluations run bare, in a throwaway tree with an allowlisted environment. The image is ignored even when one is on disk.
+A Slurm cluster with no container runtime sets `OUTERLOOP_UNCONTAINED=1` in `~/.config/outerloop/.env`. Sessions and evaluations then run as local mode does without an image, but as Slurm jobs on your account. Sessions get a scrubbed environment and their own home directory but can read any file the account can. Evaluations run bare, in a throwaway tree with an allowlisted environment. The image is ignored even when one is on disk.
 
 The local-mode rules carry over. The panel is off unless you set `OUTERLOOP_PANEL_UNCONTAINED=1`, and `start` refuses a Codex or Hermes author. A session can read any file your account can: the bot's credential, the model key files, the evaluator's tree and the kernel's state. Key secrecy and measurement integrity both weaken: the benchmark command can write its own eval directory, and on a multi-node benchmark any node can write every node's result files, so a measurement is only as trustworthy as the author whose code ran. Use it where the site already confines processes, or where that exposure is acceptable to you.