herdr-gentle-shell 1.5.1 → 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
@@ -881,7 +933,7 @@ report after a Pi restart or `/new` (both recreate the extension runtime)
881
933
  lose, freezing the pane's `agent_session` binding at the old session while
882
934
  the producer keeps beating for the new one — the consumer then rejects those
883
935
  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
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
885
937
  reversibly (`-extensions/herdr-agent-state.ts` in Pi settings, bytes
886
938
  preserved on disk, never auto-loaded next to ours). `node
887
939
  bin/gentle-sidebar.js (enable|disable|status|toggle)` selects the
@@ -1054,7 +1106,10 @@ exactly one mechanism writes each piece of state.
1054
1106
  user-facing value is `blocked` (§5.3). `gentle_title_review` likewise
1055
1107
  keeps its machine-key-derived token name; only its user-facing value is
1056
1108
  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)`
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)`
1058
1113
  count display) is swept, never written.
1059
1114
  - Coexistence: `herdr-pi-tree` stays installed but disabled for gentle-owned
1060
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,19 +254,24 @@ 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
@@ -292,7 +301,7 @@ by a racy non-final status read (only the authoritative launch outcomes,
292
301
  completions, and presence terminals move it), so principal activity with
293
302
  live delegates keeps `gentle` while an idle principal keeps the role word; a
294
303
  sanitized unknown slug exactly
295
- equal to `working` or `subagent` degrades to `gentle` (neither bare word ever
304
+ equal to `working` or `subagent` degrades to the pink `gentle` (neither bare word ever
296
305
  renders; `subagent` is the producer's launch-correlation placeholder, never
297
306
  an agent name).
298
307
  Background launches (`subagent_run` with `mode: background`) announce
@@ -323,10 +332,13 @@ herdr server reload-config
323
332
  Live check: with the daemon running and the override applied, open a Pi pane
324
333
  and confirm row 2 shows pink `gentle` (machine key
325
334
  `orchestrating`) while
326
- the principal session actively works — even with zero subagents — and keeps
327
- `gentle` while its delegates run (a role word such as `worker`, `explorer`,
328
- `verify`, `judge` shows once the principal itself is idle — and also while a
329
- 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
330
342
  shows the single heading cell (`● <project>` plus ` +N`/` -N`/` ↑N` inline, zero `·`) after edits / when behind upstream; then `ask` on an open
331
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
332
344
  `HERDR_CONFIG_PATH` on a temp file for apply/uninstall checks.
@@ -353,7 +365,10 @@ coalesced refresh after every landed token beat, so a status change
353
365
  it publishes is drawn at once, and the daemon caps each sleep at the nearest
354
366
  live `done` expiry, so a settled row reaches `idle` when its short hold (5 s by
355
367
  default, `GENTLE_HERDR_DONE_HOLD_MS`-overridable) lapses instead of one poll
356
- 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
357
372
  are floored at 250 ms, so a burst can never spin the daemon. Polling stays the
358
373
  fallback for every lifecycle signal and the only source for what no Herdr event
359
374
  carries (the git-derived `+N/-N` and `↑N` row data and the presence prefix), so a
@@ -367,10 +382,12 @@ See [DESIGN.md](DESIGN.md) §4 (producer) and §5 (consumer), and
367
382
  ## Key Features You Should Know About
368
383
 
369
384
  - Full v1 state matrix including the root-session `orchestrating` marker
370
- (pink `●` + user-facing word `gentle`, while the principal session actively
371
- works — even with zero subagents — retaining subagent/pending coverage;
372
- yielding only to `ask`/`rdd`/`blocked` and terminal `done` (done needs
373
- 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
374
391
  (`explorer` / `worker` / `verify` / `judge` / `rdd` from `TaskRecord.agent`,
375
392
  oldest running first by immutable first-seen, shown while the principal
376
393
  itself is idle — a working principal's own turn keeps `gentle`, asserted by
@@ -379,10 +396,12 @@ See [DESIGN.md](DESIGN.md) §4 (producer) and §5 (consumer), and
379
396
  synchronous `subagent_run`/`subagent_continue` call holds the principal's
380
397
  turn open, so the in-flight child's role shows instead (the
381
398
  `gentle_pending_v1` role marker) until that call resolves, while a
382
- background delegate never takes that path; `gentle` (machine
383
- key `working`) for the principal's own working state; an unknown delegation
399
+ background delegate never takes that path; an unknown delegation
384
400
  keeps its original sanitized name, 32-char bound — never a generic
385
- 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
386
405
  delegates run, `ask` on blocked user input,
387
406
  `rdd` during native review execution (machine key stays `review`; execution
388
407
  is silent — desktop attention fires only for a waiting `ask` intent, as
@@ -428,7 +447,7 @@ See [DESIGN.md](DESIGN.md) §4 (producer) and §5 (consumer), and
428
447
  nothing and logs one line per reason. The gs pane's own live state stays
429
448
  unobservable until the isolated install forwards `HERDR_ENV` to its agent (a
430
449
  gentle-ai concern, out of scope here).
431
- - 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.
432
451
  - Sidebar switch (`enable` / `disable` / `status` / `toggle`):
433
452
  `node bin/gentle-sidebar.js <verb>` picks between this plugin's sidebar rows
434
453
  and the native Herdr sidebar. `status` is read-only; `enable` converges the
@@ -731,6 +731,23 @@ const paneId = process.env.HERDR_PANE_ID;
731
731
 
732
732
  const TTL_MS = 60000;
733
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;
734
751
  // Synthesized finish signal (DESIGN §4.3, S2/D2). The host never reports
735
752
  // `done`, so the producer mints the finish itself: one session-bound
736
753
  // `<hash>:<expiry>` token per finish at the settled-and-empty edge, carrying
@@ -931,6 +948,20 @@ export function doneHoldMs(raw = process.env[DONE_HOLD_ENV]) {
931
948
  return Math.min(DONE_HOLD_MAX_MS, Math.max(DONE_HOLD_MIN_MS, Math.round(parsed)));
932
949
  }
933
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
+
934
965
  // Cap a label at MAX_LABEL_CHARS UTF-16 units — the same unit the consumer's
935
966
  // `parseNames` checks, so a label the producer writes is never one the
936
967
  // consumer drops — while backing off one unit when the cut would split a
@@ -1140,6 +1171,15 @@ function cliFallback(patch) {
1140
1171
  // unverified) and no new imports (self-contained single file). Do NOT
1141
1172
  // reinstall the native publisher from Herdr: two publishers for the same
1142
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.
1143
1183
  // ---------------------------------------------------------------------------
1144
1184
 
1145
1185
  export const NATIVE_STATES = ["working", "blocked", "idle"];
@@ -1160,6 +1200,11 @@ const NATIVE_MAX_ATTEMPTS = 2;
1160
1200
  // done/finished (only working|blocked|idle) and never a notification
1161
1201
  // method — the host owns finished text plus toast/sound, and desktop ask
1162
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.
1163
1208
  export function computeNativeState({
1164
1209
  agentActive,
1165
1210
  settled,
@@ -2635,6 +2680,10 @@ export default function (pi) {
2635
2680
  // opened the current ask episode.
2636
2681
  let moshiContext;
2637
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;
2638
2687
  let lastAskToolName;
2639
2688
 
2640
2689
  // Live background jobs (Gentle Shell `bash_background` / `monitor`) from the
@@ -2694,6 +2743,7 @@ export default function (pi) {
2694
2743
  // freshness bound measures from.
2695
2744
  function onJobsSnapshot(value) {
2696
2745
  if (!isRecord(value) || !isRecord(value.snapshot) || !Array.isArray(value.snapshot.jobs)) return;
2746
+ noteActivity();
2697
2747
  const jobs = value.snapshot.jobs.filter(
2698
2748
  (entry) => isRecord(entry) && typeof entry.id === "string" && entry.id.length > 0,
2699
2749
  );
@@ -2830,6 +2880,13 @@ export default function (pi) {
2830
2880
  let presenceReconciler = createPresenceReconciler();
2831
2881
  let transportFails = 0;
2832
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;
2833
2890
  let publishQueued = false;
2834
2891
  let publishInFlight = false;
2835
2892
  // Native owner queue (always on): monotonic seq per logical report,
@@ -2852,7 +2909,17 @@ export default function (pi) {
2852
2909
  // beat arriving mid-send is describing.
2853
2910
  let nativeSending = null;
2854
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).
2855
2921
  let nativeSettledPending = false;
2922
+ let nativeSettledPendingUntil = 0;
2856
2923
  // Finish-hold episode (S2): minted once at the settled-and-empty edge so the
2857
2924
  // row reads `done`, then republished unchanged (never refreshed) until the
2858
2925
  // hold expires. `donePending` carries the unannounced finish to the beat
@@ -2862,6 +2929,12 @@ export default function (pi) {
2862
2929
  let doneExpiry;
2863
2930
  let donePending = false;
2864
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;
2865
2938
  // LIVE-1 startup latency: the session binding is still INITIATED on
2866
2939
  // session_start (so Herdr can attribute the pane from the first frame), but
2867
2940
  // the host no longer waits for it. The host awaits every session_start
@@ -2871,12 +2944,117 @@ export default function (pi) {
2871
2944
  // unchanged, only the host's startup return is freed. Reset with the session
2872
2945
  // so a stale binding can never gate the next one.
2873
2946
  let sessionReportPending = null;
2874
- // T2 native-only terminal guard: agent_settled clears the metadata
2875
- // pending-launch hint below, but a settle that observes in-flight
2876
- // launches retains pending evidence here so native idle gating stays
2877
- // working until those launches resolve. Metadata/tasks untouched; the
2878
- // guard clears when a launch resolves, on agent_start, and with the
2879
- // 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
+ }
2880
3058
 
2881
3059
  function refreshSessionRef(ctx) {
2882
3060
  try {
@@ -3150,13 +3328,15 @@ export default function (pi) {
3150
3328
  ) {
3151
3329
  return "rdd";
3152
3330
  }
3153
- // The bare visible words `working` and `subagent` are banned: a sanitized
3154
- // unknown slug exactly equal to either degrades to no role (generic
3155
- // `gentle`) in metadata roles and the native message alike. `subagent` is
3156
- // the launch-correlation placeholder, never an agent name, so it must
3157
- // never reach the wire as a role word.
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.
3158
3338
  const slug = sanitizeAgentSlug(agent);
3159
- return slug === "working" || slug === "subagent" ? undefined : slug;
3339
+ return slug === "working" || slug === "subagent" || slug === "gentle" ? undefined : slug;
3160
3340
  }
3161
3341
 
3162
3342
  // Bounded CSV of role words, oldest-first (subs already arrive
@@ -3300,7 +3480,7 @@ export default function (pi) {
3300
3480
  sawActivity = true;
3301
3481
  doneExpiry = undefined;
3302
3482
  donePending = false;
3303
- } else if (settled) {
3483
+ } else if (settled && turnSettled) {
3304
3484
  if (doneExpiry === undefined && sawActivity) {
3305
3485
  doneExpiry = Date.now() + doneHoldMs();
3306
3486
  donePending = true;
@@ -3371,16 +3551,73 @@ export default function (pi) {
3371
3551
  if (beatTimer || !rootSession) return;
3372
3552
  if (!interesting() && settled) return;
3373
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
+ }
3374
3583
  void publishNow();
3375
- }, BEAT_MS);
3584
+ }, beatMs());
3376
3585
  if (beatTimer.unref) beatTimer.unref();
3377
3586
  }
3378
3587
 
3588
+ function stopBeat() {
3589
+ if (!beatTimer) return;
3590
+ clearInterval(beatTimer);
3591
+ beatTimer = undefined;
3592
+ }
3593
+
3379
3594
  function maybeStopBeat() {
3380
- if (beatTimer && !interesting()) {
3381
- clearInterval(beatTimer);
3382
- beatTimer = undefined;
3383
- }
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
+ );
3384
3621
  }
3385
3622
 
3386
3623
  // N1 parity report: state + message. Working carries the SPECIFIC
@@ -3407,7 +3644,7 @@ export default function (pi) {
3407
3644
  agentActive,
3408
3645
  settled,
3409
3646
  activeCount: activeSubs().length,
3410
- pendingCount: pendingCalls.size + (nativeSettledPending ? 1 : 0),
3647
+ pendingCount: pendingCalls.size + (settledPendingHeld() ? 1 : 0),
3411
3648
  askActive: askActiveNow(),
3412
3649
  reviewActive,
3413
3650
  });
@@ -3622,6 +3859,9 @@ export default function (pi) {
3622
3859
  // flight publishes nothing: `rootSession` is re-read after the wait.
3623
3860
  await awaitSessionBinding();
3624
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();
3625
3865
  reconcilePresence();
3626
3866
  queueNative();
3627
3867
  const tokens = buildTokens();
@@ -3773,10 +4013,11 @@ export default function (pi) {
3773
4013
  nativePending = null;
3774
4014
  nativeSending = null;
3775
4015
  nativeLastOk = undefined;
3776
- nativeSettledPending = false;
4016
+ clearSettledPending();
3777
4017
  doneExpiry = undefined;
3778
4018
  donePending = false;
3779
4019
  sawActivity = false;
4020
+ turnSettled = false;
3780
4021
  jobsSnapshot = undefined;
3781
4022
  clearJobsExpiry();
3782
4023
  errorCode = undefined;
@@ -3786,9 +4027,13 @@ export default function (pi) {
3786
4027
  liveQueued = false;
3787
4028
  sessionReportPending = null;
3788
4029
  sessionCwd = undefined;
4030
+ settleCtx = undefined;
4031
+ quietBeats = 0;
4032
+ lostSettleBeats = 0;
3789
4033
  changes = { files: 0, added: 0, deleted: 0 };
3790
4034
  agentActive = false;
3791
4035
  settled = false;
4036
+ turnSettled = false;
3792
4037
  }
3793
4038
 
3794
4039
  function clearEmittedLabel() {
@@ -3843,6 +4088,7 @@ export default function (pi) {
3843
4088
 
3844
4089
  pi.on("tool_execution_start", (event) => {
3845
4090
  if (!rootSession || !isRecord(event) || typeof event.toolCallId !== "string") return;
4091
+ noteActivity();
3846
4092
  runningTools.add(event.toolCallId);
3847
4093
  // Structured ask tools open ONLY on genuine execution (never on
3848
4094
  // `tool_call` proposal), keyed by call id so the matching end or
@@ -3968,6 +4214,7 @@ export default function (pi) {
3968
4214
  if (!rootSession || !isRecord(event) || typeof event.toolName !== "string") return;
3969
4215
  // A tool starting proves a run is alive: an error left over from a run that
3970
4216
  // already died is released here rather than sticking until the next turn.
4217
+ noteActivity();
3971
4218
  clearRunError();
3972
4219
  // Structured ask proposals never open ask (execution does); subagent
3973
4220
  // launch correlation below is unchanged.
@@ -3997,6 +4244,7 @@ export default function (pi) {
3997
4244
 
3998
4245
  pi.on("tool_result", (event) => {
3999
4246
  if (!rootSession || !isRecord(event) || typeof event.toolName !== "string") return;
4247
+ noteActivity();
4000
4248
  clearRunError();
4001
4249
  if (typeof event.toolCallId === "string" && askToolCalls.delete(event.toolCallId)) {
4002
4250
  updateBlocker();
@@ -4013,7 +4261,7 @@ export default function (pi) {
4013
4261
  // outcome is now covered by the task record (working via activeSubs),
4014
4262
  // the error latch (blocked), or genuine emptiness (idle on next beat).
4015
4263
  if (event.toolName === "subagent_run" || event.toolName === "subagent_continue") {
4016
- nativeSettledPending = false;
4264
+ clearSettledPending();
4017
4265
  }
4018
4266
  if (typeof event.toolCallId === "string" ? reviewCalls.delete(event.toolCallId) : false) {
4019
4267
  // The ended id was a known acknowledged execution; remaining tracked
@@ -4123,6 +4371,7 @@ export default function (pi) {
4123
4371
  // never passes through `tool_result` details.
4124
4372
  pi.on("message_end", (event) => {
4125
4373
  if (!rootSession || !isRecord(event)) return;
4374
+ noteActivity();
4126
4375
  const message = event.message;
4127
4376
  if (!isRecord(message)) return;
4128
4377
  if (message.role === "assistant") {
@@ -4185,7 +4434,7 @@ export default function (pi) {
4185
4434
  rootSession = true;
4186
4435
  sessionManager = ctx.sessionManager;
4187
4436
  refreshSessionRef(ctx);
4188
- moshiCtxRef = ctx;
4437
+ retainContext(ctx);
4189
4438
  if (moshiEnabled()) moshiEnsureContext();
4190
4439
  // LIVE-1: bind the session before any state beat so Herdr attributes the
4191
4440
  // pane from the first frame (mirrors the managed publisher). The binding is
@@ -4203,14 +4452,17 @@ export default function (pi) {
4203
4452
  pi.on("agent_start", (_event, ctx) => {
4204
4453
  if (!rootSession) return;
4205
4454
  refreshSessionRef(ctx);
4206
- moshiCtxRef = ctx;
4455
+ retainContext(ctx);
4207
4456
  // LIVE-1: re-bind the session like the managed publisher did, so a
4208
4457
  // restart or re-announcement never leaves the pane binding-less while
4209
4458
  // metadata beats flow.
4210
4459
  void reportSession();
4211
4460
  agentActive = true;
4212
4461
  settled = false;
4213
- nativeSettledPending = false;
4462
+ turnSettled = false;
4463
+ clearSettledPending();
4464
+ quietBeats = 0;
4465
+ noteActivity();
4214
4466
  clearRunError();
4215
4467
  refreshChanges();
4216
4468
  schedulePublish();
@@ -4218,13 +4470,17 @@ export default function (pi) {
4218
4470
 
4219
4471
  pi.on("agent_settled", (_event, ctx) => {
4220
4472
  if (!rootSession || ctx?.isIdle?.() !== true) return;
4221
- moshiCtxRef = ctx;
4222
- agentActive = false;
4223
- settled = true;
4473
+ retainContext(ctx);
4224
4474
  // Retain settle-time pending evidence for native gating before the
4225
- // metadata hint clears (see nativeSettledPending above).
4226
- 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;
4227
4478
  pendingCalls.clear();
4479
+ applySettled(true);
4480
+ if (pendingAtSettle) {
4481
+ nativeSettledPending = true;
4482
+ nativeSettledPendingUntil = Date.now() + doneHoldMs();
4483
+ }
4228
4484
  // S62 turn-end: the working tree may have changed without transcript
4229
4485
  // evidence (external/untracked edits), so re-scan before publishing.
4230
4486
  refreshChanges();
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "herdr-gentle-shell",
3
- "version": "1.5.1",
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",