loopy-loop 0.2.1__tar.gz → 0.4.0__tar.gz

loopy_loop-0.4.0/.github/workflows/docs-deploy.yml

@@ -0,0 +1,66 @@
+name: Docs Site
+
+on:
+  push:
+    branches: ["main"]
+    paths:
+      - "website/**"
+      - ".github/workflows/docs-deploy.yml"
+  pull_request:
+    branches: ["main"]
+    paths:
+      - "website/**"
+      - ".github/workflows/docs-deploy.yml"
+  workflow_dispatch:
+
+# Allow GITHUB_TOKEN to deploy to GitHub Pages.
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: website
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: npm
+          cache-dependency-path: website/package-lock.json
+
+      - name: Install dependencies
+        run: npm ci
+
+      # `next build` type-checks the project and generates .next/types, so a
+      # separate pre-build `tsc` step is intentionally omitted (it would run
+      # before those generated types exist).
+      - name: Build static site (Next.js export + Pagefind index)
+        run: npm run build
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: website/out
+
+  deploy:
+    # Only publish from main; PRs run the build job above as a check.
+    if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
+    needs: build
+    runs-on: ubuntu-latest
+    # Serialize production deployments only, so PR build-checks stay concurrent.
+    concurrency:
+      group: "pages-deploy"
+      cancel-in-progress: false
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

loopy_loop-0.4.0/AGENTS.md

@@ -0,0 +1,80 @@
+# AGENTS.md — working agreement for this repo
+
+`loopy-loop` runs long-running AI agent workflows inside a repository. A FastAPI
+**coordinator** owns durable loop state in files and picks the next workflow; a single
+**worker** runs each assignment through `team-harness`. Continuity lives in files and git,
+not in a chat transcript. Read `README.md` for the user-facing model, and
+`design/decisions.md` for *why the system is the way it is*.
+
+This file is the working agreement for any agent (or human) changing this repo. Three
+things are non-negotiable.
+
+## Rule 1 — Respect the deliberate decisions; don't "fix" them
+
+`design/decisions.md` is the canonical Architecture Decision Log (D1, D2, …). **Several
+decisions there look like defects if you only skim the code, and are recorded precisely so
+they don't get "fixed" by accident.** Before changing behavior in these areas, read the
+relevant decision (and its companion design doc):
+
+- **D3 — iteration success ≠ "work is good."** `IterationResult.success` means only that
+  the harness ran without erroring. Do not make it consult worker exit codes / infer
+  semantic success. The eval layer (`control.json` + `goal_check.json`) decides quality.
+- **D4 — evaluation is LLM-as-judge; agents don't author deterministic checks.** Do not
+  "add deterministic checks" to the stock `inner_outer_eval` eval workflows. (A target
+  repo that owns its own test suite is a different case — see D4.)
+- **D2 — single worker is deliberate.** Do not add parallel loopy workers as a scaling
+  feature.
+- **D5 — full autonomy with a last-resort escape hatch.** See Rule 2.
+
+If you believe a decision is genuinely wrong, propose amending `design/decisions.md`
+(state what changes and why) — do not silently contradict it in code.
+
+## Rule 2 — Autonomy is the goal; the human escape hatch is a LAST resort (D5)
+
+This system is meant to run **fully autonomously, with no human in the loop**. Human
+involvement is a last resort, never a normal step.
+
+- **The one sanctioned escape hatch already exists.** When a workflow hits a *genuinely
+  terminal* blocker — a decision only a human can make, a missing credential, a
+  billable/destructive action it isn't permitted to take — it writes the session
+  `control.json` with:
+  ```json
+  {"state": "stopped", "reason": "<specific terminal blocker>", "stop_reason": "unresolvable_error", "schema_version": 1}
+  ```
+  This stops the loop as terminal, with a recorded reason. That is the entire
+  human-in-the-loop mechanism, and it is enough.
+- **Exhaust autonomous options first.** Re-scope, retry with a better child goal, route
+  around the blocker. Reach for `unresolvable_error` only when a blocker is genuinely
+  unavoidable without a human. It should fire rarely.
+- **Make the give-up legible.** The recorded blocker is the only thing a human sees when a
+  run stops — state exactly what was missing and what was tried.
+- **Do NOT build or assume a preferred human gate.** No `paused` / `waiting_for_human`
+  state, no `gate_request.json`, no external-action approval flow. That was considered and
+  rejected (D5; `design/designs/improvement-proposals.md` P0.2). Do not pause a run to ask
+  a question when you could either solve it autonomously or stop cleanly with
+  `unresolvable_error`.
+
+## Rule 3 — Design and decision docs must be understandable cold, by future agents AND humans
+
+A design or decision doc is read by someone who was **not** in the conversation that
+produced it — a future agent with no memory of this session, or a human who is not a
+specialist. Write for them.
+
+- **Explain, don't just name.** Naming a mechanism ("the ping-pong protocol", "cadence
+  scheduling", "the double loop") is not explaining it. State, in plain language, *what it
+  is, what problem it solves, and why we chose it*, with a concrete example where it helps.
+- **The reasoning lives in the doc, not in your head.** Don't rely on a future reader
+  re-deriving the rationale. A decision-log entry may state the conclusion tersely; the
+  companion design section must be self-contained.
+- **Anchor claims in the code.** Reference the file/function (e.g. `coordinator_app.py`,
+  `harness_runner.py`) so a reader can verify — but lead with the plain-English meaning.
+- **Keep `design/` honest about status.** `design/designs/` is binding; `design/analysis/`
+  is working notes (may be superseded); `improvement-proposals.md` is *proposed, not
+  decided*. Don't cite a proposal as if it were a decision.
+
+When in doubt on any rule, favor the version a stranger could read cold and fully
+understand.
+
+---
+
+Note: `CLAUDE.md` points here. Keep this file as the single source; don't fork the two.

loopy_loop-0.4.0/CHANGELOG.md

@@ -0,0 +1,143 @@
+# Changelog
+
+## 0.4.0 (breaking)
+
+**Breaking API interaction — completions must echo the dispatched
+`attempt_id`.** Every dispatched task now carries an `attempt_id` that the
+worker must echo on `/finished`; a completion without the live task's attempt
+is treated as stale (this is what fences superseded work). A 0.3.0 worker
+therefore cannot complete tasks against a 0.4.0 coordinator — upgrade workers
+and coordinator together (they normally ship in the same install).
+
+- **Durable session-stack recovery (P0.1).** While a child session runs, the
+  parent's `state.json` records `active_child_session_id`; on `--resume` the
+  coordinator walks the pointer chain to the deepest live session instead of
+  silently reopening the parent and orphaning the running child. Terminal
+  children found at startup are finalized (children.json completed, pointer
+  cleared) and their parent resumed. Every interrupted-dispatch crash window
+  reconciles deterministically: dangling pointers are cleared, a fully
+  created child whose parent commit never landed is adopted, and leftover
+  request files never dispatch twice (children.json records the originating
+  `request_file`). Invalid child requests are terminally rejected
+  (`*.json.rejected`) instead of being re-read forever.
+- **Attempt ids.** Every dispatched task carries a unique `attempt_id`
+  (also on the wire in `TaskResponse`, echoed in `FinishedRequest`); a late
+  `/finished` from a superseded attempt of the same coordinates is treated as
+  stale rather than recorded as the current result.
+- Iteration artifacts (`result.json`, `result_text.txt`, `prompt.txt`,
+  `harness_run_id.txt`, `pending_finished_request.json`), `children.json`,
+  and `salvage.json` are all written atomically (unique temp + rename) — a
+  crash can never leave a truncated recovery artifact.
+- Internal: the three duplicated dispatch blocks in the coordinator collapsed
+  into one `_advance()` step (stop checks → child dispatch → next workflow →
+  stamped task), so they can no longer drift apart. `_advance()` also enforces
+  the suspended-parent invariant: a parent with a live child can never acquire
+  its own task (a duplicate `/finished` retry gets the child's live task
+  instead), and a coordinator-level transition lock serializes cross-store
+  handoffs.
+- Review hardening (adversarial Codex review of the above): request-file
+  tombstones apply only to RUNNING child records (a completed child's
+  filename is reusable for new work); the children.json record lands BEFORE
+  the child state so an interrupted dispatch is always discoverable
+  (`failed_dispatch` + exactly-once redispatch); startup reconciles every
+  running-projected record (terminal children finalize even without a
+  pointer); the first child task carries an attempt id; attempt checks are
+  strict whenever the live task has one (including `result.json` provenance —
+  a stale artifact can no longer complete a new attempt); semantically
+  unusable child requests (unknown workflow set, no eligible workflow) are
+  terminally rejected instead of wedging every completion; packaged prompts
+  instruct atomic control/goal_check publication; the crash model (process
+  crash, no fsync) is documented.
+- **The `pm_planner_dispatcher` template is executable from a clean init
+  (P0.4).** `loopy init --template pm_planner_dispatcher` now also ships the
+  `inner_outer_eval` child workflow set its dispatcher spawns — previously a
+  clean init could not execute a single child session. The child set is
+  sourced from the `inner_outer_eval` template itself, so the two copies can
+  never drift apart.
+
+## 0.3.0 (breaking)
+
+**Breaking API change — `/register` requires the worker's process identity.**
+A register without a `worker` object is rejected with HTTP 400. Pre-0.3
+workers cannot register against a 0.3 coordinator; upgrade workers and
+coordinator together (they normally ship in the same install).
+
+- **Worker liveness verification (D7).** The worker sends its process
+  identity (hostname + pid + a pid-reuse-proof start-time token) with
+  `/register` and `/finished`; the coordinator stamps it onto the dispatched
+  task. A `/register` while the recorded worker is *verifiably still alive*
+  returns HTTP 409 instead of abandoning live work — closing the
+  duplicate-work window. Unverifiable identities (remote hosts, or a
+  team-harness without process identity) keep the pre-existing
+  assume-abandoned recovery behavior. Because every dispatched task now has
+  a recorded owner, a stale `/finished` is replayed **only to that owner**
+  (anyone else gets HTTP 409) — a task persisted by a pre-identity version
+  keeps the legacy replay for that one resume.
+- **Orphaned-agent recovery (P2.5 / TH-D5 consumer side).** When a worker is
+  confirmed dead with nothing recoverable, the coordinator applies
+  `recovery_policy` (new coordinator-side config, NOT part of the wire
+  snapshot; default `drain`, one shared `recovery_drain_timeout_s` deadline,
+  default 600s) to agent processes the dead worker's harness run left behind,
+  via team-harness's process reaper: drained agents finish and their repo
+  edits survive; a `salvage.json` in the interrupted iteration directory
+  records what was handled; the history entry is `abandoned_after_<policy>`
+  when anything settled. Recovery runs OUTSIDE the state lock (`loopy
+  status`/`stop` stay usable while draining), validates that each discovered
+  run record actually belongs to the iteration, is same-host-only (a worker
+  identity from another hostname skips reaping), and refuses to dispatch
+  replacement work (HTTP 409) when any orphan may still be running or when
+  team-harness's parent-liveness guard reports the run's owner alive.
+  Requires team-harness with the process reaper (> 0.2.10); older versions
+  skip orphan recovery gracefully.
+- A stale `/finished` from a **different identified worker** now gets HTTP 409
+  instead of a second copy of the live task; unknown identities keep the
+  pre-existing stale-retry behavior. State-lock contention surfaces as a clean
+  HTTP 503 (and friendly CLI errors) instead of raw tracebacks.
+- The bundled worker uses an unbounded read timeout on `/register` only
+  (recovery can legitimately block registration up to the drain deadline),
+  keeps the bounded timeout on `/finished`, and exits with code 3 on a 409.
+
+## 0.2.1
+
+- Improve README onboarding, install, initialization, configuration, and logging docs.
+- Update package and skill descriptions to avoid unclear repository-scope jargon.
+
+## 0.2.0 (breaking)
+
+**Breaking API change — drop leases, polling, and worker identity.**
+
+The three-endpoint API (`POST /workers/register`, `POST /workers/{worker_id}/next`,
+`POST /workers/{worker_id}/finished`) is replaced by a two-endpoint ping-pong API:
+
+- `POST /register` — returns `TaskResponse` directly (`action: "run"` or `"stop"`).
+- `POST /finished` — returns `TaskResponse` for the next task or stop signal.
+
+The `"wait"` action is gone. The worker loop is now a simple `while task.action == "run"`
+loop with no polling.
+
+**Removed models and fields:**
+- `WorkerState`, `ActiveAssignment`, `RegisterWorkerResponse`, `NextActionResponse` removed.
+- `assignment_id` removed from `FinishedRequest` and `HistoryEntry`.
+- `worker_id` removed from `HistoryEntry`.
+- `workers` dict and `active_assignment` removed from `LoopState`.
+- Constants `DEFAULT_LEASE_SECONDS`, `DEFAULT_POLL_INTERVAL_SECONDS`,
+  `DEFAULT_FINISHED_RETRY_ATTEMPTS`, `DEFAULT_FINISHED_RETRY_BACKOFF_SECONDS`,
+  `WAIT_ACTION` removed.
+
+**Added:**
+- `CurrentTask` model replaces `ActiveAssignment` (no `worker_id`, no lease).
+- `TaskResponse` model returned by both `/register` and `/finished`.
+- `LoopState.current_task: CurrentTask | None` replaces `active_assignment`.
+
+**Crash recovery:** If a worker crashes mid-run, the next `/register` call detects the
+orphaned `current_task`, records it in history as `error="abandoned"`, and dispatches
+fresh work.
+
+**Migration note:** Existing `state.json` files containing `active_assignment` or `workers`
+fields will have those fields silently dropped on first read (Pydantic ignores unknown
+fields). Any in-flight run at upgrade time will lose its `active_assignment` record without
+a history entry. Drain all workers before deploying this version.
+
+## 0.1.0
+
+- Initial release.

loopy_loop-0.4.0/CLAUDE.md

@@ -0,0 +1,17 @@
+# CLAUDE.md
+
+The working agreement for this repo lives in **[`AGENTS.md`](./AGENTS.md)** — read it first.
+It is the single source; this file only points to it so the two never diverge.
+
+Quick orientation for what most often trips up a change here:
+
+- **`design/decisions.md`** is the canonical decision log. Several decisions look like
+  defects if you only skim the code and are recorded so they don't get "fixed" by accident
+  (notably **D3** iteration-success semantics and **D4** LLM-as-judge evaluation).
+- **Autonomy is the goal; the human escape hatch is a last resort (D5).** The system runs
+  unattended. When a workflow hits a genuinely terminal blocker it stops by writing
+  `control.json` with `stop_reason: "unresolvable_error"` and a specific recorded reason —
+  that is the entire human-in-the-loop mechanism. Do **not** build or assume a preferred
+  `paused` / `waiting_for_human` gate; exhaust autonomous options first, then stop cleanly.
+
+See `AGENTS.md` Rules 1–3 for the full agreement.

{loopy_loop-0.2.1 → loopy_loop-0.4.0}/Makefile

@@ -7,12 +7,12 @@
 ## Start Claude Code with MCP configuration
 claude:
 	@test -f .mcp.json || (echo "Error: .mcp.json not found. Please create it first." && exit 1)
-	PATH="$(HOME)/.bun/bin:$(PATH)" CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 TELEGRAM_STATE_DIR=$(PWD)/.claude/channels/telegram claude --dangerously-skip-permissions --mcp-config .mcp.json --remote-control
+	CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 CLAUDE_CODE_ENABLE_AUTO_MODE=1 claude --dangerously-skip-permissions --mcp-config .mcp.json --remote-control
 
 ## Continue previous Claude Code session
 claudecontinue:
 	@test -f .mcp.json || (echo "Error: .mcp.json not found. Please create it first." && exit 1)
-	PATH="$(HOME)/.bun/bin:$(PATH)" CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 TELEGRAM_STATE_DIR=$(PWD)/.claude/channels/telegram claude --dangerously-skip-permissions --mcp-config .mcp.json --continue --remote-control
+	CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 CLAUDE_CODE_ENABLE_AUTO_MODE=1 claude --dangerously-skip-permissions --mcp-config .mcp.json --continue --remote-control
 
 ## Codex
 codex:

{loopy_loop-0.2.1 → loopy_loop-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: loopy-loop
-Version: 0.2.1
+Version: 0.4.0
 Summary: Run long-running AI agent workflows inside your repository.
 Project-URL: Homepage, https://github.com/writeitai/loopy-loop
 Project-URL: Repository, https://github.com/writeitai/loopy-loop
@@ -29,7 +29,7 @@ Requires-Dist: httpx>=0.28
 Requires-Dist: pydantic>=2.11
 Requires-Dist: pyyaml>=6.0.2
 Requires-Dist: rich>=14.0
-Requires-Dist: team-harness>=0.2.10
+Requires-Dist: team-harness>=0.3.0
 Requires-Dist: uvicorn[standard]>=0.32.0
 Provides-Extra: dev
 Requires-Dist: pyright>=1.1; extra == 'dev'
@@ -40,6 +40,10 @@ Description-Content-Type: text/markdown
 
 # loopy-loop
 
+<p align="center">
+  <img src="docs/images/logo.png" alt="loopy-loop logo" width="400">
+</p>
+
 `loopy-loop` runs long-running AI agent workflows inside your repository.
 It turns a goal file in your repository into an inspectable sequence of agent
 iterations: plan, implement, evaluate, record evidence, and continue until the
@@ -52,8 +56,8 @@ logs. You can pause, resume, audit what happened, adjust the goal, inspect every
 prompt/result pair, and keep the actual project changes in normal git branches
 and PRs.
 
-Under the hood, loopy-loop runs a small FastAPI coordinator and one or more
-workers. The coordinator owns the loop state and chooses the next workflow. The
+Under the hood, loopy-loop runs a small FastAPI coordinator and a single
+worker. The coordinator owns the loop state and chooses the next workflow. The
 workers run assignments through
 [`team-harness`](https://github.com/writeitai/team-harness), which can delegate
 to agent CLIs such as Codex, Claude Code, and Gemini. The packaged
@@ -269,6 +273,12 @@ Important rules:
 - `team_harness_max_retries`, `team_harness_retry_base_delay_s`, and
   `team_harness_retry_max_delay_s` are optional retry controls for transient
   team-harness API/network errors.
+- `recovery_policy` (`drain` by default, or `reap`) and
+  `recovery_drain_timeout_s` control what crash recovery does with agent
+  processes a dead worker left running: drain lets them finish (one shared
+  bounded deadline) before the iteration is re-run; reap kills them
+  immediately. These are coordinator-side settings and are not part of the
+  config snapshot sent to workers.
 
 Workflow config lives beside each workflow prompt:
 
@@ -474,7 +484,8 @@ loopy init [--template default|inner_outer_eval|pm_planner_dispatcher]
 Scaffolds loopy-loop files. The default template creates only the reserved
 `goal_check` workflow. `inner_outer_eval` creates the recommended outer/inner/eval
 workflow set. `pm_planner_dispatcher` creates planner/dispatcher workflows for
-child-session orchestration.
+child-session orchestration — and also ships the `inner_outer_eval` child set
+its dispatcher spawns, so a clean init is executable end to end.
 
 ```bash
 loopy coordinator --host 0.0.0.0 --port 8080 [--resume] [--workflow-set NAME] [--goal-file PATH]

{loopy_loop-0.2.1 → loopy_loop-0.4.0}/README.md

@@ -1,5 +1,9 @@
 # loopy-loop
 
+<p align="center">
+  <img src="docs/images/logo.png" alt="loopy-loop logo" width="400">
+</p>
+
 `loopy-loop` runs long-running AI agent workflows inside your repository.
 It turns a goal file in your repository into an inspectable sequence of agent
 iterations: plan, implement, evaluate, record evidence, and continue until the
@@ -12,8 +16,8 @@ logs. You can pause, resume, audit what happened, adjust the goal, inspect every
 prompt/result pair, and keep the actual project changes in normal git branches
 and PRs.
 
-Under the hood, loopy-loop runs a small FastAPI coordinator and one or more
-workers. The coordinator owns the loop state and chooses the next workflow. The
+Under the hood, loopy-loop runs a small FastAPI coordinator and a single
+worker. The coordinator owns the loop state and chooses the next workflow. The
 workers run assignments through
 [`team-harness`](https://github.com/writeitai/team-harness), which can delegate
 to agent CLIs such as Codex, Claude Code, and Gemini. The packaged
@@ -229,6 +233,12 @@ Important rules:
 - `team_harness_max_retries`, `team_harness_retry_base_delay_s`, and
   `team_harness_retry_max_delay_s` are optional retry controls for transient
   team-harness API/network errors.
+- `recovery_policy` (`drain` by default, or `reap`) and
+  `recovery_drain_timeout_s` control what crash recovery does with agent
+  processes a dead worker left running: drain lets them finish (one shared
+  bounded deadline) before the iteration is re-run; reap kills them
+  immediately. These are coordinator-side settings and are not part of the
+  config snapshot sent to workers.
 
 Workflow config lives beside each workflow prompt:
 
@@ -434,7 +444,8 @@ loopy init [--template default|inner_outer_eval|pm_planner_dispatcher]
 Scaffolds loopy-loop files. The default template creates only the reserved
 `goal_check` workflow. `inner_outer_eval` creates the recommended outer/inner/eval
 workflow set. `pm_planner_dispatcher` creates planner/dispatcher workflows for
-child-session orchestration.
+child-session orchestration — and also ships the `inner_outer_eval` child set
+its dispatcher spawns, so a clean init is executable end to end.
 
 ```bash
 loopy coordinator --host 0.0.0.0 --port 8080 [--resume] [--workflow-set NAME] [--goal-file PATH]