herdr-gentle-shell 1.5.0 → 1.5.2

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
 
@@ -201,13 +205,13 @@ Sidecar only: ships beside `herdr-agent-state.ts`, never modifies it.
201
205
 
202
206
  | Producer event (source) | Tokens written | v1 state contribution |
203
207
  |---|---|---|
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 |
208
+ | `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 |
205
209
  | 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 |
206
210
  | `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
211
  | 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
212
  | 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
213
  | 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` |
214
+ | `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
215
  | `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
216
 
213
217
  `waiting`/`finished` TaskStore entries never count as active, and `queued`
@@ -234,11 +238,12 @@ exact `gentle-ai-worker` → `worker`, exact `gentle-ai-verify` → `verify`,
234
238
  `jd-fix-` families) → the distinct `judge` slug (never `rdd`), and a
235
239
  review agent / `gentle-ai-review*` / any role containing `review` → `rdd`;
236
240
  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`).
241
+ slug, 32-char bound — never a generic collapse; unsalvageable shapes and the
242
+ reserved slugs `gentle`, `working`, and `subagent` read
243
+ the pink generic `gentle`, machine key `orchestrating`).
239
244
  The consumer displays the oldest role word (known short word or unknown
240
245
  sanitized name) whenever the principal itself is not working, regardless of
241
- how many delegates run; a working principal renders `gentle` instead.
246
+ how many delegates run; a working principal renders the pink `gentle` instead.
242
247
  Role labels carry the total running-delegate count in parentheses when greater
243
248
  than one. Role order is immutable first-seen (progress reads never reorder;
244
249
  sound same-session presence createdAt/startedAt may correct a late local
@@ -250,7 +255,8 @@ flight with no TaskStore record until it returns `tool_result`, so the exact
250
255
  agent name in the pending `tool_call` input is the only live role evidence;
251
256
  counting it would inflate the normative `gentle_work_v1` total with an
252
257
  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
258
+ sidebar on the active role (`worker`, never the amber `working` cell —
259
+ generic activity reads the pink `gentle`) with the count
254
260
  authoritative at 0. The hint merges with authoritative active TaskStore roles
255
261
  (oldest-first) and clears when the tool result arrives, the call is
256
262
  cancelled, or the agent settles. On a tool
@@ -264,7 +270,7 @@ launch outcomes keep `running` (and its agent) against `queued`/`waiting`/
264
270
  re-resolve oldest-first — so a working principal with live delegates keeps
265
271
  `gentle`, and a settle with running delegates keeps the oldest role word
266
272
  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
273
+ `working` degrades to no role (the pink generic `gentle`) on both the producer
268
274
  (`agentToRole`) and the consumer (`roleToDisplay`) sides. No local
269
275
  age/staleness timeout is applied — Gentle Shell owns lifecycle/status truth.
270
276
  Finished/failed/cancelled records may linger in the map but never count;
@@ -276,10 +282,11 @@ coverage while the authoritative active list is non-empty or any
276
282
  once the main session settles — settled, or any non-root session. The marker carries no
277
283
  count and changes neither the work total nor the roles CSV: it is a pure
278
284
  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.
285
+ gentle_work_v1) that the consumer reduces to the same pink `gentle` the
286
+ principal's own activity renders, only with no role word above it (§5.2):
287
+ below attention (error/ask/review), terminal `done`/native-`blocked`, and
288
+ role words; ahead of the positive-count generic fallback only, which renders
289
+ that same pink `gentle`.
283
290
  The root session also emits `gentle_principal_v1` while its own agent is
284
291
  active (`agentActive`) and clears it (null) the moment the principal
285
292
  settles, keeping the same binding/TTL discipline. This is the principal-only
@@ -290,7 +297,7 @@ principal itself works. The native status keeps that aggregate meaning for
290
297
  Herdr's own pane state; the row's working-vs-idle decision reads only
291
298
  `gentle_principal_v1` (§5.2). It carries no count and alters neither the work
292
299
  total nor the roles CSV. `agentActive` alone would render that blocked call
293
- as generic `gentle`.
300
+ as the pink generic `gentle`.
294
301
  The root session additionally emits `gentle_pending_v1` (`<hash>:<role>:<exp>`)
295
302
  while a synchronous (task mode) `subagent_run`/`subagent_continue` tool call
296
303
  is still in flight: such a call blocks the principal's own turn, so the
@@ -326,7 +333,10 @@ role = "explorer" / "worker" / "verify" / "judge" / "rdd" / passthrou
326
333
  ; stays distinct, never `rdd`)
327
334
  ; passthrough = 1*32 lowercase [a-z0-9_-], leading [a-z0-9]
328
335
  ; (unknown delegation keeps its sanitized original name —
329
- ; never a generic collapse; producer truncates to 32)
336
+ ; never a generic collapse; producer truncates to 32;
337
+ ; the reserved words `gentle`, `working`, and `subagent`
338
+ ; resolve to no role on both sides — producer and reducer —
339
+ ; so they degrade to the pink generic `gentle`)
330
340
  gentle_roles_v1 = role *("," role) ; total <= 512 UTF-8 bytes; null (clear)
331
341
  ; when no delegation is active (no role words)
332
342
  gentle_orchestrating_v1 = sessionHash ":" expiry
@@ -435,17 +445,19 @@ explorers with count 3 → `explorer (3)`; 5 files
435
445
  `● myproj +110 -22` (` +` green for added, ` -` red for deleted with a
436
446
  leading-space match, zero `·` separators because exactly one heading cell
437
447
  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.
448
+ A review label renders `rdd` with a blue `●` (`#89b4fa`, same as explorer/pull). A
449
+ `gentle_orchestrating_v1` marker renders the pink `gentle` (machine display
450
+ key `orchestrating`, pink palette unchanged): it covers the principal's
451
+ queued/running subs and pending launches, and it yields to a delegate role
452
+ word and to attention (`ask`/`review`/`blocked`) and terminal `done` states.
453
+ The marker is not a principal-working signal: it stays live while the
454
+ principal is idle with queued or running delegates, so it never decides the
455
+ working state. That state comes from `gentle_principal_v1` alone, and it is
456
+ the same pink `gentle` with or without a fresh root marker: the amber
457
+ `working` cell is never the principal's own. With no fresh principal marker
458
+ the pane shows the oldest role word, the pink generic `gentle` when a running
459
+ delegate has no resolvable name, or `idle` — but never an amber generic
460
+ because delegates run.
449
461
 
450
462
  ### 4.5 Publication and chunking
451
463
 
@@ -470,6 +482,27 @@ principal marker the pane shows the oldest role word (or `idle`), never
470
482
  - Writes are idempotent full-state snapshots per pane (all gentle tokens
471
483
  re-emitted each beat), never deltas — a lost report is repaired by the next
472
484
  beat.
485
+ - The producer beats every 15 s by default; `GENTLE_HERDR_BEAT_MS` overrides
486
+ the cadence for tests and debugging (clamped to [100, 300000]). The
487
+ override changes no TTL: the write horizon stays `now+60000` (§8).
488
+ - Every beat first reconciles the settle from the host's own live truth: with
489
+ no turn active and no work evidence (no running/queued delegate, no pending
490
+ launch, no live background job), the retained context's `isIdle()` flips
491
+ `settled`, so a run whose `agent_settled` never reached the producer still
492
+ reaches native `idle` instead of republishing a fresh count-0 work token
493
+ forever. A turn this producer saw start is never overridden from there.
494
+ When the host offers no truth at all, a producer that observed no turn stops
495
+ beating after a bounded budget (three beats) instead of publishing a native
496
+ state the host never confirmed; a turn this producer saw start is never
497
+ bounded, so the budget cannot trade a truthful `working` for a false `idle`
498
+ on a host with no truth to settle on. The beat is re-armed by the edges that
499
+ schedule a publish (ask, review, launch, session changes, jobs), while an
500
+ ordinary tool edge reaches the row through the host's own truth rather than
501
+ by re-arming it. A settle recovered this way is not an observed turn, so it
502
+ mints no `gentle_done_v1` and sends no finish notification.
503
+ - The settle-time pending latch (`pendingCount`) is bounded by the finish hold
504
+ of the settle that raised it: past that hold a launch that never reports
505
+ back stops counting, so it cannot pin the native report at `working`.
473
506
  - Session-change tokens are refreshed/cleared from the current Gentle Shell
474
507
  session model every beat and never carried across sessions: zero changed
475
508
  files publishes a clear (null over socket metadata, `--clear-token <name>`
@@ -532,17 +565,20 @@ blockingRole := fresh gentle_pending_v1 (session-bound, TTL-fresh) whose
532
565
  principalWorking := fresh gentle_principal_v1 (session-bound, TTL-fresh) —
533
566
  the principal's OWN activity, never the delegate count and
534
567
  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
568
+ any running delegate or pending launch); renders the pink
569
+ `gentle` (machine key `orchestrating`) with or without a
570
+ fresh gentle_orchestrating_v1; outranks every delegate role
538
571
  word; stale, foreign, or absent falls through to the
539
572
  branches below
540
573
  role := gentle_work_v1 fresh AND gentle_roles_v1 yields a
541
574
  recognized role (oldest first, incl. the in-flight pending
542
575
  role hint at count = 0 for task-mode launches with no
543
576
  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.
577
+ delegate word wins. A non-contemplated subagent renders on
578
+ the `working` display, whose label is that subagent's own
579
+ sanitized name (never `gentle`). Role and name labels append
580
+ the total when at least two delegates run. Tool-only review
581
+ has no suffix.
546
582
  orchestrating := gentle_orchestrating_v1 fresh with no role word above
547
583
  (root-only per §4.2: fresh while the main session actively
548
584
  works, even with zero subagents, retaining running/queued-sub,
@@ -550,8 +586,11 @@ orchestrating := gentle_orchestrating_v1 fresh with no role word above
550
586
  falls through to the
551
587
  branches below; attention, terminal `done`/native-`blocked`,
552
588
  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)
589
+ generic := gentle_work_v1 fresh AND count > 0 with no role word —
590
+ renders the pink `gentle` (machine key `orchestrating`), the
591
+ principal session's generic status; a count = 0 beat asserts
592
+ no activity — it reaches `done` only through the terminal
593
+ gate, otherwise `idle`
555
594
  done := (native done OR fresh gentle_done_v1) AND gentle_work_v1
556
595
  fresh with count = 0 (no running delegates) AND no roles AND
557
596
  no fresh gentle_orchestrating_v1 AND no fresh
@@ -565,7 +604,7 @@ done := (native done OR fresh gentle_done_v1) AND gentle_work_v1
565
604
  idle := otherwise (native fallback; also all-gentle-tokens-missing-or-expired)
566
605
  ```
567
606
 
568
- Priority: `error > ask > review > done > blockingRole > principal working > role > orchestrating > working(main) > idle`.
607
+ Priority: `error > ask > review > done > blockingRole > principal working > role > orchestrating > generic > idle`.
569
608
  `done` is matched before the principal/role branches in the reducer; it is
570
609
  listed here below the activity branches only so its settled-and-empty
571
610
  precondition reads together.
@@ -574,11 +613,15 @@ precondition reads together.
574
613
  (error/ask/review) and the terminal `done` state always outrank principal
575
614
  status and activity roles. Below them the principal's own activity decides,
576
615
  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
616
+ principal** renders the pink `gentle` (machine key `orchestrating`, fresh
617
+ root marker or not) and outranks every delegate role word; an **idle
618
+ principal** shows the oldest running role word
580
619
  (`explorer`, `worker`, `verify`, `judge`, or `rdd` when it is the oldest)
581
- however many delegates run. The one exception sits between them and is
620
+ however many delegates run, and falls back to that same pink `gentle` when a
621
+ running delegate has no resolvable name (that row is not idle: a delegate
622
+ runs). A live count-0 work token asserts no activity: it reaches `done` only
623
+ through the terminal gate above, otherwise `idle`, so `gentle` never renders
624
+ on an idle session. The one exception sits between them and is
582
625
  evidence-based, never a precedence guess: while a **synchronous**
583
626
  `subagent_run`/`subagent_continue` call is in flight the principal's own turn
584
627
  is blocked on the child, so the fresh `gentle_pending_v1` role word decides
@@ -606,10 +649,13 @@ marker, and only after the minted finish hold lapses does it recede to
606
649
  The visible second row is structural, with no rules: the eleven
607
650
  presence-encoded
608
651
  `gentle_title_<working|orchestrating|explorer|worker|verify|judge|ask|review|error|done|idle>`
609
- state tokens (state word only: `working` / `gentle` (machine key
652
+ state tokens (a state word only: `gentle` (pink, machine key
610
653
  `orchestrating`) / `explorer` / `worker` /
611
- `verify` / `judge` / `ask` / `blocked` / `done` / `idle` / `review`;
612
- role words carry a running-count suffix above one).
654
+ `verify` / `judge` / `ask` / `blocked` / `done` / `idle` / `review` — with
655
+ the one exception that the amber `working` cell carries a
656
+ non-contemplated subagent's own sanitized name, never the word `working`
657
+ and never `gentle`; role and name words carry a running-count suffix above
658
+ one).
613
659
  Only the current display's title token carries a value; the rest are null.
614
660
  Each state cell carries its state's semantic color as its base fg with
615
661
  no rules — working/worker golden `#f9e2af`, orchestrating pink fuchsia
@@ -625,13 +671,17 @@ marker, and only after the minted finish hold lapses does it recede to
625
671
  tokens plus the row-2 title and change-segment tokens to
626
672
  the pi-only `rows_by_agent` override (E10); exact block wiring is
627
673
  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
674
+ - Label shapes: exactly one `gentle` — pink `#f5c2e7`, machine key
675
+ `orchestrating`: the principal session's own working status (asserted by a
676
+ fresh `gentle_principal_v1`, with or without a fresh root marker and with
677
+ or without delegated roles) and its generic status (a positive running
678
+ count with no resolvable name, only unsalvageable role shapes, or a fresh
679
+ root-session marker covering queued/running subs and pending launches);
680
+ never rendered on an idle session | the amber `working` cell (`#f9e2af`)
681
+ carries a non-contemplated subagent's own sanitized name from
682
+ `gentle_roles_v1` / `gentle_pending_v1` — never the word `working` and
683
+ never `gentle`, so a bare `working` display fails closed to the pink
684
+ `gentle` | `explorer` / `worker` / `verify` / `judge` (oldest
635
685
  TaskStore role word while the principal itself is idle, however many
636
686
  delegates run) | `ask` | `rdd` (user-facing word for the `review`
637
687
  machine key; a delegated rdd and a tool-only review both render `rdd` —
@@ -782,7 +832,9 @@ gentle-ai concern and explicitly out of scope for this plugin.
782
832
  next landed beat resets the counter. The one real error leg — the run
783
833
  itself stopping on an error — is released by the next non-error beat
784
834
  (`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
835
+ latched; no exception path ever stops the producer beat (a quiet producer
836
+ with no host truth and no work evidence ends its own bounded budget instead,
837
+ §4.5). While the leg
786
838
  stands it publishes the durable `gentle_error_v1` token on every beat, so
787
839
  an error the sidebar missed on one beat is repaired by the next, and the
788
840
  release beat clears it (the missed-beat discipline of the ask/review
@@ -804,6 +856,10 @@ gentle-ai concern and explicitly out of scope for this plugin.
804
856
  the poll after the native one for the same question, a systematic
805
857
  duplication. The ask token still drives the sidebar ask display; sounds,
806
858
  suppression, and delay stay Herdr's.
859
+ - Herdr's own done/ask attention — the finished and needs-attention pop-ups and
860
+ their sound — is Herdr's native behavior, configured in Herdr itself (its
861
+ config and its settings). This package deliberately offers no switch for it;
862
+ its only notification surface is the optional Moshi channel.
807
863
  - `review` and `error` never emit a plugin notification: `review` attention
808
864
  stays in-flow/native; `error` is sidebar state only — our own `error:` label
809
865
  with the pane left on native `working`, so neither the `NeedsAttention`
@@ -877,7 +933,7 @@ report after a Pi restart or `/new` (both recreate the extension runtime)
877
933
  lose, freezing the pane's `agent_session` binding at the old session while
878
934
  the producer keeps beating for the new one — the consumer then rejects those
879
935
  fresh tokens as a session-hash mismatch and the pane stays on `idle` until a
880
- 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
936
+ 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
881
937
  reversibly (`-extensions/herdr-agent-state.ts` in Pi settings, bytes
882
938
  preserved on disk, never auto-loaded next to ours). `node
883
939
  bin/gentle-sidebar.js (enable|disable|status|toggle)` selects the
@@ -1050,7 +1106,10 @@ exactly one mechanism writes each piece of state.
1050
1106
  user-facing value is `blocked` (§5.3). `gentle_title_review` likewise
1051
1107
  keeps its machine-key-derived token name; only its user-facing value is
1052
1108
  now `rdd` (aligned from `review` by the native-owner T1). `gentle_title_orchestrating` likewise keeps its machine-key-derived
1053
- token name; only its user-facing value is `gentle`. The retired `*_working_subs` token family (the old `working (n)`
1109
+ token name; only its user-facing value is `gentle`. `gentle_title_working`
1110
+ likewise keeps its machine-key-derived token name; its user-facing value is
1111
+ a non-contemplated subagent's own sanitized name, never the word `working`.
1112
+ The retired `*_working_subs` token family (the old `working (n)`
1054
1113
  count display) is swept, never written.
1055
1114
  - Coexistence: `herdr-pi-tree` stays installed but disabled for gentle-owned
1056
1115
  panes (O1). No uninstall, no token migration, no dual-run merge — ownership
package/README.md CHANGED
@@ -6,21 +6,23 @@ Local Herdr plugin so the sidebar recognises Pi + Gentle Shell agents.
6
6
 
7
7
  ## What It Does
8
8
 
9
- Reports per-pane agent state (`gentle` for generic activity — machine key
10
- `working` — e.g. the orchestrator/main agent when settled with no fresh
11
- root marker; `gentle` in pink while the principal
12
- session actively works — even with zero
13
- subagents — (machine display key
14
- `orchestrating`, pink palette unchanged). The principal's own activity marker
15
- (`gentle_principal_v1`, published while the principal session itself works and
16
- cleared when it settles) decides the row — never the delegate count, and
17
- never Herdr's aggregate native status (which reads `working` whenever any
18
- delegate runs): the default is still the principal's own state, so while the
19
- principal works its own turn it reads `gentle` and no delegate role word
20
- wins; while the principal is idle
21
- the oldest running delegate role shows — `explorer`, `worker`, `verify`,
22
- `judge`, `rdd` — with the total running count in parentheses when two or
23
- more subagents run, for example `explorer (3)`). The single exception is a
9
+ Reports per-pane agent state (exactly one user-facing `gentle` — pink
10
+ `#f5c2e7`, machine key `orchestrating`: the principal session's own working
11
+ status and its generic status; a non-contemplated subagent renders its own
12
+ sanitized name on the amber `working` cell `#f9e2af` — never the word
13
+ `working`, never `gentle` — and a recognized gentle role keeps its
14
+ abbreviation — `explorer`, `worker`,
15
+ `verify`, `judge`, `rdd` — with the total running count in parentheses when
16
+ two or more subagents run, for example `explorer (3)`). The principal's own
17
+ activity marker (`gentle_principal_v1`, published while the principal session
18
+ itself works and cleared when it settles) decides the row — never the
19
+ delegate count, and never Herdr's aggregate native status (which reads
20
+ `working` whenever any delegate runs): the default is still the principal's
21
+ own state, so while the principal works its own turn it reads pink `gentle`,
22
+ with or without a fresh root marker, and no delegate word wins; while the
23
+ principal is idle the oldest running delegate role shows, or that subagent's
24
+ own name when no role word is recognized. `gentle` never renders on an idle
25
+ session. The single exception is a
24
26
  blocking synchronous subagent call (`gentle_pending_v1`): a task-mode
25
27
  `subagent_run`/`subagent_continue` holds the principal's turn open until the
26
28
  child returns, so the principal is waiting on that child rather than working
@@ -214,8 +216,10 @@ sidebar-only, DESIGN §7; it rides the durable session-bound
214
216
  `gentle_error_v1` token, republished on every beat while the run-error leg
215
217
  stands and cleared the beat it releases, so a beat the sidebar missed is
216
218
  repaired by the next one); the orchestrating
217
- leg renders the user-facing word `gentle` (machine key stays
218
- `orchestrating`, pink `#f5c2e7`). Remaining state colors:
219
+ leg renders the one user-facing `gentle` (machine key stays
220
+ `orchestrating`, pink `#f5c2e7`), while the `working` leg (amber `#f9e2af`)
221
+ carries a non-contemplated subagent's own sanitized name and never renders
222
+ the word `gentle` or `working`. Remaining state colors:
219
223
  working/worker amber `#f9e2af`, explorer blue `#89b4fa`, verify teal
220
224
  `#94e2d5`, ask orange `#fab387`, error red `#f38ba8`, done green `#a6e3a1`,
221
225
  idle grey `#7c7f93`. Added stays green and deleted stays red; the mapping
@@ -250,26 +254,34 @@ unavailable counts (unavailable files stay in the file count with 0/0); `↑N` s
250
254
  branch is behind its upstream (branch-ab status only, no diff). `gentle_project`,
251
255
  `gentle_changes_summary`, and the segment
252
256
  tokens (`gentle_changes_added`/`_deleted`/`_pull`) stay published for
253
- compatibility but render no visible row. `gentle`
254
- renders for generic activity (machine key `working`): the main agent when settled with no fresh root marker or roles
255
- (or active subs with an unsalvageable role shape and no fresh marker); pink
256
- `gentle` (machine key `orchestrating`, pink palette unchanged) renders while the principal session actively works — even with zero subagents —
257
- retaining running-subagent or pending-launch coverage. The principal's own
257
+ compatibility but render no visible row. Pink `gentle` (machine key
258
+ `orchestrating`, pink palette unchanged) is the
259
+ only user-facing `gentle`: it renders while the principal session actively
260
+ works — even with zero subagents, with or without a fresh root marker — and
261
+ as its generic status when a running delegate has no resolvable name, when
262
+ only unsalvageable role shapes remain, or when the root marker covers a
263
+ queued/running sub or a pending launch; it never renders on an idle session.
264
+ A non-contemplated subagent renders its own sanitized name on the amber
265
+ `working` cell instead, and a recognized gentle role keeps its abbreviation
266
+ (`explorer`, `worker`, `verify`, `judge`, `rdd`). The principal's own
258
267
  activity decides the row, never the delegate count and never Herdr's
259
268
  aggregate native status (the work token counts running delegates, and the
260
269
  native status reads `working` for any running delegate or pending launch — so
261
270
  neither can say the principal works): the dedicated
262
271
  `gentle_principal_v1` marker is published while the principal session itself
263
272
  works and cleared when it settles. That is the default: a **working
264
- principal** reads `gentle` — pink
265
- `orchestrating` while a fresh root marker is live — and no delegate role word
273
+ principal** reads the pink `gentle` — machine key `orchestrating`, fresh root
274
+ marker or not — and no delegate role word
266
275
  wins; an **idle principal** shows the oldest running TaskStore role
267
276
  (`explorer`, `worker`, `verify`, `judge`, `rdd`), however many delegates run.
268
277
  The one exception is a blocking synchronous subagent call: while a task-mode
269
278
  `subagent_run`/`subagent_continue` is in flight the principal's own turn is
270
279
  blocked on the child, so the producer publishes that child's role in
271
280
  `gentle_pending_v1` and it renders instead of `gentle`, for as long as the
272
- call lasts. Background launches resolve their tool call immediately, so a
281
+ call lasts. A resume (`subagent_continue`) carries no agent, so its role is
282
+ the tracked task record's agent for its `task_id`; when neither the input nor
283
+ a record names one, the call publishes no role and the row keeps its generic
284
+ display. Background launches resolve their tool call immediately, so a
273
285
  queued or running background delegate publishes no such marker and leaves
274
286
  the principal's own display untouched. These yield to `ask`/`rdd`/`blocked`
275
287
  and terminal `done` — where `done` needs
@@ -281,15 +293,17 @@ work total is a direct projection of the
281
293
  Gentle Shell TaskStore `running` records (only `running` counts as
282
294
  executing; queued/waiting never count), never a calculated
283
295
  pending-call estimate: pending tool calls are role-only display hints (exact
284
- in-flight subagent agent -> role slug, so task-mode launches show the active
296
+ in-flight subagent agent -> role slug, resolved from the tool input or, for a
297
+ resume, from the tracked task record, so task-mode launches show the active
285
298
  role even at count 0) plus label correlation, and
286
299
  true concurrent tasks all count. A live `running` record is never regressed
287
300
  by a racy non-final status read (only the authoritative launch outcomes,
288
301
  completions, and presence terminals move it), so principal activity with
289
302
  live delegates keeps `gentle` while an idle principal keeps the role word; a
290
303
  sanitized unknown slug exactly
291
- equal to `working` degrades to `gentle` (the bare word `working` never
292
- renders).
304
+ equal to `working` or `subagent` degrades to the pink `gentle` (neither bare word ever
305
+ renders; `subagent` is the producer's launch-correlation placeholder, never
306
+ an agent name).
293
307
  Background launches (`subagent_run` with `mode: background`) announce
294
308
  lifecycle over `message_end` custom results: an ACTIVE status promotes the
295
309
  start into the tasks map like a task-mode record, so an active background
@@ -318,10 +332,13 @@ herdr server reload-config
318
332
  Live check: with the daemon running and the override applied, open a Pi pane
319
333
  and confirm row 2 shows pink `gentle` (machine key
320
334
  `orchestrating`) while
321
- the principal session actively works — even with zero subagents — and keeps
322
- `gentle` while its delegates run (a role word such as `worker`, `explorer`,
323
- `verify`, `judge` shows once the principal itself is idle — and also while a
324
- task-mode subagent call blocks the principal's turn, until it returns), row 1
335
+ the principal session actively works — even with zero subagents, and with or
336
+ without a fresh root marker — and keeps `gentle` while its delegates run (a
337
+ role word such as `worker`, `explorer`,
338
+ `verify`, `judge`, or a non-contemplated subagent's own name in amber, shows
339
+ once the principal itself is idle — and also while a
340
+ task-mode subagent call blocks the principal's turn, until it returns), that
341
+ a row never reads `gentle` on an idle pane; row 1
325
342
  shows the single heading cell (`● <project>` plus ` +N`/` -N`/` ↑N` inline, zero `·`) after edits / when behind upstream; then `ask` on an open
326
343
  question (choice / native-questionnaire / legacy event legs, executed `ask_user_question`/`ask_user_choice`, tool-gated `ui_prompt` dialog spans (a `custom` panel — agents view, ODD viewer, changes view, design canvas — never counts, because opening a panel is navigation, not a question), or permission waiting; `gentle_review` starts never speculate ask, and no failed tool ever does either: a tool error changes nothing, see the error rule below). `rdd` (machine key `review`) applies during acknowledged native capture/group execution only (`reviewerRunAcknowledged: true` at execution start — never proposal, never forecast-only, never `correctionLines` planning, never `gentle_review`/`gentle_review_scope` in any operation; no hook/sidebar signal observed; unknown legacy shapes stay dark; call-id tracked so thrown/cancelled calls still clear, read-only `assess` excluded). Bounded approximation: the acknowledged interval contains preparation and admission; no exact reviewer internal events exist today. The orchestrator-host `ask_user_choice` prompt emits no Pi tool/event observable by this extension and stays covered only by the event legs above. Never point the fixture commands at the live config: keep
327
344
  `HERDR_CONFIG_PATH` on a temp file for apply/uninstall checks.
@@ -348,7 +365,10 @@ coalesced refresh after every landed token beat, so a status change
348
365
  it publishes is drawn at once, and the daemon caps each sleep at the nearest
349
366
  live `done` expiry, so a settled row reaches `idle` when its short hold (5 s by
350
367
  default, `GENTLE_HERDR_DONE_HOLD_MS`-overridable) lapses instead of one poll
351
- later. Reports in one window collapse into one frame, and refresh-driven frames
368
+ later. The producer's own beat is 15 s by default and
369
+ `GENTLE_HERDR_BEAT_MS`-overridable for tests and debugging (clamped to
370
+ [100, 300000]); the override changes the cadence only, never the 60 s token
371
+ TTL. Reports in one window collapse into one frame, and refresh-driven frames
352
372
  are floored at 250 ms, so a burst can never spin the daemon. Polling stays the
353
373
  fallback for every lifecycle signal and the only source for what no Herdr event
354
374
  carries (the git-derived `+N/-N` and `↑N` row data and the presence prefix), so a
@@ -362,10 +382,12 @@ See [DESIGN.md](DESIGN.md) §4 (producer) and §5 (consumer), and
362
382
  ## Key Features You Should Know About
363
383
 
364
384
  - Full v1 state matrix including the root-session `orchestrating` marker
365
- (pink `●` + user-facing word `gentle`, while the principal session actively
366
- works — even with zero subagents — retaining subagent/pending coverage;
367
- yielding only to `ask`/`rdd`/`blocked` and terminal `done` (done needs
368
- settled-plus-empty)) and the authoritative TaskStore role signal
385
+ (pink `●` + the one user-facing word `gentle`, the principal session's
386
+ working and generic status: it shows while the principal actively works —
387
+ even with zero subagents and with or without a fresh root marker — and
388
+ covers queued/running subagents and pending launches; yielding only to
389
+ `ask`/`rdd`/`blocked` and terminal `done` (done needs settled-plus-empty);
390
+ never on an idle session) and the authoritative TaskStore role signal
369
391
  (`explorer` / `worker` / `verify` / `judge` / `rdd` from `TaskRecord.agent`,
370
392
  oldest running first by immutable first-seen, shown while the principal
371
393
  itself is idle — a working principal's own turn keeps `gentle`, asserted by
@@ -374,10 +396,12 @@ See [DESIGN.md](DESIGN.md) §4 (producer) and §5 (consumer), and
374
396
  synchronous `subagent_run`/`subagent_continue` call holds the principal's
375
397
  turn open, so the in-flight child's role shows instead (the
376
398
  `gentle_pending_v1` role marker) until that call resolves, while a
377
- background delegate never takes that path; `gentle` (machine
378
- key `working`) for the principal's own working state; an unknown delegation
399
+ background delegate never takes that path; an unknown delegation
379
400
  keeps its original sanitized name, 32-char bound — never a generic
380
- collapse), with a running-count suffix on role labels when two or more
401
+ collapse (the reserved words `gentle`, `working`, and `subagent` are no name
402
+ and degrade to the pink generic) — and renders on the amber `working` cell,
403
+ which never carries the
404
+ word `gentle`), with a running-count suffix on role labels when two or more
381
405
  delegates run, `ask` on blocked user input,
382
406
  `rdd` during native review execution (machine key stays `review`; execution
383
407
  is silent — desktop attention fires only for a waiting `ask` intent, as
@@ -423,7 +447,7 @@ See [DESIGN.md](DESIGN.md) §4 (producer) and §5 (consumer), and
423
447
  nothing and logs one line per reason. The gs pane's own live state stays
424
448
  unobservable until the isolated install forwards `HERDR_ENV` to its agent (a
425
449
  gentle-ai concern, out of scope here).
426
- - Gentle mode is enabled by default: while selected, this extension is the single publisher of native `pane.report_agent` (`working`/`blocked`/`idle`) alongside its metadata beats, with session path-or-id binding, monotonic seq, and a serial latest-wins coalesced queue. Parity contract: `working` carries the specific working role in the message (oldest running role word — known short word, unknown sanitized name, or `gentle` with no delegation; never bare generic `working`; machine keys unchanged); terminal `idle` fires 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). Live background jobs (`bash_background` / `monitor`) are read from Gentle Shell's session-scoped `gentle-ai:jobs-sidebar` bus event, so waiting on a CI run or a long command keeps the row on `gentle` and never reaches `done`; `blocked` fires only for an actual human-wait intervention leg with its label (review/RDD execution stays `working`, silent). `blocked` is never derived from an error: native `blocked` is what fires the host's NeedsAttention toast and sound, so a failed run shows our own `error` state — the durable, session-bound `gentle_error_v1` token (republished every beat while the leg stands, cleared when it releases) that the sidebar reduces to the `error` row word — while the pane stays on `working`, and a failed tool call (or a delegate that ended `failed`, or a failed beat transport) changes nothing at all: it is detected and logged, never published, and never reaches the error token. The native status keeps its aggregate meaning — it reads `working` while any delegate runs — while the sidebar row's working-vs-idle decision reads the principal-only `gentle_principal_v1` marker, so an idle principal with a running delegate shows the delegate role word instead of `gentle`. Our code never emits `done`/`finished` native states or a Herdr notification (the opt-in Moshi replacement below is a separate, off-by-default channel): the host owns finished text on `done`, `blocked`/unknown presentation, sound, and all desktop attention toasts (ask + finish) — there is no consumer toast path left to dedup. Single publisher by design: the managed native extension file stays on disk and is excluded through an ownership-bound Pi settings entry while Gentle mode is selected. `node bin/gentle-sidebar.js disable` removes only our owned exclusion and managed rows, gates our producer/daemon, and hands the sidebar back to the native publisher (running Pi sessions need `/reload`); never run both publishers on the same pane. Limits (unverified, host-owned): the host `idle`→`done`→`finished` mapping and unknown-state handling are owned by Herdr.
450
+ - Gentle mode is enabled by default: while selected, this extension is the single publisher of native `pane.report_agent` (`working`/`blocked`/`idle`) alongside its metadata beats, with session path-or-id binding, monotonic seq, and a serial latest-wins coalesced queue. Parity contract: `working` carries the specific working role in the message (oldest running role word — known short word, unknown sanitized name, or the pink generic `gentle` with no delegation; never bare generic `working`; machine keys unchanged); terminal `idle` fires 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). A settle is reconciled from the host's own live truth (`isIdle()`) whenever nothing is active and no work evidence remains, so a run whose settle never reached the producer still reaches `idle` instead of freezing the pane on native `working`; a quiet producer the host never answers stops beating after a bounded budget instead of republishing a count-0 work token forever — but only when it observed no turn, while a turn it saw start keeps beating so the budget never trades a truthful `working` for a false `idle` on a truth-less host; the beat is re-armed by the edges that schedule a publish (ask, review, launch, session changes, jobs), while an ordinary tool edge reaches the row through the host's own truth rather than by re-arming it; the settle-time pending latch is bounded by that settle's finish hold. A reconciled settle is not an observed turn, so it mints no `done` and sends no `task_complete`. Live background jobs (`bash_background` / `monitor`) are read from Gentle Shell's session-scoped `gentle-ai:jobs-sidebar` bus event, so waiting on a CI run or a long command keeps the row on `gentle` and never reaches `done`; `blocked` fires only for an actual human-wait intervention leg with its label (review/RDD execution stays `working`, silent). `blocked` is never derived from an error: native `blocked` is what fires the host's NeedsAttention toast and sound, so a failed run shows our own `error` state — the durable, session-bound `gentle_error_v1` token (republished every beat while the leg stands, cleared when it releases) that the sidebar reduces to the `error` row word — while the pane stays on `working`, and a failed tool call (or a delegate that ended `failed`, or a failed beat transport) changes nothing at all: it is detected and logged, never published, and never reaches the error token. The native status keeps its aggregate meaning — it reads `working` while any delegate runs — while the sidebar row's working-vs-idle decision reads the principal-only `gentle_principal_v1` marker, so an idle principal with a running delegate shows that delegate's own role word or name instead of the principal's `gentle`. Our code never emits `done`/`finished` native states or a Herdr notification (the opt-in Moshi replacement below is a separate, off-by-default channel): the host owns finished text on `done`, `blocked`/unknown presentation, sound, and all desktop attention toasts (ask + finish) — there is no consumer toast path left to dedup. Single publisher by design: the managed native extension file stays on disk and is excluded through an ownership-bound Pi settings entry while Gentle mode is selected. `node bin/gentle-sidebar.js disable` removes only our owned exclusion and managed rows, gates our producer/daemon, and hands the sidebar back to the native publisher (running Pi sessions need `/reload`); never run both publishers on the same pane. Limits (unverified, host-owned): the host `idle`→`done`→`finished` mapping and unknown-state handling are owned by Herdr.
427
451
  - Sidebar switch (`enable` / `disable` / `status` / `toggle`):
428
452
  `node bin/gentle-sidebar.js <verb>` picks between this plugin's sidebar rows
429
453
  and the native Herdr sidebar. `status` is read-only; `enable` converges the
@@ -449,7 +473,12 @@ See [DESIGN.md](DESIGN.md) §4 (producer) and §5 (consumer), and
449
473
  shows the single `Sidebar agent rows` row, and the only Moshi switch is the
450
474
  `Notifications` row under `Moshi notifications`. The two are never mixed —
451
475
  `Sidebar agent rows` neither reads nor writes `gentle-moshi.json`, so turning
452
- the agent rows off never turns the notification channel off. The plain
476
+ the agent rows off never turns the notification channel off. Herdr's own
477
+ done/ask attention (the finished and needs-attention pop-ups and their
478
+ sound) is Herdr's native behavior, configured in Herdr itself — its config
479
+ and its settings — and this package deliberately offers no switch for it:
480
+ the optional Moshi channel below is the only notification surface the
481
+ package owns. The plain
453
482
  two-step menu stays as the fallback
454
483
  when the TUI helpers or `ctx.ui.custom` are unavailable.
455
484
  `Sidebar agent rows` drives the Herdr plugin's own `bin/configure.js`
@@ -73,10 +73,13 @@
73
73
  // gentle_names_v1 = CSV of TaskRecord.label/agent (sanitized, ≤64 chars
74
74
  // each, oldest-first, total ≤ 512 UTF-8 BYTES; excess
75
75
  // advisory names are dropped whole, never chunked — the
76
- // §4.5 #p= overflow form never triggers by construction)
76
+ // §4.5 #p= overflow form never triggers by construction;
77
+ // a record whose label and agent are both absent has no
78
+ // identity to publish and is skipped, never replaced by a
79
+ // placeholder or a stringified absent value)
77
80
  // Compatibility transport only: the consumer renders
78
81
  // roles, never names. Null (clear) when the active
79
- // TaskStore list has no labels; null change tokens when the session model has
82
+ // TaskStore list has no names; null change tokens when the session model has
80
83
  // zero changed files — refreshed/cleared from the live
81
84
  // session model, never carried across sessions.
82
85
  // gentle_ask_v1 = <hash>:<intentId>:<expiry>
@@ -728,6 +731,23 @@ const paneId = process.env.HERDR_PANE_ID;
728
731
 
729
732
  const TTL_MS = 60000;
730
733
  const BEAT_MS = 15000;
734
+ const BEAT_MIN_MS = 100;
735
+ const BEAT_MAX_MS = 300000;
736
+ const BEAT_ENV = "GENTLE_HERDR_BEAT_MS";
737
+ // Bounded budget of quiet beats a producer may publish while it has no work
738
+ // evidence and no host truth to settle on (`quietWithoutTruth` in the
739
+ // factory): three beats, one BEAT_MS each. See the comment there.
740
+ const QUIET_BEAT_LIMIT = 3;
741
+ // Consecutive beats a producer must see the lost-settle contradiction (it
742
+ // believes a turn is running, the host answers `isIdle() === true`, and
743
+ // nothing else keeps the session busy) before it applies the settle the host
744
+ // already reports (`reconcileSettled` in the factory). One beat is not enough:
745
+ // the host flips to idle at the very end of a run, so a genuine `agent_settled`
746
+ // can reach the producer one host tick later, and a single sample would repaint
747
+ // a still-settling turn as idle. Two consecutive samples — 30 s of
748
+ // host-confirmed idle at the 15 s beat — cannot be that race, and a lost edge
749
+ // still recovers within one beat period after the window closes.
750
+ const LOST_SETTLE_BEATS = 2;
731
751
  // Synthesized finish signal (DESIGN §4.3, S2/D2). The host never reports
732
752
  // `done`, so the producer mints the finish itself: one session-bound
733
753
  // `<hash>:<expiry>` token per finish at the settled-and-empty edge, carrying
@@ -928,6 +948,20 @@ export function doneHoldMs(raw = process.env[DONE_HOLD_ENV]) {
928
948
  return Math.min(DONE_HOLD_MAX_MS, Math.max(DONE_HOLD_MIN_MS, Math.round(parsed)));
929
949
  }
930
950
 
951
+ // Beat cadence override, the same discipline as doneHoldMs: an absent or
952
+ // unparseable value keeps the 15 s default and anything outside the band is
953
+ // clamped, so a debugging session (or a test that cannot wait 15 s per beat)
954
+ // can shorten the beat without touching the 60 s token TTL or the transport's
955
+ // own 500/1500 ms bounds. The 100 ms floor keeps every beat far slower than a
956
+ // single send.
957
+ function beatMs(raw = process.env[BEAT_ENV]) {
958
+ const text = typeof raw === "string" ? raw.trim() : "";
959
+ if (text.length === 0) return BEAT_MS;
960
+ const parsed = Number(text);
961
+ if (!Number.isFinite(parsed)) return BEAT_MS;
962
+ return Math.min(BEAT_MAX_MS, Math.max(BEAT_MIN_MS, Math.round(parsed)));
963
+ }
964
+
931
965
  // Cap a label at MAX_LABEL_CHARS UTF-16 units — the same unit the consumer's
932
966
  // `parseNames` checks, so a label the producer writes is never one the
933
967
  // consumer drops — while backing off one unit when the cut would split a
@@ -1137,6 +1171,15 @@ function cliFallback(patch) {
1137
1171
  // unverified) and no new imports (self-contained single file). Do NOT
1138
1172
  // reinstall the native publisher from Herdr: two publishers for the same
1139
1173
  // pane collide (dual-publish).
1174
+ //
1175
+ // T2 (the pane must never freeze at `working`): the settle this owner gates on
1176
+ // is reconciled from the host's own live truth on every beat instead of being
1177
+ // inferred — including when a turn was seen to start but its settle edge was
1178
+ // lost, which needs a bounded window of contradictory beats rather than a
1179
+ // single sample; a quiet producer the host never confirms stops beating after a
1180
+ // bounded budget instead of republishing a count-0 work token forever; and the
1181
+ // settle-time pending latch stops counting once the finish hold that raised it
1182
+ // expires.
1140
1183
  // ---------------------------------------------------------------------------
1141
1184
 
1142
1185
  export const NATIVE_STATES = ["working", "blocked", "idle"];
@@ -1157,6 +1200,11 @@ const NATIVE_MAX_ATTEMPTS = 2;
1157
1200
  // done/finished (only working|blocked|idle) and never a notification
1158
1201
  // method — the host owns finished text plus toast/sound, and desktop ask
1159
1202
  // attention (including toast dedup) is host-owned (DESIGN §7).
1203
+ //
1204
+ // The `settled` input is never inferred here: the beat reconciles it from the
1205
+ // host's own live truth (`ctx.isIdle()`), so a missed `agent_settled` cannot
1206
+ // leave this producer unable to reach `idle` — not when no turn was observed,
1207
+ // and not when a turn this producer saw start never delivered its settle edge.
1160
1208
  export function computeNativeState({
1161
1209
  agentActive,
1162
1210
  settled,
@@ -2438,17 +2486,21 @@ async function applyCustomizeSwitch(id, value, ctx) {
2438
2486
  if (result.needsReload && typeof ctx?.reload === "function") await ctx.reload();
2439
2487
  }
2440
2488
 
2441
- // The single apply path shared by the overlay and the menu fallback. An
2442
- // inconclusive sidebar verdict is never a refusal: choosing On still attempts
2443
- // the repair and reports the apply step's own error, exactly like the baseline
2444
- // menu did. `switchId` names the switch a row drives, never the category it is
2445
- // painted under: each category now owns exactly one switch, so the sidebar rows
2446
- // can only ever resolve `sidebar` and the notification row only `moshi`.
2447
- async function applyCustomizeChoice(categoryId, valueId, ctx, switchId) {
2448
- const target = switchId === "sidebar" || switchId === "moshi" ? switchId : categoryId;
2449
- if (target !== "sidebar" && target !== "moshi") return;
2489
+ // The single apply path shared by the overlay and the menu fallback. The choice
2490
+ // the panel resolves names the switch it drives (`switchId`) and the value to
2491
+ // apply; that switch id is the only thing read here, so a row can never apply a
2492
+ // switch its category does not own. An inconclusive sidebar verdict is never a
2493
+ // refusal: choosing On still attempts the repair and reports the apply step's
2494
+ // own error, exactly like the baseline menu did.
2495
+ const CUSTOMIZE_SWITCH_IDS = ["sidebar", "moshi"];
2496
+
2497
+ async function applyCustomizeChoice(choice, ctx) {
2498
+ if (!isRecord(choice)) return;
2499
+ const switchId = choice.switchId;
2500
+ const valueId = choice.valueId;
2501
+ if (!CUSTOMIZE_SWITCH_IDS.includes(switchId)) return;
2450
2502
  if (valueId !== "on" && valueId !== "off") return;
2451
- await applyCustomizeSwitch(target, valueId, ctx);
2503
+ await applyCustomizeSwitch(switchId, valueId, ctx);
2452
2504
  }
2453
2505
 
2454
2506
  // The former plain menu, kept as the fallback when the TUI helpers or
@@ -2477,7 +2529,7 @@ async function runCustomizeFallback(ctx) {
2477
2529
  choice = undefined;
2478
2530
  }
2479
2531
  if (choice !== CUSTOMIZE_ON && choice !== CUSTOMIZE_OFF) return;
2480
- await applyCustomizeChoice(id, choice === CUSTOMIZE_ON ? "on" : "off", ctx);
2532
+ await applyCustomizeChoice({ switchId: id, valueId: choice === CUSTOMIZE_ON ? "on" : "off" }, ctx);
2481
2533
  }
2482
2534
 
2483
2535
  async function executeCustomize(rawArgs, ctx) {
@@ -2548,7 +2600,7 @@ async function executeCustomize(rawArgs, ctx) {
2548
2600
  // Esc (null) does nothing at all: no notification, no write, no reload.
2549
2601
  // Anything else runs the single apply path once the overlay is disposed.
2550
2602
  if (!choice || typeof choice !== "object") return;
2551
- await applyCustomizeChoice(choice.categoryId, choice.valueId, ctx, choice.switchId);
2603
+ await applyCustomizeChoice(choice, ctx);
2552
2604
  return;
2553
2605
  }
2554
2606
  await runCustomizeFallback(ctx);
@@ -2590,7 +2642,7 @@ export default function (pi) {
2590
2642
  // Finished/failed/cancelled/waiting entries may linger in the map but
2591
2643
  // never count; the map is cleared only on session reset (plus the
2592
2644
  // bounded-map guard) — never by a local staleness timeout.
2593
- const pendingCalls = new Map(); // toolCallId -> { agent, label, at }
2645
+ const pendingCalls = new Map(); // toolCallId -> { agent, label, at }; agent/label are undefined when no agent is resolvable
2594
2646
  const tasks = new Map(); // taskId -> { agent, label, status, at }
2595
2647
 
2596
2648
  // Blocker legs. ask combines choice + native questionnaire + legacy
@@ -2628,6 +2680,10 @@ export default function (pi) {
2628
2680
  // opened the current ask episode.
2629
2681
  let moshiContext;
2630
2682
  let moshiCtxRef;
2683
+ // Last context the host handed us, retained so a beat can ask the host's own
2684
+ // live truth (`isIdle()`) instead of inferring a settle. Kept apart from
2685
+ // `moshiCtxRef`, whose capture leg owns that reference.
2686
+ let settleCtx;
2631
2687
  let lastAskToolName;
2632
2688
 
2633
2689
  // Live background jobs (Gentle Shell `bash_background` / `monitor`) from the
@@ -2687,6 +2743,7 @@ export default function (pi) {
2687
2743
  // freshness bound measures from.
2688
2744
  function onJobsSnapshot(value) {
2689
2745
  if (!isRecord(value) || !isRecord(value.snapshot) || !Array.isArray(value.snapshot.jobs)) return;
2746
+ noteActivity();
2690
2747
  const jobs = value.snapshot.jobs.filter(
2691
2748
  (entry) => isRecord(entry) && typeof entry.id === "string" && entry.id.length > 0,
2692
2749
  );
@@ -2823,6 +2880,13 @@ export default function (pi) {
2823
2880
  let presenceReconciler = createPresenceReconciler();
2824
2881
  let transportFails = 0;
2825
2882
  let beatTimer;
2883
+ // Consecutive quiet beats published without host truth (see
2884
+ // `quietWithoutTruth`); bounded by QUIET_BEAT_LIMIT and reset by work.
2885
+ let quietBeats = 0;
2886
+ // Consecutive beats that contradict a turn this producer saw start (see
2887
+ // `lostSettleContradiction`); bounded by LOST_SETTLE_BEATS and reset by any
2888
+ // activity edge.
2889
+ let lostSettleBeats = 0;
2826
2890
  let publishQueued = false;
2827
2891
  let publishInFlight = false;
2828
2892
  // Native owner queue (always on): monotonic seq per logical report,
@@ -2845,7 +2909,17 @@ export default function (pi) {
2845
2909
  // beat arriving mid-send is describing.
2846
2910
  let nativeSending = null;
2847
2911
  let nativeLastOk = undefined;
2912
+ // T2 native-only terminal guard: agent_settled clears the metadata
2913
+ // pending-launch hint below, but a settle that observes in-flight launches
2914
+ // retains pending evidence here so native idle gating stays working until
2915
+ // those launches resolve. Metadata/tasks untouched; the guard clears when a
2916
+ // launch resolves, on agent_start, with the session, and — when a launch
2917
+ // never reports back — at `nativeSettledPendingUntil`, the finish-hold
2918
+ // deadline of the settle that raised it. Past that hold the evidence stops
2919
+ // counting, so a lost launch result can never pin the native report at
2920
+ // `working` for good (seq itself never resets).
2848
2921
  let nativeSettledPending = false;
2922
+ let nativeSettledPendingUntil = 0;
2849
2923
  // Finish-hold episode (S2): minted once at the settled-and-empty edge so the
2850
2924
  // row reads `done`, then republished unchanged (never refreshed) until the
2851
2925
  // hold expires. `donePending` carries the unannounced finish to the beat
@@ -2855,6 +2929,12 @@ export default function (pi) {
2855
2929
  let doneExpiry;
2856
2930
  let donePending = false;
2857
2931
  let sawActivity = false;
2932
+ // Whether the settle this row sits in came from an observed turn
2933
+ // (`agent_settled`) rather than from the host-truth reconcile: only an
2934
+ // observed turn can mint a finish, so non-turn activity (an ask, a review, a
2935
+ // job) on a producer that never saw a turn can never announce `done` or the
2936
+ // phone's `task_complete`.
2937
+ let turnSettled = false;
2858
2938
  // LIVE-1 startup latency: the session binding is still INITIATED on
2859
2939
  // session_start (so Herdr can attribute the pane from the first frame), but
2860
2940
  // the host no longer waits for it. The host awaits every session_start
@@ -2864,12 +2944,117 @@ export default function (pi) {
2864
2944
  // unchanged, only the host's startup return is freed. Reset with the session
2865
2945
  // so a stale binding can never gate the next one.
2866
2946
  let sessionReportPending = null;
2867
- // T2 native-only terminal guard: agent_settled clears the metadata
2868
- // pending-launch hint below, but a settle that observes in-flight
2869
- // launches retains pending evidence here so native idle gating stays
2870
- // working until those launches resolve. Metadata/tasks untouched; the
2871
- // guard clears when a launch resolves, on agent_start, and with the
2872
- // session (seq itself never resets).
2947
+
2948
+ // Retain the host context the settle reconcile reads (`isIdle()`), next to
2949
+ // the Moshi capture reference it already replaced. A lifecycle event that
2950
+ // arrives without a context must not erase the last truth we hold.
2951
+ function retainContext(ctx) {
2952
+ moshiCtxRef = ctx;
2953
+ if (ctx) settleCtx = ctx;
2954
+ }
2955
+
2956
+ function clearSettledPending() {
2957
+ nativeSettledPending = false;
2958
+ nativeSettledPendingUntil = 0;
2959
+ }
2960
+
2961
+ // Past the finish hold of the settle that raised it, the retained pending
2962
+ // evidence stops counting: the hold is the span it exists to cover.
2963
+ function settledPendingHeld() {
2964
+ return nativeSettledPending && Date.now() < nativeSettledPendingUntil;
2965
+ }
2966
+
2967
+ // The settle state `agent_settled` applies, shared with the reconcile below
2968
+ // so both paths agree on every field except the finish episode.
2969
+ function applySettled(fromTurn) {
2970
+ agentActive = false;
2971
+ settled = true;
2972
+ turnSettled = fromTurn === true;
2973
+ lostSettleBeats = 0;
2974
+ clearSettledPending();
2975
+ }
2976
+
2977
+ // Every activity edge restarts the lost-settle window: a tool call, a
2978
+ // delegate, a job, an ask/review/error leg (the contradiction predicate reads
2979
+ // those legs directly) or a new `agent_start`. Only consecutive beats that
2980
+ // still contradict the host may settle.
2981
+ function noteActivity() {
2982
+ lostSettleBeats = 0;
2983
+ }
2984
+
2985
+ // Nothing observable keeps this session busy: no authoritative
2986
+ // running|queued delegate, no launch in flight, no live background job.
2987
+ // `agentActive` is not part of this evidence: it is this producer's own
2988
+ // inference from turn events, so the reconcile guards it separately and
2989
+ // never overrides a turn it saw start.
2990
+ function noWorkEvidence() {
2991
+ return (
2992
+ activeSubs().length === 0 &&
2993
+ pendingCalls.size === 0 &&
2994
+ freshRunningJobCount() === 0
2995
+ );
2996
+ }
2997
+
2998
+ // Live host truth for the settle decision: the retained context's `isIdle()`.
2999
+ // `undefined` means the host offers no truth (no context yet, or one without
3000
+ // the method); `false` means the host still considers the agent busy, which
3001
+ // is never this producer's to override.
3002
+ function hostIdleTruth() {
3003
+ const probe = settleCtx?.isIdle;
3004
+ if (typeof probe !== "function") return undefined;
3005
+ try {
3006
+ return probe.call(settleCtx) === true;
3007
+ } catch {
3008
+ return undefined;
3009
+ }
3010
+ }
3011
+
3012
+ // The lost-settle contradiction: this producer still believes its turn runs,
3013
+ // the host answers that nothing is processing, and no work evidence or
3014
+ // owning leg keeps the session busy. Both sides are live truth re-read on
3015
+ // every beat, so the contradiction is never remembered from a stale sample.
3016
+ function lostSettleContradiction() {
3017
+ return (
3018
+ agentActive &&
3019
+ hostIdleTruth() === true &&
3020
+ noWorkEvidence() &&
3021
+ !askActiveNow() &&
3022
+ !reviewActive &&
3023
+ errorCode === undefined
3024
+ );
3025
+ }
3026
+
3027
+ // Recover a settle this producer missed. `settled` flips only in
3028
+ // `agent_settled`, which early-returns unless the host already reports idle,
3029
+ // so a session first observed while idle — or an aborted or failed run whose
3030
+ // `agent_settled` never arrived — leaves `settled` false: `computeNativeState`
3031
+ // returns undefined and the pane keeps the last native `working`. The host
3032
+ // answers the same question `agent_settled` asks, so read its live truth here
3033
+ // instead of inferring a terminal from a timeout or from a count.
3034
+ function reconcileSettled() {
3035
+ if (!rootSession || settled) return;
3036
+ // No turn edge was ever observed: nothing local contradicts the host, so
3037
+ // its answer settles the producer on the same beat.
3038
+ if (!agentActive) {
3039
+ if (!noWorkEvidence()) return;
3040
+ if (hostIdleTruth() !== true) return;
3041
+ applySettled(false);
3042
+ return;
3043
+ }
3044
+ // A turn the producer itself saw start is local evidence of a running
3045
+ // agent, and `isIdle()` turns true at the end of the run — so a genuine
3046
+ // settle edge can still be in flight. Only a bounded window of consecutive
3047
+ // contradictory beats proves the edge was lost.
3048
+ if (!lostSettleContradiction()) {
3049
+ lostSettleBeats = 0;
3050
+ return;
3051
+ }
3052
+ lostSettleBeats += 1;
3053
+ if (lostSettleBeats < LOST_SETTLE_BEATS) return;
3054
+ // `fromTurn` false: a recovered settle is never a turn, so it can mint no
3055
+ // finish episode (no `gentle_done_v1`, no finish notification).
3056
+ applySettled(false);
3057
+ }
2873
3058
 
2874
3059
  function refreshSessionRef(ctx) {
2875
3060
  try {
@@ -3082,7 +3267,20 @@ export default function (pi) {
3082
3267
  const parts = [];
3083
3268
  let length = 0;
3084
3269
  for (const sub of subs) {
3085
- const name = sanitizeLabel(sub.label, sub.agent);
3270
+ // An entry whose label and agent are both absent has no name to publish:
3271
+ // a record can carry no identity at all (an observation without an agent
3272
+ // and no previous record), and `sanitizeLabel` stringifies whatever
3273
+ // fallback it is handed, so passing the absence through would put the
3274
+ // literal `undefined` on the wire as a name.
3275
+ const label =
3276
+ typeof sub.label === "string" && sub.label.length > 0 ? sub.label : undefined;
3277
+ const subAgent =
3278
+ typeof sub.agent === "string" && sub.agent.length > 0 ? sub.agent : undefined;
3279
+ if (label === undefined && subAgent === undefined) continue;
3280
+ // Label first, agent as fallback, unchanged for every entry that has
3281
+ // either; the fallback is never absent here, so the sanitizer always has
3282
+ // a real string to fall back to.
3283
+ const name = sanitizeLabel(label, subAgent ?? label);
3086
3284
  if (parts.includes(name)) continue;
3087
3285
  const add = (parts.length === 0 ? 0 : 1) + utf8Bytes(name);
3088
3286
  if (length + add > MAX_TOKEN_BYTES) break;
@@ -3130,11 +3328,15 @@ export default function (pi) {
3130
3328
  ) {
3131
3329
  return "rdd";
3132
3330
  }
3133
- // The bare visible word `working` is banned: a sanitized unknown slug
3134
- // exactly equal to `working` degrades to no role (generic `gentle`)
3135
- // in metadata roles and the native message alike.
3331
+ // The bare visible words `working`, `subagent`, and `gentle` are banned: a
3332
+ // sanitized unknown slug exactly equal to one of them degrades to no role
3333
+ // (generic `gentle`) in metadata roles and the native message alike.
3334
+ // `subagent` is the launch-correlation placeholder, never an agent name, so
3335
+ // it must never reach the wire as a role word. `gentle` is the pink
3336
+ // generic's own word (S1), so an agent literally named `gentle` must not
3337
+ // become a second one on the amber cell.
3136
3338
  const slug = sanitizeAgentSlug(agent);
3137
- return slug === "working" ? undefined : slug;
3339
+ return slug === "working" || slug === "subagent" || slug === "gentle" ? undefined : slug;
3138
3340
  }
3139
3341
 
3140
3342
  // Bounded CSV of role words, oldest-first (subs already arrive
@@ -3278,7 +3480,7 @@ export default function (pi) {
3278
3480
  sawActivity = true;
3279
3481
  doneExpiry = undefined;
3280
3482
  donePending = false;
3281
- } else if (settled) {
3483
+ } else if (settled && turnSettled) {
3282
3484
  if (doneExpiry === undefined && sawActivity) {
3283
3485
  doneExpiry = Date.now() + doneHoldMs();
3284
3486
  donePending = true;
@@ -3349,16 +3551,73 @@ export default function (pi) {
3349
3551
  if (beatTimer || !rootSession) return;
3350
3552
  if (!interesting() && settled) return;
3351
3553
  beatTimer = setInterval(() => {
3554
+ // A tick with nothing interesting to publish has nothing to do. Stopping
3555
+ // here (instead of only after a landed publish) is what keeps a slow
3556
+ // send from re-arming the interval through `publishQueued` and spinning
3557
+ // a beat nobody needs.
3558
+ if (!interesting()) {
3559
+ stopBeat();
3560
+ return;
3561
+ }
3562
+ // T2 quiet bound: a beat with no work evidence, no host truth, and no
3563
+ // leg that still owns the row has nothing confirmed to publish — every
3564
+ // such beat republishes a fresh count-0 `gentle_work_v1`, and that
3565
+ // eternal fresh work token is what keeps the row from ever reaching
3566
+ // idle. The beat spends a bounded budget of quiet beats (one BEAT_MS
3567
+ // each) and then stops. Stopping is the honest outcome: a native state
3568
+ // the host never confirmed must not be published in its place. The
3569
+ // bound never applies to a turn this producer saw start (see
3570
+ // `quietWithoutTruth`), so it cannot leave live work unpainted; the
3571
+ // edges that schedule a publish (ask, review, launch, session changes,
3572
+ // jobs) re-arm the beat, while an ordinary tool edge reaches the row
3573
+ // through the host's own truth rather than by re-arming it.
3574
+ if (quietWithoutTruth()) {
3575
+ quietBeats += 1;
3576
+ if (quietBeats >= QUIET_BEAT_LIMIT) {
3577
+ stopBeat();
3578
+ return;
3579
+ }
3580
+ } else {
3581
+ quietBeats = 0;
3582
+ }
3352
3583
  void publishNow();
3353
- }, BEAT_MS);
3584
+ }, beatMs());
3354
3585
  if (beatTimer.unref) beatTimer.unref();
3355
3586
  }
3356
3587
 
3588
+ function stopBeat() {
3589
+ if (!beatTimer) return;
3590
+ clearInterval(beatTimer);
3591
+ beatTimer = undefined;
3592
+ }
3593
+
3357
3594
  function maybeStopBeat() {
3358
- if (beatTimer && !interesting()) {
3359
- clearInterval(beatTimer);
3360
- beatTimer = undefined;
3361
- }
3595
+ if (beatTimer && !interesting()) stopBeat();
3596
+ }
3597
+
3598
+ // T2 quiet bound predicate (see the budget applied inside `ensureBeat`): the
3599
+ // host offers no truth at all, nothing is active by evidence, and no leg
3600
+ // still owns the row. A host that answers `false` is not quiet — it says the
3601
+ // agent is still running — and a host that answers `true` settles through
3602
+ // `reconcileSettled` instead. No native state is ever inferred here.
3603
+ //
3604
+ // `agentActive` is excluded on purpose: a turn this producer saw start is
3605
+ // live work, and the host offers no way to confirm its settle. Bounding that
3606
+ // beat would stop painting a running turn, which is exactly the pin the bound
3607
+ // exists to avoid (S2) — the bound must never trade a truthful "still
3608
+ // working" for a false `idle`. It therefore covers only a producer with no
3609
+ // observed turn behind it and no host truth to settle on.
3610
+ function quietWithoutTruth() {
3611
+ return (
3612
+ !agentActive &&
3613
+ !settled &&
3614
+ hostIdleTruth() === undefined &&
3615
+ noWorkEvidence() &&
3616
+ !askActiveNow() &&
3617
+ !reviewActive &&
3618
+ errorCode === undefined &&
3619
+ doneExpiry === undefined
3620
+ );
3362
3621
  }
3363
3622
 
3364
3623
  // N1 parity report: state + message. Working carries the SPECIFIC
@@ -3385,7 +3644,7 @@ export default function (pi) {
3385
3644
  agentActive,
3386
3645
  settled,
3387
3646
  activeCount: activeSubs().length,
3388
- pendingCount: pendingCalls.size + (nativeSettledPending ? 1 : 0),
3647
+ pendingCount: pendingCalls.size + (settledPendingHeld() ? 1 : 0),
3389
3648
  askActive: askActiveNow(),
3390
3649
  reviewActive,
3391
3650
  });
@@ -3600,6 +3859,9 @@ export default function (pi) {
3600
3859
  // flight publishes nothing: `rootSession` is re-read after the wait.
3601
3860
  await awaitSessionBinding();
3602
3861
  if (!rootSession || !sidebarPublishingEnabled()) return;
3862
+ // Host truth first: a settle this producer missed must be visible to both
3863
+ // the native report and the tokens built below.
3864
+ reconcileSettled();
3603
3865
  reconcilePresence();
3604
3866
  queueNative();
3605
3867
  const tokens = buildTokens();
@@ -3751,10 +4013,11 @@ export default function (pi) {
3751
4013
  nativePending = null;
3752
4014
  nativeSending = null;
3753
4015
  nativeLastOk = undefined;
3754
- nativeSettledPending = false;
4016
+ clearSettledPending();
3755
4017
  doneExpiry = undefined;
3756
4018
  donePending = false;
3757
4019
  sawActivity = false;
4020
+ turnSettled = false;
3758
4021
  jobsSnapshot = undefined;
3759
4022
  clearJobsExpiry();
3760
4023
  errorCode = undefined;
@@ -3764,9 +4027,13 @@ export default function (pi) {
3764
4027
  liveQueued = false;
3765
4028
  sessionReportPending = null;
3766
4029
  sessionCwd = undefined;
4030
+ settleCtx = undefined;
4031
+ quietBeats = 0;
4032
+ lostSettleBeats = 0;
3767
4033
  changes = { files: 0, added: 0, deleted: 0 };
3768
4034
  agentActive = false;
3769
4035
  settled = false;
4036
+ turnSettled = false;
3770
4037
  }
3771
4038
 
3772
4039
  function clearEmittedLabel() {
@@ -3821,6 +4088,7 @@ export default function (pi) {
3821
4088
 
3822
4089
  pi.on("tool_execution_start", (event) => {
3823
4090
  if (!rootSession || !isRecord(event) || typeof event.toolCallId !== "string") return;
4091
+ noteActivity();
3824
4092
  runningTools.add(event.toolCallId);
3825
4093
  // Structured ask tools open ONLY on genuine execution (never on
3826
4094
  // `tool_call` proposal), keyed by call id so the matching end or
@@ -3923,17 +4191,30 @@ export default function (pi) {
3923
4191
 
3924
4192
  // -- subagent activity -----------------------------------------------------
3925
4193
 
4194
+ // `subagent_run` carries the agent in its input, but `subagent_continue`
4195
+ // carries only `task_id`/`prompt`/`label`/`mode`: a resume names the task
4196
+ // whose record already holds the child's agent. Neither source means no
4197
+ // role evidence at all — the pending call still covers the blocking/
4198
+ // orchestrating marker, but it contributes no role and no name, and it
4199
+ // must never publish the launch-correlation placeholder as a role word.
3926
4200
  function launchInput(input) {
3927
4201
  if (!isRecord(input)) return undefined;
3928
- const agent = typeof input.agent === "string" ? input.agent : "subagent";
3929
- const label = sanitizeLabel(typeof input.label === "string" ? input.label : agent, agent);
3930
- return { agent: truncateChars(agent, MAX_LABEL_CHARS), label };
4202
+ const taskId = typeof input.task_id === "string" ? input.task_id : undefined;
4203
+ const inputAgent =
4204
+ typeof input.agent === "string" && input.agent.length > 0 ? input.agent : undefined;
4205
+ const agent =
4206
+ inputAgent ?? (taskId !== undefined ? tasks.get(taskId)?.agent : undefined);
4207
+ const labelSource =
4208
+ typeof input.label === "string" && input.label.length > 0 ? input.label : agent;
4209
+ const label = labelSource === undefined ? undefined : sanitizeLabel(labelSource, labelSource);
4210
+ return { agent: agent === undefined ? undefined : truncateChars(agent, MAX_LABEL_CHARS), label };
3931
4211
  }
3932
4212
 
3933
4213
  pi.on("tool_call", (event) => {
3934
4214
  if (!rootSession || !isRecord(event) || typeof event.toolName !== "string") return;
3935
4215
  // A tool starting proves a run is alive: an error left over from a run that
3936
4216
  // already died is released here rather than sticking until the next turn.
4217
+ noteActivity();
3937
4218
  clearRunError();
3938
4219
  // Structured ask proposals never open ask (execution does); subagent
3939
4220
  // launch correlation below is unchanged.
@@ -3963,6 +4244,7 @@ export default function (pi) {
3963
4244
 
3964
4245
  pi.on("tool_result", (event) => {
3965
4246
  if (!rootSession || !isRecord(event) || typeof event.toolName !== "string") return;
4247
+ noteActivity();
3966
4248
  clearRunError();
3967
4249
  if (typeof event.toolCallId === "string" && askToolCalls.delete(event.toolCallId)) {
3968
4250
  updateBlocker();
@@ -3979,7 +4261,7 @@ export default function (pi) {
3979
4261
  // outcome is now covered by the task record (working via activeSubs),
3980
4262
  // the error latch (blocked), or genuine emptiness (idle on next beat).
3981
4263
  if (event.toolName === "subagent_run" || event.toolName === "subagent_continue") {
3982
- nativeSettledPending = false;
4264
+ clearSettledPending();
3983
4265
  }
3984
4266
  if (typeof event.toolCallId === "string" ? reviewCalls.delete(event.toolCallId) : false) {
3985
4267
  // The ended id was a known acknowledged execution; remaining tracked
@@ -4051,10 +4333,13 @@ export default function (pi) {
4051
4333
  : undefined;
4052
4334
  // A stale read's agent is distrusted with its status, and a missing
4053
4335
  // agent keeps the previous record's agent (never reset to a guess).
4336
+ // With neither source the record has no agent at all: `subagent` is the
4337
+ // launch-correlation placeholder, never an identity, so inventing it here
4338
+ // would publish that word as the record's name.
4054
4339
  const agent =
4055
4340
  staleRead && previous?.agent
4056
4341
  ? previous.agent
4057
- : (incomingAgent ?? previous?.agent ?? "subagent");
4342
+ : (incomingAgent ?? previous?.agent);
4058
4343
  const now = Date.now();
4059
4344
  tasks.set(details.taskId, {
4060
4345
  agent,
@@ -4086,6 +4371,7 @@ export default function (pi) {
4086
4371
  // never passes through `tool_result` details.
4087
4372
  pi.on("message_end", (event) => {
4088
4373
  if (!rootSession || !isRecord(event)) return;
4374
+ noteActivity();
4089
4375
  const message = event.message;
4090
4376
  if (!isRecord(message)) return;
4091
4377
  if (message.role === "assistant") {
@@ -4105,10 +4391,13 @@ export default function (pi) {
4105
4391
  if (typeof details.status !== "string") return;
4106
4392
  if (!FINAL_TASK.has(details.status) && !ACTIVE_TASK.has(details.status)) return;
4107
4393
  const previous = tasks.get(details.taskId);
4394
+ // Same rule as the tool_result path: an observation without an agent keeps
4395
+ // the previous record's agent, and with neither there is no agent at all —
4396
+ // the launch-correlation placeholder must never become a record identity.
4108
4397
  const agent =
4109
4398
  typeof details.agent === "string" && details.agent.length > 0
4110
4399
  ? truncateChars(details.agent, MAX_LABEL_CHARS)
4111
- : (previous?.agent ?? "subagent");
4400
+ : previous?.agent;
4112
4401
  // Record identity is immutable per taskId: firstSeen never moves (T2b
4113
4402
  // ordering only) whether this observation promotes a background start
4114
4403
  // or replaces the record with its terminal status; completion still
@@ -4145,7 +4434,7 @@ export default function (pi) {
4145
4434
  rootSession = true;
4146
4435
  sessionManager = ctx.sessionManager;
4147
4436
  refreshSessionRef(ctx);
4148
- moshiCtxRef = ctx;
4437
+ retainContext(ctx);
4149
4438
  if (moshiEnabled()) moshiEnsureContext();
4150
4439
  // LIVE-1: bind the session before any state beat so Herdr attributes the
4151
4440
  // pane from the first frame (mirrors the managed publisher). The binding is
@@ -4163,14 +4452,17 @@ export default function (pi) {
4163
4452
  pi.on("agent_start", (_event, ctx) => {
4164
4453
  if (!rootSession) return;
4165
4454
  refreshSessionRef(ctx);
4166
- moshiCtxRef = ctx;
4455
+ retainContext(ctx);
4167
4456
  // LIVE-1: re-bind the session like the managed publisher did, so a
4168
4457
  // restart or re-announcement never leaves the pane binding-less while
4169
4458
  // metadata beats flow.
4170
4459
  void reportSession();
4171
4460
  agentActive = true;
4172
4461
  settled = false;
4173
- nativeSettledPending = false;
4462
+ turnSettled = false;
4463
+ clearSettledPending();
4464
+ quietBeats = 0;
4465
+ noteActivity();
4174
4466
  clearRunError();
4175
4467
  refreshChanges();
4176
4468
  schedulePublish();
@@ -4178,13 +4470,17 @@ export default function (pi) {
4178
4470
 
4179
4471
  pi.on("agent_settled", (_event, ctx) => {
4180
4472
  if (!rootSession || ctx?.isIdle?.() !== true) return;
4181
- moshiCtxRef = ctx;
4182
- agentActive = false;
4183
- settled = true;
4473
+ retainContext(ctx);
4184
4474
  // Retain settle-time pending evidence for native gating before the
4185
- // metadata hint clears (see nativeSettledPending above).
4186
- if (pendingCalls.size > 0) nativeSettledPending = true;
4475
+ // metadata hint clears (see nativeSettledPending above), bounded by the
4476
+ // finish hold this settle opens.
4477
+ const pendingAtSettle = pendingCalls.size > 0;
4187
4478
  pendingCalls.clear();
4479
+ applySettled(true);
4480
+ if (pendingAtSettle) {
4481
+ nativeSettledPending = true;
4482
+ nativeSettledPendingUntil = Date.now() + doneHoldMs();
4483
+ }
4188
4484
  // S62 turn-end: the working tree may have changed without transcript
4189
4485
  // evidence (external/untracked edits), so re-scan before publishing.
4190
4486
  refreshChanges();
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "herdr-gentle-shell",
3
- "version": "1.5.0",
3
+ "version": "1.5.2",
4
4
  "description": "Pi package for Herdr sidebar states: the Pi extension sidecar that publishes session facts as Herdr pane-metadata tokens, the optional Moshi notification channel, and the Pi-side helpers the Herdr Gentle Shell plugin drives.",
5
5
  "keywords": [
6
6
  "pi-package",