Răsfoiți Sursa

README: document goal-2 QoL features and Force Wake

Adds the dashboard Queue card's waiting-for-attention semantics (ready + parked incl. suspended runs + answered-awaiting-saddle; auto-enqueue-gated rows out), the slot-update mutation answers on task/goal pages, the saddles page ssh_public_key dark-panel contrast note, and a Force Wake section covering the goal/task page buttons, immediate offerability, the explicit resume_notice line, draft - NOT enqueued naming, single wake per press and the 400 guards.
clanker 1 lună în urmă
părinte
comite
37c5e22801
1 a modificat fișierele cu 34 adăugiri și 2 ștergeri
  1. 34 2
      README.md

+ 34 - 2
README.md

@@ -187,7 +187,9 @@ share the `/workspace` volume.
    Registration mints a per-saddle token and delivers it to the daemon's
    `POST /register` (with this app's base URL); the daemon then asks
    for work whenever idle-awake and sleeps on a 204 answer, so a ready
-   task reaches it within one dispatcher tick (wake → ask → allocate).
+   task reaches it within one dispatcher tick (wake → ask → allocate). The saddles page
+   renders the daemon's `ssh_public_key` in a dark panel with the text
+   colour lifted for readable contrast.
 
 **Goals** (`/goals`) are the orchestrated path: write the Initial Brief
 and a branch name, start it, and a goal agent investigates (asking
@@ -233,6 +235,9 @@ own password — current, new, confirm. Change the seeded admin's
 - **`/tasks/{id}`** — the control room; it refreshes on every state
   pulse while a saddle works: comments thread (yours and the agent's),
   blocks, goal context, session history, and the agent's final summary.
+  Your mutations on this page (and the goal page's) answer with the
+  refreshed state slots themselves rather than a navigate or reload —
+  the page lands in its post-mutation shape in one round trip.
 - **`/tasks/{id}/terminal`** — the full bash session log: the raw PTY
   stream the daemon pushes (chunk batches land in `session_raw_log` and
   stream over SSE byte-exact), with the typed entry view as the fallback
@@ -243,7 +248,13 @@ own password — current, new, confirm. Change the seeded admin's
   supervision narrative and the completion review.
 - **`/`** — dashboard: the "needs your attention" pile (goal AND task
   blocks interleaved, newest-first) above the activity timeline, saddle
-  cards and queue summary.
+  cards and queue summary. The Queue card's **queued** figure counts
+  waiting-for-attention work: ready-to-dispatch queued tasks, parked
+  (suspended) tasks — suspended goal-agent runs included — and tasks
+  whose raised blocks are all answered and now wait for a saddle to
+  resume them; queued rows gated on an unfinished auto-enqueue
+  predecessor stay out (the predecessor itself is already counted).
+  **blocked** stays human-answerable rows only.
 
 ## Answering block questions
 
@@ -276,6 +287,27 @@ the task/its projects, or new project notes. The daemon appends it as
 a TURN on resume (prompt-cache friendly) instead of refreshing the
 system prompt; the member is absent when nothing changed.
 
+## Force Wake (human-triggered resume)
+
+A parked agent normally resumes only when the machinery owes it a wake
+(a block answered, an owned task's terminal transition). When a run
+parks with nothing pending — the goal agent suspends itself right
+after a typo'd enqueue, say — no wake ever fires and it would sit
+suspended forever. **Force wake** is the human lever. On an active
+goal whose run task is suspended, the goal page's lifecycle head
+offers a **Force wake** button (beside Pause/Resume); on a suspended
+plain task the task page offers the same, and on a suspended goal-run
+task row it routes to the same goal force-wake path — one lever, no
+duplicates. One press sets the flag; the next dispatcher pass makes
+the run offerable immediately (no coalesce wait), and the resumed
+assignment's `resume_notice` leads with an explicit line — "The user
+explicitly force-woke this goal's supervision — you were parked with
+no pending wake." — followed by the standard batched report, which
+names draft-status tasks as "draft — NOT enqueued" so a parked agent
+that typo'd an enqueue sees it immediately. The flag clears on the
+wake (one wake per press). Paused goals and non-suspended tasks hide
+the button and the API refuses them (400).
+
 ## Browser notifications (Web Push)
 
 The app speaks the real Web Push protocol (VAPID + RFC 8291 payload