fix(orchestrator): make suggestions.md a mailbox, drop the byte cursor

The async human-feedback channel tracked delivery with a byte offset
(.goaloop/suggestions.cursor) into an append-only suggestions.md. That
assumed the file only ever grows: if the human edited or deleted earlier
notes, the offset drifted — a shorter rewrite could clamp the cursor to
end-of-file and silently swallow freshly added guidance.

Replace it with a mailbox model and no cursor at all. suggestions.md now
holds undelivered guidance; each fresh attempt atomically CLAIMS its
contents (os.rename aside), injects them into the brief, archives them to
.goaloop/suggestions.delivered.md (stamped per attempt), and clears the
file. The atomic rename is the whole trick: a note appended while a claim
is in flight lands either in that batch or in a fresh file the next attempt
picks up — never lost, never delivered twice, with nothing to drift when
the human edits or deletes earlier notes. The inflight file persists until
the archive write succeeds, so a crash mid-claim is recovered (at worst
delivered twice — harmless — never dropped) on the next call.

Bonus: each note now reaches exactly one attempt and history moves to the
archive, instead of stacking up in the live file (which, in a long run,
left the Runner guessing which of several blocks was current).

Docs (README, design.md, goal-run skill) updated to describe the mailbox.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CHb1FkoMGfDfwmeJR5hBG6

Author: luohaha

README.md

@@ -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.md` is an optional async channel — a mailbox: append a one-off
+note and the next fresh attempt claims it (exactly once), archiving it to
+`.goaloop/suggestions.delivered.md` and clearing the file. Edit or delete
+freely before it's claimed; the claim is atomic, so nothing is lost or
+double-delivered. Use `goal.md` for permanent/structural changes,
+`suggestions.md` for transient nudges (e.g. left while AFK).
 
 ## Workspace contents
 

docs/design.md

@@ -244,10 +244,10 @@ tokens.
 │   ├── 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}
+    ├── suggestions.delivered.md  # Archive of consumed suggestions.md notes, stamped per attempt
     ├── 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)
@@ -534,13 +534,17 @@ just the starting configuration.
 **`suggestions.md` — 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 human appends to
+`<workspace>/suggestions.md`. The file is a **mailbox, not a log**: whatever it
+holds is undelivered. On each FRESH attempt the orchestrator atomically
+*claims* its contents (renaming it aside), injects them into the Runner's brief
+as a "Human guidance (NEW)" section, archives them to
+`.goaloop/suggestions.delivered.md`, and clears the file — so each note reaches
+exactly one attempt. The atomic rename is what makes this race-free: a note
+appended while a claim is in flight lands in either that batch or a fresh file
+the next attempt picks up — never lost, never delivered twice, with no byte
+cursor to drift when the human edits or deletes earlier notes. Use `goal.md`
+for changes that should persist; use `suggestions.md` for transient nudges.
 
 **The Manager distinguishes messages for itself vs. goal edits.**
 

goaloop/orchestrator.py

@@ -87,11 +87,15 @@ 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.
+        # Async human feedback channel (optional). suggestions.md is a MAILBOX,
+        # not a log: whatever it holds is undelivered guidance. Each fresh
+        # attempt atomically CLAIMS its contents (rename aside), injects them as
+        # NEW into the brief, archives them, and clears the file — so there is
+        # no byte cursor to drift when the human edits/deletes (the old model).
         self.suggestions_path = self.ws / "suggestions.md"
-        self.cursor_path = self.state_dir / "suggestions.cursor"
+        # Atomic-claim staging + permanent archive of delivered notes.
+        self.suggestions_inflight = self.state_dir / "suggestions.inflight"
+        self.suggestions_archive = self.state_dir / "suggestions.delivered.md"
 
         self.adapter = ClaudeAdapter(
             cwd=str(self.ws),
@@ -189,34 +193,39 @@ 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).
+    def _consume_suggestions(self, n: int) -> str:
+        """Claim any pending human notes from suggestions.md (the mailbox) and
+        return them as a brief section, or "" if none.
+
+        suggestions.md holds undelivered guidance; we CLAIM it by atomically
+        renaming it aside. That rename is the whole trick: a human append that
+        races the claim lands either in the batch we just took or in a fresh
+        file the next attempt picks up — never lost, never delivered twice, and
+        with no byte cursor to drift when the human edits or deletes earlier
+        notes. The claimed text is appended to suggestions.delivered.md
+        (stamped with the attempt) so history survives the cleared live file.
+        goal.md stays the channel for permanent/structural guidance.
+
+        Crash-safety: the inflight file persists until the archive write
+        succeeds, so a crash mid-claim leaves it for the next call to recover
+        (at worst delivered twice — harmless — never dropped).
         """
-        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():
+        self.state_dir.mkdir(parents=True, exist_ok=True)
+        if not self.suggestions_inflight.exists():
+            if not self.suggestions_path.exists():
+                return ""
             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:
+                self.suggestions_path.rename(self.suggestions_inflight)
+            except OSError:
+                return ""
+        text = self.suggestions_inflight.read_text().strip()
+        if not text:
+            self.suggestions_inflight.unlink(missing_ok=True)
             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"
+        with self.suggestions_archive.open("a") as fh:
+            fh.write(f"\n## Delivered to attempt {n:03d}\n\n{text}\n")
+        self.suggestions_inflight.unlink(missing_ok=True)
+        return f"\n## Human guidance (NEW — address this attempt)\n\n{text}\n"
 
     def _wait_for_continue(self, n: int) -> None:
         """Copilot mode: block until the human approves the next attempt.
@@ -235,7 +244,7 @@ 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()
+        guidance = self._consume_suggestions(n)
         return f"""Workspace: {self.ws}
 This is attempt {n:03d}; write your attempt record to attempts/{n:03d}.md.
 {guidance}

skills/goal-run/SKILL.md

@@ -153,10 +153,11 @@ durable guidance channels, by intent serving different purposes.
   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`.
+  `~/.goaloop/<name>/suggestions.md` (a mailbox). The next fresh attempt
+  claims it exactly once — injected into the brief, archived to
+  `.goaloop/suggestions.delivered.md`, and the file cleared. Use this for
+  one-off nudges (e.g. dropped while AFK) rather than changes that should
+  persist — those belong in `goal.md`.
 - **Stop the orchestrator**: `goaloop stop <name>` (sends SIGTERM; it
   exits after the in-flight attempt's process settles).