outerloop-science 0.2.1__tar.gz → 0.3.0rc1__tar.gz

{outerloop_science-0.2.1 → outerloop_science-0.3.0rc1}/CHANGELOG.md

@@ -6,6 +6,270 @@ Versions follow [SemVer](https://semver.org).
 
 ## [Unreleased]
 
+### Upgrading
+
+Operator actions (everything else needs no action; details in each entry):
+
+- Before selecting a chat-only Codex endpoint profile, install the bridge:
+  `outerloop harness upgrade --used`.
+- Existing Hermes source-only installs: run `bash scripts/install_hermes.sh
+  "$REVIEW_HERMES_REPO"` (or full `outerloop init`) before Hermes sessions launch.
+- Harness version overrides now need matching SHA-256 settings.
+- Evals and baselines recorded by the previous kernel are measured again once
+  under the new cache key, with no extra charge.
+- Parked authors keep the instructions they started with; judges use the new
+  rubric at once.
+- Runs parked by the previous kernel resume after the upgrade.
+- Before rolling back: consume pending rebind requests, finish capacity-parked
+  runs, runs with extended session limits, overridden and endpoint-routed runs,
+  and chat-only Codex sessions, and stop additional instances.
+
+- A PR tests one idea. It may include the few changes that idea needs, and the
+  report states the effect of each change. Authors test several values in one
+  array launch and report the results around the chosen value; the panel may
+  block a single-value tuning change without them (new `landscape` finding
+  category). Upgrading: no action. Judges use the new rubric at once. An author
+  parked across the upgrade keeps the instructions it started with. Older readers
+  treat `landscape` as `other`. (This was listed under 0.2.1 by mistake; it
+  shipped after that tag.)
+
+- Include GPU count and resolved GPU type in dispatched eval and baseline cache identity, including budget discounts. Legacy eval slots and baseline entries are cache misses. Upgrading: no action. An eval or baseline recorded by the previous kernel, in flight or finished, is measured again once under the new cache key, with no extra budget charge; pausing or draining before the upgrade does not avoid it.
+
+- Park launch capacity refusals in capacity wait when an immediate resume is
+  unavailable or already refused, instead of ending the run. The next wake
+  delivers the refusal and a retry note, resuming the same session when supported
+  or starting a fresh session with the run context otherwise. Meters are
+  preserved and capacity waits do not exhaust stuck retries.
+  Upgrading: no action; existing records need no migration. A run parked by the
+  previous kernel in author-sleep with no session and no pending job starts a
+  fresh author leg on its next wake instead of ending as a session error.
+  Finish capacity-parked runs before rolling back; older kernels cannot resume
+  them.
+
+- Add operator `outerloop rebind <run-id> [--root <root>] [--note <text>]` to
+  explicitly move an existing run to its slot's current author at the next leg,
+  including runs waiting on retired endpoints. Reports and board details show
+  ordered authors; evaluation and launch provenance retain the producing author.
+  Pending requests can be cancelled; three failed applications stop retries,
+  with the count and last error visible in status. A new request replaces a failed one.
+- Upgrading: optional run fields `author_history`, `author_rebind_id` and
+  `stage.candidate_author` / `stage.candidate_authors`, plus `rebind.json` requests
+  and evaluation provenance, require no migration. Legacy author history is populated lazily. Consume
+  pending requests before rolling back to a kernel without rebind support.
+
+- Add `outerloop end <run-id> [--root <root>] [--note <text>]` to request an
+  operator ending at the next tick, including runs waiting for an unavailable
+  endpoint. The tick uses the existing ending cleanup and refuses later publish.
+- Upgrading: existing run records need no backfill; an absent `end-request.json`
+  means no request. Older kernels ignore requests and do not recognize the new
+  `operator` ending when writing records; keep the updated kernel for these runs.
+
+- Author overrides accept operator-only `session_minutes` (10–240) and
+  `session_max_turns` (10–300). Limits bind with the author selection and survive
+  settings changes across wakes and review replies. Contracts can still lower
+  budgets; job walltime follows session duration and the operator job cap.
+  Judge budgets are unchanged.
+- Upgrading: the new override fields are optional; existing settings and legacy
+  run records need no migration. Finish runs using extended limits before
+  rolling back to a version without bound author limits.
+
+- Bad author overrides hold only affected fresh claims during ticks, with one log
+  per entry per tick; malformed settings hold named targets, or all fresh claims
+  when unreadable. Other tick services and bound runs continue; `outerloop start`
+  and `outerloop init` remain strict. No persisted state changes.
+
+- Add read-only `outerloop status` (text/`--json`) for local runs and endpoint
+  outages. Endpoint waits stay out of the published board/status strip and never
+  trigger research-log commits; log one shared outage start and recovery with
+  duration and run IDs.
+  Validate optional served model and expiry in bounded endpoint address records.
+- Upgrading: no action needed; the first endpoint deferral adds
+  `stage.endpoint_wait` and an `endpoint-waits/<profile>.json` log latch. Missing
+  keys/journals are tolerated; ended runs and in-flight PRs are unchanged.
+  Rollback to the preceding kernel safely ignores the additive state.
+
+- Startup validation of `OUTERLOOP_AUTHOR_OVERRIDES` (`outerloop start`) uses the
+  image sessions actually run with, the default image when `OUTERLOOP_IMAGE` is unset. Before, a
+  codex override on a deployment without `OUTERLOOP_IMAGE` failed validation and stopped the tick.
+
+- `OUTERLOOP_AUTHOR_OVERRIDES` accepts a list of entries per target, so different
+  slots of one target can use different authors (each listed entry names its slots;
+  a slot may appear only once). The single-object form is unchanged.
+
+- Reject Codex authors and judges on chat-only endpoints during preflight when
+  the bridge runtime is missing or stale, with `outerloop harness upgrade --used`
+  as the fix, before spending the author budget.
+
+- Codex authors and judges can use chat-only endpoint profiles through a
+  per-session LiteLLM bridge and streaming shim, including tool calls and
+  reasoning replay on resume. The bridge runtime is isolated, transitively
+  locked, installed by `outerloop harness upgrade`, and mounted read-only.
+  Direct Responses profiles keep their existing route and interruption behavior;
+  the Codex pin is unchanged. Bridge runtime defaults use `OUTERLOOP_CACHE_ROOT`,
+  else `$OUTERLOOP_ROOT/cache` (local fallback: `~/.outerloop/cache`). Harness
+  upgrades skip bridge detection for misconfigured roles with a diagnostic and
+  continue upgrading the other configured harnesses.
+- Upgrading: install the bridge with `outerloop harness upgrade --used` before
+  selecting chat-only Codex profiles. Existing run records, session homes, and
+  harness retry records retain their formats; no backfill is needed. In-flight
+  direct-endpoint runs are unchanged. Before rollback, finish chat-only Codex
+  sessions or select a Responses-capable profile; older kernels reject that route.
+
+- Research-line salvage and terminal snapshots now recheck scope admission
+  against the trusted contract before sealing. Out-of-scope changes are
+  dropped from the seal (tracked paths retain their parent content), while
+  admitted work and line memory survive normal endings and crashes after
+  scope refusals. Filtering leaves working files and the real index untouched
+  and logs a bounded list of dropped paths. Upgrading: no action; existing line
+  branches are left as they are, and the next snapshot drops out-of-scope paths.
+  Rollback is safe.
+
+- Support separate instances on one cluster account: process-only absolute
+  `OUTERLOOP_ENV_FILE`, with the existing ownership/write-permission checks,
+  and stable settings-path suffixes for resident and per-cadence scheduler jobs.
+  Init, launch, deploy, harness status, and successor recovery use the selected
+  settings and instance identity.
+- Upgrading: no action needed for the default fleet; its settings path and job
+  names remain unchanged. Existing run records, leases, and heartbeats need no
+  migration. Stop additional instances before rolling back to a version without
+  instance isolation.
+
+- Launch, submit, and stale-submit checkpoint scope violations now refuse every
+  request and resume the author with the offending paths and bounded allowed
+  scope in the kernel inbox. Later refusals say “Refused again:”. Refusals
+  repeat and never end the run; session walltime and contract sleep, launch,
+  and GPU-hour budgets bound the loop. Refusal seals nothing, runs no jobs or
+  measurements, and spends no request budget. The authoritative measurement
+  scope check remains terminal. Abandoning a refused tree ends normally
+  without measurement, a line snapshot, or a push; outage and budget endings
+  also preserve the rejection. Scope admission precedes malformed request
+  and budget refusals.
+- Upgrading: no action or backfill needed. Scope refusals use the existing
+  kernel note payload and refusal keys; old inboxes, ended runs, and in-flight
+  runs remain readable without rewriting delivered messages. The next request
+  uses the new admission behavior. The rejection flag is in-memory only;
+  no run-record fields change; rollback is
+  safe and restores terminal scope admission checks.
+
+- Deployment author overrides select a backend/model per target or agent slot,
+  bind it to each run, and leave panel and CI reviewer inheritance on the fleet
+  author. Per-run board details identify the effective author and overrides.
+- Endpoint profiles accept an absolute `URL_FILE` instead of `URL`, reading bare
+  URLs or JSON addresses on every session. Missing files, failed bounded health
+  checks, and interrupted checks defer sessions without spending wake retries.
+  Init provisions fleet and override backends before validating prerequisites.
+- Upgrading: no action or backfill needed; records without `author_overridden`
+  retain their existing author and panel behavior, including ended runs. New
+  overridden records reuse the saved author route and add this optional flag.
+  Rollback reads the records but loses fleet-only panel inheritance for overrides;
+  finish overridden runs and fresh endpoint capacity parks before rolling back.
+  Fresh endpoint deferrals reuse author-sleep capacity parks without a session ID;
+  older kernels cannot resume those parks.
+
+- Launch ledger submissions require dispatched launch job IDs, preventing stale
+  checkpoints from attributing discarded launches to a commit. Gate capacity
+  waits still record any dispatched sibling launches. Existing ledger rows and
+  run records remain readable and unchanged; no schema change or backfill.
+
+- PR measurement tables identify the base and candidate commits and the shared
+  eval command from the base tree; experiment tables identify launch commits.
+  Verify and review briefs caution against comparing numbers across commits
+  without checking history.
+- Upgrading: no action or backfill needed; the first tick tolerates launch ledger
+  rows without `commit` (shown as unknown), including ended runs and in-flight
+  PRs. New launch records include the sealed commit; existing records and PR
+  bodies are not rewritten. Rollback is safe: older readers ignore the added
+  field.
+
+- Hermes author resumes that exceed the replay budget stay parked with a
+  configuration-blocked status, retaining their session and snapshot without
+  consuming wake retries. Author/judge separation checks effective key paths
+  and credential values before constructing sessions; init rejects incomplete
+  Hermes configuration only for Hermes authors. Endpoint author credentials are
+  shared by attempt and tick preflight, including native panel key comparisons.
+- Upgrading: no action or backfill needed; legacy records without
+  `stage.hermes_resume_required_chars` are unblocked. The first oversized wake
+  records the required budget; raising `OUTERLOOP_HERMES_RESUME_MAX_CHARS` lets
+  the next tick or wake resume. Successful resumes and endings clear the marker,
+  so later normal sleeps are not configuration wakes. Before rollback, resolve
+  blocked runs: older kernels ignore this optional field and may consume retries
+  or abort them.
+
+- Hermes is an author peer: init, native provider/endpoint validation, contained
+  fresh and resumed sessions, absolute syscall commands, and separate author keys.
+  Resume replay preserves the original brief and latest results within
+  `OUTERLOOP_HERMES_RESUME_MAX_CHARS` (default 120000), with explicit omission counts.
+- Upgrading: no backfill; existing records and full saved transcripts remain
+  readable. The first Hermes wake applies the replay bound. Finish Hermes author
+  runs before rollback: older kernels reject unsupported Hermes author wakes
+  (the endpoint-profile predecessor accepts endpoint routes only). Ended records
+  remain readable. See [Hermes setup and compatibility](docs/install.md).
+
+- Endpoint profiles declare compatible APIs and use `model[endpoint=profile]`
+  selectors, preserving native vendor model IDs. Judge credentials enforce file
+  separation; verdicts redact the session key before posting or aggregation.
+- Upgrading: legacy records missing model/route fields retain native routing;
+  missing native model configuration fails closed instead of adopting fleet endpoints.
+
+
+- Named, file-authenticated endpoint profiles work for authors, panel lenses,
+  and standalone reviewers on Claude Code, Codex, and Hermes. Sessions use each
+  backend's native API configuration; keys reach contained sessions through env,
+  never argv. See [endpoint settings and validation](docs/endpoints.md).
+- Hermes is pinned to v2026.9.24 (`f97608f178d1ffeca59860195ab7da295f7c8e5f`).
+  Remove Fire quoting for its new argparse entrypoint, enable
+  `model.reasoning_echo` for endpoint profiles, and sanitize its instruction-file
+  aliases in judge checkouts.
+- Upgrading: existing runs need no backfill; the first tick validates endpoint
+  selections without changing legacy routes. New endpoint authors save
+  `model[endpoint=profile]` selectors; keep those profiles until runs finish, and finish
+  endpoint runs before rolling back. Hermes source/runtime must be upgraded
+  with the harness. See [compatibility and rollback](docs/endpoints.md#upgrade-and-rollback).
+
+### Fixed
+
+- Manual harness upgrades honor `--root`, environment, and `.env` state roots. Retry records are replaced atomically; unreadable or invalid records are logged and ignored. Deploy loads the configured cache root before selecting the uv cache.
+- Harness installers reinstall changed binaries rather than refusing repair; Codex checks its installed binary digest separately from the archive pin, and Hermes runtime reuse checks the interpreter digest.
+
+- Harness upgrades enforce a per-harness deadline, kill timed-out installer process groups, restrict installer environments, and back off failed pins while deleting failed candidates. Overrides require explicit integrity hashes; installed binaries are hash-checked before reuse. Workflow pin resolution fails explicitly on older reviewer refs without a pins reader.
+
+- Tick entrypoints export a state-root uv cache before running Python. Fleet job environments preserve explicit cache paths and default per-user caches below `OUTERLOOP_CACHE_ROOT` (or the state root).
+
+- Run-owned launch, evaluation, and wake job names stay within 128 characters, retaining a stable run key when shortened. Normal names stay unchanged; GPU usage, queue attribution, evaluation deduplication, and flight retention recognize the bounded names.
+- Intake admission counts queued attempts using the existing pending markers, including jobs queued beyond the marker TTL.
+
+- GPU accounting accepts Slurm 25.05 wrapped numeric fields and legacy integers, recognizes typed GPU requests and per-node counts, and limits pending array remainders to available throttle slots.
+- CI Hermes provisioning uses the shared runtime installer with anonymous clone retries and matching workflow pins. A source-specific lock protects checkout and runtime mutations; Python discovery excludes active virtualenvs.
+- Panel preflight checks Hermes runtime readiness and explains installation; full init preserves review model and provider settings with environment precedence.
+
+- Contained Hermes sessions can start with read-only source; sessions no longer reinstall dependencies or attempt an editable project build.
+
+### Added
+
+- Optional per-target GPU lanes route evals and author launches to deployment-specific partitions, accounts, GPU types, and sbatch flags.
+
+- Packaged `harnesses.toml` owns Claude, Codex, and Hermes pins. `outerloop harness status` reports installed versions, paths, drift, and operator overrides; `harness upgrade [name...]` verifies versioned installations before atomically recording their paths. Successful kernel deploys upgrade only configured backends; failures retain the previous installation.
+
+- Live, tighten-only `<root>/limits.toml` GPU and active-attempt ceilings, with global defaults and per-target sections. Scheduler-reported GPU usage covers pending and running experiments, sweeps, evaluations, and GPU-bearing sessions. Authors receive uncharged launch refusals; evaluations wait for capacity. Lowering a ceiling does not cancel jobs.
+- Read-only `outerloop limits` reports operator ceilings and fleet-owned running/pending GPU usage.
+
+### Changed
+
+- Upgrading: legacy Codex archive-only markers and Hermes runtimes without interpreter digests are reinstalled on upgrade; legacy Hermes runtimes remain launchable. Existing retry records remain readable, and corrupt records are treated as empty. Run state and in-flight PRs are unchanged; rollback leaves the additional digest files unused.
+
+- Upgrading: version overrides now require matching SHA-256 settings; legacy Codex installs without hash markers are reprovisioned. New retry state and hash markers are ignored by older kernels; the first successfully synced tick verifies configured harnesses and records new paths only when needed. Legacy `.env` paths and Hermes runtimes remain readable; old artifacts are retained. See `docs/install.md` for rollback across kernel pins.
+
+- Hermes installs a standalone Python and venv once per pinned commit in a sibling runtime, then launches Python directly. Full `init` provisions configured Hermes judges and records their source path; `--no-install-harness` opts out.
+
+### Upgrading notes for the entries above
+
+- No action needed; OUTERLOOP_GPU_LANES is optional.
+
+- Upgrading: full run-ID names and legacy 60-character queue names remain readable; shortened names use a derived run key without changing run records. Intake adds `@intake-<issue>` files in the existing pending directory; legacy unsuffixed and agent-slot markers remain readable. Drain queued intake jobs from older submitters (which wrote no marker) before relying on attempt ceilings. Upgrade all kernels together; older kernels do not recognize shortened names or intake markers, so drain those jobs before rollback.
+
+- Upgrading: the optional `stage.capacity_wait` flag tolerates missing fields; existing state records need only their target for scheduler attribution. No contract schema change or admission journal. Drain older jobs whose names omit the full run ID (and older local jobs without scheduler metadata), and upgrade all submitters before relying on ceilings. Concurrent admissions may overshoot by one batch for two simultaneous checks; no cross-node admission lock.
+- Upgrading: existing Hermes source-only installs require `bash scripts/install_hermes.sh "$REVIEW_HERMES_REPO"` (or full `outerloop init --force` with Hermes configured) to create the persisted runtime. Run records and resume transcripts are unchanged; rollback leaves the sibling runtime unused.
+
 ## [0.2.1] - 2026-09-25
 
 ### Upgrading
@@ -45,6 +309,7 @@ Versions follow [SemVer](https://semver.org).
 
 ### Changed
 
+- An idea with a clear mechanism that does not yet beat the best is reported as a success and kept on the author's research line.
 - The sweep rechecks ancestry for PRs held only by a base-moved blessing.
 - Merges performed by the sweep are observed and confirmed in the same tick.
 - Scope checks compare the full candidate tree with its merge-base against the fetched base tip; changes that landed on the base branch never count as the author's, and author edits to the ledger files are refused like any other out-of-scope path.

{outerloop_science-0.2.1 → outerloop_science-0.3.0rc1}/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.2.1
-date-released: "2026-09-25"
+version: 0.3.0rc1
+date-released: "2026-10-03"

{outerloop_science-0.2.1 → outerloop_science-0.3.0rc1}/CLAUDE.md

@@ -22,6 +22,11 @@ uv run pre-commit run --all-files
   `.github/` are forbidden write paths everywhere, regardless of contract YAML.
 - Budget caps are load-bearing safety features, not tunables to raise casually.
 - Never commit credentials, transcripts, or run artifacts (SECURITY.md).
+- This repository is public: code, tests, docs, commit messages and PR
+  descriptions carry no deployment specifics (cluster, account, partition or
+  node names, or what hardware a lab has). Use generic examples such as
+  `owner/repo`, `my-account`, `gpu-large`, and motivate a change by the general
+  need.
 - Merge commits only; never rebase, squash, or force-push.
 - **Review until quiet**: development PRs iterate advisory-review rounds
   (after a fix commit, remove then re-add the `autoresearch:review` label

{outerloop_science-0.2.1 → outerloop_science-0.3.0rc1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: outerloop-science
-Version: 0.2.1
+Version: 0.3.0rc1
 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

outerloop_science-0.3.0rc1/docs/design/accelerators.md

@@ -0,0 +1,205 @@
+# Accelerators: metering and placement beyond GPUs
+
+**Status: proposal, revised after review (2026-10-02); not built.** Outerloop
+meters, caps and places experiment work in GPUs. This note proposes adding
+Cloud TPUs as a second, separately metered device kind, so the same kernel can
+run TPU benchmarks under budgets, operator limits and refusals as strict as
+the GPU ones. Budget caps are safety features: nothing in this proposal may let TPU work
+run unmetered, or let a GPU budget pay for it.
+
+## Why
+
+A benchmark that runs on TPUs today would have to declare `gpus: 0`. The
+kernel would then charge no device-hours, apply no `gpu_hours_per_run` budget,
+count nothing against `max_gpus`, and might dispatch its evals as plain CPU
+jobs. The meter is the safety feature, so a new device kind has to be metered,
+placed and capped before any TPU contract is accepted.
+
+## What assumes a GPU today
+
+- **Declaration.** `Benchmark.gpus: int (0..8)`; `Measure.gpus`,
+  `JobSpec.gpus`; the GPU type lives on the operator's per-target lane
+  (`OUTERLOOP_GPU_LANES`, `gpu_lanes.py`). Whether evals dispatch depends on
+  `eval_minutes`, not on `gpus`.
+- **Metering.** Launches charge minutes × array × gpus / 60; gates charge the
+  main eval (one when a cached baseline applies, else two) and every suite
+  sibling pair × walltime × gpus (`syscall.py`). The run meter is
+  `stage.gpu_hours_used`; budgets are `gpu_hours_per_run` plus
+  `review_topup.gpu_hours`; `max_concurrent_gpus` paces sweeps.
+- **Placement.** `JobSpec.to_argv` emits `--gres=gpu:TYPE:N` or
+  `--gpus-per-node=N`, single node; dispatched evals add `--nv` and size CPUs
+  and memory per GPU.
+- **Operator limits.** `limits.toml` `max_gpus`, counted from one
+  `squeue --me --json` snapshot by parsing `gres/gpu` TRES, attributing jobs to
+  this fleet by run id.
+- **Local backend.** `nvidia-smi` detection (or `OUTERLOOP_LOCAL_GPUS`),
+  `CUDA_VISIBLE_DEVICES` pinning.
+- **Surfaces.** Briefs, wake lines, refusals, `budget.json`
+  (`gpu_hours_remaining`), `outerloop status`, `outerloop limits` and the board
+  carry GPU-named fields.
+
+## Proposal
+
+The first version is deliberately narrow: **existing GPU keys and behaviour
+stay exactly as they are**, and TPU is added beside them with its own fields.
+
+### Declaration
+
+```yaml
+benchmarks:
+  - name: speedrun-tpu
+    tpu_chips: 8          # one TPU node per job; mutually exclusive with gpus
+```
+
+`tpu_chips` is a positive integer equal to one supported single-host node
+size (4 or 8 chips in the first version); other values are refused at contract
+load. `tpu_chips` and `gpus` cannot both be set. A suite gate's device demand is
+the union over all its benchmarks, including the one that initiated it. In the
+first version a gate may demand at most one device kind, and the initiating
+benchmark must carry that kind: GPU and TPU never mix in one gate, and a
+CPU-led gate with an accelerator sibling is refused at contract load. That
+kind decides authorization, dispatch and the meter for the whole gate.
+
+### Budgets and meters, per kind
+
+- New contract field `budgets.tpu_chip_hours_per_run` (and
+  `review_topup.tpu_chip_hours`). A TPU benchmark needs an explicit TPU budget;
+  a contract with `tpu_chips` but no TPU budget is refused. GPU budgets never
+  authorize TPU spending, and vice versa.
+- New run-stage meter `stage.tpu_chip_hours_used`, retained everywhere
+  `gpu_hours_used` is retained today (`STAGE_RETAINED_KEYS` and the stage
+  reconstruction paths), and a persisted `stage.meter_kind`. The GPU meter is
+  unchanged and stays authoritative for GPU runs, so a rollback never resets GPU
+  spending.
+- The arithmetic matches GPUs: chip-hours = minutes × array × chips / 60 for
+  launches, evals × walltime × chips for gates.
+- No conversion between kinds and no money in the kernel; operators set
+  per-kind caps.
+
+### Placement
+
+One TPU node per job in the first version (a single-host slice, e.g. 8 chips):
+the backend requests one whole node from the operator's TPU lane, with no GPU
+GRES and no `--nv`. Multi-host slices are out of scope until the kernel owns
+distributed worker start-up, topology and per-node environment. The TPU lane
+is per target, like GPU lanes, and carries the node's chip count and the
+container image; the kernel refuses a benchmark whose `tpu_chips` does not
+equal the lane's node size.
+
+The first backend provisions one Cloud TPU VM per job (Slurm on Google Cloud
+does not support current TPU generations out of the box). It is a bounded
+adapter behind general compute interfaces the kernel gains once: accelerator
+demand, opaque job ids, lifecycle and accounting observations, artifact
+staging, and capability refusals. Cloud API calls, state translation,
+transport and cleanup stay inside the adapter, which owns deterministic
+resource names, reconciliation after an ambiguous create, queue and execution
+deadlines, and deletion confirmed independently of the worker. Author sessions
+and wakes never run on a TPU allocation; the deployment gives them a CPU lane.
+
+The TPU worker runs the benchmark in the same no-credential jail as dispatched
+GPU evals: the adapter's cloud credentials, the GitHub App key and any operator
+secret stay in the adapter's process and never reach the TPU VM or the
+container. The VM's own service identity can only read the job's inputs and
+write its outputs in the staging bucket; it cannot create, change or delete
+TPU resources.
+
+### Operator limits
+
+`limits.toml` gains `max_tpu_chips` (fleet default and per target). Admission
+checks every kind a request demands; a ceiling on one kind is not skipped
+because another kind has none. The kernel persists what it submitted for each
+TPU job (allocation id, chips, array concurrency) and counts running and
+pending allocations from that record, reconciled with the backend. A fleet
+job whose TPU allocation cannot be bounded from either source blocks further
+TPU admission until it is resolved; it is never counted as zero or as a
+guess. Admission is serialized: a request takes the fleet's admission lock,
+counts persisted allocations plus outstanding reservations, writes its own
+reservation (allocation id, chips) before asking the backend to create
+anything, and releases the lock; the reservation turns into an allocation or
+is removed on refusal or failure. Two concurrent requests therefore cannot
+both fit into the same headroom. A finite ceiling with no usable snapshot fails closed, as today. A
+capacity refusal parks the run (#453). The limits bound this fleet's own jobs
+(attributed by run id); they are not a cloud-project-wide cap, which the
+deployment enforces separately.
+
+### Refusal until complete
+
+TPU support ships behind one operator setting, `OUTERLOOP_TPU=1` in the
+operator settings file, read by the tick like the other settings. It defaults
+to off, and the kernel refuses to enable it unless a TPU lane and a finite
+`max_tpu_chips` are configured. Until declaration, budgets, meters, placement,
+limits, caches and surfaces are all in place, the setting is not offered. Until then a
+contract with `tpu_chips` is refused with a clear message, never run as CPU.
+The local backend refuses TPU benchmarks explicitly.
+
+### Caches
+
+Both measurement caches (the baseline cache and the dispatched-eval
+determinant) include the device kind, count, resolved image and runtime
+identity. A legacy cache entry never satisfies a TPU measurement.
+
+### Preemption
+
+Spot TPU and spot GPU nodes can be reclaimed. The first version submits TPU
+jobs with no automatic requeue: a preempted job fails, the author sees it on
+wake, and its time is charged. Automatic retries come later and only with
+cumulative accounting (every execution's time charged, the retry reserved
+before it starts).
+
+### Surfaces
+
+Text names the unit in front of the reader ("GPU-hours", "TPU chip-hours")
+from one helper. `budget.json`, `outerloop status` and the board gain
+`tpu_chip_hours_*` fields beside the GPU ones; durable board rows record the
+meter kind with the value.
+
+## Existing GPU accounting gaps (separate fixes, found in review)
+
+- The dispatched-eval cache determinant omits the GPU count, so a result can
+  be reused across different GPU counts (`measure.py`).
+- Jobs allocate declared minutes plus ten setup minutes, but only the declared
+  minutes are charged (`dispatch.py` `eval_job_spec`); refunds never debit an
+  overrun.
+- Launch-hour reconciliation reads one `sacct` record, so a requeued job's
+  earlier executions can drop out of accounting.
+- `max_concurrent_gpus` is a per-launch pacing hint (at least one task runs),
+  not an aggregate cap; concurrent admissions can overshoot `max_gpus`
+  (documented in `operator_limits.submit_batch`).
+
+These are fixed for GPUs first (they are the template the TPU meter copies),
+each in its own PR.
+
+## Compatibility
+
+New persisted fields only: `tpu_chips` and TPU budget fields in contracts,
+`tpu_chip_hours_used` and `meter_kind` in run stages, the per-job TPU
+allocation and reservation records (allocation id, chips, array concurrency)
+under the run and the fleet state root, `max_tpu_chips` in `limits.toml`,
+device identity in cache keys. GPU records, contracts and limits
+are byte-identical. Rolling back: an older kernel rejects contracts and
+`limits.toml` files carrying the new keys (unknown fields are errors there).
+Before rolling back: end every TPU run, parked ones included (`outerloop end`),
+and confirm no TPU allocation remains; then restore contracts without
+`tpu_chips`, `budgets.tpu_chip_hours_per_run` and `review_topup.tpu_chip_hours`,
+and `limits.toml` without `max_tpu_chips`. Older kernels load ended TPU run
+records (unknown fields are ignored there) and show them without TPU usage.
+GPU runs are unaffected. Release fixtures cover legacy records, an interrupted
+TPU run, and an idempotent rollback.
+
+## Phases
+
+0. **GPU accounting fixes** above (independent PRs).
+1. **TPU, end to end behind the flag**: declaration, budgets, meters, limits,
+   caches, placement on one backend, surfaces, refusals; fixtures for legacy
+   records and contracts.
+2. **First TPU fleet**: one TPU benchmark, one smoke run, then real runs.
+3. Later, only if needed: multi-host slices, automatic retries with
+   cumulative accounting, local TPU.
+
+## Decisions
+
+1. Cross-kind work in one run: no. A benchmark has one kind; suites are
+   homogeneous.
+2. Money in the kernel: no. Per-kind caps; cost reporting stays operational.
+3. Preemption: fail and report on wake, all time charged; retries later with
+   cumulative accounting.

outerloop_science-0.3.0rc1/docs/design/agent-environment.md

@@ -0,0 +1,95 @@
+# Environment, not workflow
+
+Status: proposal, 2026-09-25.
+
+## The rule
+
+The kernel adds structure only where it guards a trust boundary. Everything
+else is environment: the agent uses its tools as it sees fit, and research
+habits are taught through the brief and skills, where they can change without
+a kernel release and where each adopter can set their own.
+
+The boundaries:
+
+- **Credentials.** Sessions hold none. Anything published goes through the
+  kernel.
+- **Measurement and credit.** The gate, the panel, the ledger, and what
+  reaches the base branch.
+- **Budgets.** GPU-hours, launches and sleeps.
+- **Other agents' state.** Another author's branches and private memory.
+
+A rule that guards none of these is a convention, not a mechanism. If a
+convention keeps failing in a way that crosses a boundary, it earns a
+mechanism then, not before.
+
+## What this changes now
+
+**1. Sessions may commit on their own line.** The rule "do not commit" guards
+no boundary. The sealed tree is what gets measured, the scope check guards
+what reaches the base branch, and the `.git` tamper guard protects the
+repository. The rule did cause harm: an author could not merge the updated
+base branch into its own work until a special permission was added, and
+merging another author's work would have needed another. Lifting it removes that class of exception.
+Pushing stays with the kernel.
+
+**2. Authors may publish branches under their own namespace.** One generic
+capability: stage a push of a named branch under `ideas/<agent-id>/`. The
+kernel checks these things and nothing else:
+
+- the name stays inside the author's namespace and is a valid ref name;
+- the author's memory (`AGENT_MEMORY.md`, `agent_memory/`) is left out of
+  the published tree, and instruction-bearing files carry the base
+  branch's reviewed versions, the same cleanup the kernel applies when it
+  checks out a line;
+- the author stays within a bound: at most 20 published branches, and a
+  push that adds more than 50 MB of new objects is refused. The byte
+  bound applies to every push the kernel makes for an author, line
+  snapshots included, which today are unbounded. Both numbers are
+  defaults the contract can change.
+
+Memory is owned, not secret. Every session already fetches every agent
+line, so an author's memory is readable by its siblings today. Leaving it
+out of the published tree keeps it out of merges and measured trees; it
+does not remove it from history. If memory ever needs to be confidential,
+it has to leave the shared repository, which is a separate design.
+
+The author may also reset or delete its own branches. Work another author
+already merged survives in that author's line; only the shared name goes.
+
+Publishing costs no budget and earns no credit. A failed publish comes back
+to the author as a message.
+
+Branches under another agent's namespace are read-only to everyone else.
+Every session already fetches all branches, so reading and merging them is
+plain git.
+
+**3. Ideas are a convention, not a mechanism.** How an author names an idea,
+describes it, marks it parked or abandoned, and finds a sibling's idea is up
+to the author, using git. The brief and a skill suggest a default: the
+branch name says what the idea is, the commit message states the mechanism
+and points at the reports, and a PR that builds on another author's idea
+cites its branch and commit. The board lists the branches under `ideas/`
+with their last commit, and nothing more.
+
+## Two protections a merge needs
+
+When a session merges another branch into its line, the kernel keeps the
+receiver's private memory and the reviewed instruction files. It already
+resets instruction files after merging the base branch at run start; keeping
+the receiver's memory through an arbitrary merge is new, since today's rule
+for it covers only resets. The scope check is unchanged: code merged from an
+idea counts as the author's change when it reaches the base branch.
+
+## Deferred
+
+Idea status fields, automatic parking, per-author caps, "best number"
+tracking, a separate discovery command, and an operator command for humans.
+Each can be added if the plain version shows a need.
+
+## Decided
+
+- Authors may reset or delete their own published branches (owner,
+  2026-09-25).
+- The namespace is `ideas/<agent-id>/`: it names the purpose and matches
+  the "one idea per PR" language of the brief and panel. Adopters may use
+  it for other purposes; the kernel only enforces ownership.

{outerloop_science-0.2.1 → outerloop_science-0.3.0rc1}/docs/design/agent-protocols.md

@@ -94,7 +94,7 @@ park, terminal at the ending. Legs are turns inside it.
 An ending is a completion with an outcome, not a task state. A negative
 result is successful work; a rejected PR is a human's decision, not the
 agent rejecting the task. Only kernel-side failure (stuck, aborted) maps to
-failed or canceled. The six endings travel as data on the final message.
+failed or canceled. The endings travel as data on the final message.
 
 | Outerloop | A2A | Note |
 | --- | --- | --- |

{outerloop_science-0.2.1 → outerloop_science-0.3.0rc1}/docs/design/architecture.md

@@ -98,7 +98,7 @@ needs inbound access is a human with the runbook.
 
 ## Task granularity
 
-A task is **one hypothesis, one PR** — but its evaluation scope follows the
+A task is **one idea, one PR** — but its evaluation scope follows the
 target's artifact structure, declared in the contract:
 
 - *Independent solvers* (the pilot): scope = a single benchmark; one PR moves
@@ -114,8 +114,9 @@ Scope checks compare the full candidate tree with its merge-base against the fet
 base tip, so changes made only on the base branch do not count as author edits.
 Missing shared history refuses publication; the separate base-tip ancestry check still applies.
 
-What stays absolute regardless of scope: one hypothesis per PR (attributable
-diffs), full-scope reporting, and **cross-target separation** — separate clones,
+What stays absolute regardless of scope: one idea per PR (an idea may bring
+the few changes it needs, and the report attributes each one), full-scope
+reporting, and **cross-target separation** — separate clones,
 branches, budgets, and report streams per target (`runs/<target>/`,
 `lessons/<target>.md`), never cross-target code reuse. The only global artifact
 is this machinery; the only cross-project channel is process lessons in the