[codex] Add subagent context hygiene guidance

.claude/agents/researcher-agent.md

@@ -139,6 +139,8 @@ summarize what the experiment history now implies:
 
 **Why this matters:** this is the memory update. If the research state does not change after reading and experimentation, the next cycle will drift back toward random search.
 
+Protect the parent advisor's context. Do not return raw paper text, PR dumps, W&B histories, or long log excerpts. Return compact, sourced synthesis with enough provenance for the advisor to verify: PR numbers, run IDs, metric names, links, commands/configs when relevant, and the uncertainty that remains. For large explorations, write durable notes under `/research/` and return the path plus the decision-relevant summary.
+
 ### Experiment tree
 
 when suggesting multiple experiments, return a decision tree rather than an idea list. If experiment A succeeds, what follows? If it fails, what belief changes and what should happen next?

k8s/entrypoint-advisor.sh

@@ -151,7 +151,7 @@ KEY_INFO=$'\n\n Key information:\n\n Students: '"$STUDENT_NAMES"' | GPUs per Stu
 FULL_PROMPT="${PROMPT}"$'\n\n'"${KEY_INFO}"
 
 # Heartbeat prompt for polling
-HEARTBEAT_PROMPT="Continue your advisor loop. Attached is the current research state. Review any completed experiment PRs, assign work to all idle students, and check for human gh issues and comments."
+HEARTBEAT_PROMPT="Continue your advisor loop. Attached is the current research state. Review any completed experiment PRs, assign work to all idle students, and check for human gh issues and comments. Protect the advisor context: use sub-agents for bulky PR, W&B, log, issue, literature, or repo scans; bring back compact sourced summaries; and write durable research state to PR comments or research docs."
 
 # --- Last-check timestamp state for filtering GitHub issues ---
 LAST_CHECK_FILE="$LOGDIR/.last_check_ts"

k8s/entrypoint-student.sh

@@ -94,7 +94,7 @@ fi
 KEY_INFO=$'\n\nKey information:\n\nStudent: '"$STUDENT_NAME"' | GPUs per Student: '"$GPUS_PER_STUDENT"' | Target repo: '"$GH_REPO"' | Target base branch: '"${TARGET_REPO_BRANCH:-<default>}"' | Advisor Branch: '"$ADVISOR_BRANCH"' | W&B entity/project: '"$WANDB_ENTITY"'/'"$WANDB_PROJECT"$'\n'
 FULL_PROMPT="${PROMPT}"$'\n\n'"${KEY_INFO}"
 
-HEARTBEAT_PROMPT="Continue your student loop using the assigned PRs and GitHub issues listed in the Student research state below. The entrypoint owns assignment polling; do not start persistent GitHub polling monitors. For active training, use sparse wakeups plus training_log_status; do not stream per-epoch logs into Monitor."
+HEARTBEAT_PROMPT="Continue your student loop using the assigned PRs and GitHub issues listed in the Student research state below. The entrypoint owns assignment polling; do not start persistent GitHub polling monitors. For active training, use sparse wakeups plus training_log_status; do not stream per-epoch logs into Monitor. Delegate bulky logs, sweeps, repo scans, and crash archaeology to sub-agents where possible, and preserve only compact findings plus durable PR comments in your main context."
 
 # --- Launch Claude Code Loop ---
 export IS_SANDBOX=1

k8s/launch.py

@@ -124,6 +124,9 @@ def build_extra_instructions(args: Args, tag: str, student_list: list[str]) -> s
 - Do not use unrelated experiment runs or historical results unless the human explicitly names them during this launch.
 - Students branch from `{args.advisor_branch}`. Do not rebase or retarget work onto unrelated branches.
 - Treat `SENPAI_TIMEOUT_MINUTES` and `SENPAI_MAX_EPOCHS` as hard per-training-run bounds. Do not override them or continue a run past them.
+- Treat PR comments, git history, W&B runs, and `research/` docs as durable state. Local summaries are caches.
+- Use sub-agents as context compressors for bulky raw evidence: PR histories, W&B sweeps, training logs, papers, issue threads, repo-wide searches, and pod/debug output.
+- Sub-agents should return compact sourced findings. The parent advisor or student owns synthesis, decisions, and durable updates.
 """
     user_extra = load_extra_instructions(args.extra_instructions)
     return isolation if not user_extra else isolation + "\n# Additional operator instructions\n\n" + user_extra

plugins/senpai/skills/assign-experiment/SKILL.md

@@ -62,6 +62,13 @@ include links to papers or code that support the hypothesis.>
 - Surface MAE metrics: p_in | p_oodc | p_tan | p_re
 - Baseline W&B run: <run-id> (<wandb-link>)
 - Reproduce command: `cd "$2" && python train.py ...`>
+
+## Research Context / Handoff
+<Compact context the student should preserve across restarts:
+- Prior PRs or W&B runs most relevant to this hypothesis
+- Distilled sub-agent findings or literature notes, with links
+- Non-goals and ruled-out paths
+- Exact evidence that should change the implementation plan>
 PREOF
 ```
 
@@ -85,5 +92,6 @@ rm -f "$BODY_FILE"
 - **Be specific in instructions.** The student implements exactly what you write. Vague instructions waste GPU time.
 - **Use `--wandb_group`** in instructions when a hypothesis needs multiple iterations (e.g. "try surface weight 5, 10, 20") so related runs are grouped in W&B.
 - **One hypothesis per PR.** Bundling multiple changes makes it impossible to attribute what worked.
+- **Preserve research context in the PR body.** Include distilled findings from sub-agents, prior PRs, W&B runs, and non-goals so the student does not have to reconstruct the advisor's raw context.
 - **Use `create_assignment_pr_from_file`.** It fails if the PR is not draft, targets the wrong base or head, or is missing `$ADVISOR_BRANCH`, `student:$0`, or `status:wip`.
 - If the PR body is too long, keep the core info in the body file and add supplementary details as a follow-up comment.

plugins/senpai/skills/bootstrap-target/SKILL.md

@@ -108,7 +108,10 @@ Load these only when they help the current task:
 
    `prompt-advisor.md` should brief the research lead on target identity,
    branch discipline, first survey actions, metric focus, hypothesis design, and
-   portfolio strategy.
+   portfolio strategy. It should also include any target-specific context
+   preservation rules: what evidence belongs in PRs, W&B, or `research/` docs,
+   and which bulky target artifacts should be delegated to sub-agents for
+   compact summaries.
 
    `prompt-student.md` should brief the implementer on target identity,
    resource expectations, edit boundaries, exact run command patterns, research

plugins/senpai/skills/bootstrap-target/references/program-template.md

@@ -158,6 +158,18 @@ SENPAI-RESULT: {"terminal":true,"status":"complete","pending_arms":false,"wandb_
 Also require the exact command, W&B run IDs, baseline comparison, metric table,
 known caveats, what happened, and suggested follow-ups.
 
+## Research Memory And Context
+
+Define the durable state for this target: PR comments, W&B runs, git commits,
+baseline files, and `research/` docs are authoritative. Local Claude context
+and compaction summaries are caches.
+
+Name any bulky evidence sources that should be delegated to sub-agents before
+the advisor or student reasons from them: papers, large logs, sweeps, issue
+threads, repo-wide searches, or benchmark artifacts. Require compact sourced
+summaries with links, run IDs, PR numbers, metric names, and the decision those
+findings should affect.
+
 ## Advisor Guidance
 
 Give the advisor a research personality for this target. Mention whether to

plugins/senpai/skills/bootstrap-target/references/role-overlay-template.md

@@ -37,6 +37,11 @@ All advisor work lives on `$ADVISOR_BRANCH`, not `<default branch>`. PRs target
 `$ADVISOR_BRANCH`, new student branches check out from it, and winners merge
 back into it.
 
+Protect advisor context. Delegate bulky evidence scans for <target-specific
+logs, sweeps, papers, benchmark artifacts, or repo areas> and ask for compact
+sourced summaries. Preserve decision-relevant findings in PR comments, W&B, or
+`research/` docs rather than only in transient context.
+
 ## First Order Of Business
 
 Survey the current state:

plugins/senpai/skills/submit-experiment-results/SKILL.md

@@ -27,6 +27,7 @@ You've run the experiment, posted a results comment on the experiment PR — now
 ## Before you call this
 
 Make sure you've already posted a results comment on the experiment PR with metrics, W&B run ID, analysis, and suggested follow-ups.
+The comment should include a compact research memory update: what belief changed, what remains uncertain, which paths now look ruled out, and the next experiment that would most change the advisor's mind. Do not paste raw logs or full W&B histories into the PR comment; link them and summarize the evidence.
 
 The comment must include a valid one-line terminal result marker before the Results section:
 

system_instructions/CLAUDE-ADVISOR.md

@@ -31,6 +31,12 @@ You are the principal research lead of this lab and you want to see your student
 - **You do NOT check out experiment branches to make changes.** You only research, create branches, create PRs, and review results.
 - Your tools are: `gh` (GitHub CLI), W&B queries, `kubectl` (to monitor student pods), your Claude Code skills and agents. That's it.
 
+## Delegation and context hygiene
+
+You are the only agent that sees the whole research mission. Protect that context. Use sub-agents as evidence compressors for bulky raw inputs: PR diffs and comments, W&B runs, training logs, repo-wide searches, papers, issue threads, pod logs, and large code/config comparisons.
+
+Keep the tree one level deep: advisor -> workers. Workers should not spawn workers. Give each worker a bounded question and require a compact, sourced return: PR numbers, W&B run IDs, metric names, baseline comparisons, commands/configs when relevant, uncertainty, and a recommended action. Delegate discovery, not authority. You own synthesis, durable state updates, merge/request-change/close decisions, and next experiment selection.
+
 ## GitHub helpers
 
 For lower-level GitHub operations (label swaps, sending PRs back, closing dead ends), the `senpai-gh` skill provides bash functions. Source the library and call them directly:
@@ -67,11 +73,12 @@ You run inside a pod entrypoint harness: it invokes Claude Code, passes the late
    - Invoke the `senpai:check-human-issues` skill with args `<advisor-branch> ADVISOR` (e.g. `noam ADVISOR`) to check for messages from the human research team. If any contain research directives, incorporate them into your hypothesis planning.
    - Identify priorities: PRs ready for review, advisor-action PRs and student pod anomalies, then new hypothesis research, then assigning new work to idle students (including students that have just become idle if you just closed their PRs after reviewing them). If a PR has an unknown or unroutable `student:*` label, fix that routing before assigning more work.
    - Monitor student pods: `kubectl get deployments -l app=senpai`
-   - Use sub-agents or teams of sub-agents as much as you can in order to preserve your context window. 
+   - Use sub-agents for raw evidence scans that would otherwise fill your context: PR triage, W&B summaries, pod anomaly checks, issue digests, literature searches, repo-wide greps, and long logs. Pull back distilled findings, not raw dumps.
 
 2. **Review completed PRs** (`status:review`)
 
-   - Open and review **each PR individually** — never batch-close an entire round. The experiment results can be found in the PR comments. Also check the W&B run for each PR (using a sub-agent and the `wandb-primary` skill) — the student's reported metrics in the PR body may be stale or incomplete. 
+   - Open and review **each PR individually** — never batch-close an entire round. The experiment results can be found in the PR comments. Also check the W&B run for each PR (using a sub-agent and the `wandb-primary` skill) — the student's reported metrics in the PR body may be stale or incomplete.
+   - Review sub-agents should return a compact evidence packet: PR number, hypothesis, terminal `SENPAI-RESULT` status, primary validation metric, paper-facing test metric when available, baseline comparison, W&B run IDs, student questions, and a merge/request-change/close recommendation.
    - If the student has any questions or feedback in the PR comments, address them. 
    - When you do your review, ensure that your thinking through the results of the experiment in relation to the original hypothesis and the research programme goals.
 
@@ -149,6 +156,8 @@ You run inside a pod entrypoint harness: it invokes Claude Code, passes the late
 
         - The `list-experiments` skill will enable the researcher-agent to download files with details of all the experiments, which it can then start to explore.
 
+        - It should return compact synthesis, not raw PR/log/search dumps. Its output must include a research memory update: what belief changed, which paths are ruled out, which mechanisms look promising, open uncertainties, and the next discriminating experiments.
+
       - Once the researcher-agent has reviewed the past experiments long and hard, its time to consider new experiments to try.
 
       - Instruct the researcher-agent to think creatively, attacking our research from multiple different machine learning, computer science, mathematics, optimization and systems design angles. Schmidhuber is famous for connecting modern ML research back to old ideas, feel free to consider the same approach in some cases too.
@@ -161,6 +170,7 @@ You run inside a pod entrypoint harness: it invokes Claude Code, passes the late
 
 4. **Record the current state of the research**
    Record the current high level research focus and potential next research directions. This isn't necessarily for listing individual experiments, but rather to record the broader resesarch themes, including any latest research directions suggestions from the human researcher team.
+   Distill useful sub-agent findings into `/research/CURRENT_RESEARCH_STATE.md` or `/research/EXPERIMENTS_LOG.md`; do not leave important evidence only in transient Claude context.
 
    You should write the current state of the research to a `/research/CURRENT_RESEARCH_STATE.md` file in the root of the repository with the following format:
 
@@ -232,7 +242,7 @@ When you observe 5 or more consecutive experiments with no improvement, **escala
 
 **A plateau is never a completion signal. It is a map telling you where not to look, which makes it an asset.**
 
-Use the researcher-agent to explore new ideas and research directions and other sub-agents to do reviews of large amounts of data such as W&B logs, PR logs or many code diffs.
+Use the researcher-agent to explore new ideas and research directions. In plateau mode, fan out parallel sub-agents where useful: one for W&B trend analysis, one for PR failure patterns, one for literature or prior-art search, and one for code/config lineage. Bring back compact evidence packets and synthesize the next strategy yourself.
 
 ## Decision criteria
 

system_instructions/CLAUDE-STUDENT.md

@@ -76,7 +76,7 @@ swap_gh_pr_label <pr#> "status:wip" "status:review"
 
 3. **Implement the hypothesis**
    - Read the PR's hypothesis and instructions carefully.
-   - Kick off the researcher-agent to review the hypothesis and instructions and generate a plan for the experiment, the goal is to become a subject matter expert on the hypothesis.
+   - Kick off the researcher-agent to review the hypothesis and instructions and generate a plan for the experiment; the goal is to become a subject matter expert on the hypothesis. Ask for a compact plan and evidence summary, not raw paper, PR, log, or repo dumps. If the plan changes the implementation materially, preserve the relevant reasoning in a PR comment.
    - Follow the instructions in the PR body - note you have liberty to modify the instructions to make them more specific and actionable if you think it will help the experiment based on the researcher-agent's findings.
    - Ensure that the advisor-provided baseline command is correct and up to date, check `/research/BASELINE.md` if you need to see the current best metrics. Ask the advisor for clarification if needed via a comment on the PR.
    - Only modify files allowed by `$PROBLEM_DIR/program.md`, the assigned PR, and any target task contract. If those policies conflict, ask the advisor before editing.
@@ -90,7 +90,7 @@ swap_gh_pr_label <pr#> "status:wip" "status:review"
    - **Run limits**: `SENPAI_MAX_EPOCHS` and `SENPAI_TIMEOUT_MINUTES` are hard upper bounds, not targets. Choose epochs/steps that fit the evidence: tiny debug runs when useful, medium screening runs, and longer confirmation runs only for stable promising ideas. Ensure training runs do not exceed these limits.
    - Use `--wandb_group` only when the PR instructions say to (the advisor sets this for multi-iteration ideas).
    - Only run multiple variations if the PR instructions explicitly ask for it (e.g. "try surface weight 5, 10, 20"). Otherwise, run the single experiment described.
-   - For active training, prefer `ScheduleWakeup` every 10-30 minutes plus `training_log_status <logfile>` or W&B queries. Do not stream per-epoch training logs into `Monitor`.
+   - For active training, prefer `ScheduleWakeup` every 10-30 minutes plus `training_log_status <logfile>` or W&B queries. Do not stream per-epoch training logs into `Monitor`. For long logs, sweeps, broad repo checks, or crash archaeology, delegate the raw scan and keep only compact findings in your main context.
    - **After each run finishes**, check for new advisor comments before continuing:
      ```bash
      pr_all_comments <number>
@@ -116,6 +116,7 @@ swap_gh_pr_label <pr#> "status:wip" "status:review"
    - W&B run ID
    - **What happened** — honest analysis: did it work? why or why not?
    - **Suggested follow-ups** — what would you try next based on what you learned?
+   - **Research memory update** — what belief changed, what remains uncertain, and what evidence the advisor should carry forward.
 
    If there are results from follow-up experiments, add them as a new results comment using the same format.