Phase 2a part 1: depth primitives (dial, resume-entry, candidate sha)

[renmengye]

What

The primitives the cumulative-depth loop (Phase 2a, research-loop-buildout.md) needs — landed ahead of the live_climb surgery, all additive + no behavior change at today's defaults:

• Benchmark.depth_k dial (default 1 = today's single pass; bounded [1, 8]; per-benchmark, so "does depth pay here?" is answerable per benchmark). The declared knob — a contract can set it now; the depth loop that reads it lands in part 2.
• climb_once resume-entry: resume_session_id + improve_prompt resume the prior session with the improve prompt instead of a fresh brief — a depth pass builds on, and sees the measured result of, its own last pass (cumulative depth). The two are a coupled pair (both-or-neither, validated loudly); a resume also rejects the brief-only inputs it would silently drop (task_hypothesis/lessons/recent_reports/created/brief_baseline) and a no-resume backend. Default off → identical to today.
• ClimbResult.candidate_sha: the sealed (immutable) candidate commit an improved result was measured on — so the caller publishes that tree and a depth loop selects the best across passes by it. Set on both the in-job and wake improved returns.

Why split from the loop

Part 2 is the live_climb fixed-k depth loop that drives these and publishes the best gate+panel-clean candidate. It touches the live climb-publish path (today it commits the live workspace; best-of-k must publish the best sealed candidate_sha, as the wake path already does — climb.py:397), so it gets its own reviewed PR.

Part-2 constraints surfaced in review (captured, not part-1 bugs):

• The depth loop must retain the winning candidate's snapshot ref until publish (the inline caller's finally drops snapshot refs — cf. the park path's kept_ref). In part 1 nothing dereferences candidate_sha, so it's latent until part 2.
• When part 2 constructs improve_prompt from measured result text, it must data-fence it like the panel wake path (panel.py). In part 1 improve_prompt is a dormant caller-supplied param.
• The depth loop must thread one run_seed across passes for a fair best-of-k (the resume-entry draws a fresh seed per call today; a shared seed belongs where it's consumed, not as an unused part-1 param).

Test plan

• depth_k: default 1, accepts in-range, rejects out-of-range.
• candidate_sha on improved (in-job and wake path); resume-entry skips the brief and resumes with the improve prompt; the coupled-pair, no-resume-backend, and all five brief-only-input preconditions raise.
• Full suite green (703), no behavior change at the defaults. Gate (ruff + mypy) green.

No secrets / no large files

Confirmed.

[github-actions]

Round 1 — reviewed head 781e3d8a — reviewer hermes/gpt-5.6-terra.

second opinion — terra
Advisory findings from autoresearch — the code owner decides. Reply to disagree; the autoresearch:no-review label opts this PR out.

Verdict: no defects found.

No defects found in the diff.

[github-actions]

Round 1 — reviewed head 781e3d8a — reviewer claude/claude-opus-5.

Advisory findings from autoresearch — the code owner decides. Reply to disagree; the autoresearch:no-review label opts this PR out.

Verdict: nothing blocking — 4 advisory notes.

2 findings attached to the lines below.

Advisory (non-blocking):

• Wake path returns an improved result without candidate_sha (src/autoresearch/orchestrator.py:916; medium)
• Last assertion in the resume test can never fail (tests/test_orchestrator.py:145; medium)

depth_k is added to the Benchmark model but is not read anywhere in src/ yet and has no test; that is consistent with the stated "part 1 primitives only" scope. The improve_prompt is passed verbatim to the harness while panel wake text is data-fenced in panel.py; whether that matters depends on how part 2 builds the prompt, which is not in this diff.

[renmengye]

Round 1 addressed (90b83e0). Thanks both.

• candidate_sha on the wake path (medium) — fixed. The wake-path improved result now carries candidate_sha, matching the in-job path; both improved results now report the sealed tree they were measured on.
• Empty-prompt resume-entry (medium) — fixed with a loud precondition: resume_session_id now requires a non-empty improve_prompt.
• supports_resume on the resume-entry (low) — added a precondition rather than the silent fresh-brief fallback: a silent fallback would turn a depth pass into a fresh attempt behind the caller's back, which is the wrong semantics for cumulative depth. The depth loop (Phase 2b caller) stays the single owner of when to resume; this just validates that choice loudly. Uses the same getattr(harness, "supports_resume", True) idiom as the panel policy.
• Dead test assertion (medium) — removed; the exact-equality above it already pins the prompt. Added two tests for the new preconditions.

On the two scope notes: depth_k unread in src/ and the improve_prompt data-fencing question are both Phase 2b (the live_climb depth loop + prompt construction) — out of this primitives-only PR by design.

[github-actions]

Round 2 — reviewed head 90b83e0c — reviewer hermes/gpt-5.6-terra.

second opinion — terra
Advisory findings from autoresearch — the code owner decides. Reply to disagree; the autoresearch:no-review label opts this PR out.

Verdict: nothing blocking — 1 advisory note.

1 finding attached to the lines below.

[github-actions]

Round 2 — reviewed head 90b83e0c — reviewer claude/claude-opus-5.

Advisory findings from autoresearch — the code owner decides. Reply to disagree; the autoresearch:no-review label opts this PR out.

Verdict: nothing blocking — 4 advisory notes.

1 finding attached to the lines below.

Advisory (non-blocking):

• depth_k is accepted in contracts but nothing reads it (src/autoresearch/contract.py:101; high)
• New contract field has no CHANGELOG entry (CHANGELOG.md; medium)
• improve_prompt goes to the model unfenced and uncapped (src/autoresearch/orchestrator.py:1074; low)

I verified the diff against the checked-out files: candidate_sha is always assigned before the improved return in climb_once's loop and before the improved return in resume_climb; all ClimbResult constructions in src use keyword args, so inserting the new field is safe; FakeHarness has a supports_resume field and records (prompt, workspace, resume_id) tuples, so the new tests exercise real behavior. I could not run the test suite or the gate, so the "699 green / mypy clean" claim is unverified here.

[renmengye]

Round 2 addressed (e587c2a).

• depth_k unread (high) + no CHANGELOG (medium) — resolved by moving depth_k out of this PR into part 2, where the depth loop actually reads it. Landing an unread dial a PR early bought nothing and read as dead code every round. Part 1 is now purely the two exercised primitives (resume-entry, candidate_sha), both internal API → no CHANGELOG entry needed.
• improve_prompt discarded when session_id empty (medium) — good catch, fixed. The precondition is now symmetric (bool(resume_session_id) != bool(improve_prompt) → raise): a lone improve_prompt (e.g. a backend that returned no session id) no longer falls through to the fresh-brief branch and silently drops the prompt.
• candidate_sha can name a different tree (terra, high) — the sha is a sealed, immutable commit (snapshot_tree write-tree), not the mutable live tree; the wake path already branches exactly this sealed sha (climb.py:397, "never the live tree"). The "measured fresh — content not pinned by the sha" comment is the existing single-pass inline invariant (the contained eval doesn't mutate tracked files), which part 2's best-of-k inherits unchanged — the sealed sha faithfully names the agent's edits at snapshot time. No code change.
• improve_prompt unfenced/uncapped (low) — deferred to part 2, where the prompt is actually constructed (a fixed template, later agent-authored). Fencing belongs at construction — if part 2 folds measured result text into the prompt, it fences like the panel wake path does. In part 1 it's a dormant caller-supplied param.

[github-actions]

Round 3 — reviewed head e587c2a6 — reviewer hermes/gpt-5.6-terra.

second opinion — terra
Advisory findings from autoresearch — the code owner decides. Reply to disagree; the autoresearch:no-review label opts this PR out.

Verdict: 1 blocking, 0 advisory.

The depth_k benchmark setting is not implemented. Benchmark forbids extra fields and has no depth_k, so a contract that sets the promised per-benchmark dial fails to load and cannot configure depth. (src/autoresearch/contract.py:64; high confidence)

[github-actions]

Round 3 — reviewed head e587c2a6 — reviewer claude/claude-opus-5.

Advisory findings from autoresearch — the code owner decides. Reply to disagree; the autoresearch:no-review label opts this PR out.

Verdict: nothing blocking — 3 advisory notes.

1 finding attached to the lines below.

Advisory (non-blocking):

• The new candidate_sha points at a commit whose retaining ref the inline caller has already dropped (src/autoresearch/orchestrator.py:412; medium)
• Question: improve_prompt is sent to the author with no cap or data fence (src/autoresearch/orchestrator.py:1075; low)

The PR description advertises a Benchmark.depth_k dial, but no depth_k exists anywhere in the checked-out head (grep over src/tests/docs finds nothing); the head commit message says it was moved to part 2, so the description is stale relative to the code. Verified: ClimbResult is only ever built with keyword args and is not serialized by field order, so the inserted field breaks no caller; candidate_sha at the final return is always bound because the loop body runs before any break; FakeHarness already has a supports_resume field and a 3-tuple calls log, so the new tests exercise real behavior and would fail if the resume-entry or the field were removed.

[renmengye]

Round 3 addressed (2e69bbd). The two reviews split on depth_k — terra flags its absence as blocking, Opus 5 was fine with it gone — so as code owner I resolved the split by restoring the dial:

• depth_k restored — it aligns with the Mengye-approved Phase 2a design (research-loop-buildout.md), this repo's precedent of landing primitives before their consumer (the codex author backend), and terra's request. To address Opus 5's round-2 quality concerns it now ships with a contract test (default 1, accepts in-range, rejects 0/9) and a CHANGELOG entry. Benchmark is extra="forbid", so the dial has to exist for a contract to set it — which is exactly why it belongs here rather than after part 2.
• Stale PR description (Opus 5) — rewritten; the body now matches the code (depth_k present) and documents the two part-2 constraints below.
• candidate_sha's retaining ref is dropped by the inline caller (Opus 5, medium) — correct, and it's a part-2 constraint, not a part-1 bug: nothing dereferences candidate_sha in part 1 (only a test reads the string). Part 2's depth loop will retain the winning candidate's snapshot ref until publish, exactly like the park path's kept_ref. Captured in the PR body.
• improve_prompt uncapped/unfenced (Opus 5, low) — deferred to part 2, where the prompt is constructed; if it folds in measured result text it gets data-fenced like the panel wake path. Dormant caller-supplied param here. Captured in the PR body.

terra — the dial is now implemented; no contract fails to load (existing contracts omit it and default to 1).

[github-actions]

Round 4 — reviewed head 2e69bbdd — reviewer hermes/gpt-5.6-terra.

second opinion — terra
Advisory findings from autoresearch — the code owner decides. Reply to disagree; the autoresearch:no-review label opts this PR out.

Verdict: no defects found.

No defects found in the diff.

[github-actions]

Round 4 — reviewed head 2e69bbdd — reviewer claude/claude-opus-5.

Advisory findings from autoresearch — the code owner decides. Reply to disagree; the autoresearch:no-review label opts this PR out.

Verdict: nothing blocking — 4 advisory notes.

2 findings attached to the lines below.

Advisory (non-blocking):

• candidate_sha returned by the inline path names a commit whose ref is dropped (src/autoresearch/orchestrator.py:1259; medium)
• depth_k is accepted but never read (src/autoresearch/contract.py:101; medium)

I read contract.py, orchestrator.py (climb_once, resume_climb, _panel_revise_policy), role_runner.run_role, harness.FakeHarness and climb.py's inline/wake paths. The new params are keyword-only in effect and no caller constructs ClimbResult positionally, so inserting candidate_sha into the dataclass is safe. The coupling and no-resume-backend checks and the candidate_sha assignments match the described behavior. I cannot execute the suite, so the "702 green" claim is unverified from here.

[github-actions]

Round 5 — reviewed head c5641156 — reviewer hermes/gpt-5.6-terra.

second opinion — terra
Advisory findings from autoresearch — the code owner decides. Reply to disagree; the autoresearch:no-review label opts this PR out.

Verdict: nothing blocking — 1 advisory note.

Advisory (non-blocking):

• The candidate SHA test misses the wake path (tests/test_orchestrator.py:279; high)

[github-actions]

Round 5 — reviewed head c5641156 — reviewer claude/claude-opus-5.

Advisory findings from autoresearch — the code owner decides. Reply to disagree; the autoresearch:no-review label opts this PR out.

Verdict: nothing blocking — 2 advisory notes.

1 finding attached to the lines below.

Advisory (non-blocking):

• depth_k is accepted by the contract loader but no code reads it (src/autoresearch/contract.py:102; medium)

I read climb_once, resume_climb, run_role, FakeHarness, and climb.py's publish/wake paths. candidate_sha is not consumed anywhere yet (only the local variable in climb.py is used), so adding it to ClimbResult changes no behavior; all ClimbResult constructions use keyword args, so the new field's position is harmless. The new params are appended and all callers/tests use keywords. improve_prompt reaches the author session unfenced, but in this codebase fencing is done by the producer (panel.py builds wake_text), so a part-2 caller fencing it would match existing practice; I could not verify the part-2 caller since it is not in this diff. The new tests fail without the change (default candidate_sha is "", and the preconditions do not exist), so they are not vacuous.

[github-actions]

Round 6 — reviewed head f84d8aa9 — reviewer hermes/gpt-5.6-terra.

second opinion — terra
Advisory findings from autoresearch — the code owner decides. Reply to disagree; the autoresearch:no-review label opts this PR out.

Verdict: no defects found.

No defects found in the diff.

[github-actions]

Round 6 — reviewed head f84d8aa9 — reviewer claude/claude-opus-5.

Advisory findings from autoresearch — the code owner decides. Reply to disagree; the autoresearch:no-review label opts this PR out.

Verdict: nothing blocking — 2 advisory notes.

1 finding attached to the lines below.

Advisory (non-blocking):

• depth_k is accepted but nothing reads it (src/autoresearch/contract.py:102; high)

Verified against the checked-out files: run_role accepts resume_session_id, FakeHarness records (text, workspace, resume_id) and has a supports_resume field, resume_climb's improved return has candidate_sha in scope, and candidate_sha is always bound before the improved return in climb_once (assigned each loop pass before any break). The tests match the code paths they claim. The snapshot-ref lifetime problem (live_climb's finally drops every snapshot ref, so a returned candidate_sha would be unreferenced) is real in climb.py:1444-1450 but nothing consumes candidate_sha yet, and the PR description already records it as a part-2 constraint. I could not run tests or the gate.

[github-actions]

Round 7 — reviewed head d1b392dd — reviewer hermes/gpt-5.6-terra.

second opinion — terra
Advisory findings from autoresearch — the code owner decides. Reply to disagree; the autoresearch:no-review label opts this PR out.

Verdict: no defects found.

[github-actions]

Round 7 — reviewed head d1b392dd — reviewer claude/claude-opus-5.

Advisory findings from autoresearch — the code owner decides. Reply to disagree; the autoresearch:no-review label opts this PR out.

Verdict: nothing blocking — 1 advisory note.

1 finding attached to the lines below.

I checked the rest of the diff against the current sources. candidate_sha is assigned before every break in climb_once's loop, so the improved return is always populated, and the panel-revision path leaves it pointing at the last snapshot that was measured; resume_climb sets the same field for the wake path. All ClimbResult(...) constructions in src/ use keyword arguments, so inserting the new field is safe. depth_k is validated but nothing reads it yet, so a contract setting it above 1 gets no depth — the CHANGELOG says this explicitly, so I did not raise it. improve_prompt is passed to run_role unfenced, but that matches the existing split where the producer fences (panel.py _render_wake), and no caller in the repo constructs one yet.

[github-actions]

Round 8 — reviewed head 2a0e288a — reviewer hermes/gpt-5.6-terra.

second opinion — terra
Advisory findings from autoresearch — the code owner decides. Reply to disagree; the autoresearch:no-review label opts this PR out.

Verdict: no defects found.

No defects found in the provided diff.

[github-actions]

Round 8 — reviewed head 2a0e288a — reviewer claude/claude-opus-5.

Advisory findings from autoresearch — the code owner decides. Reply to disagree; the autoresearch:no-review label opts this PR out.

Verdict: nothing blocking — 3 advisory notes.

Advisory (non-blocking):

• candidate_sha comment says the caller publishes that tree, but the in-job caller does not (src/autoresearch/orchestrator.py:412; medium)
• the "exhaustive" brief-only guard misses config.budget (src/autoresearch/orchestrator.py:1054; low)
• no way to pin run_seed across depth passes (src/autoresearch/orchestrator.py:1069; low)

I verified the diff against the checked-out sources: FakeHarness has a supports_resume field and records (prompt, workspace, resume_id) tuples, so the resume test's assertions are real; ClimbResult is never built positionally or serialized field-by-field, so adding candidate_sha mid-dataclass is safe; load_contract lets pydantic ValidationError escape, so the depth_k range test is valid. depth_k is read nowhere yet, which the CHANGELOG and the field comment both state, so I did not raise it as a defect. improve_prompt is forwarded to the harness unfenced, but it is caller-supplied here and the repo fences at the construction site (panel.py:97-105), so that is a part-2 concern, not a defect in this diff. I could not run the test suite (no execute tool), so the "702 green" claim is unverified.

[renmengye]

Round 8 addressed (8c55503): the two comment-accuracy notes are fixed (candidate_sha 'caller publishes' → capability wording; the guard comment now explains ruler/config.budget are excluded as required-can't-omit, not missed). The third — no way to pin run_seed across depth passes — is a part-2 constraint (the depth loop threads one seed across passes for a fair best-of-k; adding it as an unused param here would just be dead code), captured in the PR-body constraints + noted for part 2.

[github-actions]

Round 9 — reviewed head 8c55503f — reviewer hermes/gpt-5.6-terra.

second opinion — terra
Advisory findings from autoresearch — the code owner decides. Reply to disagree; the autoresearch:no-review label opts this PR out.

Verdict: no defects found.

[github-actions]

Round 9 — reviewed head 8c55503f — reviewer claude/claude-opus-5.

Advisory findings from autoresearch — the code owner decides. Reply to disagree; the autoresearch:no-review label opts this PR out.

Verdict: nothing blocking — 3 advisory notes.

Advisory (non-blocking):

• candidate_sha comment overstates that a caller can publish that tree on the in-job path (src/autoresearch/orchestrator.py:409; medium)
• depth_k is validated but ignored, with no runtime signal (src/autoresearch/contract.py:102; medium)
• improve_prompt reaches the harness with no length cap and no data fence (src/autoresearch/orchestrator.py:1087; low)

I could not run the test suite (no execute tool), so the "703 green" claim is unverified; I checked the new tests by reading them and the helpers they use (FakeHarness records (text, workspace, resume_id) and has a supports_resume field, so the resume assertions are meaningful). The three preconditions in climb_once are consistent with today's optional brief-only params: BriefInputs has task/contract_text/ruler/lessons/recent_reports/budget and build_brief takes created, all covered by the guard or required. The new params are keyword-defaulted and the only production caller (climb.py:1387) passes neither, so behavior at defaults is unchanged.