docs(design): forward-looking improvement proposals#57
Open
fazpu wants to merge 8 commits into
Open
Conversation
Companion to success-semantics-and-evaluation.md. Where that doc records decisions already made and not to be reverted, this one collects the forward-looking changes we are considering, curated from the July 2026 review under design/analysis/ and re-prioritized. Framing decision that drives priority: we intend to drive a large, multi-phase target project with the planner/dispatcher double loop from the very beginning (not after a single-loop pilot), which moves the parent/child machinery from "harden later" to "harden first". Priorities: - P0 (double-loop foundations): durable session-stack/active-child recovery (the untested crash gap), human-in-the-loop pause state, per-child budgets, and making the PM template runnable from a clean init. - P1 (legibility/safety): events.jsonl + cost ledger, a deterministic backstop UNDER the judge for high-stakes targets (without reverting the eval decision), and fixing the stale Agent Skill. - P2 (hardening/DX): model profiles + trio version pins, the _advance() refactor folded into the state-machine work, richer failure taxonomy, and operator UX (doctor/validate/session-aware status+stop). - Explicitly deferred: parallel loopy workers, web dashboard, breadth-first child sessions. All items are Proposed, not Accepted. No code changes. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PN8aFwwxA8FzMy9LgpbQFt
…n-gate The goal is full autonomy; human involvement is a last resort, not a step. The earlier P0.2 (a first-class, resumable paused/waiting_for_human gate with gate_request.json and resume-after-human) is rejected as contrary to that goal and redundant: the escape hatch already exists end to end — control.json stop_reason "unresolvable_error" is modeled (models.py), handled (coordinator_app _apply_session_control / _apply_stop_precedence), and already instructed by the stock planner prompt as the terminal-blocker path. P0.2 now only proposes optional prompt-level polish (make unresolvable_error a genuine last resort; keep the give-up report legible). Fixed the two spots that leaned on the old "human-gated" framing (sequencing + closing). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PN8aFwwxA8FzMy9LgpbQFt
…add P2.5 - P0.3 (per-child budgets): withdrawn. Not important enough to justify the trouble — it expands the child-request schema and config-resolution surface and adds ways for a misconfigured child to surprise; inheriting root config bounded by root max_turns is an adequate default. Kept as a withdrawn entry (house style) with the rationale for any future re-proposer. - P0.1: added a scope note making explicit that it recovers session/child STATE from files, not running processes. Coordinator crash has no orphan problem (agents are the worker's children); worker crash mid-run is a separate process-cleanup problem, not folded into P0.1. - P2.5 (new): orphan agent-process cleanup on restart. Neither loopy-loop nor team-harness persists agent PIDs (team-harness holds the handle in memory only, spawns with no process group); a hard worker crash can orphan agent CLIs that keep spending money. Re-adopting a running orphan is not portably possible, so the fix is prevent + clean up (start_new_session + persist PGID + reap on startup), mostly at the team-harness level. Fixed the two stale P0.3 references (deferred section, sequencing). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PN8aFwwxA8FzMy9LgpbQFt
Now that we own team-harness, reframe P2.5 as a designed team-harness feature (TH-D5, its process-lifecycle-and-reaping design) rather than a /proc-scraping hack, and record the ownership split (D7): team-harness owns agent-process identity + reap; loopy-loop calls reap on recovery and surfaces it. Add a P0.1 worker-liveness bullet: the loopy worker records pid + heartbeat so a second /register can verify the worker is dead before reclaiming (closing the duplicate-work window) and trigger reap for the interrupted run — making state recovery safe rather than optimistic. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PN8aFwwxA8FzMy9LgpbQFt
Reflect the reap/drain/ignore policy menu the team-harness liveness tracking enables: on recovery loopy picks a policy per orphan (reap by default, or drain to let expensive/nearly-done work finish and harvest it, pausing fresh work). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PN8aFwwxA8FzMy9LgpbQFt
…h TH-D5) Flip loopy's recovery default from reap to bounded drain: for a cost-conscious, git-is-truth consumer, letting a near-complete agent finish and harvesting it beats killing it (no wasted spend, no half-applied edits), and draining during recovery has no concurrent-writer problem. Reap stays the escape for force-stop / hung-past-timeout / unsafe-to-finish. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PN8aFwwxA8FzMy9LgpbQFt
Two stale reap-only references left over from before the drain-default flip: - P0.1 worker-liveness bullet now applies the recovery policy (default bounded drain, reap as escape) instead of "trigger reap". - P2.5 team-harness-side summary now lists liveness + drain/reap/ignore ops instead of a reap-only surface. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PN8aFwwxA8FzMy9LgpbQFt
…ed_after_drain Pin down the fuzziest part of the drain design at the loopy layer. A drained iteration is still re-run: its result.json never existed, and we deliberately do NOT synthesize one from drained agent outputs — that would fabricate a result the coordinator never produced (the false-closure trap D3 prevents). Instead the salvage is made explicit and auditable: - write salvage.json into the interrupted iteration dir (drained agent ids, exit codes, harness output pointers, diffstat of working-tree changes); - record the iteration as abandoned_after_drain (distinct from abandoned), giving provenance for the surviving repo edits and a hook for the failure taxonomy (P2.3) to distinguish "crashed but salvaged" from "crashed, lost". P2.5 loopy-side bullet aligned (drain = finalized worker record + preserved repo edits, never a synthesized result). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PN8aFwwxA8FzMy9LgpbQFt
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds
design/designs/improvement-proposals.md— the forward-looking companion to the success-semantics design doc (#53). Where #53 records decisions already made (not to be reverted), this collects the changes we're considering, curated from the July 2026 review underdesign/analysis/and re-prioritized. Every item is marked Proposed, not Accepted. No code changes.Replaces the earlier #54 (which was stacked on the pre-merge #53 branch and referenced a specific downstream project by name); this version is based on
mainand kept generic.Framing decision that drives priority
We intend to drive a large, multi-phase target project with the planner/dispatcher double loop from the very beginning — not after a single-loop pilot. That moves the parent/child machinery from "harden later" to harden first.
Priorities
P0 — double-loop foundations: durable session-stack/active-child recovery (the untested crash gap where a restart reopens the parent and orphans a running child);
paused/waiting_for_humanstate + typed gate/external-action requests; per-child budgets (a child currently inheritsmax_turns: 120); make the PM template runnable from a clean init (it doesn't bundle itsinner_outer_evalchild set today).P1 — legibility & safety:
events.jsonl+ usage/cost ledger, thenloopy status --watch; a deterministic backstop under the judge for high-stakes targets (shells out to the repo's own contract tests — explicitly does not revert the eval decision in #53); fix the stale Agent Skill / "multi-worker" claims.P2 — hardening & DX: named model profiles + pin the trio;
_advance()refactor folded into the P0.1 state-machine work; richer failure taxonomy + per-workflow failure cap;doctor/validate/session-awarestatus+stop.Explicitly deferred: parallel loopy workers, web dashboard, breadth-first child sessions.
🤖 Generated with Claude Code
https://claude.ai/code/session_01PN8aFwwxA8FzMy9LgpbQFt