loopy-loop 0.3.0__tar.gz → 0.5.0__tar.gz

loopy_loop-0.5.0/CHANGELOG.md

@@ -0,0 +1,206 @@
+# Changelog
+
+## 0.5.0
+
+- **events.jsonl is now written (P1.1).** The coordinator appends one
+  versioned JSON event per significant transition — `session_started`,
+  `task_dispatched`, `task_finished` (with tokens/duration/failure_kind),
+  `iteration_abandoned`, `goal_check`, `child_started`, `child_finished`,
+  `session_stopped` — to each session's `events.jsonl` after the producing
+  state mutation commits. Delivery is best-effort by design: a crash in the
+  commit-to-append window drops the event while the durable truth
+  (`state.json` history/ledger) survives; readers key on `event_id` and
+  tolerate gaps and a torn final line. New `loopy events [--follow]
+  [--json]` tails the deepest active session's stream and follows the
+  active session as it changes.
+- **Usage/cost ledger + `max_cost_usd` (P1.1).** The worker reads
+  coordinator-model token usage from team-harness's `run.json` and reports
+  it (plus wall-clock duration) on `/finished`; the coordinator keeps a
+  durable per-session ledger in `state.json` and records a finalized
+  child's totals on its `children.json` record. With the new optional
+  `model_prices` (USD per 1M tokens, coordinator-side), `loopy status`
+  shows estimated cost and the new optional `max_cost_usd` budget stops
+  the loop with `stop_reason="max_cost_usd"`. Cost explicitly covers the
+  harness coordinator model only — agent-CLI subprocess spend is not
+  measurable and is never pretended into the number.
+- **`loopy status` shows the session stack and `--watch`.** While a child
+  session runs, `status` now walks the durable parent→child pointers and
+  shows the live child (previously it showed only the suspended parent);
+  `--watch` re-renders every 2 seconds.
+
+- **Failure taxonomy + per-workflow failure cap (P2.3).** Failed iterations
+  now record a `failure_kind` — `transient` (provider said retry;
+  team-harness's own retries were exhausted), `deterministic` (auth/config
+  errors retries cannot fix), `crash` (worker died mid-iteration), or
+  `unknown` — on `result.json`, `/finished`, and session history. A new
+  coordinator-side `workflow_consecutive_failures_cap` (default 5) stops the
+  loop with `stop_reason="workflow_failure_cap"` when the same workflow fails
+  that many iterations in a row (crash-abandoned iterations included; any
+  success resets the workflow's counter) instead of burning the remaining
+  `max_turns` on a wedged workflow. The cap is not part of the wire config
+  snapshot, so released workers are unaffected.
+- **Agent Skill rewritten for the current API (P1.3).** `skills/loopy-loop/SKILL.md`
+  still described the removed pre-0.2.0 surface (top-level `.loopy_loop/state.json`,
+  polling multi-worker model, inline `goal`, `.loopy_loop/workflows/<id>/` layout) and
+  would have taught agents to generate broken setups. It now documents the 0.4.0
+  reality: `goal_file`, workflow sets, all three templates, the single
+  identity-verified worker, child sessions, crash recovery, and resume semantics —
+  validated against clean `loopy init` runs of every template. Remaining plural
+  "workers" wording in the README corrected to the single-worker model.
+- **eval-banana is now a hard dependency.** The recommended
+  `inner_outer_eval` template (and the PM template's child sessions) shell
+  out to the `eval-banana` CLI; previously it had to be installed
+  separately, so a fresh install could dispatch eval workflows against a
+  missing tool. It now installs with loopy-loop — no extra, no preflight.
+- **Worker appends its bundled-CLI scripts directory to `PATH`.** Harness
+  agents inherit the worker's environment, but under `uv tool install` /
+  `pipx` only loopy-loop's own entry points are exposed on `PATH`, so
+  dependency CLIs such as `eval-banana` were invisible to agents. The
+  directory is derived from where eval-banana's script was actually
+  installed (its package record; `sysconfig` only as fallback — the default
+  scheme is wrong for e.g. `pip install --user` under a system
+  interpreter). It is appended, never prepended, and existing `PATH`
+  entries are preserved verbatim: the target repo's own `python`/tooling
+  and any eval-banana already on `PATH` keep winning.
+
+## 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.3.0 → loopy_loop-0.5.0}/Makefile

@@ -17,7 +17,7 @@ claudecontinue:
 ## Codex
 codex:
 	# do /fast
-	codex --yolo --model gpt-5.5
+	codex --yolo --model gpt-5.6-sol
 
 install_globally:
 	uv tool install --editable "$(CURDIR)"

{loopy_loop-0.3.0 → loopy_loop-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: loopy-loop
-Version: 0.3.0
+Version: 0.5.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
@@ -23,6 +23,7 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
 Requires-Python: >=3.12
 Requires-Dist: click>=8.1
+Requires-Dist: eval-banana>=0.3.1
 Requires-Dist: fastapi>=0.115.0
 Requires-Dist: filelock>=3.16
 Requires-Dist: httpx>=0.28
@@ -58,12 +59,13 @@ and PRs.
 
 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
+worker runs 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
 `inner_outer_eval` template also uses
 [`eval-banana`](https://github.com/writeitai/eval-banana) conventions for
-session-scoped evaluation checks.
+session-scoped evaluation checks; eval-banana installs automatically as a
+loopy-loop dependency.
 
 ## Install
 
@@ -118,7 +120,8 @@ This is the recommended starting template. It creates:
 - a `.gitignore` entry for `.loopy_loop/sessions/`
 
 `loopy init` is idempotent. It creates missing files and leaves existing files
-alone.
+alone — except `.gitignore`, which is updated in place to ensure the sessions
+ignore rule.
 
 ## Write the Goal
 
@@ -244,6 +247,7 @@ goal_file: loopy_loop_goal.txt
 workflow_set: inner_outer_eval
 max_turns: 160
 goal_check_consecutive_failures_cap: 3
+# workflow_consecutive_failures_cap: 5
 team_harness_provider: "codex"
 team_harness_model: "gpt-5.5"
 team_harness_agents:
@@ -278,7 +282,21 @@ Important rules:
   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.
+  config snapshot sent to the worker.
+- `workflow_consecutive_failures_cap` (default 5) is a per-workflow circuit
+  breaker: that many consecutive failed iterations of the same workflow stop
+  the loop with `stop_reason="workflow_failure_cap"` instead of retrying a
+  wedged workflow until `max_turns`. Any success of the workflow resets its
+  counter. Coordinator-side only; not part of the config snapshot sent to
+  the worker.
+- `model_prices` (optional, coordinator-side only) sets USD prices per 1M
+  tokens for the harness coordinator model (`prompt_usd_per_1m`,
+  `completion_usd_per_1m`); with prices set, `loopy status` derives an
+  estimated cost from the token ledger. `max_cost_usd` (optional, requires
+  `model_prices`) stops the loop with `stop_reason="max_cost_usd"` once the
+  session tree's estimated cost reaches the budget. Cost covers the harness
+  COORDINATOR model only — agent-CLI subprocesses (codex, claude, gemini)
+  bill through their own accounts and are not measurable here.
 
 Workflow config lives beside each workflow prompt:
 
@@ -332,8 +350,12 @@ Important session files:
 
 - `goal.md`: the exact goal text copied into the session.
 - `session.json`: session metadata.
-- `state.json`: coordinator-owned dispatch state.
-- `events.jsonl`: reserved append-only diagnostics log.
+- `state.json`: coordinator-owned dispatch state, including the session's
+  token/duration usage ledger.
+- `events.jsonl`: append-only event stream — one versioned JSON line per
+  significant transition (`session_started`, `task_dispatched`,
+  `task_finished`, `iteration_abandoned`, `goal_check`, `child_started`,
+  `child_finished`, `session_stopped`). Tail it with `loopy events --follow`.
 - `control.json`: workflow-owned stop switch.
 - `updates_from_user.md`: human-writable inbox for changes after the session
   starts.
@@ -419,7 +441,13 @@ To stop because the loop cannot continue:
 A valid `goal_check.json` does not stop the loop by itself. It is evidence.
 Stopping is controlled by session `control.json`. If goal-check output is
 missing or invalid repeatedly, the coordinator stops with
-`stop_reason="goal_check_broken"` after the configured failure cap.
+`stop_reason="goal_check_broken"` after the configured failure cap. Similarly,
+consecutive failed iterations of any single workflow stop the loop with
+`stop_reason="workflow_failure_cap"` after `workflow_consecutive_failures_cap`.
+Failed iterations record a `failure_kind` in history — `transient` (provider
+said retry; team-harness's own retries were exhausted), `deterministic`
+(auth/config errors retries cannot fix), `crash` (worker died mid-iteration),
+or `unknown` — so a stopped run is legible without reading harness logs.
 
 ## Workflow Sets and Child Sessions
 
@@ -431,8 +459,11 @@ Workflow sets are mandatory. Even a single-loop repo uses:
 
 The older `.loopy_loop/workflows/...` layout is not loaded.
 
-A workflow can request one sequential child session by writing a JSON file under
-the active session's `child_requests/` directory:
+A top-level session's workflow can request one sequential child session by
+writing a uniquely named `*.json` file under the active session's
+`child_requests/` directory (only `*.json` filenames are scanned; publish via
+a non-`.json` temp name plus rename — invalid requests are renamed to
+`*.json.rejected` and skipped):
 
 ```json
 {
@@ -484,7 +515,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]
@@ -500,16 +532,24 @@ loopy worker --coordinator http://127.0.0.1:8080
 Runs a blocking worker until the coordinator returns `action: "stop"`.
 
 ```bash
-loopy status
+loopy status           # session stack, usage totals, estimated cost
+loopy status --watch   # re-render every 2 seconds
+loopy events           # the active session's event stream
+loopy events --follow  # tail it live (--json for raw lines)
 loopy stop
 ```
 
-`status` prints the latest session state. `stop` sets `stop_requested=true` in
-the latest session-local state.
+`status` prints the latest session state — the whole session stack while a
+child runs (the live child is shown under its suspended parent), each
+session's subtree token usage, and (with `model_prices` configured) estimated
+cost. `stop` still flags the latest **top-level** session only: a running
+child does not see the flag, and the stop takes effect once the child reaches
+a terminal state and the parent resumes.
 
 ## Related Projects
 
 - [`team-harness`](https://github.com/writeitai/team-harness): the model and
-  agent-CLI orchestration layer used by loopy-loop workers.
+  agent-CLI orchestration layer used by the loopy-loop worker.
 - [`eval-banana`](https://github.com/writeitai/eval-banana): a lightweight YAML
-  evaluation framework used by the packaged eval workflows.
+  evaluation framework used by the packaged eval workflows. Installed
+  automatically as a loopy-loop dependency.

{loopy_loop-0.3.0 → loopy_loop-0.5.0}/README.md

@@ -18,12 +18,13 @@ and PRs.
 
 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
+worker runs 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
 `inner_outer_eval` template also uses
 [`eval-banana`](https://github.com/writeitai/eval-banana) conventions for
-session-scoped evaluation checks.
+session-scoped evaluation checks; eval-banana installs automatically as a
+loopy-loop dependency.
 
 ## Install
 
@@ -78,7 +79,8 @@ This is the recommended starting template. It creates:
 - a `.gitignore` entry for `.loopy_loop/sessions/`
 
 `loopy init` is idempotent. It creates missing files and leaves existing files
-alone.
+alone — except `.gitignore`, which is updated in place to ensure the sessions
+ignore rule.
 
 ## Write the Goal
 
@@ -204,6 +206,7 @@ goal_file: loopy_loop_goal.txt
 workflow_set: inner_outer_eval
 max_turns: 160
 goal_check_consecutive_failures_cap: 3
+# workflow_consecutive_failures_cap: 5
 team_harness_provider: "codex"
 team_harness_model: "gpt-5.5"
 team_harness_agents:
@@ -238,7 +241,21 @@ Important rules:
   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.
+  config snapshot sent to the worker.
+- `workflow_consecutive_failures_cap` (default 5) is a per-workflow circuit
+  breaker: that many consecutive failed iterations of the same workflow stop
+  the loop with `stop_reason="workflow_failure_cap"` instead of retrying a
+  wedged workflow until `max_turns`. Any success of the workflow resets its
+  counter. Coordinator-side only; not part of the config snapshot sent to
+  the worker.
+- `model_prices` (optional, coordinator-side only) sets USD prices per 1M
+  tokens for the harness coordinator model (`prompt_usd_per_1m`,
+  `completion_usd_per_1m`); with prices set, `loopy status` derives an
+  estimated cost from the token ledger. `max_cost_usd` (optional, requires
+  `model_prices`) stops the loop with `stop_reason="max_cost_usd"` once the
+  session tree's estimated cost reaches the budget. Cost covers the harness
+  COORDINATOR model only — agent-CLI subprocesses (codex, claude, gemini)
+  bill through their own accounts and are not measurable here.
 
 Workflow config lives beside each workflow prompt:
 
@@ -292,8 +309,12 @@ Important session files:
 
 - `goal.md`: the exact goal text copied into the session.
 - `session.json`: session metadata.
-- `state.json`: coordinator-owned dispatch state.
-- `events.jsonl`: reserved append-only diagnostics log.
+- `state.json`: coordinator-owned dispatch state, including the session's
+  token/duration usage ledger.
+- `events.jsonl`: append-only event stream — one versioned JSON line per
+  significant transition (`session_started`, `task_dispatched`,
+  `task_finished`, `iteration_abandoned`, `goal_check`, `child_started`,
+  `child_finished`, `session_stopped`). Tail it with `loopy events --follow`.
 - `control.json`: workflow-owned stop switch.
 - `updates_from_user.md`: human-writable inbox for changes after the session
   starts.
@@ -379,7 +400,13 @@ To stop because the loop cannot continue:
 A valid `goal_check.json` does not stop the loop by itself. It is evidence.
 Stopping is controlled by session `control.json`. If goal-check output is
 missing or invalid repeatedly, the coordinator stops with
-`stop_reason="goal_check_broken"` after the configured failure cap.
+`stop_reason="goal_check_broken"` after the configured failure cap. Similarly,
+consecutive failed iterations of any single workflow stop the loop with
+`stop_reason="workflow_failure_cap"` after `workflow_consecutive_failures_cap`.
+Failed iterations record a `failure_kind` in history — `transient` (provider
+said retry; team-harness's own retries were exhausted), `deterministic`
+(auth/config errors retries cannot fix), `crash` (worker died mid-iteration),
+or `unknown` — so a stopped run is legible without reading harness logs.
 
 ## Workflow Sets and Child Sessions
 
@@ -391,8 +418,11 @@ Workflow sets are mandatory. Even a single-loop repo uses:
 
 The older `.loopy_loop/workflows/...` layout is not loaded.
 
-A workflow can request one sequential child session by writing a JSON file under
-the active session's `child_requests/` directory:
+A top-level session's workflow can request one sequential child session by
+writing a uniquely named `*.json` file under the active session's
+`child_requests/` directory (only `*.json` filenames are scanned; publish via
+a non-`.json` temp name plus rename — invalid requests are renamed to
+`*.json.rejected` and skipped):
 
 ```json
 {
@@ -444,7 +474,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]
@@ -460,16 +491,24 @@ loopy worker --coordinator http://127.0.0.1:8080
 Runs a blocking worker until the coordinator returns `action: "stop"`.
 
 ```bash
-loopy status
+loopy status           # session stack, usage totals, estimated cost
+loopy status --watch   # re-render every 2 seconds
+loopy events           # the active session's event stream
+loopy events --follow  # tail it live (--json for raw lines)
 loopy stop
 ```
 
-`status` prints the latest session state. `stop` sets `stop_requested=true` in
-the latest session-local state.
+`status` prints the latest session state — the whole session stack while a
+child runs (the live child is shown under its suspended parent), each
+session's subtree token usage, and (with `model_prices` configured) estimated
+cost. `stop` still flags the latest **top-level** session only: a running
+child does not see the flag, and the stop takes effect once the child reaches
+a terminal state and the parent resumes.
 
 ## Related Projects
 
 - [`team-harness`](https://github.com/writeitai/team-harness): the model and
-  agent-CLI orchestration layer used by loopy-loop workers.
+  agent-CLI orchestration layer used by the loopy-loop worker.
 - [`eval-banana`](https://github.com/writeitai/eval-banana): a lightweight YAML
-  evaluation framework used by the packaged eval workflows.
+  evaluation framework used by the packaged eval workflows. Installed
+  automatically as a loopy-loop dependency.