outerloop-science 0.1.1__tar.gz → 0.2.0rc1__tar.gz

{outerloop_science-0.1.1 → outerloop_science-0.2.0rc1}/CHANGELOG.md

@@ -6,6 +6,54 @@ Versions follow [SemVer](https://semver.org).
 
 ## [Unreleased]
 
+### Fixed
+
+- `outerloop permissions` checks App access and opens the next page to edit or accept missing permissions with `--open`; upgrades, starts and sweep warnings provide guidance for existing installations.
+
+- In auto mode the sweep merges only a clean PR at the head the kernel measured and approved. Publish never arms GitHub auto-merge; the sweep withdraws old arms and reports head moves to the author.
+
+- A reply returning after PR merge or close preserves the run’s ending. GitHub outages no longer skip job and deadline handling, failed reply posts suppress duplicate final text, and terminal snapshot cleanup survives notebook failures. Inbox delivery retries refused messages and refuses symlinked destinations.
+
+- A review panel skipped at preflight or in the follow-up now sends the author a kernel note and records the reason in the submit’s PR addendum. These publishes never arm auto-merge.
+
+- A submitted review measurement could go unreported when its push failed. The number is now posted once, as soon as it is known. Review submits push a bot commit with the report’s first line and measured number as its message.
+- On local compute an author-sleep wake could lose an improvement: the gate answers inline there, and the wake only knew how to end a run, so the result became an aborted ending with no PR (cluster0, three runs). Fresh and resumed climbs now share one terminal: the report, the line notebook, a PR or an ending record, and the issue note. A wake that opened its PR but died before recording it reconciles to that PR instead of opening a second, and a park's snapshot is released only once the run has left waiting.
+- A research line lost its snapshot when the author's session reset its branch to main: the seal parented on main, the push was refused, and the run left no notebook entry (#368). The kernel now records the line head itself and the line only moves forward from that record. Memory files a reset dropped from the tree come back at the seal; files the session deleted on the line stay deleted.
+- Intake dropped an issue from a private org member without a word: the App's token sees such an author as CONTRIBUTOR, and only OWNER/MEMBER/COLLABORATOR qualified. Every skipped issue is now logged with its reason, a maintainer's `outerloop:task` label vouches for an issue regardless of association, and new Apps request members read so private members read as MEMBER.
+
+### Changed
+
+- Completed CI checks reach the author as messages with bounded log tails. Failed checks wake idle runs; successful, neutral and skipped checks wait as context.
+
+- Messages carry an origin and a qualified repository thread. Staged replies keep their destination through retries and later PR changes.
+
+- Memory guidance now covers every session boundary and asks authors to record durable findings as they learn them. Sleep, submit and end help say the session ends there.
+
+- The board's live strip says what a parked run waits on beside its state: jobs, gate, review or wake. Read off the record; the three states are unchanged.
+- Runs have three states: running, parked and ended; the board and the logs show those names, and an open PR is a link on the run. The sweep delivers comments, base moves and job results through one wake path; the separate follow-up job is gone. Old state names are mapped on read; inbox cursors migrate once under the run lease, and every tick logs the number of legacy follow-up records until it is zero. An older kernel cannot read the new state names; that is the only incompatible field, and fleets are updated by commit. The contract's `followup_job_minutes` now sizes the wake job of a run with an open PR.
+
+
+- Authors can stage `end [--report <file>]` and end their turn: without a PR it ends as a negative result with the last failed verdict's note, or “ended without a submit”; with an open PR it posts the supplied report and parks until a message arrives. End costs nothing and cannot accompany launch, sleep or submit.
+- Opening a run's first PR grants a review top-up once: 2 launches, 4 sleeps and 0.5 GPU-hours by default, configurable through `budgets.review_topup`. The increased ceilings and prior spend appear in the tool, brief and every wake.
+
+- Submit works in review and fast-forwards the PR after a confirmed auto-merge disarm; the measured number is posted first, even if publication is refused. Each review leg measures against its freshly fetched base. Verdicts, findings and publish refusals reach the author as messages. A reply staged during a review leg suppresses its final-text comment. A failed submitted park ends as negative-result only when no author session can resume to receive its verdict; its report and notebook are saved and its issue claim released. Sessions without the tool (no launcher or no resume support) are still measured at finish and may end on the verdict by design. Submit needs no prior launch or report. A session offered submit that stops without it ends unmeasured, or returns to review if it has a PR. Legacy follow-up re-measures retire on their next wake and release their snapshots.
+
+- Authors can post replies through `reply` and launch experiments or sleep while a PR is in review, using the run’s remaining budget. Comments and base moves received while parked reach the author at its next wake. Replies are kept in an outbox for retries, review launches check committed edits, and closing a run holds its wake lease. Review edits are measured and published only on submit, using the same remaining GPU budget as other author work.
+
+- Wake messages now use one inbox and one renderer. Launch results, gate verdicts, panel findings, review comments and base moves reach the session in the same fenced format, from files kept beside the run's record. Advisory panel findings now reach the author alongside blocking ones. The sibling view is refreshed at every wake of a parked author session. The kernel's wake text states facts; the research advice it used to carry is gone.
+
+- Dispatched wakes are on by default. The old on-switch (`OUTERLOOP_DISPATCH_WAKE=1` or a `DISPATCH_WAKE` sentinel) is gone; the operator turns wakes off with `OUTERLOOP_DISPATCH_WAKE=0` or a `<root>/DISARM_WAKE` sentinel, and a dry sweep says so in the log. An unarmed loop stranded every parked run silently, which local compute, able to park since 0.1.2, hit at once.
+- The brief's launch section says that a launch runs a sealed snapshot of the working tree and is scope-checked like the final tree, so experiment scripts must live under the contract's allowed paths.
+
+- Whether jobs need a lane is now the compute backend's word (`has_lanes`): the measurer, the launcher, and the tick's GPU preflight ask it instead of testing for local mode. The dispatch settings always exist (a backend always does), so local compute arms the author's `launch`/`sleep` syscalls for benchmarks with `depth_k`, and a local wake no longer needs a container image. A `--image` path that is not a file is refused at the command line instead of silently degrading the run to inline evaluation.
+- Author sessions start with no GPU visible on any backend (`CUDA_VISIBLE_DEVICES` is empty), so experiments that need one go through `launch`, where they are recorded in the ledger and metered against the GPU budget. This is the bare session's default; a contained session has no GPU device at all, which is the enforcement.
+
+## [0.1.2] - 2026-09-11
+
+### Fixed
+
+- A GPU benchmark on local compute aborted at its first gate measure with "no GPU lane is configured". The measure placement now follows the launch placement's rule: local compute has no lanes, the job runs on the machine's own GPUs.
+
 ## [0.1.1] - 2026-09-11
 
 ### Fixed

{outerloop_science-0.1.1 → outerloop_science-0.2.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.1.1
+version: 0.1.2
 date-released: "2026-09-11"

{outerloop_science-0.1.1 → outerloop_science-0.2.0rc1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: outerloop-science
-Version: 0.1.1
+Version: 0.2.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.1.1 → outerloop_science-0.2.0rc1}/docs/design/agent-substrate.md

@@ -61,7 +61,7 @@ per tiny thing is the accretion trap in a new costume.
 - steward: `ruler-hardening` (when/how to make the metric harder once it's gamed —
   add a transfer split, harder cells) · `benchmark-design` (noise floors, seeds,
   why a sweep beats a single point)
-- follow-up: `respond-to-review` (address maintainer comments; which task
+- resumed author: `respond-to-review` (address maintainer comments; which task
   instruction a wake supersedes; honest scope)
 
 **Target (e.g. `yolo-jepa`)**
@@ -138,7 +138,7 @@ planned set — none are wired yet):
 | author | Read/Grep/Glob/Write/Edit/Bash | kernel-primer, plain-style, hypothesis-discipline, honest-method, experiment-lifecycle, research-report (+ self-review, analyze-results — proposed) | literature-search (retriever), result-aggregation |
 | reviewer | Read/Grep/Glob + pr-context-read, retriever | kernel-primer, plain-style, review-rubric, read-only-investigation | evidence-sweep (parallel read-only file/caller sweeps on large diffs), reference-check (retriever) |
 | verifier | Read/Grep/Glob + pr-context-read, retriever | kernel-primer, plain-style, integrity-lens, read-only-investigation | evidence-sweep (read-only; e.g. trace every consumer of a changed ruler input) |
-| followup | editing set, resuming role's key/scope | kernel-primer, plain-style, respond-to-review | inherits the resumed role's |
+| resumed author | editing set, resuming role's key/scope | kernel-primer, plain-style, respond-to-review | inherits the resumed role's |
 | steward | editing set, own territory | kernel-primer, plain-style, ruler-hardening, benchmark-design | literature-search (eval conventions) |
 
 The self-review skill's relationship to the panel is specified in
@@ -252,7 +252,7 @@ is the rare exception).
 
 | Field | Meaning |
 | --- | --- |
-| `name` | role id (author, reviewer, verifier, steward, followup) |
+| `name` | role id (author, reviewer, verifier, steward) |
 | `instructions` | standing role prompt, composed from skills |
 | `skills` | skill ids to load (global + role + target) |
 | `tools` | allowed tools (native + harness-provided) |
@@ -267,7 +267,7 @@ is the rare exception).
 
 Replaces the five per-role drivers' session dispatch — all five roles now run
 through `run_role` with their RoleSpec (`review_cli` and `verifier_cli` are
-deleted; author, follow-up, and steward dispatch from their kernel modules).
+deleted; author and steward dispatch from their kernel modules).
 Kernel code; it calls into the agentic realm at step 2, and everything
 trust-critical is deterministic.
 

{outerloop_science-0.1.1 → outerloop_science-0.2.0rc1}/docs/design/architecture.md

@@ -8,7 +8,8 @@ review.
 A background agent that co-develops the lab's benchmark-bearing repos (jepa-agent,
 egolearn): picks work from their roadmaps and benchmark gaps, implements on a
 branch, runs GPU experiments, opens a PR when a metric improves, reviews PRs, and
-reports weekly. Humans keep the merge button.
+reports weekly. Humans keep the merge button unless a repo owner opts in to
+`merge: auto` in the contract.
 
 ## Decisions
 
@@ -180,12 +181,12 @@ email, no command grammar to learn or to secure.
    its own.
 
 **In flight — humans steer through the PR.** A run whose PR is open enters
-`in-review` and stays alive: each tick, the sweep checks the PR for new
+`parked` and stays alive: each tick, the sweep checks the PR for new
 comments by org members (the advisory reviewer never comments on bot PRs, so
 no bot-to-bot loop can form). A qualifying comment wakes the run — the same
 resume mechanism as experiment wakes, comment text data-fenced, task-level
-supersession only — and the agent pushes fixes and replies on the thread via
-the bot identity. Review-response sessions are bounded like everything else
+supersession only. The author replies on the thread and submits changes
+through the gate and publish. Comments wait while launched jobs are active. Review-response sessions are bounded like everything else
 (attempt counter, budget). Non-member comments never trigger a wake.
 
 **Death — a run ends in exactly one of six ways, each producing a report:**
@@ -209,7 +210,7 @@ honest wording, rather than waiting for the orphan-reconciliation pass to
 mislabel a deliberate "no" as a crash.
 
 After the report is distilled into `lessons/`, the workspace and per-run HOME
-are garbage-collected (grace period first — an `in-review` run's context must
+are garbage-collected (grace period first — a `parked` run's context must
 survive until its PR closes). The notebook is the memory; the run directory
 is scaffolding.
 
@@ -363,11 +364,11 @@ failure can strand a run:
    strand the run.
 3. *Backup — the tick sweeps.* The tick chain (independently kept alive:
    two queued successors, heartbeat, GH-Actions watchdog) scans every run in
-   `waiting` each tick: experiment job terminal per `sacct` + no wake lease
+   `parked` each tick: experiment job terminal per `sacct` + no wake lease
    or completion within a grace window → the tick dispatches the wake
    itself. This covers a lost wake job, a wake killed mid-session, and Slurm
    controller restarts that drop pending jobs.
-4. *Deadline floor.* Every `waiting` run records
+4. *Deadline floor.* Every `parked` run records
    `deadline = submit_time + walltime + slack` (recomputed from `start_time`
    once the job starts, so late scheduling never truncates a healthy run).
    Past the deadline the sweep consults `sacct` and acts on what it finds:
@@ -537,5 +538,9 @@ not yet build-gating.
 - GitHub App (revisit if PAT limits bite)
 - Cloud compute backend (burst valve when Torch queues block)
 - Third-party / self-hosted models
-- Any form of auto-merge on code — never. The sole exception is the prose-only
-  notebook repo.
+- Auto-merge on code is off by default and is never the kernel's decision.
+  A repo owner may turn it on with `merge: auto` in the contract: a PR whose
+  gate and panel read are clean is merged by the kernel sweep, at the blessed
+  head only, through the repo's required checks and branch protection. The
+  kernel never arms GitHub auto-merge in this mode and withdraws old arms.
+  The prose-only notebook repo merges on its secret-scan check alone.

{outerloop_science-0.1.1 → outerloop_science-0.2.0rc1}/docs/design/base-reintegration.md

@@ -23,8 +23,8 @@ Two gaps produced this:
   arbitrarily far from main as siblings merge, and `research-lines.md` already
   names the danger ("a stale line reverting others' wins").
 The kernel already reconciles a PR whose base moves AFTER it opens: an open PR
-keeps its run in the in-review state, and the tick's follow-up conflict wake
-(`followup.py`) fetches the moved base into the workspace and asks the agent to
+keeps its run in the parked state, and the tick's base-move inbox message
+(`attempt.resume_run`) fetches the moved base into the workspace and delivers a base-move message; the author decides whether to
 merge and re-measure. So the only real gap is the first bullet — a line that
 never re-syncs main mid-run and opens its PR against a base superseded days
 earlier.
@@ -66,8 +66,8 @@ The semantic choices, settled — the mechanics follow from them.
    beaten (e.g. "warmdown was taken further by #10"); the agent decides to
    pivot or push on. The kernel never kills a line for it.
 4. **Healing a PR after its base moves: already handled, no new mechanism.**
-   An open PR's run stays in-review, and the follow-up conflict wake already
-   fetches the moved base and asks the agent to merge and re-measure. The
+   An open PR's run stays parked, and the base-move inbox message already
+   fetches the moved base and delivers a base-move message; the author decides whether to merge and re-measure. The
    note's earlier "post-terminal" framing was wrong (terra, #341): the run is
    not terminated while its PR is open. Base reintegration is therefore stage 1
    alone — closing the during-run drift; the post-open case needs nothing new.
@@ -77,7 +77,7 @@ The semantic choices, settled — the mechanics follow from them.
 
 **Build order.** The whole feature is one stage: re-pin at wake with the digest
 (decisions 1–3), the re-measure paid only on keep (decision 5). Decision 4 needs
-no code — the existing follow-up conflict wake already covers a base that moves
+no code — the existing base-move inbox message already covers a base that moves
 after the PR opens.
 
 ## Why this shape addresses the problem
@@ -86,7 +86,7 @@ The base pin is correct during a run — you cannot measure improvement against
 a moving target. The failure is not the pin; it is holding one pin for a
 multi-day run and having no reconciliation once the run ends. Waking the line to merge the fresh base keeps the stability the pin gives
 while bounding the drift to a single iteration, and it reuses the exact
-mechanism the in-review conflict wake already uses — the kernel fetches, the
+mechanism the parked PR wake already uses — the kernel fetches, the
 agent merges — rather than adding new kernel git machinery. The post-open case
-needs nothing more: an open PR's run stays in-review and that same conflict
+needs nothing more: an open PR's run stays parked and that same conflict
 wake already reconciles it.

{outerloop_science-0.1.1 → outerloop_science-0.2.0rc1}/docs/design/consolidation.md

@@ -120,7 +120,7 @@ scope, key), and their spend counts against its budget.
 
 | Now | Fate |
 | --- | --- |
-| `climb`, `steward`, `followup` | Session dispatch collapsed: all five roles run through **one role-runner + a RoleSpec** (judges via their agent modules, `review_cli`/`verifier_cli` deleted; author via `climb_once`; follow-up via `respond_once` under the resuming role's key and scope; steward via `live_steward`) with the harness built from the spec (one `build_harness` for every role). What remains of these modules is each role's kernel half — measure/gate/PR/wake plumbing. The brief/skills halves becoming app config is the remaining consolidation. |
+| `climb`, `steward`, `wake` | Session dispatch collapsed: all five roles run through **one role-runner + a RoleSpec** (judges via their agent modules, `review_cli`/`verifier_cli` deleted; author via `climb_once`; follow-up via `attempt.run_author_leg` under the resuming role's key and scope; steward via `live_steward`) with the harness built from the spec (one `build_harness` for every role). What remains of these modules is each role's kernel half — measure/gate/PR/wake plumbing. The brief/skills halves becoming app config is the remaining consolidation. |
 | `review`, `verifier` (rendering, verdict/blocking machinery) | On the agent-session path; hold the shared vocabulary and rendering both judges use. |
 | `harness`, `brief` | The seam. Keep. Adapters live: claude, codex, hermes. |
 | `orchestrator`, `contract`, `github`, `compute`, `runstate`, `disk`, `limits`, `intake` | Kernel. Barely moves — the point. |

{outerloop_science-0.1.1 → outerloop_science-0.2.0rc1}/docs/design/dispatcher.md

@@ -35,7 +35,7 @@ Dispatch is a **syscall on the existing compute seam** — `submit(JobSpec)` +
 an `afterany` wake job, the same two primitives the tick chain already uses,
 zero new kernel concepts. When the orchestrator (or, in phase 2, an author
 session through a tool) needs an experiment run, it submits the job, writes
-the run record into `waiting` with `experiment_job_id` and a deadline, and
+the run record into `parked` with `experiment_job_id` and a deadline, and
 **ends the session**. Results arrive by wake: the afterany job is the
 primary delivery, the tick's waiting-sweep is the backup (both exist; the
 sweep runs dry today). Nothing polls, and no clock runs while a job queues.
@@ -160,7 +160,7 @@ AFTER the session:
 3. The MEASURE-AND-DECIDE phase — a pure function of `(base_sha,
    candidate_sha, contract, seed, suite_seed)` — dispatches its measures
    through the `Measurer`, and on `MeasurementPending` the run parks as
-   `waiting`. It measures LAZILY, in the same order `climb_once` did: first
+   `parked`. It measures LAZILY, in the same order `climb_once` did: first
    baseline@base_sha + candidate@candidate_sha (one wake); only if that pair
    clears the improvement threshold AND the diff touched shared code does it
    dispatch the sibling pairs (a second wake). A non-improving candidate never
@@ -198,7 +198,7 @@ Sub-parts, each its own PR through the panel:
   logic behind a re-enterable function over committed shas; pure, tested
   with a fake measurer.
 - **B.2b:** wire `live_climb` — session -> snapshot -> measure_and_decide;
-  on park write the `waiting` record (base_sha/candidate_sha/`candidate_ref`/
+  on park write the `parked` record (base_sha/candidate_sha/`candidate_ref`/
   seed/stage + `experiment_job_id` = the afterany set) and end. A terminal
   wake `drop_snapshot`s `candidate_ref` (the snapshot outlives every park/wake
   cycle, so the drop is deferred to run end, never mid-cycle). When a revision
@@ -356,8 +356,8 @@ single writer via lease):
 | field | role |
 |---|---|
 | `run_id` `target` `benchmark` `agent_id` `task_title` `issue_number` `pr_url` | identity/topology |
-| `climb_job_id` | the transaction's own job — lets the sweep tell KILLED from crashed; must be re-stamped by any path re-entering `implementing` from a new job |
-| `experiment_job_id` `wake_job_id` `followup_job_id` | Slurm handles for the dispatched work, its afterany wake, and review servicing |
+| `climb_job_id` | the transaction's own job — lets the sweep tell KILLED from crashed; must be re-stamped by any path re-entering `running` from a new job |
+| `experiment_job_id` `wake_job_id` | Slurm handles for the dispatched work and its afterany wake |
 | `resume_session_id` | the harness session a wake reconstructs — the entire "pause" state for a session's mind |
 | `state` `deadline` `terminal_seen` `wake_attempts` | wake bookkeeping; a waiting record REQUIRES a deadline |
 | `stage` (phase 1) | a small object, not a label: the parked measure point PLUS the process-local state re-entry needs — `base_sha`, `candidate_sha` and the candidate snapshot's `candidate_ref` (random, so it MUST be stored — a terminal wake hands it to `drop_snapshot` or the snapshot leaks), the drawn `seed` and `suite_seed` (both random, both stored so the wake re-measures PAIRED), the pre-eval tree fingerprints the drift check compares (today locals; a resumed process without them would fail the drift check closed on every dispatch), and the expected result-file names. The scope/suite `measured_paths` are NOT in here — they are re-derived from the `base_sha..candidate_sha` diff (step 4), not stored |

{outerloop_science-0.1.1 → outerloop_science-0.2.0rc1}/docs/design/headline.md

@@ -87,11 +87,9 @@ survival the other. No strawman reimplementation.
 Drop the "human keeps the merge button" framing as a principle — it is the
 DEFAULT, not a law. Merge policy becomes a contract knob (`merge:
 manual | auto`, target owner's declaration, like a harness permission mode):
-`auto` = gate + panel clean → the PR merges itself. NOTE the current
-arming path is review-required-shaped (`arm_auto_merge_when_review_required`
-— GitHub only arms against a pending requirement), so `auto` mode needs a
-small publish change: merge directly when the gate CI is the sole
-requirement, arm otherwise. Graded
+`auto` = the kernel sweep merges a clean PR at the head approved by the gate
+and panel, with the API's expected-head guard. Publish never arms GitHub
+auto-merge in this mode. Manual mode keeps the required-review guard. Graded
 autonomy is paper material: interventions per accepted step, measured at
 each grade.
 

outerloop_science-0.2.0rc1/docs/design/lifecycle.md

@@ -0,0 +1,338 @@
+# The run lifecycle: states, messages, and what the kernel decides
+
+**Status: lifecycle redesign landed (2026-09-12).** A re-read of the
+whole lifecycle against one rule, from Mengye: benchmark verification and
+launching jobs are rigid; everything else is the author deciding, through
+tool calls. It absorbs Phase C of `research-loop-buildout.md` and supersedes
+the follow-up sections of `roles.md` and `orchestrator-verify.md`. Built from
+three inventories of the code as of main `8944625` (states and transitions,
+inbound messages and syscalls, standing design rulings) and cross-checked by
+an independent read of the note against the code; the numbers in brackets
+refer to the kernel-decision inventory posted on the PR that carries this
+note.
+
+## The rule
+
+The kernel owns two things because nobody else can be trusted with them:
+
+- **The gate.** The credited number is the kernel's paired measurement of a
+  sealed tree on the fixed benchmark under a private seed, with scope checked
+  on the diff and the suite re-measured when shared paths moved. The author
+  never sees the seed, never edits the ledger, and cannot make a number.
+- **Launching.** Jobs run outside the sandbox under the kernel's containment,
+  on the lane the contract names, metered in counts and GPU-hours, always
+  queued, cancelled when the run ends.
+
+Around those sit invariants that are not science and are not the author's to
+change: who may send a message and who may merge, that a human's commit is
+never overwritten, isolation of the session, crash-proof liveness, a report on
+every ending, the line notebook sealed at every terminal. Everything else is
+judgment, and judgment belongs to the author: what to run, what a result
+means, whether to answer a reviewer with an experiment or a sentence, when to
+submit, when to stop. Where the kernel makes such a call today, that call
+goes.
+
+## What exists
+
+The lifecycle is now the three-state one: `running`, `parked`, `ended`.
+A PR is recorded in `pr_url`. The sweep polls parked runs for terminal jobs,
+checkpoint deadlines and inbox messages. GitHub comments and base moves enter
+the inbox; a run sleeping on jobs receives them with the job results. A PR
+at rest waits without a deadline or idle wake cost. Every author leg resumes
+through `attempt.run_author_leg`, including the steward's review work.
+
+`followup.py` and its job are gone. GitHub collection positions live beside
+the inbox, while the run record carries the delivered sequence. Replies are
+posted by the author leg; only a submit invokes the gate and one publish.
+The six endings and reports remain. Old state names and collection positions
+migrate on read. Each tick logs `legacy follow-up records: N` from raw live
+records; operators must confirm zero across every fleet before deployment.
+
+## The lifecycle
+
+### Three states
+
+| State | Meaning | Leaves it |
+| --- | --- | --- |
+| `running` | a session is live in a job | the session ends: it slept (park), or it stopped (end) |
+| `parked` | no session; the run waits for jobs it launched, for messages, or both | a wake (the same session resumes), or a human ends the PR |
+| `ended` | terminal, with a report | never |
+
+A PR being open is a fact about a run, recorded in `pr_url`, not a state. A
+parked run with a PR is what `in-review` was. `implementing` is `running`;
+`waiting` and `in-review` are `parked`; `concluding` is deleted. The six
+endings stay as they are: merged, rejected, negative result, budget exhausted,
+aborted, stuck. They are how a human reads the board, and every one still
+produces a report.
+
+### One engine: park and wake
+
+A run parks when its session ends with a sleep. A run wakes when the kernel
+has something to deliver: the jobs the session slept on have finished, or a
+message arrived for a run that is not waiting on jobs. A wake resumes the
+same session with everything in its inbox rendered as one data-fenced text.
+That is the whole engine, the same on every backend and in every phase of a
+run: before a PR, with a PR open, after a reviewer writes. The four park
+shapes become one park with a job list that may be empty; the wake paths
+become one.
+
+A sleep on no jobs is a checkpoint. It wakes when a message arrives or at the
+checkpoint deadline, whichever comes first, and the wake text says which. A
+parked run with a PR and no jobs waits for messages without a deadline; idle
+waiting spends no wake attempt and cannot end as stuck.
+
+### Messages
+
+A message is the unit the kernel delivers. Every message has a source and an
+origin (the login, job name or run behind that source), a qualified thread
+such as `owner/repo#9` (the PR when one exists, else the issue the run claimed),
+a trust level (everything but the kernel's own budget and clock lines is data, never
+instructions), and an arrival time. The tick writes messages into the run's
+inbox; the wake drains it in arrival order.
+
+| Message | Source | Written by | Delivered |
+| --- | --- | --- | --- |
+| launch result: exit code, bounded tails, declared artifacts | the author's own job | the sweep, when the job is terminal | at the wake the sleep asked for |
+| gate verdict: the paired numbers, the floor, the suite, or an eval error; the sealed tree, the base and the contract it was measured under | the kernel's measurement of a submitted tree | the sweep, when the gate jobs are terminal | at the wake |
+| panel verdict: blocking and advisory findings, the transcript | judge sessions | the panel run | at the wake |
+| human comment or review, on the run's thread | a person with standing; others as context, never as triggers | the tick's poll | at the next wake |
+| check result: the current PR head, check name, conclusion, URL and bounded log tail | CI, with the app slug or check name as origin | the tick, once per check run and conclusion | failures wake runs sleeping on no jobs; success, neutral and skipped wait as context |
+| head moved: the PR head no longer matches the blessed head | git | the tick, once per new head in auto mode | at the next wake |
+| base moved: the digest of what merged and the siblings' numbers | git, main | the tick, once per new base | at the next wake |
+| budget and clock: counts remaining, the review top-up, walltime | the kernel | the wake itself | leads every wake |
+| PR merged or closed | a human, on GitHub | the tick's poll | ends the run; not delivered |
+
+The author's session never sees a raw comment body outside a fence, never
+sees the seed, and never sees a message the kernel did not write into the
+inbox. Advisory findings are delivered like blocking ones; the author decides
+what to do with them. The sibling view is refreshed at every wake, not only
+at start. The inbox keeps a position per GitHub collection, since issue
+comments, reviews and review comments carry independent id sequences, and
+delivers each message once.
+
+Human messages do not interrupt a sleep on jobs. They wait in the inbox and
+arrive with the job results. The author who wants to answer sooner takes a
+checkpoint sleep. The kernel stays out of scheduling.
+
+The inbox is files: a directory beside the run's record, one file per
+message named by a sequence number, written by temp-and-rename, never
+deleted, outside the workspace so the session cannot forge one. The record
+holds the delivered position. A message file is durable before any poll
+position advances, and the delivered position advances only after the wake's
+session leg ends, so a wake that dies re-delivers; double delivery is
+harmless, as it is for today's leases. Records, leases and the inbox all sit behind
+one small storage interface (put, list, get, conditional put) with a
+filesystem implementation for Slurm and local compute; a cloud backend gives
+it an object-store implementation and nothing else changes. No messaging
+service is needed: delivery only happens at a wake, which the kernel
+triggers, so nothing waits on a push. A job-completion callback may later
+wake the tick sooner than its cadence; that is a trigger, not a transport.
+
+### The author's moves
+
+| Move | What the kernel does | Rigid part |
+| --- | --- | --- |
+| `launch` | stages a contained job for the contract's lane; the author keeps working | metering |
+| `sleep` | seals the tree, submits the staged jobs, records them in the ledger, parks the run on them (possibly none); the results arrive at the wake | containment, placement, the sleep count |
+| `submit` | seals the tree, runs the gate and the panel as jobs, delivers the verdict as a message; a credited verdict publishes | the gate; the publish |
+| `reply` | posts text on the thread the message came from, with secrets redacted and self-approval scrubbed, through the author leg | standing of the poster; redaction |
+| `end` | without a PR, ends with the report and last failed verdict; with an open PR, posts a supplied report and parks for messages | the report |
+
+`reply` and `end` are new. A session that stops without sleeping or
+submitting ends the run with what it has, unmeasured. That is a change: today
+a plain finish is measured by the gate on the tree it left, and can publish.
+Under this note only a submit is measured, on every benchmark, so the author
+always asks for its number. The read-only verbs stay: `status`, `queue`,
+`history`, `siblings`, `reports`, `sync`. The steward has the same moves under
+its own key, with its own scope.
+
+The research advice now written into the wake text and the brief moves to
+the role's instructions, where it can be edited without a kernel change. The
+kernel's wake text states facts: the messages, the counts, the clock.
+
+### Submit, and the one publish
+
+A submit means: measure this sealed tree, and if it is credited, publish it.
+The verdict comes back as a message whatever it says, naming the sealed
+tree, the base and the contract it was measured under. A gate that says no is
+not a terminal; the author reads the numbers and decides to try again, launch
+more, or end. Today a plain finish's failed gate ends the run and a submitted
+park's failed gate wakes the author; the second is right, and with `end` the
+author can still choose the first.
+
+The publish is the one rigid act after the gate, and there is one of it. When
+no PR exists, the kernel opens one from the sealed tree with the number and
+the author's report. When a PR exists, the kernel moves its head to the
+sealed tree and posts the number, after confirming auto-merge is disarmed.
+The move is a fast-forward only: the sealed tree must contain the PR's
+current head. When a person pushed to the PR since the author last saw it,
+the publish is refused and the fact is delivered as a message; the author
+merges and submits again. A human's commit is never overwritten. The publish
+is also refused when the base's contract no longer defines the benchmark
+with the measurement the verdict was made under; a stale verdict is said,
+not published.
+
+Blocking findings at a publish open a draft, or keep the PR as it is, and are
+delivered to the author with the verdict. The ledger row moves only when a
+credited number beats the recorded best by the floor; every other number is
+posted and leaves the row alone. A submit whose number is worse than the PR's
+current one still moves the head, with the number stated plainly; the author
+chose it, the thread shows it, and the PR is merged or not.
+
+A steward submit is a ruler change and is measured as one: the full suite
+runs, every sibling's eval is smoke-checked, and the credited number resets
+the baseline instead of competing with it. That is the steward's publish; the
+steward's copy of the review pipeline is not.
+
+### The meter
+
+One meter for the run's whole life: the launch count, the sleep count and the
+GPU-hours the contract sets, spent from the first session to the last. When a
+PR opens the counts get a small top-up the contract names, so review has
+headroom, and every wake states the counts remaining and that the top-up was
+added, so the author can plan for review while still climbing. A reply costs
+nothing. A run that has spent everything can still reply and end.
+
+### Endings
+
+A run ends when the author ends it, when its PR is merged or closed,
+when the meter runs out, or when the kernel cannot continue: a crash, a
+tampered workspace, or a kernel action that made no progress
+`MAX_WAKE_ATTEMPTS` times, a failed publish retry included. A merge or close
+ends the run at the next tick whatever it is doing: pending jobs are
+cancelled, a session in flight finishes its leg and its publish is refused.
+Every ending writes the report, seals the line notebook, releases the issue
+claim when no PR exists, and cancels the run's live launches. No other path
+ends a run. A gate verdict never ends a run by itself, and a reviewer's
+comment never does.
+
+## What stays rigid
+
+| Kept | Why it is the kernel's |
+| --- | --- |
+| the paired measurement, the private seed, the floor, the suite, the cached baseline rule, the zero-change rule (an unchanged tree cannot be credited), the verdict bound to its sealed tree, base and contract | the number must be nobody's claim |
+| scope on the diff before anything is sealed, launched or measured | the out-of-scope edit could be to the ruler |
+| containment, the lane from the contract, `--nice` on launches, always queue, cancel on end | the session cannot hold GPUs or credentials |
+| launch, sleep and GPU-hour counts; refusal on exhaustion with the numbers | the meter is the only bound on spend |
+| the publish: open or fast-forward the PR head to the sealed tree, the ledger row rule, disarm before a head moves, refuse when a human pushed or the contract moved; under `merge: auto`, record the blessed head and let the sweep merge a clean, quiet PR at that head only, never arm GitHub auto-merge; otherwise humans merge | credit, merge authority, and nobody's work overwritten |
+| the steward's ruler measurement: full suite, sibling smoke checks, baseline reset | a ruler change must be verified as one |
+| standing: which comments are messages, the bot's own markers, the task label; the issue claim and its release; one delivery per message | authorization and liveness |
+| leases, the sweep, deadline floors, the stuck cap, the outage latch, the tamper guard, the report on every ending, the line seal at every terminal | liveness and audit |
+
+## What becomes the author's, and what is deleted
+
+| Today | After |
+| --- | --- |
+| an in-scope edit during review is re-measured as the PR candidate [25, 29] | nothing is measured unless submitted |
+| the base-sync ladder: sync, conflict, behind, withheld, superseded, "the numbers above still stand" [25, 26, 30, 31] | one message, base moved; the author merges or not and submits or not |
+| six withhold wordings for a reverted change [29] | the change is never reverted; the author's tree is the author's |
+| abandon a finished re-measure when the head moved [34] | the publish is a fast-forward or a refusal delivered as a message |
+| the panel re-read after a push, its two-revision cap [36, 37] | a submit runs the panel; findings are a message; the sleep count bounds revisions |
+| `finish_attempts` | folds into `wake_attempts`: any kernel retry without progress counts |
+| the kernel re-pins the base and tells the agent to merge; kernel-written conflict prompts [26, 54] | the base-moved message says what happened; no instruction |
+| a submit is refused until the run has launched [49]; a metered finish without a submit is scored no-improvement [7]; a submit needs a report [50] | the meter and the gate are the constraints; the report is `end`'s and the publish's |
+| a plain finish is measured; its failed gate ends the run as negative-result [9] | only a submit is measured; the verdict is a message; `end` is the author's |
+| research advice in the wake text and the brief | the role's instructions |
+| advisory findings never reach the author; siblings frozen at start | delivered; refreshed |
+| two first-publish implementations; an inline submit that drops its sibling launches | one publish; one job-and-wake path on every backend |
+| three cursors as record fields, `followup_stage`, `panel_wake_*`, `dirty_wake_head`, `extra_update`, `improve_prompt` | one inbox with per-collection positions, one renderer |
+| the steward's copy of the pipeline; its mission text in kernel code [43, 45] | the steward is a role with the same moves and its own publish; its text is role configuration |
+| `MAX_COMMENTS_PER_WAKE`, `PANEL_WAKE_CAP`, `finish_attempts`, `panel_wake_rounds` | gone; the sleep count and `wake_attempts` are the bounds |
+
+Out of this pass, and named so nobody reads their absence as a decision: the
+outer loop's choices (which issue, which benchmark next, an issue naming one
+benchmark [39–42]) belong to a planner note; the declared-comparison gate and
+the portfolio ledger stay in `research-loop.md`.
+
+## The record
+
+```
+run_id, target, benchmark, agent_id, issue_number
+state: running | parked | ended        ending, ending_note
+pr_url                                 the fact a PR is open
+session: backend, model, key_file, resume_session_id
+park: jobs (afterany ids), sealed_ref, base_sha, base_branch, deadline
+inbox: positions per GitHub collection, last delivered message
+meter: launches_used, sleeps_used, gpu_hours_used, review_topup_added
+wake_attempts                          liveness only
+```
+
+Gone from the record: `followup_stage`, `followup_job_id`, `panel_wake_head`,
+`panel_wake_text`, `panel_wake_rounds`, `dirty_wake_head`. `auto_blessed_head`
+stays only as long as `merge: auto` does.
+
+The candidate and submitted phases remain inside `stage`: they describe what
+its jobs measure and what result handling the shared wake must resume. They
+are metadata within the one park, not separate lifecycle states or wake paths.
+
+## Decisions
+
+Settled (Mengye, 2026-09-12):
+
+1. A human message waits for the jobs a run sleeps on; no interrupt.
+2. One meter for the run's life, with a small top-up when the PR opens, stated
+   in every wake.
+3. A worse submit on an open PR moves the head, with the number posted
+   plainly; the ledger row does not move.
+4. `end` is a verb, so a report is asked for at the moment the author
+   decides; a session that simply stops still ends the run with what it has.
+
+5. **Auto-merge** (Mengye, 2026-09-13): the owner opts in with `merge: auto`.
+   Publish records `auto_blessed_head` and never arms GitHub auto-merge in
+   this mode. The sweep merges a clean, quiet PR at that head only, with the
+   API's expected-head guard, while its base contract still permits auto.
+   Old arms are withdrawn; a changed head is a message to the author.
+   Manual mode keeps its required-human-review arming guard.
+
+### Later
+
+Multi-agent collaboration and sub-agent teams will need real addressing:
+sender and recipient, with routable messages. That is a future design item.
+The per-run inbox and outbox stay until then. Replies store their qualified
+thread when staged, so a later PR change does not change their destination.
+
+## Sequencing
+
+Each stage is one PR, reviewed, run from its commit on one fleet before any
+release, and deletes what it replaces. A fleet never lacks a working path
+between stages.
+
+1. **One inbox, one renderer.** Every inbound message, including the ones
+   delivered today, is written to the inbox and rendered by one function;
+   pending blocking findings are read from the inbox from this stage on, so
+   `panel_wake_text` can go. Advisory findings and a refreshed sibling view
+   ride along. No lifecycle change yet.
+2. **Messages reach a parked author.** Status: landed. `reply` exists. A run with an open PR
+   parks; comments and base moves are inbox messages; the author can launch,
+   reply and sleep in review. A session that edits code in review still goes
+   through today's re-measure-and-push until the next stage replaces it.
+3. **Submit in review, and `end`.** Status: landed in full, including `end`
+   and the review top-up. The publish moves the PR head by
+   fast-forward; a gate verdict is a message on every path; the meter's
+   top-up exists; the submit policies [7, 49, 50] go; the follow-up
+   re-measure path no longer runs.
+4. **Three states.** Status: landed. `running`, `parked`, `ended`; the record migrates on
+   read. This stage lands only when no live record on any fleet carries
+   `followup_stage` or a follow-up job; the tick reports the count until it is zero.
+   `followup.py`, the steward's pipeline copy, and the counters are deleted
+   with their tests.
+
+5. **Session memory, message identities, CI results and direct merging.** Status: landed.
+   Memory guidance covers every session boundary. Messages carry origins and
+   qualified threads; staged replies keep their destinations. CI results and
+   head moves use the inbox. Auto mode merges through the sweep at the blessed
+   head and never arms GitHub auto-merge.
+
+## Standing contradictions this settles
+
+- Launches are submitted at sleep time, not when `launch` is called: kept.
+  Staging is the primitive; the author keeps working after a launch and the
+  jobs start when it sleeps.
+- There is a live channel to a running session, the watcher, for read-only
+  questions. `roles.md`'s "no live channel" is stale.
+- A follow-up's change is not re-measured by the orchestrator; only a submit
+  is measured. `roles.md` and `orchestrator-verify.md` are superseded here.
+- The panel re-read loop after a push is retired; a submit runs the panel.
+- A moved base is told, never forced; the finish's "merge and re-measure
+  both sides" in `roles.md`'s flow is retired.
+- One batch in flight per run is not a rule; launch several, sleep once.