Merge pull request #14 from luohaha/fix/suggestions-mailbox

fix(orchestrator): per-attempt human notes via suggestions/NNN.md, drop the byte cursor

Author: luohaha

README.md

@@ -165,9 +165,9 @@ the same session indefinitely.)
 
 You stay in control throughout: read what each attempt did via
 `/goal-run` or `goaloop status`; **edit `goal.md`** for a permanent
-change or **append to `suggestions.md`** for a transient per-attempt
-note — the next attempt picks it up. There's no live conversation into a
-running Runner.
+change or **drop a `suggestions/NNN.md`** note for a transient per-attempt
+nudge — the Runner of that attempt reads it. There's no live conversation into
+a running Runner.
 
 ### Configuration & modes
 
@@ -182,10 +182,12 @@ and waits for your approval before the next one; release it with
 `goaloop continue <name>`. (`pass`/`blocked`/`error` are terminal, and
 `in_progress` resumes automatically — only `advanced` waits.)
 
-`suggestions.md` is an optional async channel: append a one-off note and
-the next fresh attempt sees the text added since it was last read, once.
-Use `goal.md` for permanent/structural changes, `suggestions.md` for
-transient nudges (e.g. left while AFK).
+`suggestions/` is an optional async channel — a directory parallel to
+`attempts/`: the Runner of attempt NNN reads `suggestions/NNN.md` at the start
+of that attempt, so the manager drops a note named for the round that will read
+it (e.g. `suggestions/006.md` while attempt 005 runs). The file stays in place
+afterward as part of the audit trail. Use `goal.md` for permanent/structural
+changes, `suggestions/` for transient nudges (e.g. left while AFK).
 
 ## Workspace contents
 
@@ -194,8 +196,8 @@ After running, the workspace looks like:
 ```
 <workspace>/
 ├── goal.md
-├── config.yaml           # optional: model / interval / mode
-├── suggestions.md        # optional: async per-attempt notes
+├── config.yaml           # optional: model / interval / mode / caps
+├── suggestions/          # optional: per-attempt human notes (NNN.md read by attempt NNN)
 ├── memory/
 │   └── learnings.md      # ~4KB cap; Runner curates this
 └── attempts/

agents/goal-runner.md

@@ -15,6 +15,11 @@ optional Initial Context), `memory/learnings.md` if present, and the last few
 on them rather than assumptions. Also read whatever `goal.md`'s Verification
 references (rubrics, scripts, baselines).
 
+Also read `suggestions/NNN.md` for THIS attempt's number (your brief states it),
+if it exists — a transient human note left for exactly this round. Treat it as
+guidance to address this attempt; `goal.md` still wins for the permanent spec.
+Leave the file in place (it's part of the audit trail, like `attempts/NNN.md`).
+
 ## 2. Verify
 Run the Verification procedure from `goal.md` — the **only authoritative check**,
 not your sense that it "looks done". It yields **pass** (objective met AND no hard

docs/design.md

@@ -235,26 +235,26 @@ tokens.
 ```
 <workspace>/
 ├── goal.md            # Objective + Hard Constraints + Verification spec
-├── config.yaml        # Optional: model / interval / mode (see below)
-├── suggestions.md     # Optional: async per-attempt human notes (see below)
+├── config.yaml        # Optional: model / interval / mode / caps (see below)
+├── suggestions/       # Optional: per-attempt human notes (see below)
+│   └── 006.md         # suggestions/NNN.md is read by the Runner of attempt NNN
 ├── memory/
 │   └── learnings.md   # Run-level curated knowledge; Runner self-maintains, ~4KB cap
 ├── attempts/
 │   ├── 001.md         # Per-attempt factual record, written by the Runner of that attempt
 │   ├── 002.md
 │   └── ...            # Append-only: each file is written once, never modified
 └── .goaloop/          # Orchestrator-private state (not part of the goal record)
-    ├── state.json     # Checkpoint: active session id for crash/quota resume
+    ├── state.json     # Checkpoint: active session id + cumulative counters/cost for resume
     ├── status.txt     # Current one-line orchestrator status (read by /goal-run)
-    ├── attempt_complete.json  # Last completed attempt's {attempt, status, cost_usd}
-    ├── suggestions.cursor     # Byte offset into suggestions.md already shown
+    ├── attempt_complete.json  # Last completed attempt's {attempt, status, cost_usd, total_cost_usd}
     ├── continue.json  # copilot-mode approval token (written by `goaloop continue`)
     ├── orchestrator.log       # Per-attempt log: Runner messages, tool calls, results
     └── pipeline.pid   # PID of the running orchestrator (for status/stop)
 ```
 
 The `goal.md` + `memory/` + `attempts/` triple is the goal record GoaLoop
-requires; `config.yaml` and `suggestions.md` are optional human inputs, and
+requires; `config.yaml` and `suggestions/` are optional human inputs, and
 `.goaloop/` is the orchestrator's own bookkeeping and can be deleted
 between runs without losing the audit trail. Anything else (scripts the
 verification uses, source code being modified, datasets, etc.) lives wherever
@@ -443,8 +443,8 @@ The orchestrator, not the Manager, performs the per-attempt mechanics:
 3. **Spawn the Runner.** `claude -p <brief> --append-system-prompt
    goal-runner.md --output-format stream-json --session-id <uuid>
    --dangerously-skip-permissions`. The brief carries the workspace path,
-   the attempt number, the read-context + terminator instructions, and —
-   on a fresh attempt — any NEW `suggestions.md` text since the cursor.
+   the attempt number, and the read-context + terminator instructions; the
+   Runner itself reads `suggestions/NNN.md` for that attempt as context.
 4. **Parse the terminator** (`{"status": pass|advanced|in_progress|blocked}`)
    and branch: `pass`/`blocked` → exit; `advanced` (and `attempts/NNN.md`
    exists) → pace (or, in copilot mode, wait for approval), then next
@@ -531,23 +531,28 @@ on the user's confirmation** — not to carry the guidance itself.
 This is also why `goal.md` is mutable mid-run: it is the steering wheel, not
 just the starting configuration.
 
-**`suggestions.md` — transient / per-attempt.**
+**`suggestions/` — transient / per-attempt.**
 
 For a one-off note that does not belong in the goal spec (e.g. something left
-while AFK — "try lock granularity next"), the human appends a line to
-`<workspace>/suggestions.md`. On each FRESH attempt the orchestrator injects
-the text added since a stored cursor (`.goaloop/suggestions.cursor`) into the
-Runner's brief as a "Human guidance (NEW)" section, then advances the cursor
-— so each note is shown to exactly one attempt and not repeated. Use
-`goal.md` for changes that should persist; use `suggestions.md` for transient
-nudges.
+while AFK — "try lock granularity next"), the manager drops a note file into
+`<workspace>/suggestions/` — a directory parallel to `attempts/`. Delivery is
+**Runner-side, by attempt number**: the Runner of attempt NNN reads
+`suggestions/NNN.md` as part of its Load-context step (just like it reads
+`goal.md` and `attempts/`), so the manager — which knows the current attempt
+from status — names the note for the round that will read it (`suggestions/006.md`
+while 005 runs). The orchestrator never touches it; there is no injection, no
+consumption, no cursor. The file stays in place afterward as part of the audit
+trail. Because delivery is an exact number match, a note whose round the loop
+has already passed simply sits unread until re-pointed — an accepted, low-odds
+trade for the simplicity of "Runner reads its own `suggestions/NNN.md`". Use
+`goal.md` for changes that should persist; `suggestions/` for transient nudges.
 
 **The Manager distinguishes messages for itself vs. goal edits.**
 
 | User message | Manager's response |
 |---|---|
 | "How is it going?" | Answer directly by reading `.goaloop/status.txt` + latest `attempts/NNN.md` |
-| "Try lock granularity instead next time" | A transient nudge → append to `suggestions.md` (next attempt sees it once); a permanent change → propose editing `goal.md`'s Initial Context |
+| "Try lock granularity instead next time" | A transient nudge → write `suggestions/<next-attempt>.md` (that Runner reads it); a permanent change → propose editing `goal.md`'s Initial Context |
 | "Stop the orchestrator" | `goaloop stop <name>`; confirm it stopped |
 | "Change the target to P99 < 3s" | Propose editing `goal.md`'s Objective; edit on confirmation |
 | "Hmm" / "OK" / chit-chat | Ignore |
@@ -629,8 +634,8 @@ Human pacing during a run is achieved by:
 - **Reading status** via `/goal-run` (or `goaloop status`, or
   `tail -f .goaloop/orchestrator.log`) — the orchestrator writes `status.txt` and
   `attempt_complete.json` each attempt.
-- **Editing `goal.md`** (permanent) or **appending to `suggestions.md`**
-  (transient, per-attempt) to steer — the next attempt's Runner picks it up
+- **Editing `goal.md`** (permanent) or **dropping a `suggestions/NNN.md`**
+  (transient, per-attempt) to steer — the Runner of that attempt picks it up
   (see Human guidance protocol).
 - **`goaloop continue`** to release the next attempt in copilot mode.
 - **`goaloop stop`** to halt earlier than `pass`.
@@ -679,9 +684,9 @@ The following were considered and deliberately not built. Each appears here
 with the reason so future contributors don't reintroduce them by reflex.
 
 > **Implemented after v0.1 (now included).** Two features once listed here as
-> excluded have since been built: `suggestions.md` (a transient per-attempt
-> human → agent channel, NEW-since-cursor injection — see Human guidance
-> protocol) and copilot mode (the `--mode copilot` human-review pause,
+> excluded have since been built: `suggestions/` (a transient per-attempt
+> human → agent channel — the Runner of attempt NNN reads `suggestions/NNN.md`;
+> see Human guidance protocol) and copilot mode (the `--mode copilot` human-review pause,
 > released with `goaloop continue` — see How to run). They are documented
 > above and are no longer exclusions.
 

goaloop/orchestrator.py

@@ -87,11 +87,10 @@ def __init__(
         self.status_path = self.state_dir / "status.txt"
         self.complete_path = self.state_dir / "attempt_complete.json"
         self.continue_path = self.state_dir / "continue.json"
-        # Async human feedback channel (optional). The human appends notes to
-        # suggestions.md; we inject anything past the cursor as NEW into the
-        # next fresh attempt's brief, then advance the cursor.
-        self.suggestions_path = self.ws / "suggestions.md"
-        self.cursor_path = self.state_dir / "suggestions.cursor"
+        # Human feedback is delivered Runner-side, not here: the manager writes
+        # a note to suggestions/NNN.md and the Runner of attempt NNN reads it as
+        # context for that round (see agents/goal-runner.md, "Load context").
+        # The orchestrator stays out of it — no injection, no consumption.
 
         self.adapter = ClaudeAdapter(
             cwd=str(self.ws),
@@ -189,35 +188,6 @@ def _end_error(self, attempt: int, reason: str) -> None:
         self._mark_complete(attempt, "error", None)
         self._clear_active()
 
-    def _suggestions_section(self) -> str:
-        """Build the NEW-since-cursor block from suggestions.md, then advance
-        the cursor (these notes are now delivered into a session).
-
-        Returns "" when there's no suggestions.md or nothing new. Only NEW
-        text is injected — older notes stay in the file for the human; the
-        Runner can read it directly if it wants history. goal.md remains the
-        channel for permanent/structural guidance; suggestions.md is for
-        transient per-attempt notes (e.g. left while AFK).
-        """
-        if not self.suggestions_path.exists():
-            return ""
-        content = self.suggestions_path.read_text()
-        if not content.strip():
-            return ""
-        cursor = 0
-        if self.cursor_path.exists():
-            try:
-                cursor = int(self.cursor_path.read_text().strip())
-            except ValueError:
-                cursor = 0
-        cursor = max(0, min(cursor, len(content)))
-        new = content[cursor:].strip()
-        if not new:
-            return ""
-        self.state_dir.mkdir(parents=True, exist_ok=True)
-        self.cursor_path.write_text(str(len(content)))  # delivered — advance
-        return f"\n## Human guidance (NEW — address this attempt)\n\n{new}\n"
-
     def _wait_for_continue(self, n: int) -> None:
         """Copilot mode: block until the human approves the next attempt.
 
@@ -235,10 +205,8 @@ def _wait_for_continue(self, n: int) -> None:
         self.log("[orchestrator] approval received — continuing")
 
     def _build_brief(self, n: int) -> str:
-        guidance = self._suggestions_section()
         return f"""Workspace: {self.ws}
 This is attempt {n:03d}; write your attempt record to attempts/{n:03d}.md.
-{guidance}
 Run one attempt per your system-prompt workflow, then end your final message
 with a single line that is exactly one of these JSON objects:
   {{"status": "pass", "verification": "<one-line summary>"}}

skills/goal-flash/SKILL.md

@@ -115,8 +115,10 @@ rather than interviewing for it:
   `goaloop status <name>` or `tail -f <workspace>/.goaloop/orchestrator.log`.
 - **The inferred goal.md is the steering wheel and is mutable mid-run.** If
   the inference was off, edit `<workspace>/goal.md` (esp. Verification) — the
-  next attempt picks it up. Drop a transient nudge in `suggestions.md`. Halt
-  with `goaloop stop <name>`.
+  next attempt picks it up. For a transient nudge, drop a note file the next
+  attempt will read — `suggestions/<next-attempt>.md`, named per the convention
+  `/goal-run` describes (check `goaloop status` for the round). Halt with
+  `goaloop stop <name>`.
 
 From here, progress relay is identical to `/goal-run` — read
 `.goaloop/status.txt`, `.goaloop/attempt_complete.json`, and the latest

skills/goal-init/SKILL.md

@@ -131,9 +131,9 @@ After writing, tell the user:
   mid-run, edit `goal.md` — the next attempt picks it up.
 - (Optional, no action needed at init) the workspace may also hold a
   `config.yaml` (flat keys `model` / `interval` / `mode: auto|copilot`)
-  to set run defaults, and a `suggestions.md` where they can drop async
-  per-attempt notes mid-run (each note is shown to one fresh attempt);
-  `goal.md` remains the place for permanent changes.
+  to set run defaults, and a `suggestions/` directory where the manager can
+  drop async per-attempt note files mid-run (the Runner of attempt NNN reads
+  `suggestions/NNN.md`); `goal.md` remains the place for permanent changes.
 
 Encourage them to read and tweak `goal.md` before kicking off — it's
 the load-bearing artifact of the whole framework.

skills/goal-run/SKILL.md

@@ -152,11 +152,15 @@ durable guidance channels, by intent serving different purposes.
   (or a file it references, like a rubric). The next attempt's Runner
   reads the updated spec naturally — no relay needed. Propose the edit,
   make it on the user's confirmation; no restart required.
-- **Transient per-attempt note**: append a line to
-  `~/.goaloop/<name>/suggestions.md`. The next fresh attempt sees the
-  text added since it was last read, once (then it's not repeated). Use
-  this for one-off nudges (e.g. dropped while AFK) rather than changes
-  that should persist — those belong in `goal.md`.
+- **Transient per-attempt note**: the Runner of attempt NNN reads
+  `~/.goaloop/<name>/suggestions/NNN.md` at the start of that attempt. So
+  write the note there, targeting the round that will read it: check
+  `goaloop status` for the current attempt and write the NEXT number — if
+  attempt 005 is running, write `suggestions/006.md`. The file stays in place
+  afterward as an audit trail (parallel to `attempts/NNN.md`). Use this for
+  one-off nudges (e.g. dropped while AFK); `goal.md` is for changes that
+  should persist. (If the loop has already moved past the round you targeted,
+  the note just sits unread — re-point it at the new next attempt.)
 - **Stop the orchestrator**: `goaloop stop <name>` (sends SIGTERM; it
   exits after the in-flight attempt's process settles).