outerloop-science 0.1.0.dev3__tar.gz → 0.1.0.dev4__tar.gz

{outerloop_science-0.1.0.dev3 → outerloop_science-0.1.0.dev4}/CHANGELOG.md

@@ -6,8 +6,58 @@ Versions follow [SemVer](https://semver.org).
 
 ## [Unreleased]
 
+### Changed
+
+- Install guide: a lab member who is not an org owner now has documented steps
+  for GitHub App auth — make the personal App public, request the install, an
+  org owner approves, then optionally transfer the App to the org — matching
+  what `init --github-app` prints on the personal-App fallback.
+- Docs: corrected stale `autoresearch` command and module paths left by the
+  rename (onboarding, author-syscalls, architecture, role-cli), refreshed the
+  architecture component map (`budget` → `limits`, `report` →
+  `progress`/`climbboard`), and documented the tick scheduling knobs
+  `OUTERLOOP_CADENCE_MIN`, `OUTERLOOP_MAX_JOB_MINUTES`, and
+  `OUTERLOOP_MIN_TICK_MINUTES` in the install guide.
+
+- The maintainer digest issue now carries the scan date in its title
+  (`Maintainer digest — YYYY-MM-DD`), so its freshness shows in the issue list.
+  The scan's long verdict and rejected-findings text now folds into a
+  collapsible block, keeping the top of the issue a short summary (title,
+  advisory line, counts).
+
+### Fixed
+
+- `outerloop init --github-app` no longer dead-ends a non-owner of an
+  organization. Creating an org-owned App needs org-owner rights, so GitHub
+  makes a personal App that will not install on the org repo by default. init
+  now detects that the App landed under a different account and prints the path
+  that works — make it public, request the install, have an org owner approve
+  it, then rerun `init --force --github-app` (and optionally transfer the App to
+  the org). The install-failure help names the same steps.
+
+### Fixed
+
+- The follow-up finalizer no longer gets stuck withholding a measured re-sync
+  when auto-merge is already off. Before pushing a re-measured head it confirms
+  the PR will not auto-merge by the PR's actual auto-merge state, rather than by
+  matching one error string — whose text varies with the repo's "Allow
+  auto-merge" setting and the token type — so a merge:manual repo under a GitHub
+  App token no longer re-withholds its successful re-measurements.
+
 ### Added
 
+- `outerloop upgrade`: one verb for a local install to move to the newest
+  release (`--pre` to track pre-releases), the local counterpart of the Slurm
+  resident tick's `OUTERLOOP_AUTO_UPDATE` policy. It runs `pip install --upgrade`,
+  reports the version change, and reminds you to restart the loop.
+- Base reintegration (docs/design/base-reintegration.md): when a research
+  line's base moves while it sleeps, its wake fetches the fresh base and tells
+  the agent to merge it and decide what to re-run — the same fetch-and-merge
+  the in-review conflict wake already uses, so a long depth run no longer
+  drifts behind sibling merges and opens a stale PR.
+- `docs/design/base-reintegration.md`: a proposal to keep a running line's
+  base current by re-pinning at each wake and to reconcile a PR whose base
+  moved after the run ended, with the owner's five decisions and the build order.
 - A weekly maintenance digest (`maintenance-agent.yml`, reusable; the kernel's
   own caller is `maintenance.yml`): read-only lens sessions scan a repository's
   default branch for dead pathways, duplicated logic, oversized modules, stale
@@ -649,6 +699,19 @@ Versions follow [SemVer](https://semver.org).
 
 ### Changed
 
+- CI and reusable-workflow Actions bumped to current majors: actions/checkout
+  v7, astral-sh/setup-uv v10, upload-artifact v7, download-artifact v8. The
+  single-name artifact downloads stay flat and the pattern download reads
+  recursively, so the review split is unaffected; the node24 runtime is on the
+  hosted runners.
+- The tick reads its run records once per phase instead of once per service: a
+  single snapshot after the mutation phase feeds the read services, and one
+  feeds the board pass. About twelve full run-directory scans per tick become
+  five, which matters under a large fleet (the 2026-09-03 disk pressure); the
+  freshness guards that re-read a single record are unchanged.
+- The maintenance scan gains an `architecture` lens: it proposes abstraction
+  simplifications and missing extension points (a new backend, benchmark, or
+  role should need zero kernel change), as decision-kind digest items.
 - Helpers shared across kernel modules are public in their owning module:
   `brief.code_fence`, `brief.cap`, `attempt.target_clone_url`,
   `attempt.stage_launch_job_ids`, `orchestrator.metric_from_output`,

{outerloop_science-0.1.0.dev3 → outerloop_science-0.1.0.dev4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: outerloop-science
-Version: 0.1.0.dev3
+Version: 0.1.0.dev4
 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.0.dev3 → outerloop_science-0.1.0.dev4}/docs/design/architecture.md

@@ -35,7 +35,7 @@ scope:
 roadmap: docs/roadmap.md
 ```
 
-The schema lives here (`autoresearch.contract`). The loader hard-codes invariants
+The schema lives here (`outerloop.contract`). The loader hard-codes invariants
 no YAML can override: `.github/`, the contract file itself, and the roadmap are
 always forbidden write paths; the contract is read from the default branch only;
 **autoresearch is never a valid target of itself**.
@@ -278,7 +278,7 @@ insights across all targets and must never be part of any public flip. Raw
 metrics stay in W&B; the notebook links to runs. No database or vector store —
 grep + recency + distillation until that provably fails.
 
-## Components (`src/autoresearch/`)
+## Components (`src/outerloop/`)
 
 | Module | Job |
 | --- | --- |
@@ -287,8 +287,8 @@ grep + recency + distillation until that provably fails.
 | `orchestrator` | Tick logic: sentinel, lease, task selection, session dispatch, state sync |
 | `compute` | sbatch/squeue submit-and-poll behind one interface |
 | `github` | Bot auth and push (orchestrator-side, after sessions end), PR/issue ops |
-| `budget` | Hard caps: $ per run, weekly $, GPU-hours, PRs per week; subscription backends metered by a session/token proxy |
-| `report` | Per-run research reports (takeaways + next steps), notebook writes + distillation, weekly digests, cost ledger, leaderboard history |
+| `limits` | Effective session and job limits — turns, session and job minutes — with each contract wish clamped into our `[floor, ceiling]`; the tick's `OUTERLOOP_MAX_JOB_MINUTES` floors here |
+| `progress` / `climbboard` | `progress` writes the human-readable benchmark-progress files into the target repo on each improvement PR; `climbboard` publishes the climb board — every ended attempt and its outcome, plus the ledger and views — to the target's `research-log` branch whenever runs end |
 
 ## Harness and context engineering
 
@@ -309,7 +309,7 @@ exactly what any given agent saw, and a bad run can be replayed from its brief:
 | Ruler: how the metric is computed, how claims get re-verified | target repo docs | fixed |
 | Lessons: distilled, bounded per-target lessons file | notebook `lessons/<target>.md` | hard cap |
 | Recent history: last N run reports for this target (incl. failures) | notebook `runs/<target>/` | hard cap, newest first |
-| Budget state: remaining GPU-hours/$/PRs this week | `budget` | fixed |
+| Budget state: remaining GPU-hours/$/PRs this week | tick weekly accounting | fixed |
 
 Everything else is deliberately absent: no other targets' data (cross-target
 separation), no raw transcripts (distillation instead), no maintainer-private

outerloop_science-0.1.0.dev4/docs/design/base-reintegration.md

@@ -0,0 +1,92 @@
+# Base reintegration: keeping a running line current, and reconciling its PR
+
+Status: proposal (2026-09-08). Extends `research-lines.md`, which owns the
+per-agent branch and the "merge main in at run start" rule. Prompted by a
+real case, PR #12 on gpt-speedrun.
+
+## The problem, concretely
+
+agent-04's line started 2026-09-04 in the morning. That evening a sibling
+merged #10, moving the record from 8192 to 7808. agent-04's line kept
+iterating on its own 8192-era base for three more days and opened PR #12
+claiming 7232, against a base that had been superseded on day one.
+
+The claim was real: 7232 came from setting `warmdown_iters` to 6400, the same
+knob #10 set to 4352, on a monotonic trend, and it holds against the current
+base. But the PR conflicted, and by the time it opened, the run had
+terminated, so nothing in the kernel could reconcile it. A human merged it by
+hand.
+
+Two gaps produced this:
+
+- A line merges main only at run start. A long depth run therefore drifts
+  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
+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.
+
+## Proposed protocol
+
+1. **Re-pin at each wake, not only at run start.** When a line wakes for its
+   next depth iteration, the kernel merges main into the line and hands the
+   agent a short digest of what changed since it last ran — the sibling record
+   moves and the files they touched. The agent decides what to re-run given
+   the new base. This bounds drift to a single iteration instead of the whole
+   run.
+
+2. **Never mid-experiment.** A running eval keeps its base. Re-pinning happens
+   only at the iteration boundary, the sleep-to-wake seam, so no in-flight
+   measurement is invalidated and no launch is wasted.
+
+3. **Re-measure the baseline at the new merge-base.** This is the roadmap's
+   "baseline re-run at merge-base." `research-lines.md` already makes every
+   claim name the baseline pair it was measured against, so a re-pinned line
+   stays legible about which base each number used.
+
+4. **Keep a PR reconcilable after the run's terminal.** A line whose PR is
+   open stays reachable until the PR is merged or closed, so a base that moves
+   after the PR opens fires the existing conflict wake — merge main,
+   re-measure, push — instead of stranding the PR for a human.
+
+## Decisions (owner, 2026-09-08)
+
+The semantic choices, settled — the mechanics follow from them.
+
+1. **Re-pin cadence: only when main moved.** Each wake does a cheap
+   fetch-and-compare; it re-merges and re-pins only when a sibling actually
+   landed something. No churn when nothing changed.
+2. **What the agent sees: the record move, plus each sibling PR's metric and a
+   one-line summary — not full diffs.** Enough to decide whether its line is
+   still worth pursuing, without flooding its context.
+3. **A superseded axis: tell, don't force.** The wake digest says its axis was
+   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
+   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.
+5. **Who pays the re-measure GPU: only when the agent keeps its change.** The
+   re-measure is then a normal launch against the line's own budget. No eager
+   baseline re-runs on every merge.
+
+**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
+after the PR opens.
+
+## Why this shape addresses the problem
+
+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
+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
+wake already reconciles it.

{outerloop_science-0.1.0.dev3 → outerloop_science-0.1.0.dev4}/docs/design/onboarding.md

@@ -15,7 +15,7 @@ honest when it says three steps:
 
 ## What the wizard does
 
-`python -m autoresearch.init` (interactive; every answer has a flag for
+`python -m outerloop.init` (interactive; every answer has a flag for
 non-interactive use):
 
 - **Detect compute.** `sbatch` on PATH → Slurm mode (prompt for account and
@@ -47,7 +47,7 @@ non-interactive use):
   The doctor is re-runnable on its own (`init --doctor`) and is the first
   thing support asks for.
 - **Print the start command.** Nothing starts implicitly. The command is
-  `autoresearch start` on both paths: it submits the resident tick where
+  `outerloop start` on both paths: it submits the resident tick where
   `sbatch` exists and runs the local loop elsewhere, taking the root and
   placement from flags, the environment, or the `.env` the wizard wrote.
 
@@ -73,7 +73,7 @@ simultaneously the zero-Slurm on-ramp and the paper's Karpathy-loop
 ablation cell (width 1 × serialized) — the same kernel, the compute seam
 swapped, nothing else different.
 
-- **The chain is a loop.** No sbatch → `autoresearch start` runs
+- **The chain is a loop.** No sbatch → `outerloop start` runs
   `tick --loop`, a tick every cadence in the foreground. State stays in records on
   disk, so killing and restarting the loop resumes exactly like the Slurm
   chain surviving a dead tick.
@@ -98,8 +98,8 @@ swapped, nothing else different.
    `OUTERLOOP_COMPUTE` selection at the two `SlurmCompute()` sites,
    `tick --loop`, local-mode wake-arming skip, per-mode required-env
    relaxation (no account/partition in local mode), and the one launch
-   command `autoresearch start` (`src/autoresearch/cli.py`). Done.
-2. **The wizard**: `autoresearch.init` — detection, prompts, `.env` writer,
+   command `outerloop start` (`src/outerloop/cli.py`). Done.
+2. **The wizard**: `outerloop.init` — detection, prompts, `.env` writer,
    doctor (PAT path first).
 3. **The manifest flow**: App mint + installation discovery inside the
    wizard.

{outerloop_science-0.1.0.dev3 → outerloop_science-0.1.0.dev4}/docs/design/reviewer-infra.md

@@ -252,9 +252,9 @@ cron (weekly) or by hand. It fans out one read-only lens session per digest
 section (`maintain.MAINTENANCE_LENSES`, plus `general` for the whole
 checklist) over a checkout of the calling repository's default branch, merges
 the opinions with the same summarizer the wide review round uses, and posts
-ONE rolling issue ("Maintainer digest") whose body each scan replaces;
-earlier digests stay in the edit history, and a short comment per scan
-notifies watchers. The role is `roles.maintainer_spec`: the reviewer's tools
+ONE rolling issue (titled "Maintainer digest — <date>", the date of the digest
+it currently shows) whose body each scan replaces; earlier digests stay in the
+edit history, and a short comment per scan notifies watchers. The role is `roles.maintainer_spec`: the reviewer's tools
 and verdict shape (findings through the syscall tool, no scope), a larger
 budget because a tree is more to read than a diff. Items carry a section
 (`--category`), an effort and risk estimate, and a kind: `change` is

{outerloop_science-0.1.0.dev3 → outerloop_science-0.1.0.dev4}/docs/design/role-cli.md

@@ -30,7 +30,7 @@ The invariants, proven on #132/#133 and non-negotiable everywhere:
    kernel-side (authoritative validators, PAT-out-of-session, scope, budgets).
    The tool is ergonomics and fast feedback; authority stays in the kernel.
 2. **Sandbox-side tools are standalone** (stdlib-only — the target repo has no
-   autoresearch), which duplicates a little advisory validation, pinned by
+   outerloop), which duplicates a little advisory validation, pinned by
    parity tests (`test_artifact_path_check_matches_the_kernel`).
    **Orchestrator-side roles** (reviewer/verifier/panel/planner/steward run on
    our own checkout, not a target sandbox) import the real validators — no

{outerloop_science-0.1.0.dev3 → outerloop_science-0.1.0.dev4}/docs/install.md

@@ -105,8 +105,9 @@ always exits successfully so your PR stays green.
 
 The same reviewer, pointed at your whole repository once a week: dead code,
 duplicated logic, oversized modules, stale pins, slow tests, repeated work on
-the hot path, documentation drift. It writes one issue, "Maintainer digest",
-and replaces its body each scan. It changes no code and opens no work orders.
+the hot path, documentation drift. It writes one issue, titled "Maintainer
+digest — <date>" (the date of the digest it shows), and replaces its body each
+scan. It changes no code and opens no work orders.
 Add `.github/workflows/maintenance.yml` with the same secret as the reviewer:
 
 ```yaml
@@ -227,6 +228,21 @@ declares Contents, Issues and Pull requests read-write and Metadata read,
 nothing else. If the install step was cut short, run
 `outerloop init --force --github-app` to finish and re-check it.
 
+**If you are a member, not an owner, of the organization.** Creating an App
+*owned by the org* needs org-owner rights, so init falls back to creating one
+under your personal account — and a personal App does not install on an org
+repo by default. You do not need an org-owned App or a shared key:
+
+1. In the App's settings, make it **public** (a private App installs only on
+   its owner's account, which is why the org repo is not offered).
+2. Request its installation on your repo; an **org owner approves** the request.
+3. Run `outerloop init --force --github-app` to record the installation.
+
+Your key never leaves your machine. To let the lab own the App centrally later,
+transfer it to the org from the App's Advanced settings — the same key keeps
+working, so nothing has to be recreated. init prints these steps itself when it
+detects the personal-App fallback.
+
 **A fine-grained PAT — the fallback.** For an org that already runs a machine
 user, or one where you cannot create Apps: pick `pat` (or pass `--pat-file`).
 Mint the token on the machine user with these settings:
@@ -284,8 +300,10 @@ release tag at the next cadence (pre-releases included; the repo is public, so
 no credential is needed). `main` follows every merge and is meant for the
 kernel's own developers. Whatever moves the checkout, you or the policy, the
 environment is synced to the commit that is checked out, or the deploy rolls
-back to the last commit whose environment was installed. The local loop runs the installed package: upgrade it with
-`pip install -U outerloop-science` and start it again.
+back to the last commit whose environment was installed. The local loop runs
+the installed package, which has no such policy: run `outerloop upgrade` to move
+it to the newest release (add `--pre` to track pre-releases), then start it
+again. That is `pip install --upgrade outerloop-science` under one verb.
 
 Experiments run wherever your `compute` backend says. Slurm is the first
 backend; the interface is small (submit a job, poll for completion), so a CI
@@ -318,7 +336,14 @@ still read). A Codex author always runs contained, so it also needs the image
 cluster, evals 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, and
-GPU jobs are requested per node (`--gpus-per-node`).
+GPU jobs are requested per node (`--gpus-per-node`). The tick has three
+scheduling knobs. `OUTERLOOP_CADENCE_MIN`, read from the `.env`, is how often the
+chain ticks (minutes; default 30). Two finer ones are read from the tick's own
+environment (set at launch, not the per-tick `.env`): `OUTERLOOP_MIN_TICK_MINUTES`
+coalesces ticks that land too close together (0 disables; unset defaults to the
+lesser of 10 minutes and half the cadence), and `OUTERLOOP_MAX_JOB_MINUTES` caps
+the walltime the tick requests for the climb and author-sleep wake jobs it sizes
+(clamped under a code ceiling).
 
 **Local mode without an image.** On a machine with no Apptainer image,
 `OUTERLOOP_COMPUTE=local` still runs. Sessions run under the harness's own

{outerloop_science-0.1.0.dev3 → outerloop_science-0.1.0.dev4}/docs/validation/author-syscalls.md

@@ -22,7 +22,7 @@ Then run one climb by hand (not via the tick):
 
 ```bash
 source env.sh
-uv run python -m autoresearch.attempt \
+uv run python -m outerloop.attempt \
   --target <org/repo> --benchmark <a-cheap-benchmark> \
   --run-root <run-root> --image <image.sif> \
   <the account/partition/limit args the tick normally passes>

{outerloop_science-0.1.0.dev3 → outerloop_science-0.1.0.dev4}/src/outerloop/__init__.py

@@ -2,7 +2,7 @@
 
 import os
 
-__version__ = "0.1.0.dev3"
+__version__ = "0.1.0.dev4"
 
 
 def _bridge_legacy_env() -> None:

{outerloop_science-0.1.0.dev3 → outerloop_science-0.1.0.dev4}/src/outerloop/appauth.py

@@ -17,8 +17,10 @@ network; the production signer lives behind the `app-auth` extra.
 
 from __future__ import annotations
 
+import argparse
 import base64
 import json
+import os
 import time
 import urllib.error
 import urllib.parse
@@ -29,6 +31,7 @@ from pathlib import Path
 from typing import Any
 
 from outerloop.github import AUTH_SAFE_OPENER, FileTokenProvider, TokenProvider
+from outerloop.paths import CONFIG_DIR
 
 # RS256-sign the JWT signing input, returning the raw signature bytes.
 Signer = Callable[[bytes], bytes]
@@ -211,3 +214,17 @@ def resolve_bot_auth(pat_file: str | Path, app_file: str | Path = "") -> TokenPr
     if str(app_file).strip():
         return app_provider_from_file(Path(str(app_file)).expanduser())
     return FileTokenProvider(Path(str(pat_file)).expanduser())
+
+
+def add_credential_args(parser: argparse.ArgumentParser) -> None:
+    """Add the shared bot-auth options to a role parser: `--pat-file`, and
+    `--github-app-file`, which supplies installation tokens instead of the PAT
+    when set. `resolve_bot_auth` reads the pair. One owner so the defaults and
+    help cannot drift between attempt, followup, and steward."""
+    parser.add_argument("--pat-file", default=str(CONFIG_DIR / "bot_pat"))
+    parser.add_argument(
+        "--github-app-file",
+        default=os.environ.get("OUTERLOOP_GITHUB_APP_FILE", ""),
+        help="GitHub App config (JSON: app_id, installation_id, private_key); "
+        "when set, installation tokens replace the PAT",
+    )

{outerloop_science-0.1.0.dev3 → outerloop_science-0.1.0.dev4}/src/outerloop/attempt.py

@@ -26,7 +26,7 @@ from functools import partial
 from pathlib import Path
 from typing import Any, cast
 
-from outerloop.appauth import resolve_bot_auth
+from outerloop.appauth import add_credential_args, resolve_bot_auth
 from outerloop.brief import BudgetState, distill_lessons
 from outerloop.compute import LocalCompute
 from outerloop.contract import Benchmark, Contract, contract_text_in_tree, load_contract
@@ -928,6 +928,22 @@ def _wake_author_sleep(
     if extra_update:
         # a submitted park's gate/panel feedback leads; launch results follow
         wake_text = f"{extra_update}\n\n{wake_text}"
+    # A research line whose base moved while it slept RE-PINS to the fresh base
+    # and is told to merge it: the agent does the merge (mirroring the in-review
+    # conflict wake, followup.py), the kernel only fetches and re-pins. Re-pinning
+    # base_sha to the fresh head is what makes the gate baseline and the scope
+    # base the CURRENT base (like followup's base_sha_at_fetch), so a sibling's
+    # merged work is never credited to this line and a forbidden conflict
+    # resolution (differing from the fresh base) is still scope-checked. Non-line
+    # runs and an unmoved base are untouched.
+    if _line_ref_for(bench, config.agent_id):
+        fresh_base = _line_base_advanced(ws, base_branch, base_sha)
+        if fresh_base:
+            digest = _reintegration_digest(ws, base_sha, fresh_base)
+            base_sha = fresh_base
+            wake_text = (
+                REINTEGRATE_PROMPT.format(base_branch=base_branch, digest=digest) + wake_text
+            )
     _best_effort(
         "budget refresh",
         lambda: write_budget(
@@ -1296,6 +1312,54 @@ def _line_ref_for(bench: Benchmark | None, agent_id: str) -> str:
     return f"agents/{agent_id}"
 
 
+# The base moved under a line while it slept: rather than the kernel doing a
+# git merge (which mishandles the agent's in-flight tree, its conflicts, and
+# the scope gate), the wake mirrors the in-review conflict wake — fetch the
+# fresh base into the workspace and TELL THE AGENT to merge it. The agent has
+# git and already resolves the run-start merge as its first task; only the
+# credential-bearing fetch/push are the kernel's. No commit text goes in the
+# prompt (no cross-agent prompt-injection surface); the agent reads what
+# landed from git itself.
+REINTEGRATE_PROMPT = (
+    "# The base moved while you were asleep\n"
+    "`origin/{base_branch}` advanced since your last run and is fetched into "
+    "your workspace. What landed:\n{digest}\n"
+    "Merge it into your line and resolve any conflicts honestly, then decide "
+    "what to re-run given what landed — if a sibling took your direction "
+    "further, pivot or say so plainly rather than pushing on. Your change is "
+    "measured against the current base.\n\n"
+)
+
+
+def _reintegration_digest(ws: Workspace, base_sha: str, fresh_head: str) -> str:
+    """A short 'what landed' list: the subjects of the commits merged into the
+    base since this line's base, newest first, capped. These are MERGED commits
+    — vetted by the human-merge gate — so they are context, not untrusted input;
+    the agent also has them in git to read in full."""
+    try:
+        out = ws.git("log", "--no-merges", "--format=%s", f"{base_sha}..{fresh_head}")
+    except Exception:
+        return "  (recent changes on the base; see `git log`)"
+    subjects = [ln.strip() for ln in out.splitlines() if ln.strip()][:12]
+    return "\n".join(f"  - {s}" for s in subjects) or "  (a merge on the base; see `git log`)"
+
+
+def _line_base_advanced(ws: Workspace, base_branch: str, base_sha: str) -> str:
+    """Fetch `origin/<base_branch>` and return its head when it has advanced
+    past the line's pinned base, else "". The fetch doubles as making the
+    fresh base available for the agent to merge and refreshes the origin refs
+    the scope/measure path pairs against. Best-effort: any git failure returns
+    "" and the wake proceeds exactly as today."""
+    try:
+        ws.fetch_origin()
+        new = ws.git("rev-parse", f"refs/remotes/origin/{base_branch}").strip()
+        merge_base = ws.git("merge-base", new, base_sha).strip()
+        return new if new and merge_base != new else ""
+    except Exception as exc:
+        log.warning("base-moved check failed (%s); wake proceeds unchanged", type(exc).__name__)
+        return ""
+
+
 def _push_line_snapshot(
     ws: Workspace,
     line_ref: str,
@@ -3447,13 +3511,7 @@ def main() -> int:
         default=120.0,
         help="how long before the walltime the self-deadline fires (floor 60)",
     )
-    parser.add_argument("--pat-file", default=str(CONFIG_DIR / "bot_pat"))
-    parser.add_argument(
-        "--github-app-file",
-        default=os.environ.get("OUTERLOOP_GITHUB_APP_FILE", ""),
-        help="GitHub App config (JSON: app_id, installation_id, private_key); "
-        "when set, installation tokens replace the PAT",
-    )
+    add_credential_args(parser)
     parser.add_argument(
         "--key-file",
         default="",

{outerloop_science-0.1.0.dev3 → outerloop_science-0.1.0.dev4}/src/outerloop/cli.py

@@ -499,6 +499,55 @@ def start(args: argparse.Namespace) -> int:
     return 0
 
 
+DIST = "outerloop-science"  # the PyPI distribution; imported as `outerloop`
+
+
+def _installed_version(python: str) -> str:
+    """The installed version of the distribution, read from a fresh interpreter
+    so it reflects what pip just wrote rather than this process's imported copy."""
+    proc = subprocess.run(
+        [python, "-c", f"import importlib.metadata as m; print(m.version({DIST!r}))"],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    return proc.stdout.strip() or "unknown"
+
+
+def upgrade(args: argparse.Namespace) -> int:
+    """Upgrade the installed package in place, the local adopter's one verb.
+
+    On Slurm the resident tick self-updates through OUTERLOOP_AUTO_UPDATE; a local
+    install has no such loop, so this is the equivalent: `pip install --upgrade`,
+    then you restart the loop to pick the new code up. Pip already picks the newest
+    release and only falls back to a pre-release when that is all that is published;
+    --pre forces pre-releases even once a stable exists."""
+    cmd = [sys.executable, "-m", "pip", "install", "--upgrade", DIST]
+    if args.pre:
+        cmd.append("--pre")
+    if args.dry_run:
+        print(shlex.join(cmd))
+        return 0
+    before = _installed_version(sys.executable)
+    proc = subprocess.run(cmd, check=False)
+    if proc.returncode != 0:
+        print(
+            f"upgrade failed (pip exited {proc.returncode}). If this environment has no "
+            f"pip, upgrade through its installer instead, e.g. `uv pip install --upgrade {DIST}`.",
+            file=sys.stderr,
+        )
+        return proc.returncode
+    after = _installed_version(sys.executable)
+    if before == after:
+        print(f"already up to date: outerloop {after}.")
+    else:
+        print(
+            f"upgraded outerloop {before} -> {after}. Restart the loop to pick it up: "
+            f"stop the running tick, then `outerloop start`."
+        )
+    return 0
+
+
 def main(argv: list[str] | None = None) -> int:
     from outerloop import __version__
 
@@ -539,6 +588,17 @@ def main(argv: list[str] | None = None) -> int:
         help="guided setup: write ~/.config/outerloop/.env and the PAT file",
         add_help=False,
     )
+    up = sub.add_parser(
+        "upgrade",
+        help="upgrade the installed package, then restart the loop to pick it up",
+        description="Upgrade outerloop-science in this environment with pip. On Slurm the "
+        "resident tick self-updates through OUTERLOOP_AUTO_UPDATE; this is the equivalent "
+        "for a local install. Restart the loop afterwards to run the new code.",
+    )
+    up.add_argument(
+        "--pre", action="store_true", help="include pre-releases even once a stable exists"
+    )
+    up.add_argument("--dry-run", action="store_true", help="print the command and exit")
     argv = sys.argv[1:] if argv is None else list(argv)
     if argv[:1] == ["tick"]:
         # the tick entry owns its own parser; hand it the rest untouched
@@ -551,7 +611,10 @@ def main(argv: list[str] | None = None) -> int:
         from outerloop import init
 
         return init.main(argv[1:])
-    return start(parser.parse_args(argv))
+    args = parser.parse_args(argv)
+    if args.command == "upgrade":
+        return upgrade(args)
+    return start(args)
 
 
 if __name__ == "__main__":