herdr-gentle-shell 1.5.1 → 1.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/DESIGN.md CHANGED
@@ -17,11 +17,15 @@ explicitly in §10 and are not decided here.
17
17
  - Herdr sidebar (`[ui.sidebar.agents]` + `[ui.sidebar.spaces]` blocks): shows
18
18
  one state label per pane plus an optional session-changes badge.
19
19
  - The human operator watching Pi + Gentle Shell agents: needs to distinguish
20
- generic activity (`gentle`, machine key `working`) vs the active TaskStore role (`explorer`,
21
- `worker`, `verify`, `rdd`), `ask` (blocked on user input), `blocked`
22
- (the row word for the `error` key), `done`, and `idle` at a glance. No
23
- visible text ever carries
24
- a subagent count, and generic activity never reads `working`.
20
+ the principal session's own pink `gentle` (machine key `orchestrating` —
21
+ its working status and its generic status) from a delegate's own word: the
22
+ active TaskStore role abbreviation (`explorer`, `worker`, `verify`,
23
+ `judge`, `rdd`) or, for a non-contemplated subagent, that subagent's
24
+ sanitized name on the amber `working` cell — plus `ask` (blocked on user
25
+ input), `blocked` (the row word for the `error` key), `done`, and `idle` at
26
+ a glance. No visible text ever carries a subagent count, exactly one
27
+ user-facing `gentle` exists (the pink one), the amber `working` cell never
28
+ renders that word, and `gentle` never renders on an idle session.
25
29
 
26
30
  ### Current boundary and interaction
27
31
 
@@ -173,7 +177,8 @@ an explicit writer-ownership decision. Rationale follows each choice.
173
177
  ### O5. `done`/`idle` freshness vs pi-tree done-hold + idle grace → TTL WINS; SWEEP OWN TOKENS ONLY
174
178
 
175
179
  - **Chosen:** every gentle token carries an absolute `expiry <= now + 60000`
176
- (same 60 s horizon as E4). The consumer treats missing or expired gentle
180
+ (same 60 s horizon as E4), except `gentle_done_v1`, which carries the unseen
181
+ cap (§4.3). The consumer treats missing or expired gentle
177
182
  tokens as `unknown → idle` fallback (never holds `done` past expiry).
178
183
  On handover (gentle disabled/uninstalled) the consumer sweeps only token
179
184
  names it wrote (`gentle_*`, `herdr:blocked` labels it set); it never deletes
@@ -201,22 +206,38 @@ Sidecar only: ships beside `herdr-agent-state.ts`, never modifies it.
201
206
 
202
207
  | Producer event (source) | Tokens written | v1 state contribution |
203
208
  |---|---|---|
204
- | `agent_start` / `isIdle=false` (main actively working, incl. 0 active subs) | `gentle_work_v1=<hash>:0:<exp>` + `gentle_principal_v1=<hash>:<exp>` (principal-only activity marker) + `gentle_orchestrating_v1=<hash>:<exp>` (root marker while main actively works) + clear `herdr:blocked` labels | `gentle` (machine key `working`, or `orchestrating` while the root marker is fresh) while the principal session actively works, even with zero subagents |
205
- | TaskStore `running` non-empty (G3; queued/waiting never execute) | `gentle_work_v1=<hash>:<count>:<exp>` (running total of delegates — never a principal-working signal) + `gentle_roles_v1=<csv>` (roles from `TaskRecord.agent`, authoritative, oldest-first) + `gentle_names_v1=<csv>` (compat transport only, never rendered) + `gentle_orchestrating_v1=<hash>:<exp>` (root-only marker, §4.3) | the oldest running role word (known short word or unknown sanitized name) whenever the principal itself is not working; a working principal reads `gentle` instead; role labels show the total when two or more delegates run |
209
+ | `agent_start` / `isIdle=false` (main actively working, incl. 0 active subs) | `gentle_work_v1=<hash>:0:<exp>` + `gentle_principal_v1=<hash>:<exp>` (principal-only activity marker) + `gentle_orchestrating_v1=<hash>:<exp>` (root marker while main actively works) + clear `herdr:blocked` labels | the pink `gentle` (machine key `orchestrating`, with or without a fresh root marker) while the principal session actively works, even with zero subagents |
210
+ | TaskStore `running` non-empty (G3; queued/waiting never execute) | `gentle_work_v1=<hash>:<count>:<exp>` (total delegates — snapshot-confirmed running records plus distinct in-flight `subagent_run`/`subagent_continue` calls, §4.2 — never a principal-working signal) + `gentle_roles_v1=<csv>` (roles from `TaskRecord.agent`, authoritative, oldest-first) + `gentle_names_v1=<csv>` (compat transport only, never rendered) + `gentle_orchestrating_v1=<hash>:<exp>` (root-only marker, §4.3) | the oldest running role word (known short word or unknown sanitized name) whenever the principal itself is not working; a working principal reads `gentle` instead; role labels show the total when two or more delegates run |
206
211
  | `ASK_USER_CHOICE_BLOCKED_EVENT` / `gentle-pi:ask-user-choice:blocked` (G4), incl. questionnaire + tool-gated `ui_prompt` dialog spans (`kind` other than `custom` — a panel or overlay such as the agents view, ODD viewer, changes view or design canvas never counts, because opening a panel is navigation, not a question), plus direct Pi in-process `tool_execution_start` opens / `tool_execution_end` / `tool_result` closes for the exact tools `ask_user_question` and `ask_user_choice`, tracked by `toolCallId` in a call-id set (a `tool_call` proposal alone never opens; an abort/error end with no result still closes; overlapping calls correct; cleared on result/end/reset/shutdown; event legs and error > ask > review precedence unchanged; boundary: only what Pi emits as execution events is observable — a host ask UI that never emits one stays covered by the event legs only). `gentle_review` starts (any operation) never enter ask: the former consent-eligible pending signal fired before any outcome/UI and falsely blocked pre-granted sessions | `herdr:blocked` label `ask:<intentId>` + durable `gentle_ask_v1=<hash>:<intentId>:<exp>` on every beat while ask is active (null/clear when inactive — repairs a missed label edge; §4.3) | `ask` (existing machine key, user-facing `ask`, amber/orange, native `?`) |
207
212
  | Pi in-process `tool_execution_start` opens / `tool_execution_end` / `tool_result` closes (by `toolCallId`; a `tool_call` proposal alone never opens) for the exact tools `gentle_review_capture`, `gentle_review_capture_group` with `reviewerRunAcknowledged: true` in the runtime args; `correctionLines` (native planning, never a reviewer), forecast-only calls, `gentle_review` (any operation), `gentle_review_scope`, and all sidebar/hook signals never enter — unknown legacy shapes stay dark (conservative) | `herdr:blocked` label `review:<reviewId>` | `review` (machine key `review`) — during a capture-group run the single parent capture-group call stays in flight across the whole multi-reviewer span, so that one call alone holds the label. Bounded approximation: the acknowledged capture interval contains preparation and admission; no exact reviewer internal events exist today |
208
213
  | the agent run itself stops on an error (an assistant message whose `stopReason` is `error` — the same signal Pi derives `turn_end.outcome === "error"` from) | durable `gentle_error_v1=<hash>:run-failed:<exp>` on every beat while the leg stands (null/clear the beat it releases, §4.3) + `herdr:blocked` label `error:run-failed`; no native state is derived from it (the pane stays on its lifecycle state — `working` — while the leg stands, so the host raises no NeedsAttention toast or sound) | `error` (row word `blocked`) — never a native `blocked` |
209
214
  | a tool call fails, a delegate record ends `failed`, or a beat transport fails | nothing — detection only (a counter and a debug line under `GENTLE_HERDR_DEBUG=1`) | nothing: no label, no native state, no finish hold, no notification |
210
- | `agent_settled` + 0 active subs | `gentle_work_v1=<hash>:0:<exp>`; clear `blocked` labels | `done` |
215
+ | `agent_settled` + 0 active subs | `gentle_work_v1=<hash>:0:<exp>`; clear `blocked` labels | `done` — an observed turn only: the settle the beat reconciles from the host's live truth mints no finish (§4.5) |
211
216
  | `SESSION_CHANGE_ENTRY` `gentle-pi.session-change/v1` tool outcome (G1/G2) | `gentle_changes_v2=<hash>:<files>:<added>:<deleted>:<exp>` (+ legacy `gentle_changes_v1` dual-emit, §4.3) | change segments only (orthogonal to state) |
212
217
 
213
218
  `waiting`/`finished` TaskStore entries never count as active, and `queued`
214
219
  never counts as executing for the visible role + total (T2b): only `running`
215
220
  feeds `gentle_work_v1` and `gentle_roles_v1`. Liveness/marker coverage
216
221
  retains `running`/`queued`/pending (the root marker still covers a queued
217
- subagent or a pending launch). The count is a direct projection of the
218
- Gentle Shell TaskStore `running` records carried in
219
- `event.details.gentleAgents` — never a calculated pending-call estimate.
222
+ subagent or a pending launch). The count is the UNION of two live sources:
223
+ the Gentle Shell TaskStore `running` records carried in
224
+ `event.details.gentleAgents`, narrowed on every beat to the ids the read
225
+ presence snapshot lists running, and the DISTINCT
226
+ `subagent_run`/`subagent_continue` calls still in flight that record set does
227
+ not list yet, deduplicated by call id so one delegate is counted once. The
228
+ in-flight leg is why a synchronous (task-mode) launch now counts at all: it
229
+ creates no TaskStore record until it returns `tool_result`, so the records
230
+ alone read two live synchronous delegates as zero, while the union renders
231
+ `explorer (2)` for as long as both calls are in flight. It is not a
232
+ pending-call estimate: a call is counted exactly while it is in flight and
233
+ drops out on `tool_result`, cancellation, and settle, and a cancelled call
234
+ keeps blocking the terminal state only through the separate pending-call leg.
235
+ Names stay record-only (an in-flight call adds no name), and a record the
236
+ upstream store no longer lists contributes no name, no role word
237
+ and no count, even when the local map never received its final. When no
238
+ snapshot is usable (stale heartbeat, mismatched generation, inconsistent
239
+ counts) the local map stands in full, never at zero — a zero fallback would
240
+ flip the `done` gate and hide genuinely running work.
220
241
  Background launches (`subagent_run` with `mode: background`) announce their
221
242
  lifecycle over `message_end` custom results instead of `tool_result`
222
243
  details: an ACTIVE status (running|queued) there promotes the background
@@ -234,24 +255,31 @@ exact `gentle-ai-worker` → `worker`, exact `gentle-ai-verify` → `verify`,
234
255
  `jd-fix-` families) → the distinct `judge` slug (never `rdd`), and a
235
256
  review agent / `gentle-ai-review*` / any role containing `review` → `rdd`;
236
257
  any other agent keeps its original sanitized name (lowercase `[a-z0-9_-]`
237
- slug, 32-char bound — never a generic collapse; unsalvageable shapes read
238
- generic `gentle`, machine key `working`).
258
+ slug, 32-char bound — never a generic collapse; unsalvageable shapes and the
259
+ reserved slugs `gentle`, `working`, and `subagent` read
260
+ the pink generic `gentle`, machine key `orchestrating`).
239
261
  The consumer displays the oldest role word (known short word or unknown
240
262
  sanitized name) whenever the principal itself is not working, regardless of
241
- how many delegates run; a working principal renders `gentle` instead.
242
- Role labels carry the total running-delegate count in parentheses when greater
243
- than one. Role order is immutable first-seen (progress reads never reorder;
263
+ how many delegates run; a working principal renders the pink `gentle` instead.
264
+ Role labels carry that total count in parentheses when greater
265
+ than one — the §4.2 union, so two in-flight synchronous delegates of one role
266
+ render `explorer (2)` while the roles CSV still names `explorer` once. Role
267
+ order is immutable first-seen (progress reads never reorder;
244
268
  sound same-session presence createdAt/startedAt may correct a late local
245
- first-sighting, otherwise the local firstSeen stands).
269
+ first-sighting, otherwise the local firstSeen stands); the in-flight launches
270
+ sort after the running records, both oldest-first, so the oldest-role choice
271
+ is unchanged.
246
272
  Pending subagent tool calls are label correlation state for a later
247
273
  `gentleAgents.taskId` result and a role-only display hint while the call is
248
- in flight — never a count. WHY role-only: task-mode `subagent_run` stays in
274
+ in flight; the marker itself carries no count. WHY the hint stays role-only:
275
+ task-mode `subagent_run` stays in
249
276
  flight with no TaskStore record until it returns `tool_result`, so the exact
250
277
  agent name in the pending `tool_call` input is the only live role evidence;
251
- counting it would inflate the normative `gentle_work_v1` total with an
252
- estimate, while publishing its role slug as a bounded-CSV hint keeps the
253
- sidebar on the active role (`worker`, never bare `working` — generic activity reads `gentle`) with the count
254
- authoritative at 0. The hint merges with authoritative active TaskStore roles
278
+ publishing its role slug as a bounded-CSV hint keeps the
279
+ sidebar on the active role (`worker`, never the amber `working` cell —
280
+ generic activity reads the pink `gentle`), while the total itself comes from
281
+ the §4.2 union (one entry per in-flight call id), never from the hint. The
282
+ hint merges with authoritative active TaskStore roles
255
283
  (oldest-first) and clears when the tool result arrives, the call is
256
284
  cancelled, or the agent settles. On a tool
257
285
  result the producer reads the pending record before deleting it and uses it
@@ -264,7 +292,7 @@ launch outcomes keep `running` (and its agent) against `queued`/`waiting`/
264
292
  re-resolve oldest-first — so a working principal with live delegates keeps
265
293
  `gentle`, and a settle with running delegates keeps the oldest role word
266
294
  instead of settling to `idle`/`done`. A sanitized unknown slug exactly equal to
267
- `working` degrades to no role (generic `gentle`) on both the producer
295
+ `working` degrades to no role (the pink generic `gentle`) on both the producer
268
296
  (`agentToRole`) and the consumer (`roleToDisplay`) sides. No local
269
297
  age/staleness timeout is applied — Gentle Shell owns lifecycle/status truth.
270
298
  Finished/failed/cancelled records may linger in the map but never count;
@@ -276,10 +304,11 @@ coverage while the authoritative active list is non-empty or any
276
304
  once the main session settles — settled, or any non-root session. The marker carries no
277
305
  count and changes neither the work total nor the roles CSV: it is a pure
278
306
  freshness-bound presence flag (`<hash>:<exp>`, same binding/TTL style as
279
- gentle_work_v1) that the consumer reduces to `orchestrating` only with no
280
- delegation active (§5.2): below attention (error/ask/review),
281
- terminal `done`/native-`blocked`, and role words; ahead of generic
282
- activity only.
307
+ gentle_work_v1) that the consumer reduces to the same pink `gentle` the
308
+ principal's own activity renders, only with no role word above it (§5.2):
309
+ below attention (error/ask/review), terminal `done`/native-`blocked`, and
310
+ role words; ahead of the positive-count generic fallback only, which renders
311
+ that same pink `gentle`.
283
312
  The root session also emits `gentle_principal_v1` while its own agent is
284
313
  active (`agentActive`) and clears it (null) the moment the principal
285
314
  settles, keeping the same binding/TTL discipline. This is the principal-only
@@ -290,7 +319,7 @@ principal itself works. The native status keeps that aggregate meaning for
290
319
  Herdr's own pane state; the row's working-vs-idle decision reads only
291
320
  `gentle_principal_v1` (§5.2). It carries no count and alters neither the work
292
321
  total nor the roles CSV. `agentActive` alone would render that blocked call
293
- as generic `gentle`.
322
+ as the pink generic `gentle`.
294
323
  The root session additionally emits `gentle_pending_v1` (`<hash>:<role>:<exp>`)
295
324
  while a synchronous (task mode) `subagent_run`/`subagent_continue` tool call
296
325
  is still in flight: such a call blocks the principal's own turn, so the
@@ -311,6 +340,8 @@ sessionHash = 43*[A-Za-z0-9_-] ; base64url(sha256(agent_session path))
311
340
  expiry = 1*15DIGIT ; unix-ms, MUST satisfy expiry <= now+60000 at write
312
341
  count = "0" / [1-9] 0*15DIGIT
313
342
  gentle_work_v1 = sessionHash ":" count ":" expiry
343
+ ; count = the §4.2 union: snapshot-confirmed running
344
+ ; records plus distinct in-flight launches, deduped
314
345
  gentle_changes_v1 = sessionHash ":" count ":" count ":" expiry
315
346
  ; <hash>:<files>:<added+deleted>:<expiry> — LEGACY, see below
316
347
  gentle_changes_v2 = sessionHash ":" count ":" count ":" count ":" expiry
@@ -326,7 +357,10 @@ role = "explorer" / "worker" / "verify" / "judge" / "rdd" / passthrou
326
357
  ; stays distinct, never `rdd`)
327
358
  ; passthrough = 1*32 lowercase [a-z0-9_-], leading [a-z0-9]
328
359
  ; (unknown delegation keeps its sanitized original name —
329
- ; never a generic collapse; producer truncates to 32)
360
+ ; never a generic collapse; producer truncates to 32;
361
+ ; the reserved words `gentle`, `working`, and `subagent`
362
+ ; resolve to no role on both sides — producer and reducer —
363
+ ; so they degrade to the pink generic `gentle`)
330
364
  gentle_roles_v1 = role *("," role) ; total <= 512 UTF-8 bytes; null (clear)
331
365
  ; when no delegation is active (no role words)
332
366
  gentle_orchestrating_v1 = sessionHash ":" expiry
@@ -365,15 +399,28 @@ gentle_done_v1 = sessionHash ":" expiry
365
399
  ; live background jobs, no ask/review/error leg), then
366
400
  ; republished with the SAME expiry (never refreshed) until
367
401
  ; it lapses; null (clear) whenever work reappears or the
368
- ; session resets. Its expiry IS the done hold: default
369
- ; 5 s (short on purpose — the hold only makes a finish
370
- ; visible, it never pins a settled row, so `idle` follows
371
- ; within seconds), overridden by
372
- ; GENTLE_HERDR_DONE_HOLD_MS clamped to [1000, 300000], and
373
- ; the consumer accepts no expiry beyond now+300000 at read
374
- ; (the only token whose ceiling is not the 60 s TTL). The
375
- ; daemon also caps its next sleep at that expiry (§8). A
376
- ; session that never worked never mints one.
402
+ ; session resets. Its expiry IS the unseen cap: default
403
+ ; 900000 ms (15 min, S8), overridden by
404
+ ; GENTLE_DONE_UNSEEN_CAP_MS clamped to [100, 3600000], so a
405
+ ; finish nobody looks at recedes at the cap. The consumer
406
+ ; accepts no expiry beyond now+3600000 at read (the only
407
+ ; token whose ceiling is not the 60 s TTL). A VIEWED finish
408
+ ; recedes far sooner: the daemon starts one 5 s dwell
409
+ ; (DONE_VIEW_DWELL_MS) at the first frame that observes the
410
+ ; pane focused and then renders `idle` (§5.2). That ledger
411
+ ; of views is keyed by the token's absolute expiry and is
412
+ ; daemon memory only: a cleared token (reactivation,
413
+ ; session reset) drops its view and a new mint starts a new
414
+ ; episode, while a restart during a still-fresh token can
415
+ ; show `done` once more for one dwell and never mints a
416
+ ; second finish. The daemon also caps its next sleep at
417
+ ; that expiry and at the
418
+ ; pending dwell deadline (§8). The settle-edge hold that
419
+ ; withholds the mint while an in-flight launch may still
420
+ ; report back is a DIFFERENT bound:
421
+ ; GENTLE_HERDR_DONE_HOLD_MS, default 5 s, clamped
422
+ ; [1000, 300000]. A session that never worked never mints
423
+ ; one.
377
424
  gentle_ask_v1 = sessionHash ":" intentId ":" expiry
378
425
  ; durable ask signal, session-bound + TTL-fresh like
379
426
  ; gentle_orchestrating_v1 — emitted on every beat while
@@ -410,8 +457,9 @@ left it.
410
457
  Validation: consumers MUST reject tokens failing the grammar (wrong hash
411
458
  length, `expiry` in the past or `> now+60000` at read, non-numeric counts)
412
459
  and treat the pane as `unknown → idle` for that signal (§7). `gentle_done_v1`
413
- is the one ceiling exception: it is validated against `now+300000` so an
414
- overridden hold stays readable, and it still fails closed on a past expiry.
460
+ is the one ceiling exception: it is validated against `now+3600000` so an
461
+ overridden unseen cap stays readable, and it still fails closed on a past
462
+ expiry.
415
463
 
416
464
  ### 4.4 Examples
417
465
 
@@ -435,17 +483,19 @@ explorers with count 3 → `explorer (3)`; 5 files
435
483
  `● myproj +110 -22` (` +` green for added, ` -` red for deleted with a
436
484
  leading-space match, zero `·` separators because exactly one heading cell
437
485
  is nonempty).
438
- A review label renders `rdd` with a blue `●` (`#89b4fa`, same as explorer/pull). A fresh root
439
- `gentle_orchestrating_v1` marker renders pink `gentle` (machine display key
440
- `orchestrating`, pink palette unchanged) while the principal session actively
441
- works — even with zero subagents — and yields to a delegate role word and to
442
- attention (`ask`/`review`/`blocked`) and terminal `done` states. While the
443
- principal is working the marker colors that working state pink rather than
444
- competing with it. The marker is not a principal-working signal: it stays
445
- live while the principal is idle with queued or running delegates. The
446
- working state itself comes from `gentle_principal_v1`: with no fresh
447
- principal marker the pane shows the oldest role word (or `idle`), never
448
- `gentle` merely because delegates run.
486
+ A review label renders `rdd` with a blue `●` (`#89b4fa`, same as explorer/pull). A
487
+ `gentle_orchestrating_v1` marker renders the pink `gentle` (machine display
488
+ key `orchestrating`, pink palette unchanged): it covers the principal's
489
+ queued/running subs and pending launches, and it yields to a delegate role
490
+ word and to attention (`ask`/`review`/`blocked`) and terminal `done` states.
491
+ The marker is not a principal-working signal: it stays live while the
492
+ principal is idle with queued or running delegates, so it never decides the
493
+ working state. That state comes from `gentle_principal_v1` alone, and it is
494
+ the same pink `gentle` with or without a fresh root marker: the amber
495
+ `working` cell is never the principal's own. With no fresh principal marker
496
+ the pane shows the oldest role word, the pink generic `gentle` when a running
497
+ delegate has no resolvable name, or `idle` — but never an amber generic
498
+ because delegates run.
449
499
 
450
500
  ### 4.5 Publication and chunking
451
501
 
@@ -470,6 +520,29 @@ principal marker the pane shows the oldest role word (or `idle`), never
470
520
  - Writes are idempotent full-state snapshots per pane (all gentle tokens
471
521
  re-emitted each beat), never deltas — a lost report is repaired by the next
472
522
  beat.
523
+ - The producer beats every 15 s by default; `GENTLE_HERDR_BEAT_MS` overrides
524
+ the cadence for tests and debugging (clamped to [100, 300000]). The
525
+ override changes no TTL: the write horizon stays `now+60000` (§8).
526
+ - Every beat first reconciles the settle from the host's own live truth: with
527
+ no turn active and no work evidence (no running/queued delegate, no pending
528
+ launch, no live background job), the retained context's `isIdle()` flips
529
+ `settled`, so a run whose `agent_settled` never reached the producer still
530
+ reaches native `idle` instead of republishing a fresh count-0 work token
531
+ forever. A turn this producer saw start is never overridden from there.
532
+ When the host offers no truth at all, a producer that observed no turn stops
533
+ beating after a bounded budget (three beats) instead of publishing a native
534
+ state the host never confirmed; a turn this producer saw start is never
535
+ bounded, so the budget cannot trade a truthful `working` for a false `idle`
536
+ on a host with no truth to settle on. The beat is re-armed by the edges that
537
+ schedule a publish (ask, review, launch, session changes, jobs), while an
538
+ ordinary tool edge reaches the row through the host's own truth rather than
539
+ by re-arming it. A settle recovered this way is not an observed turn, so it
540
+ mints no `gentle_done_v1` and sends no finish notification.
541
+ - The settle-time pending latch (`pendingCount`) is bounded by that settle's
542
+ finish hold (`GENTLE_HERDR_DONE_HOLD_MS`, default 5 s, clamped
543
+ [1000, 300000]) — the settle-edge bound, not the finish token's unseen cap:
544
+ past that hold a launch that never reports
545
+ back stops counting, so it cannot pin the native report at `working`.
473
546
  - Session-change tokens are refreshed/cleared from the current Gentle Shell
474
547
  session model every beat and never carried across sessions: zero changed
475
548
  files publishes a clear (null over socket metadata, `--clear-token <name>`
@@ -498,8 +571,9 @@ gate for the working-vs-idle decision — never rendered as a count),
498
571
  `gentle_pending_v1` (blocking-delegate role marker + freshness gate for the
499
572
  in-flight synchronous launch — renders the child's role word while the
500
573
  principal's own turn is blocked on it),
501
- `gentle_done_v1` (synthesized finish signal + its own hold freshness gate
502
- for the reachable `done` display — the host never reports `done`, §4.3),
574
+ `gentle_done_v1` (synthesized finish signal + its own unseen-cap freshness
575
+ gate for the reachable `done` display, receded by the daemon after the viewed
576
+ dwell — the host never reports `done`, §4.3),
503
577
  `gentle_error_v1` (durable run-error signal + freshness gate for the `error`
504
578
  display — repairs a missed `error:` label edge, §4.3),
505
579
  `gentle_roles_v1` (authoritative activity roles,
@@ -532,17 +606,20 @@ blockingRole := fresh gentle_pending_v1 (session-bound, TTL-fresh) whose
532
606
  principalWorking := fresh gentle_principal_v1 (session-bound, TTL-fresh) —
533
607
  the principal's OWN activity, never the delegate count and
534
608
  never the aggregate native status (which reads working for
535
- any running delegate or pending launch); renders
536
- `orchestrating` while a fresh gentle_orchestrating_v1 is
537
- live, otherwise working(main); outranks every delegate role
609
+ any running delegate or pending launch); renders the pink
610
+ `gentle` (machine key `orchestrating`) with or without a
611
+ fresh gentle_orchestrating_v1; outranks every delegate role
538
612
  word; stale, foreign, or absent falls through to the
539
613
  branches below
540
614
  role := gentle_work_v1 fresh AND gentle_roles_v1 yields a
541
615
  recognized role (oldest first, incl. the in-flight pending
542
616
  role hint at count = 0 for task-mode launches with no
543
617
  TaskStore record yet) — the principal is not working, so the
544
- delegate word wins; role labels append the total when at
545
- least two delegates run. Tool-only review has no suffix.
618
+ delegate word wins. A non-contemplated subagent renders on
619
+ the `working` display, whose label is that subagent's own
620
+ sanitized name (never `gentle`). Role and name labels append
621
+ the total when at least two delegates run. Tool-only review
622
+ has no suffix.
546
623
  orchestrating := gentle_orchestrating_v1 fresh with no role word above
547
624
  (root-only per §4.2: fresh while the main session actively
548
625
  works, even with zero subagents, retaining running/queued-sub,
@@ -550,8 +627,11 @@ orchestrating := gentle_orchestrating_v1 fresh with no role word above
550
627
  falls through to the
551
628
  branches below; attention, terminal `done`/native-`blocked`,
552
629
  a working principal, and role words stay higher)
553
- working(main) := gentle_work_v1 fresh AND count > 0 with no role word
554
- OR (gentle_work_v1 fresh AND count = 0 AND agent not settled)
630
+ generic := gentle_work_v1 fresh AND count > 0 with no role word —
631
+ renders the pink `gentle` (machine key `orchestrating`), the
632
+ principal session's generic status; a count = 0 beat asserts
633
+ no activity — it reaches `done` only through the terminal
634
+ gate, otherwise `idle`
555
635
  done := (native done OR fresh gentle_done_v1) AND gentle_work_v1
556
636
  fresh with count = 0 (no running delegates) AND no roles AND
557
637
  no fresh gentle_orchestrating_v1 AND no fresh
@@ -560,12 +640,14 @@ done := (native done OR fresh gentle_done_v1) AND gentle_work_v1
560
640
  marker still covers; a fresh marker, any roles, or a working
561
641
  principal veto terminal (queued cover, pending-launch hint).
562
642
  The producer's finish token is the reachable path (the host
563
- never emits done); its expiry is the hold, so `done` recedes
564
- to `idle` when it lapses and is never skipped in between
643
+ never emits done); the daemon holds `done` until it first
644
+ views the pane focused (one DONE_VIEW_DWELL_MS dwell) or the
645
+ unseen cap lapses, so `done` recedes to `idle` then and is
646
+ never skipped in between
565
647
  idle := otherwise (native fallback; also all-gentle-tokens-missing-or-expired)
566
648
  ```
567
649
 
568
- Priority: `error > ask > review > done > blockingRole > principal working > role > orchestrating > working(main) > idle`.
650
+ Priority: `error > ask > review > done > blockingRole > principal working > role > orchestrating > generic > idle`.
569
651
  `done` is matched before the principal/role branches in the reducer; it is
570
652
  listed here below the activity branches only so its settled-and-empty
571
653
  precondition reads together.
@@ -574,11 +656,15 @@ precondition reads together.
574
656
  (error/ask/review) and the terminal `done` state always outrank principal
575
657
  status and activity roles. Below them the principal's own activity decides,
576
658
  never the delegate count and never the aggregate native status: a **working
577
- principal** renders `gentle` (pink
578
- `orchestrating` while a fresh root marker is live) and outranks every
579
- delegate role word; an **idle principal** shows the oldest running role word
659
+ principal** renders the pink `gentle` (machine key `orchestrating`, fresh
660
+ root marker or not) and outranks every delegate role word; an **idle
661
+ principal** shows the oldest running role word
580
662
  (`explorer`, `worker`, `verify`, `judge`, or `rdd` when it is the oldest)
581
- however many delegates run. The one exception sits between them and is
663
+ however many delegates run, and falls back to that same pink `gentle` when a
664
+ running delegate has no resolvable name (that row is not idle: a delegate
665
+ runs). A live count-0 work token asserts no activity: it reaches `done` only
666
+ through the terminal gate above, otherwise `idle`, so `gentle` never renders
667
+ on an idle session. The one exception sits between them and is
582
668
  evidence-based, never a precedence guess: while a **synchronous**
583
669
  `subagent_run`/`subagent_continue` call is in flight the principal's own turn
584
670
  is blocked on the child, so the fresh `gentle_pending_v1` role word decides
@@ -589,8 +675,8 @@ signal (it stays live while the principal is idle with queued or running
589
675
  delegates), so it never outranks a role word. An in-flight attention `review`
590
676
  (fresh `review:` label or durable `gentle_review_v1` token) overrides the
591
677
  role list; a settled session renders `done` even against a stale-fresh
592
- marker, and only after the minted finish hold lapses does it recede to
593
- `idle` (§4.3).
678
+ marker, and only after the pane has been viewed for one dwell, or its unseen
679
+ cap has lapsed, does it recede to `idle` (§4.3).
594
680
 
595
681
  ### 5.3 Publication (sidebar tokens)
596
682
 
@@ -606,10 +692,13 @@ marker, and only after the minted finish hold lapses does it recede to
606
692
  The visible second row is structural, with no rules: the eleven
607
693
  presence-encoded
608
694
  `gentle_title_<working|orchestrating|explorer|worker|verify|judge|ask|review|error|done|idle>`
609
- state tokens (state word only: `working` / `gentle` (machine key
695
+ state tokens (a state word only: `gentle` (pink, machine key
610
696
  `orchestrating`) / `explorer` / `worker` /
611
- `verify` / `judge` / `ask` / `blocked` / `done` / `idle` / `review`;
612
- role words carry a running-count suffix above one).
697
+ `verify` / `judge` / `ask` / `blocked` / `done` / `idle` / `review` — with
698
+ the one exception that the amber `working` cell carries a
699
+ non-contemplated subagent's own sanitized name, never the word `working`
700
+ and never `gentle`; role and name words carry a running-count suffix above
701
+ one).
613
702
  Only the current display's title token carries a value; the rest are null.
614
703
  Each state cell carries its state's semantic color as its base fg with
615
704
  no rules — working/worker golden `#f9e2af`, orchestrating pink fuchsia
@@ -625,13 +714,17 @@ marker, and only after the minted finish hold lapses does it recede to
625
714
  tokens plus the row-2 title and change-segment tokens to
626
715
  the pi-only `rows_by_agent` override (E10); exact block wiring is
627
716
  install configuration, not protocol.
628
- - Label shapes: `gentle` (generic activity, machine key `working` — the
629
- principal's own working state, as asserted by a fresh `gentle_principal_v1`,
630
- with or without delegated roles; also a positive count with no role word, or only
631
- unsalvageable role shapes) |
632
- `gentle` (user-facing word for the `orchestrating` machine key — fresh
633
- root-session marker while the principal works, with or without active
634
- delegation, even with zero subagents; pink palette unchanged) | `explorer` / `worker` / `verify` / `judge` (oldest
717
+ - Label shapes: exactly one `gentle` — pink `#f5c2e7`, machine key
718
+ `orchestrating`: the principal session's own working status (asserted by a
719
+ fresh `gentle_principal_v1`, with or without a fresh root marker and with
720
+ or without delegated roles) and its generic status (a positive running
721
+ count with no resolvable name, only unsalvageable role shapes, or a fresh
722
+ root-session marker covering queued/running subs and pending launches);
723
+ never rendered on an idle session | the amber `working` cell (`#f9e2af`)
724
+ carries a non-contemplated subagent's own sanitized name from
725
+ `gentle_roles_v1` / `gentle_pending_v1` — never the word `working` and
726
+ never `gentle`, so a bare `working` display fails closed to the pink
727
+ `gentle` | `explorer` / `worker` / `verify` / `judge` (oldest
635
728
  TaskStore role word while the principal itself is idle, however many
636
729
  delegates run) | `ask` | `rdd` (user-facing word for the `review`
637
730
  machine key; a delegated rdd and a tool-only review both render `rdd` —
@@ -782,7 +875,9 @@ gentle-ai concern and explicitly out of scope for this plugin.
782
875
  next landed beat resets the counter. The one real error leg — the run
783
876
  itself stopping on an error — is released by the next non-error beat
784
877
  (`agent_start`, any tool activity, or a non-error assistant message), never
785
- latched; no exception path ever stops the producer beat. While the leg
878
+ latched; no exception path ever stops the producer beat (a quiet producer
879
+ with no host truth and no work evidence ends its own bounded budget instead,
880
+ §4.5). While the leg
786
881
  stands it publishes the durable `gentle_error_v1` token on every beat, so
787
882
  an error the sidebar missed on one beat is repaired by the next, and the
788
883
  release beat clears it (the missed-beat discipline of the ask/review
@@ -881,7 +976,7 @@ report after a Pi restart or `/new` (both recreate the extension runtime)
881
976
  lose, freezing the pane's `agent_session` binding at the old session while
882
977
  the producer keeps beating for the new one — the consumer then rejects those
883
978
  fresh tokens as a session-hash mismatch and the pane stays on `idle` until a
884
- report with a higher seq lands. Parity contract: `working` carries the specific working role in the message (oldest running role word from the same roles resolution — known short word, unknown sanitized name, or `gentle` with no delegation; never bare generic `working`; machine keys unchanged); terminal `idle` only on a truly empty settle (principal settled plus zero running/queued plus zero pending plus zero live background jobs plus no human-wait prompt; settle-with-delegates/pending/jobs stays `working`, emitted once with no re-emit on repeat settles). Live background jobs come from Gentle Shell's own bus event `gentle-ai:jobs-sidebar` (`bash_background` / `monitor`), session-scoped and emitted on job edges only, so a snapshot counts only while it is fresh — a stale or foreign snapshot is zero jobs; an absent Gentle Shell simply reports none (today's behavior). Only an entry with no `status` is pending work: Gentle Shell keeps a finished job in the array as a result tail (`status: exited|stopped|failed`), and counting that tail is what pinned the row on the pink generic `gentle` — and blocked `done` — while the panel read no running job. One `unref()`-ed timer per live snapshot publishes a single beat at the instant the snapshot goes stale, so a missed exit event cannot leave the settle without a beat. While such a job waits with the principal settled and no delegate running or launching, the producer keeps the root marker live so the row stays on the pink generic `gentle` (§5.2) and the finish is held back; the wait ends on the beat the principal resumes, a delegate starts, the last job ends, or the snapshot ages past its staleness bound. `blocked` only for an actual human-wait intervention leg with its label (review/RDD execution stays `working`, silent); an error never claims native `blocked` — while our `error:` label stands the pane reports `working`, the only native state that raises no host attention, and returns to the lifecycle state on the next non-error beat. The native status keeps its aggregate meaning (it reads `working` while any delegate runs, which is what Herdr's own pane state means): the sidebar row's working-vs-idle decision reads the principal-only `gentle_principal_v1` instead (§5.2), so an idle principal with a running delegate shows the delegate role word rather than `gentle`. Single publisher by design: the managed native extension file is excluded
979
+ report with a higher seq lands. Parity contract: `working` carries the specific working role in the message (oldest running role word from the same roles resolution — known short word, unknown sanitized name, or the pink generic `gentle` with no delegation; never bare generic `working`; machine keys unchanged); terminal `idle` only on a truly empty settle (principal settled plus zero running/queued plus zero pending plus zero live background jobs plus no human-wait prompt; settle-with-delegates/pending/jobs stays `working`, emitted once with no re-emit on repeat settles). A settle the producer missed is recovered from the host's own live truth: a beat with nothing active and no work evidence reconciles `settled` from `isIdle()`, a quiet producer the host never answers stops beating after a bounded budget instead of republishing a count-0 work token forever, and only an observed turn mints `done`, so a reconciled settle announces nothing. Live background jobs come from Gentle Shell's own bus event `gentle-ai:jobs-sidebar` (`bash_background` / `monitor`), session-scoped and emitted on job edges only, so a snapshot counts only while it is fresh — a stale or foreign snapshot is zero jobs; an absent Gentle Shell simply reports none (today's behavior). Only an entry with no `status` is pending work: Gentle Shell keeps a finished job in the array as a result tail (`status: exited|stopped|failed`), and counting that tail is what pinned the row on the pink generic `gentle` — and blocked `done` — while the panel read no running job. One `unref()`-ed timer per live snapshot publishes a single beat at the instant the snapshot goes stale, so a missed exit event cannot leave the settle without a beat. While such a job waits with the principal settled and no delegate running or launching, the producer keeps the root marker live so the row stays on the pink generic `gentle` (§5.2) and the finish is held back; the wait ends on the beat the principal resumes, a delegate starts, the last job ends, or the snapshot ages past its staleness bound. `blocked` only for an actual human-wait intervention leg with its label (review/RDD execution stays `working`, silent); an error never claims native `blocked` — while our `error:` label stands the pane reports `working`, the only native state that raises no host attention, and returns to the lifecycle state on the next non-error beat. The native status keeps its aggregate meaning (it reads `working` while any delegate runs, which is what Herdr's own pane state means): the sidebar row's working-vs-idle decision reads the principal-only `gentle_principal_v1` instead (§5.2), so an idle principal with a running delegate shows that delegate's own role word or name rather than the principal's `gentle`. Single publisher by design: the managed native extension file is excluded
885
980
  reversibly (`-extensions/herdr-agent-state.ts` in Pi settings, bytes
886
981
  preserved on disk, never auto-loaded next to ours). `node
887
982
  bin/gentle-sidebar.js (enable|disable|status|toggle)` selects the
@@ -1022,9 +1117,11 @@ exactly one mechanism writes each piece of state.
1022
1117
  marker, read from local git plus `agent.list` — plus the presence prefix,
1023
1118
  because Herdr emits no event for either. That is why the fast cycle is armed
1024
1119
  by a rendered non-idle display, and why polling is never removed.
1025
- The sleep is also capped at the nearest live `gentle_done_v1` expiry among
1120
+ The sleep is also capped at the nearest live `gentle_done_v1` expiry AND the
1121
+ nearest pending view-dwell deadline (`DONE_VIEW_DWELL_MS`) among
1026
1122
  the panes just rendered (never below the 250 ms floor), so a held `done`
1027
- row reaches `idle` when the hold lapses rather than up to one poll later.
1123
+ row reaches `idle` when the cap or the dwell lapses rather than up to one
1124
+ poll later.
1028
1125
  A pending expiry may only SHORTEN the delay: with no pending expiry the
1029
1126
  delay is exactly the adaptive value above, and an already-expired or
1030
1127
  unparseable value falls to the floor (fail closed, like every parser)
@@ -1054,7 +1151,10 @@ exactly one mechanism writes each piece of state.
1054
1151
  user-facing value is `blocked` (§5.3). `gentle_title_review` likewise
1055
1152
  keeps its machine-key-derived token name; only its user-facing value is
1056
1153
  now `rdd` (aligned from `review` by the native-owner T1). `gentle_title_orchestrating` likewise keeps its machine-key-derived
1057
- token name; only its user-facing value is `gentle`. The retired `*_working_subs` token family (the old `working (n)`
1154
+ token name; only its user-facing value is `gentle`. `gentle_title_working`
1155
+ likewise keeps its machine-key-derived token name; its user-facing value is
1156
+ a non-contemplated subagent's own sanitized name, never the word `working`.
1157
+ The retired `*_working_subs` token family (the old `working (n)`
1058
1158
  count display) is swept, never written.
1059
1159
  - Coexistence: `herdr-pi-tree` stays installed but disabled for gentle-owned
1060
1160
  panes (O1). No uninstall, no token migration, no dual-run merge — ownership