herdr-gentle-shell 1.1.0 → 1.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/DESIGN.md CHANGED
@@ -28,9 +28,14 @@ explicitly in §10 and are not decided here.
28
28
  per-pane key=value tokens via `pane.report_metadata` /
29
29
  `workspace.report_metadata` over `HERDR_SOCKET_PATH`, with a CLI fallback
30
30
  (`herdr pane report-metadata <pane> --source <src> --token name=value`).
31
- - The consumer is a poller, not a subscriber: the plugin daemon reads the
32
- Herdr snapshot on a cadence and reduces pane tokens to sidebar state.
33
- No new socket, webhook, broker, or persistent connection is introduced.
31
+ - The consumer polls the Herdr snapshot and reduces pane tokens to sidebar
32
+ state. Drawing is subscription-driven: the daemon also holds ONE long-lived
33
+ socket `events.subscribe` for `pane.updated` (plus the roster kinds), which
34
+ only marks a dirty flag and wakes the existing sleep, so a landed token
35
+ report is drawn without waiting for the poll. Polling stays the fallback and
36
+ remains authoritative for everything no Herdr event can drive (§8). No new
37
+ socket, webhook, broker, or dependency is introduced: this is the existing
38
+ plugin socket, used read-only.
34
39
  - The existing native producer `herdr-agent-state.ts` (managed-by-herdr, v9,
35
40
  source `herdr:pi`) already reports main-agent `working`/`blocked`/`idle` +
36
41
  session ref. It is **read-only evidence**: never edited, reinstalled, or
@@ -39,7 +44,9 @@ explicitly in §10 and are not decided here.
39
44
  ### Style choice and reason
40
45
 
41
46
  - Style: **polled token sidecar** (same style as `herdr-pi-tree`): short-TTL
42
- `name=value` tokens on the pane, reduced by a snapshot poller.
47
+ `name=value` tokens on the pane, reduced by a snapshot poller, with one
48
+ `events.subscribe` wake so the drawing follows the report instead of the
49
+ clock (§8).
43
50
  - Reason (smallest fitting style): the transport, snapshot source, 16-token
44
51
  budget, TTL/expiry convention, and sidebar token-name mapping already exist
45
52
  and are deployed. A new push channel (SSE/WebSocket/webhook) or a new RPC
@@ -275,7 +282,7 @@ active (`agentActive`) and clears it (null) the moment the principal
275
282
  settles, keeping the same binding/TTL discipline. This is the principal-only
276
283
  signal: it carries exactly the principal input of `computeNativeState`, never
277
284
  the delegate aggregate, because the native status answers `working` for a
278
- running delegate, a pending launch, or a live job — none of which say the
285
+ running delegate or a pending launch — neither of which says the
279
286
  principal itself works. The native status keeps that aggregate meaning for
280
287
  Herdr's own pane state; the row's working-vs-idle decision reads only
281
288
  `gentle_principal_v1` (§5.2). It carries no count and alters neither the work
@@ -309,8 +316,9 @@ gentle_roles_v1 = role *("," role) ; total <= 512 UTF-8 bytes; null (cle
309
316
  gentle_orchestrating_v1 = sessionHash ":" expiry
310
317
  ; root-only presence marker, no count — fresh while the
311
318
  ; root main session actively works (even with zero subs),
312
- ; retaining running/queued-sub or pending-launch coverage;
313
- ; null (clear) once the main session settles
319
+ ; retaining running/queued-sub, pending-launch, or live
320
+ ; background-job coverage; null (clear) once the main
321
+ ; session settles
314
322
  gentle_principal_v1 = sessionHash ":" expiry
315
323
  ; principal-only activity marker, no count — fresh while
316
324
  ; the principal session's own agent is active
@@ -318,7 +326,7 @@ gentle_principal_v1 = sessionHash ":" expiry
318
326
  ; never its delegate aggregate), null (clear) once the
319
327
  ; principal settles; decides working vs idle in §5.2
320
328
  ; while the native status keeps its aggregate meaning
321
- ; (running delegate / pending launch / live job = working)
329
+ ; (running delegate / pending launch = working)
322
330
  gentle_done_v1 = sessionHash ":" expiry
323
331
  ; synthesized finish signal, no count — minted ONCE at the
324
332
  ; settled-and-empty edge (principal settled, zero
@@ -327,21 +335,14 @@ gentle_done_v1 = sessionHash ":" expiry
327
335
  ; republished with the SAME expiry (never refreshed) until
328
336
  ; it lapses; null (clear) whenever work reappears or the
329
337
  ; session resets. Its expiry IS the done hold: default
330
- ; 60 s, overridden by GENTLE_HERDR_DONE_HOLD_MS clamped to
331
- ; [1000, 300000], and the consumer accepts no expiry beyond
332
- ; now+300000 at read (the only token whose ceiling is not
333
- ; the 60 s TTL). A session that never worked never mints
334
- ; one.
335
- gentle_jobs_v1 = sessionHash ":" count ":" expiry
336
- ; pending background-job count (bash_background /
337
- ; monitor) from Gentle Shell's own session-scoped bus
338
- ; snapshot, session-bound + TTL-fresh like gentle_work_v1;
339
- ; emitted ONLY while the session is purely waiting on those
340
- ; jobs — principal settled, no running/queued delegate, no
341
- ; pending launch — and null (clear) the beat the principal
342
- ; resumes, a delegate starts, or the last job ends. Never
343
- ; a delegate count and never a finish: a settled session
344
- ; with a job pending is unfinished work.
338
+ ; 5 s (short on purpose — the hold only makes a finish
339
+ ; visible, it never pins a settled row, so `idle` follows
340
+ ; within seconds), overridden by
341
+ ; GENTLE_HERDR_DONE_HOLD_MS clamped to [1000, 300000], and
342
+ ; the consumer accepts no expiry beyond now+300000 at read
343
+ ; (the only token whose ceiling is not the 60 s TTL). The
344
+ ; daemon also caps its next sleep at that expiry (§8). A
345
+ ; session that never worked never mints one.
345
346
  gentle_ask_v1 = sessionHash ":" intentId ":" expiry
346
347
  ; durable ask signal, session-bound + TTL-fresh like
347
348
  ; gentle_orchestrating_v1 — emitted on every beat while
@@ -449,9 +450,6 @@ count), `gentle_principal_v1` (principal-only activity marker + freshness
449
450
  gate for the working-vs-idle decision — never rendered as a count),
450
451
  `gentle_done_v1` (synthesized finish signal + its own hold freshness gate
451
452
  for the reachable `done` display — the host never reports `done`, §4.3),
452
- `gentle_jobs_v1` (pending background-job count + freshness gate for the pink
453
- `job` wait — published only while the principal is settled with no delegate
454
- running or launching, §4.3),
455
453
  `gentle_roles_v1` (authoritative activity roles,
456
454
  oldest-first by immutable firstSeen), `gentle_names_v1` (compat transport only — never
457
455
  rendered), `gentle_changes_v2` (normative; a
@@ -470,7 +468,7 @@ review := herdr:blocked has review:* (fresh)
470
468
  principalWorking := fresh gentle_principal_v1 (session-bound, TTL-fresh) —
471
469
  the principal's OWN activity, never the delegate count and
472
470
  never the aggregate native status (which reads working for
473
- any running delegate, pending launch, or live job); renders
471
+ any running delegate or pending launch); renders
474
472
  `orchestrating` while a fresh gentle_orchestrating_v1 is
475
473
  live, otherwise working(main); outranks every delegate role
476
474
  word; stale, foreign, or absent falls through to the
@@ -483,22 +481,13 @@ role := gentle_work_v1 fresh AND gentle_roles_v1 yields a
483
481
  least two delegates run. Tool-only review has no suffix.
484
482
  orchestrating := gentle_orchestrating_v1 fresh with no role word above
485
483
  (root-only per §4.2: fresh while the main session actively
486
- works, even with zero subagents, retaining running/queued-sub
487
- or pending-launch coverage; absent/stale falls through to the
484
+ works, even with zero subagents, retaining running/queued-sub,
485
+ pending-launch, or live background-job coverage; absent/stale
486
+ falls through to the
488
487
  branches below; attention, terminal `done`/native-`blocked`,
489
488
  a working principal, and role words stay higher)
490
489
  working(main) := gentle_work_v1 fresh AND count > 0 with no role word
491
490
  OR (gentle_work_v1 fresh AND count = 0 AND agent not settled)
492
- job := fresh `gentle_jobs_v1` with count > 0 AND `gentle_work_v1`
493
- fresh with count = 0 (no running delegates) AND no roles AND
494
- no fresh `gentle_principal_v1` — the principal settled with no
495
- delegate running or launching while at least one background
496
- job still waits. Evaluated BEFORE `done` (a finish with a job
497
- pending is not finished) and below every attention state; a
498
- fresh `gentle_orchestrating_v1` does not block it (the marker
499
- stays live while the job runs). Any stale count, or a count
500
- that arrives beside a working principal/role, is ignored
501
- (fail closed).
502
491
  done := (native done OR fresh gentle_done_v1) AND gentle_work_v1
503
492
  fresh with count = 0 (no running delegates) AND no roles AND
504
493
  no fresh gentle_orchestrating_v1 AND no fresh
@@ -512,17 +501,14 @@ done := (native done OR fresh gentle_done_v1) AND gentle_work_v1
512
501
  idle := otherwise (native fallback; also all-gentle-tokens-missing-or-expired)
513
502
  ```
514
503
 
515
- Priority: `error > ask > review > job > done > principal working > role > orchestrating > working(main) > idle`.
516
- `job` is matched before `done` (a pending job is unfinished work) and both are
517
- matched before the principal/role branches in the reducer; they are listed here
518
- below the activity branches only so their settled-and-empty preconditions read
519
- together.
504
+ Priority: `error > ask > review > done > principal working > role > orchestrating > working(main) > idle`.
505
+ `done` is matched before the principal/role branches in the reducer; it is
506
+ listed here below the activity branches only so its settled-and-empty
507
+ precondition reads together.
520
508
  `blocked` labels are namespaced, so simultaneous
521
509
  `ask:` + `review:` resolves deterministically to `ask`. Attention states
522
510
  (error/ask/review) and the terminal `done` state always outrank principal
523
- status and activity roles. The pending-job `job` wait sits just above the
524
- terminal `done` and below every attention state and every live activity
525
- signal. Below them the principal's own activity decides,
511
+ status and activity roles. Below them the principal's own activity decides,
526
512
  never the delegate count and never the aggregate native status: a **working
527
513
  principal** renders `gentle` (pink
528
514
  `orchestrating` while a fresh root marker is live) and outranks every
@@ -547,19 +533,17 @@ marker, and only after the minted finish hold lapses does it recede to
547
533
  custom `$gentle_heading_*` / `$gentle_project` / `$gentle_agent` cells
548
534
  stay published and owned for compatibility but are wired into no visible
549
535
  row. Deleted lines stay red and added lines stay green (never swapped).
550
- The visible second row is structural, with no rules: the twelve
536
+ The visible second row is structural, with no rules: the eleven
551
537
  presence-encoded
552
- `gentle_title_<working|orchestrating|job|explorer|worker|verify|judge|ask|review|error|done|idle>`
538
+ `gentle_title_<working|orchestrating|explorer|worker|verify|judge|ask|review|error|done|idle>`
553
539
  state tokens (state word only: `working` / `gentle` (machine key
554
- `orchestrating`) / `job` / `explorer` / `worker` /
540
+ `orchestrating`) / `explorer` / `worker` /
555
541
  `verify` / `judge` / `ask` / `blocked` / `done` / `idle` / `review`;
556
- role words carry a running-count suffix above one, and the `job` word carries
557
- the pending-job count the same way).
542
+ role words carry a running-count suffix above one).
558
543
  Only the current display's title token carries a value; the rest are null.
559
544
  Each state cell carries its state's semantic color as its base fg with
560
545
  no rules — working/worker golden `#f9e2af`, orchestrating pink fuchsia
561
- `#f5c2e7`, job the same pink fuchsia `#f5c2e7` (a second pink wait state,
562
- distinct by wording from `gentle`), explorer blue `#89b4fa`, verify teal `#94e2d5`, judge purple
546
+ `#f5c2e7`, explorer blue `#89b4fa`, verify teal `#94e2d5`, judge purple
563
547
  `#cba6f7` (distinct from explorer blue, verify teal, orchestrating pink),
564
548
  ask orange `#fab387`, blocked red `#f38ba8`, done green `#a6e3a1`,
565
549
  idle grey `#7c7f93` (recedes), review blue `#89b4fa` (same as
@@ -577,11 +561,7 @@ marker, and only after the minted finish hold lapses does it recede to
577
561
  unsalvageable role shapes) |
578
562
  `gentle` (user-facing word for the `orchestrating` machine key — fresh
579
563
  root-session marker while the principal works, with or without active
580
- delegation, even with zero subagents; pink palette unchanged) | `job` (the
581
- pending background-job wait: principal settled, no delegate running or
582
- launching, at least one `bash_background` / `monitor` job still live; pink,
583
- with the pending total in parentheses above one; gone the beat the principal
584
- resumes or a delegate starts) | `explorer` / `worker` / `verify` / `judge` (oldest
564
+ delegation, even with zero subagents; pink palette unchanged) | `explorer` / `worker` / `verify` / `judge` (oldest
585
565
  TaskStore role word while the principal itself is idle, however many
586
566
  delegates run) | `ask` | `rdd` (user-facing word for the `review`
587
567
  machine key; a delegated rdd and a tool-only review both render `rdd` —
@@ -592,7 +572,7 @@ marker, and only after the minted finish hold lapses does it recede to
592
572
  running delegates keeps the role word) | `idle`. Role labels append the
593
573
  total count when at least two delegates run.
594
574
  - Row-2 changes: the nonempty `+N`/`-N`/`↑N` segments ride as their own
595
- structural row-2 cells after the twelve title cells (each its own color
575
+ structural row-2 cells after the eleven title cells (each its own color
596
576
  cell with no rules — added green, deleted red, pull blue, never
597
577
  swapped; empty segments collapse so nothing renders). `+N`/`-N` come
598
578
  from fresh `gentle_changes_v2`
@@ -612,8 +592,8 @@ marker, and only after the minted finish hold lapses does it recede to
612
592
  badge is never emitted (see the §4.3 versioning rule).
613
593
  - Placement: exactly two pi-only rows — row 1 the native `state_icon` +
614
594
  `workspace` + `agent` strings (3 cells, no custom wiring, no plugin
615
- colors), row 2 the twelve `gentle_title_*` state cells plus the three
616
- change-segment cells (15 cells: 12 state + 3 changes), each row within
595
+ colors), row 2 the eleven `gentle_title_*` state cells plus the three
596
+ change-segment cells (14 cells: 11 state + 3 changes), each row within
617
597
  Herdr's 16-token per-row ceiling — with the
618
598
  herdr-pi-tree palette (added green `#a6e3a1`,
619
599
  removed red `#f38ba8`, pull blue `#89b4fa`, working golden `#f9e2af`, ask
@@ -630,6 +610,84 @@ A signal is *fresh* iff its token parses (§4.3) and `expiry > now`. Stale or
630
610
  unparseable signals are dropped individually (one bad token never poisons the
631
611
  other two). All gentle signals stale/missing → `idle` (native fallback, O5).
632
612
 
613
+ ### 5.5 `gs`: the label for an isolated Gentle Shell pane
614
+
615
+ Herdr identifies an agent from the pane's foreground process group, and its
616
+ canonical aliases include `pi` and `gentle-shell` but never `gs`; a path prefix
617
+ is never consulted. An isolated Gentle Shell pane therefore has no Agents row
618
+ of its own unless this plugin supplies a label, which is why the label follows
619
+ a strict ladder that never lies about who owns the pane:
620
+
621
+ **Which panes belong to an isolated install.** The verified installation shape
622
+ is a user install under the XDG data dir — `<data>/gentle-shell/install`
623
+ (`$XDG_DATA_HOME/gentle-shell/install`, else
624
+ `~/.local/share/gentle-shell/install`), anchored by
625
+ `install/installation.json` (`gentle-shell-user-install/v1`, `Mode:
626
+ "separate"`), whose launcher starts the pane as `node
627
+ <root>/runtime/<channel>/bin/gentle-shell.mjs`. Qualification uses the same
628
+ input Herdr's detection reads, in this order:
629
+
630
+ - **Primary — the foreground process group.** A pane qualifies when any member
631
+ of its foreground process group exposes an argv / `argv0` / cmdline path that
632
+ resolves at or under the install root (a relative script path resolves
633
+ against that process's own cwd). This is what real panes look like: the
634
+ isolated pane is launched from the user's PROJECT directory, so its cwd is
635
+ never inside the install. A readable group with no install member is an
636
+ authoritative "no" — a cwd inside the root cannot override it.
637
+ - **Secondary — cwd.** Only when the group cannot be read at all (no
638
+ `pane.process-info` answer) does `cwd` / `foreground_cwd` at or under the root
639
+ decide, and an unreadable group never throws and never logs more than one
640
+ bounded line.
641
+
642
+ The root resolves from `GENTLE_SHELL_INSTALL_ROOT`, else the launcher's
643
+ `GENTLE_SHELL_HOME`, else the XDG data dir default. Windows keeps its own user
644
+ data dir (mirroring Herdr's `LOCALAPPDATA` state-dir convention) but is
645
+ unverified, which is why the manifest ships linux-only.
646
+
647
+ 1. **Detection first: display agent only.** A qualifying pane Herdr already
648
+ detects keeps Herdr's own truthful identity and live state. The plugin only
649
+ reports `--display-agent gs` through `pane.report-metadata`, which is
650
+ presentation-only and changes nothing about the state Herdr publishes.
651
+ 2. **Reported label as the last resort.** A qualifying pane Herdr does not
652
+ detect gets `pane report-agent --agent gs --state idle --source
653
+ plugin:<plugin-id>:gs`, because a row exists only for an agent terminal and
654
+ an undetected pane is not one. This is the only case in which the plugin
655
+ states an agent identity, and it states `gs` — never `pi`.
656
+ 3. **The report is reversible, never a mask.** Detection is a function of the
657
+ pane's foreground process group, so an unchanged group owes no re-check
658
+ while a changed one means a real agent may now be present. On that change the
659
+ plugin releases exactly its own authority (`pane release-agent`, same
660
+ source, label `gs`) and re-decides, keeping the display label: `gs` never
661
+ masks a real `pi` / `gentle-shell` detection for longer than one beat.
662
+ 4. **Release on the way out.** `pane.exited` / `pane.closed`, a pane that
663
+ leaves the qualifying set, a disabled sidebar, and daemon shutdown all clear
664
+ what this plugin reported — authority first, then the display label.
665
+ Authority this plugin did not set is never touched: both the source and the
666
+ label are part of every release.
667
+
668
+ `gs` is not a canonical Herdr agent, so `rows_by_agent.gs` is a configuration
669
+ error rather than an inert key: `rows_by_agent` stays keyed by a canonical
670
+ agent (`pi`), and `gs` exists only as a label.
671
+
672
+ Discovery — one bounded `pane list` read plus one `pane.process-info` per pane
673
+ (the read qualification needs; capped, and a scan pays for no answer twice) —
674
+ runs at daemon start, on an explicit `--refresh` (a separate request marker, so
675
+ the producer's per-beat refresh never triggers one), and on a roster event
676
+ (`pane.created`, `pane.closed`, `pane.moved`, `pane.exited`,
677
+ `pane.agent_detected`); never per frame. The only per-frame call is the
678
+ foreground re-check of a pane this plugin currently reports. Every write is
679
+ deduped against what the plugin already reported, every interpolated value is
680
+ checked against a strict identifier grammar before it reaches a fixed argv, and
681
+ any failure (no `pane list`, a CLI error, a disabled sidebar, an unreadable mode
682
+ flag) does nothing to the existing behavior and logs one bounded line per
683
+ distinct reason.
684
+
685
+ One thing this design cannot fix: the gs pane's own live state. Herdr reports
686
+ state for an agent terminal it knows, and the isolated install does not forward
687
+ `HERDR_ENV` to the pane's agent, so `gs` is a label on a row whose state is
688
+ Herdr's own (`idle` in the reported fallback). Forwarding that environment is a
689
+ gentle-ai concern and explicitly out of scope for this plugin.
690
+
633
691
  ## 6. Failure, retry, idempotency
634
692
 
635
693
  - Delivery is at-least-once snapshots over an unreliable beat: producer
@@ -732,7 +790,7 @@ report after a Pi restart or `/new` (both recreate the extension runtime)
732
790
  lose, freezing the pane's `agent_session` binding at the old session while
733
791
  the producer keeps beating for the new one — the consumer then rejects those
734
792
  fresh tokens as a session-hash mismatch and the pane stays on `idle` until a
735
- 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; an absent Gentle Shell simply reports none (today's behavior). While such a job waits with the principal settled and no delegate running or launching, the producer publishes the pending count as `gentle_jobs_v1` so the sidebar shows the pink `job` wait (§5.2); the count clears on the beat the principal resumes, a delegate starts, or the last job ends. `blocked` only for a real principal-stopped error or an actual human-wait intervention leg with its label (review/RDD execution stays `working`, silent). 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
793
+ 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). 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 a real principal-stopped error or an actual human-wait intervention leg with its label (review/RDD execution stays `working`, silent). 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
736
794
  reversibly (`-extensions/herdr-agent-state.ts` in Pi settings, bytes
737
795
  preserved on disk, never auto-loaded next to ours). `node
738
796
  bin/gentle-sidebar.js (enable|disable|status|toggle)` selects the
@@ -801,18 +859,18 @@ exactly one mechanism writes each piece of state.
801
859
  ## 8. Limits
802
860
 
803
861
  - Token budget: ≤ 16 tokens per report per pane (E8 discipline); the
804
- producer emits at most 12 tokens per beat (including the retired-token clear) (`gentle_work_v1`,
862
+ producer emits at most 11 tokens per beat (including the retired
863
+ `gentle_subs_v1` clear) (`gentle_work_v1`,
805
864
  `gentle_roles_v1`, `gentle_names_v1`,
806
865
  `gentle_orchestrating_v1`, `gentle_principal_v1`, `gentle_done_v1`,
807
- `gentle_jobs_v1`, `gentle_ask_v1`, `gentle_review_v1`, `gentle_changes_v2`,
808
- `gentle_changes_v1`) and the daemon publishes its 78-token owned family
866
+ `gentle_ask_v1`, `gentle_review_v1`, `gentle_changes_v2`,
867
+ `gentle_changes_v1`) and the daemon publishes its 72-token owned family
809
868
  chunked ≤ 16 per report (row 1 is the 3 native tokens
810
- `state_icon`/`workspace`/`agent`; the legacy 12 `gentle_heading_*` compat
811
- family stays published but wired into no visible row. Row 2 wires 12
812
- title + 3 change cells = 15 — each within the per-row ceiling). Names are
869
+ `state_icon`/`workspace`/`agent`; the legacy 11 `gentle_heading_*` compat
870
+ family stays published but wired into no visible row. Row 2 wires 11
871
+ title + 3 change cells = 14 — each within the per-row ceiling). Names are
813
872
  advisory; roles are authoritative for display and role labels carry the
814
- running total as a suffix when at least two delegates run, the job label the
815
- pending-job total the same way.
873
+ running total as a suffix when at least two delegates run.
816
874
  - TTL: `expiry <= now + 60000` at write; readers use `now` at read.
817
875
  Clock skew assumption ≤ 5 s (documented; not compensated).
818
876
  - Field bounds: `count` ≤ 16 digits; `label` ≤ 64 chars; names/roles
@@ -821,11 +879,58 @@ exactly one mechanism writes each piece of state.
821
879
  - Poll cadence: resolved — must be ≪ 60 s TTL to avoid flapping
822
880
  (see §10 U2). The daemon runs an adaptive poll (10 s baseline,
823
881
  `GENTLE_STATUS_POLL_MS`-overridable, 2 s fast cycle
824
- (`GENTLE_STATUS_FAST_POLL_MS`) while recent ask activity or send/publish
825
- failures are observed, recovering after N quiet frames
882
+ (`GENTLE_STATUS_FAST_POLL_MS`) while recent ask activity, a rendered
883
+ non-idle display, or send/publish failures are observed, recovering after
884
+ N quiet frames
826
885
  (`GENTLE_STATUS_FAST_QUIET_FRAMES`) or a TTL-bounded window
827
886
  (`GENTLE_STATUS_FAST_WINDOW_MS`), 250 ms floor, single dynamic
828
- `setTimeout` chain.
887
+ `setTimeout` chain. The active-display trigger exists because the row data
888
+ the daemon derives by itself — the `+N/-N` changes summary and the `↑N`
889
+ pull marker, read from local git plus `agent.list` — cannot be driven by a
890
+ producer report; only `idle` counts as settled, so an idle pane keeps the
891
+ baseline exactly.
892
+ Drawing is event-synchronized; polling is only the fallback. Every landed
893
+ producer beat requests the daemon's ONE coalesced refresh (the same request
894
+ file `--refresh` touches, §10 U2), so a report that changes state draws an
895
+ immediate frame instead of waiting for the next poll — the event lands on
896
+ time AND the drawing follows it. N reports in one window collapse into one
897
+ frame, and refresh-driven frames are floored at 250 ms after the frame that
898
+ started the sleep, so a report storm can never spin the loop.
899
+ The token path is also subscription-driven: the daemon holds exactly ONE
900
+ long-lived socket `events.subscribe` for `pane.updated` (plus the roster
901
+ kinds `pane.created`, `pane.closed`, `pane.moved`), because
902
+ `pane.report_metadata` bumps the pane revision and Herdr then emits
903
+ `pane.updated` with the full pane payload. Herdr repaints push-driven on that
904
+ write plus its metadata-TTL expiry, so a token write no longer waits for the
905
+ poll. An event does nothing but set ONE dirty flag and wake that
906
+ same sleep: the flag is consumed with the refresh request into a single
907
+ frame, so a burst collapses to one frame, there is no second frame loop, no
908
+ timer, no per-event frame, no queue (bounded memory is that one boolean) and
909
+ no frame sooner than the same `refreshGateMs`/`POLL_MIN_MS` floor. A
910
+ manifest `[[events]]` hook cannot do this and must not be tried again:
911
+ `pane.updated` is deliberately excluded from the 22-name hook surface
912
+ (`PLUGIN_HOOK_EVENT_KINDS`), and the runtime filter drops non-hook kinds, so
913
+ `on = "pane.updated"` in `herdr-plugin.toml` is inert. Reconnect is bounded
914
+ and single-flight: 1 s doubling to a 60 s cap, reset only after a connection
915
+ that stayed live 5 s, so a Herdr restart reconnects promptly while a server
916
+ that accepts and drops climbs to the cap instead of flapping. A rejected,
917
+ closed, or unanswered subscription logs one line per distinct reason and
918
+ changes nothing else — the poll below is unchanged and correct without it.
919
+ Shutdown closes the socket and its retry timer, and neither keeps the process
920
+ alive. Idle cost with no events is exactly today's: an idle subscription is
921
+ silent and the loop sleeps as before.
922
+ What the subscription can never drive stays poll-only: the row data the
923
+ daemon derives by itself — the `+N/-N` changes summary and the `↑N` pull
924
+ marker, read from local git plus `agent.list` — plus the presence prefix,
925
+ because Herdr emits no event for either. That is why the fast cycle is armed
926
+ by a rendered non-idle display, and why polling is never removed.
927
+ The sleep is also capped at the nearest live `gentle_done_v1` expiry among
928
+ the panes just rendered (never below the 250 ms floor), so a held `done`
929
+ row reaches `idle` when the hold lapses rather than up to one poll later.
930
+ A pending expiry may only SHORTEN the delay: with no pending expiry the
931
+ delay is exactly the adaptive value above, and an already-expired or
932
+ unparseable value falls to the floor (fail closed, like every parser)
933
+ rather than returning 0.
829
934
  The four lifecycle hooks (`pane.agent_detected`, `pane.agent_status_changed`,
830
935
  `pane.exited`, `pane.closed`) each run `node bin/gentle-status.js --refresh`
831
936
  (daemon ensure plus one coalesced immediate frame), not the cadence itself;
@@ -839,12 +944,11 @@ exactly one mechanism writes each piece of state.
839
944
  - Additive only in v1: new token names (`gentle_work_v1`,
840
945
  `gentle_roles_v1`, `gentle_names_v1`,
841
946
  `gentle_orchestrating_v1`, `gentle_principal_v1`, `gentle_done_v1`,
842
- `gentle_jobs_v1`,
843
947
  `gentle_ask_v1`, `gentle_review_v1`, `gentle_changes_v1`, `gentle_changes_v2`,
844
948
  `gentle_state_*`, `gentle_title_*`, `gentle_agent_*`, `gentle_agent`,
845
949
  `gentle_icon_*`,
846
950
  `gentle_heading_*`, `gentle_project`, `gentle_row_*` (each family now
847
- includes the `judge` and `job` displays alongside the original ten), plus display-only
951
+ includes the `judge` display alongside the original ten), plus display-only
848
952
  `gentle_changes_added`, `gentle_changes_deleted`,
849
953
  `gentle_changes_pull`, `gentle_changes_summary`); no change to `pi_subagents_work_v1`, `state_*`,
850
954
  `title_*`, or native `working`/`blocked`/`idle` semantics.
@@ -905,7 +1009,12 @@ exactly one mechanism writes each piece of state.
905
1009
  — each invoke `node bin/gentle-status.js --refresh` (L6: daemon ensure
906
1010
  plus one coalesced immediate frame, never a second writer loop), while
907
1011
  `[[startup]]` (no args) remains the polling-daemon bootstrap and polling
908
- remains the fallback for every lifecycle signal. `--once` keeps its
1012
+ remains the fallback for every lifecycle signal. The producer extension is
1013
+ the second requester of that same coalesced refresh — it requests one after
1014
+ every landed token beat, so a status change it publishes is drawn at once
1015
+ rather than at the next poll — and the daemon caps each sleep at the nearest
1016
+ live `gentle_done_v1` expiry (§8), so `idle` does not wait for a poll either.
1017
+ Neither requester renders a frame or writes tokens. `--once` keeps its
909
1018
  existing one-frame public behavior for manual use and is not wired as a
910
1019
  hook. Runtime proofs of the `--refresh` contract belong to the lifecycle
911
1020
  unit's tests, not this protocol record.
package/README.md CHANGED
@@ -215,6 +215,10 @@ encoding), so row 2 shows the current state word plus any nonempty change
215
215
  segments while the rest render empty; native separators on row 2 are
216
216
  acceptable. Row 1 holds 3 native cells and row 2 holds 14 cells (11 state
217
217
  + 3 changes), each within Herdr's 16-token per-row ceiling (full block below).
218
+ The `gs` label of an isolated Gentle Shell pane needs no key here: `gs` is not
219
+ one of Herdr's canonical agents, so `rows_by_agent.gs` is a configuration error
220
+ rather than an inert key. Only the daemon's label ladder (DESIGN.md §5.5)
221
+ makes that row appear, and `rows_by_agent` stays keyed by the canonical `pi`.
218
222
 
219
223
  ```toml
220
224
  # BEGIN herdr-gentle-agents (managed; do not edit)
@@ -222,7 +226,7 @@ acceptable. Row 1 holds 3 native cells and row 2 holds 14 cells (11 state
222
226
  # row 1 native state_icon + workspace + agent, row 2 state word + changes.
223
227
  # The parent [ui.sidebar.agents] table is user-owned and never touched here.
224
228
  [ui.sidebar.agents.rows_by_agent]
225
- pi = [["state_icon", "workspace", "agent"], [{ token = "$gentle_title_working", fg = "#f9e2af" }, { token = "$gentle_title_orchestrating", fg = "#f5c2e7" }, { token = "$gentle_title_job", fg = "#f5c2e7" }, { token = "$gentle_title_explorer", fg = "#89b4fa" }, { token = "$gentle_title_worker", fg = "#f9e2af" }, { token = "$gentle_title_verify", fg = "#94e2d5" }, { token = "$gentle_title_judge", fg = "#cba6f7" }, { token = "$gentle_title_ask", fg = "#fab387" }, { token = "$gentle_title_review", fg = "#89b4fa" }, { token = "$gentle_title_error", fg = "#f38ba8" }, { token = "$gentle_title_done", fg = "#a6e3a1" }, { token = "$gentle_title_idle", fg = "#7c7f93" }, { token = "$gentle_changes_added", fg = "#a6e3a1" }, { token = "$gentle_changes_deleted", fg = "#f38ba8" }, { token = "$gentle_changes_pull", fg = "#89b4fa" }]]
229
+ pi = [["state_icon", "workspace", "agent"], [{ token = "$gentle_title_working", fg = "#f9e2af" }, { token = "$gentle_title_orchestrating", fg = "#f5c2e7" }, { token = "$gentle_title_explorer", fg = "#89b4fa" }, { token = "$gentle_title_worker", fg = "#f9e2af" }, { token = "$gentle_title_verify", fg = "#94e2d5" }, { token = "$gentle_title_judge", fg = "#cba6f7" }, { token = "$gentle_title_ask", fg = "#fab387" }, { token = "$gentle_title_review", fg = "#89b4fa" }, { token = "$gentle_title_error", fg = "#f38ba8" }, { token = "$gentle_title_done", fg = "#a6e3a1" }, { token = "$gentle_title_idle", fg = "#7c7f93" }, { token = "$gentle_changes_added", fg = "#a6e3a1" }, { token = "$gentle_changes_deleted", fg = "#f38ba8" }, { token = "$gentle_changes_pull", fg = "#89b4fa" }]]
226
230
  # END herdr-gentle-agents
227
231
  ```
228
232
 
@@ -241,8 +245,8 @@ renders for generic activity (machine key `working`): the main agent when settle
241
245
  retaining running-subagent or pending-launch coverage. The principal's own
242
246
  activity decides the row, never the delegate count and never Herdr's
243
247
  aggregate native status (the work token counts running delegates, and the
244
- native status reads `working` for any running delegate, pending launch, or
245
- live job — so neither can say the principal works): the dedicated
248
+ native status reads `working` for any running delegate or pending launch — so
249
+ neither can say the principal works): the dedicated
246
250
  `gentle_principal_v1` marker is published while the principal session itself
247
251
  works and cleared when it settles. A **working principal** reads `gentle` —
248
252
  pink
@@ -310,13 +314,25 @@ and TTL discipline as `herdr-pi-tree`, new token names, no new socket or
310
314
  webhook. `[[startup]] node bin/gentle-status.js` (no args) is the polling-daemon
311
315
  bootstrap (ensures the adaptive poll daemon is running: 10 s baseline,
312
316
  `GENTLE_STATUS_POLL_MS`-overridable, with a 2 s fast cycle while recent ask
313
- activity or send/publish failures are observed); `[[events]] on =
314
- "pane.agent_detected"`, `pane.agent_status_changed`, `pane.exited`, and
317
+ activity, a rendered non-idle display, or send/publish failures are observed);
318
+ `[[events]] on = "pane.agent_detected"`, `pane.agent_status_changed`,
319
+ `pane.exited`, and
315
320
  `pane.closed` each run `node bin/gentle-status.js --refresh`, which ensures the
316
321
  adaptive poll daemon is running and requests one coalesced immediate frame
317
322
  so a newly opened project name/state renders without waiting for the next
318
- poll tick. Polling stays the fallback for every lifecycle signal, so a missed
319
- or undelivered event never sticks. Read-only
323
+ poll tick. Drawing follows the report, not the clock: the daemon also holds one
324
+ long-lived `events.subscribe` for `pane.updated`, so a token write Herdr already
325
+ repaints for wakes the same single frame loop (bounded reconnect, floored at
326
+ 250 ms, no second loop, no per-event frame), and the producer requests that same
327
+ coalesced refresh after every landed token beat, so a status change
328
+ it publishes is drawn at once, and the daemon caps each sleep at the nearest
329
+ live `done` expiry, so a settled row reaches `idle` when its short hold (5 s by
330
+ default, `GENTLE_HERDR_DONE_HOLD_MS`-overridable) lapses instead of one poll
331
+ later. Reports in one window collapse into one frame, and refresh-driven frames
332
+ are floored at 250 ms, so a burst can never spin the daemon. Polling stays the
333
+ fallback for every lifecycle signal and the only source for what no Herdr event
334
+ carries (the git-derived `+N/-N` and `↑N` row data and the presence prefix), so a
335
+ missed, undelivered, or rejected event never sticks. Read-only
320
336
  supervision triage ships beside it: the `doctor` and `whois` plugin actions
321
337
  (`node bin/gentle-doctor.js`, `node bin/gentle-whois.js`) plus the explicit-pane
322
338
  `node bin/gentle-trace.js <pane-id>` CLI — all read-only, none mutating state.
@@ -354,6 +370,31 @@ See [DESIGN.md](DESIGN.md) §4 (producer) and §5 (consumer), and
354
370
  session model and never carried across sessions.
355
371
  - Single-writer coexistence with `herdr-pi-tree`: no shared token names, no
356
372
  dual-write, scoped sweep of own tokens on handover.
373
+ - An isolated Gentle Shell pane gets a `gs` row in the Agents sidebar, and the
374
+ label never lies. Herdr identifies an agent from the pane's foreground
375
+ process group, whose canonical aliases are `pi` and `gentle-shell` — never
376
+ `gs` — so an isolated pane is detected only when its foreground group exposes
377
+ the gentle-shell process, and otherwise has no row at all. Qualification uses
378
+ that same input first: a pane belongs to the isolated install when a member of
379
+ its foreground process group exposes an argv/`argv0`/cmdline path under
380
+ `$XDG_DATA_HOME/gentle-shell/install` (else
381
+ `~/.local/share/gentle-shell/install`, anchored by `install/installation.json`)
382
+ — a real pane is launched from the user's project directory, so its cwd is
383
+ never the install, and cwd is only the fallback for an unreadable group. When
384
+ Herdr detects the pane, the daemon keeps Herdr's truthful identity and state
385
+ and only reports the presentation-only `--display-agent gs` label; when Herdr
386
+ detects nothing, it reports `pane report-agent --agent gs --state idle` from a
387
+ stable per-session source (`plugin:<plugin-id>:gs`) so the row exists at all.
388
+ That reported label is the last resort and is reversible: a changed foreground
389
+ group (the only thing that can make a new detection appear) releases exactly
390
+ this plugin's authority and re-decides within one beat, and `pane.exited` /
391
+ `pane.closed`, a pane leaving the install, a disabled sidebar, and daemon
392
+ shutdown all release it too. Discovery is one bounded `pane list` read plus
393
+ one `pane.process-info` per pane at start, on an explicit `--refresh`, and on
394
+ roster events — never per frame; writes are deduped, and a failure does
395
+ nothing and logs one line per reason. The gs pane's own live state stays
396
+ unobservable until the isolated install forwards `HERDR_ENV` to its agent (a
397
+ gentle-ai concern, out of scope here).
357
398
  - 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 a real error or an actual human-wait intervention leg with its label (review/RDD execution stays `working`, silent). 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.
358
399
  - Sidebar switch (`enable` / `disable` / `status` / `toggle`):
359
400
  `node bin/gentle-sidebar.js <verb>` picks between this plugin's sidebar rows
@@ -698,22 +698,27 @@ const BEAT_MS = 15000;
698
698
  // `<hash>:<expiry>` token per finish at the settled-and-empty edge, carrying
699
699
  // the hold as its absolute expiry. The sidebar reads it as `done` while it is
700
700
  // fresh and recedes to `idle` once it expires — the delay IS that expiry, so
701
- // no timer and no extra idle hold exists. The hold defaults to 60 s and is
702
- // overridden through GENTLE_HERDR_DONE_HOLD_MS, clamped to [1 s, 5 min]; the
703
- // consumer rejects any expiry beyond the same ceiling.
701
+ // no timer and no extra idle hold exists. The hold is short on purpose (5 s):
702
+ // it exists to make a finish visible, never to pin a settled row, so `idle`
703
+ // follows the finish within seconds. Overridden through
704
+ // GENTLE_HERDR_DONE_HOLD_MS, clamped to [1 s, 5 min]; the consumer rejects any
705
+ // expiry beyond the same ceiling.
704
706
  const DONE_TOKEN = "gentle_done_v1";
705
- const DONE_HOLD_MS = 60000;
707
+ const DONE_HOLD_MS = 5000;
706
708
  const DONE_HOLD_MIN_MS = 1000;
707
709
  export const DONE_HOLD_MAX_MS = 300000;
708
710
  const DONE_HOLD_ENV = "GENTLE_HERDR_DONE_HOLD_MS";
709
- // Pending background-job count (DESIGN §4.3, S5/D4): the same
710
- // `<hash>:<count>:<expiry>` shape as gentle_work_v1, but carrying the number of
711
- // live `bash_background` / `monitor` jobs from Gentle Shell's own snapshot and
712
- // published ONLY while the session is purely waiting for them — the principal
713
- // settled, no delegate running, no launch pending — so the sidebar can show the
714
- // pink `job` state instead of generic activity. Cleared on the next beat once
715
- // the principal resumes, a delegate starts, or the last job ends.
716
- const JOBS_TOKEN = "gentle_jobs_v1";
711
+ // Staleness bound for the background-job snapshot. Gentle Shell emits
712
+ // `gentle-ai:jobs-sidebar` on job EDGES only — start, monitor line batch, stop,
713
+ // exit, session shutdown (`refreshJobStatus` in extensions/gentle-agents.ts has
714
+ // no periodic caller) — so a silent `bash_background` job never refreshes it. A
715
+ // snapshot older than this bound therefore counts as ZERO jobs: fail OPEN.
716
+ // Finishing while a job silently runs is a nuisance; latching the session
717
+ // non-terminal on a snapshot that no longer describes the session is the
718
+ // incident this bound exists to prevent (odd/tasks/restore-done-idle.md). Five
719
+ // minutes is the generous end of the [30 s, 5 min] band: a job longer than this
720
+ // fails open early, and a missed exit event delays `done` by at most this long.
721
+ export const JOBS_SNAPSHOT_TTL_MS = 300000;
717
722
  const MAX_TOKENS_PER_REPORT = 16;
718
723
  const MAX_LABEL_CHARS = 64;
719
724
  // Herdr's wire ceiling for a single pane-metadata token value, measured in
@@ -738,9 +743,7 @@ const QUESTIONNAIRE_EVENT = "rpiv:ask-user:blocked";
738
743
  const PERMISSION_EVENT = "pi-permission-system:permission-request";
739
744
  // Gentle Shell's live background jobs (`bash_background` / `monitor`) are
740
745
  // published on the Pi event bus, session-scoped and display-only:
741
- // `{ sessionId, snapshot: { jobs: [{ id, label, startedAt }] } }`. A live job
742
- // is pending work exactly like a running delegate, so it must keep the
743
- // session non-terminal.
746
+ // `{ sessionId, snapshot: { jobs: [{ id, label, startedAt }] } }`.
744
747
  const JOBS_SIDEBAR_EVENT = "gentle-ai:jobs-sidebar";
745
748
  // Neither `gentle-pi:review:blocked` (reserved hook: no producer exists) nor
746
749
  // `gentle-ai:review-sidebar` snapshots (entry publishes fire before the
@@ -851,7 +854,7 @@ function utf8Bytes(value) {
851
854
  return Buffer.byteLength(value, "utf8");
852
855
  }
853
856
 
854
- // Finish-hold override: an absent or unparseable value keeps the 60 s
857
+ // Finish-hold override: an absent or unparseable value keeps the 5 s
855
858
  // default, and anything outside the ceiling is clamped, so the producer can
856
859
  // never publish an expiry the consumer reads as foreign.
857
860
  export function doneHoldMs(raw = process.env[DONE_HOLD_ENV]) {
@@ -939,7 +942,7 @@ function sendRequestAttempt(request, timeoutMs) {
939
942
  if (timeout) clearTimeout(timeout);
940
943
  try {
941
944
  socket.destroy();
942
- } catch {}
945
+ } catch { /* best effort: a failure here is non-fatal */ }
943
946
  resolve(delivered);
944
947
  };
945
948
  let socket;
@@ -1043,7 +1046,7 @@ function cliFallback(patch) {
1043
1046
  const timer = setTimeout(() => {
1044
1047
  try {
1045
1048
  child.kill();
1046
- } catch {}
1049
+ } catch { /* best effort: a failure here is non-fatal */ }
1047
1050
  finish(false);
1048
1051
  }, CLI_FALLBACK_TIMEOUT_MS);
1049
1052
  if (timer.unref) timer.unref();
@@ -1093,25 +1096,16 @@ export function computeNativeState({
1093
1096
  settled,
1094
1097
  activeCount,
1095
1098
  pendingCount,
1096
- jobCount = 0,
1097
1099
  askActive,
1098
1100
  reviewActive,
1099
1101
  hasError,
1100
1102
  }) {
1101
1103
  if (hasError) return "blocked";
1102
1104
  if (askActive) return "blocked";
1103
- if (agentActive || activeCount > 0 || pendingCount > 0 || jobCount > 0 || reviewActive) {
1105
+ if (agentActive || activeCount > 0 || pendingCount > 0 || reviewActive) {
1104
1106
  return "working";
1105
1107
  }
1106
- if (
1107
- settled &&
1108
- !agentActive &&
1109
- activeCount === 0 &&
1110
- pendingCount === 0 &&
1111
- jobCount === 0 &&
1112
- !askActive &&
1113
- !reviewActive
1114
- ) {
1108
+ if (settled && !agentActive && activeCount === 0 && pendingCount === 0 && !askActive && !reviewActive) {
1115
1109
  return "idle";
1116
1110
  }
1117
1111
  return undefined;
@@ -1420,7 +1414,7 @@ function liveRunGit(root, args) {
1420
1414
  }
1421
1415
  let stdout = "";
1422
1416
  const timer = setTimeout(() => {
1423
- try { child.kill(); } catch {}
1417
+ try { child.kill(); } catch { /* best effort: a failure here is non-fatal */ }
1424
1418
  finish({ stdout, code: 1, error: `timed out after ${LIVE_GIT_TIMEOUT_MS}ms` });
1425
1419
  }, LIVE_GIT_TIMEOUT_MS + 500);
1426
1420
  if (timer.unref) timer.unref();
@@ -1573,6 +1567,30 @@ function sidebarEffectiveDir() {
1573
1567
  return injected;
1574
1568
  }
1575
1569
 
1570
+ // Status-refresh request file, owned by the consumer daemon: a single
1571
+ // timestamp that `bin/gentle-status.js --refresh` also writes. Reading it (not
1572
+ // spawning) is the whole point — the daemon loop deletes it and draws one
1573
+ // frame, so N beats in one window collapse into one wake and this extension
1574
+ // never renders a frame, never writes a pidfile, and never starts a second
1575
+ // writer loop (DESIGN §8, §10 U2).
1576
+ const STATUS_REFRESH_FILE = "gentle-status.refresh";
1577
+
1578
+ // Event-synchronized drawing: the daemon CANNOT see a report as it lands — it
1579
+ // polls the Herdr snapshot — so without this request a state change stays
1580
+ // invisible for up to one whole baseline poll, which is the sidebar lag. Every
1581
+ // landed beat therefore requests the daemon's coalesced refresh: the drawing
1582
+ // follows the report, and polling stays pure fallback. Best effort by design:
1583
+ // a missing state dir or a read-only filesystem degrades to polling only.
1584
+ function requestStatusRefresh() {
1585
+ if (!enabled()) return false;
1586
+ try {
1587
+ fs.writeFileSync(join(sidebarEffectiveDir(), STATUS_REFRESH_FILE), String(Date.now()), "utf8");
1588
+ return true;
1589
+ } catch {
1590
+ return false;
1591
+ }
1592
+ }
1593
+
1576
1594
  // Optional Moshi notification mirror (DESIGN §7): one flag file, read per
1577
1595
  // event. The producer extension owns it; the consumer daemon never publishes
1578
1596
  // to Moshi (single emitter). Enabling is the flag plus, while
@@ -1675,7 +1693,7 @@ function moshiSendEnvelope(envelope) {
1675
1693
  sock.on("error", () => {
1676
1694
  try {
1677
1695
  sock.destroy();
1678
- } catch {}
1696
+ } catch { /* best effort: a failure here is non-fatal */ }
1679
1697
  });
1680
1698
  sock.once("connect", () => {
1681
1699
  sock.write(`${JSON.stringify(envelope)}\n`);
@@ -1790,7 +1808,7 @@ function moshiSessionIsChild(file) {
1790
1808
  } finally {
1791
1809
  try {
1792
1810
  fs.closeSync(fd);
1793
- } catch {}
1811
+ } catch { /* best effort: a failure here is non-fatal */ }
1794
1812
  }
1795
1813
  moshiChildCache.set(file, child);
1796
1814
  return child;
@@ -2151,7 +2169,7 @@ function writeSettingsDoc(path, doc) {
2151
2169
  } catch (error) {
2152
2170
  try {
2153
2171
  fs.rmSync(temp, { force: true });
2154
- } catch {}
2172
+ } catch { /* best effort: a failure here is non-fatal */ }
2155
2173
  throw error;
2156
2174
  }
2157
2175
  }
@@ -2535,13 +2553,17 @@ export default function (pi) {
2535
2553
  let moshiCtxRef;
2536
2554
  let lastAskToolName;
2537
2555
 
2538
- // Live background jobs (Gentle Shell `bash_background` / `monitor`), from
2539
- // the bus snapshot. Session-scoped: a snapshot owned by another session
2540
- // never counts here.
2556
+ // Live background jobs (Gentle Shell `bash_background` / `monitor`) from the
2557
+ // bus snapshot: session-scoped, edge-emitted, and therefore a hint with a
2558
+ // freshness bound rather than proof. A live job is PENDING WORK — it holds
2559
+ // the finish mint and keeps the row on the pink generic `gentle` wait — but
2560
+ // it is never a display state of its own: no job count is published and no
2561
+ // `job` token exists to render (odd/tasks/restore-done-idle.md).
2541
2562
  let jobsSnapshot;
2542
2563
 
2543
- function runningJobCount() {
2564
+ function freshRunningJobCount() {
2544
2565
  if (!jobsSnapshot) return 0;
2566
+ if (Date.now() - jobsSnapshot.at > JOBS_SNAPSHOT_TTL_MS) return 0;
2545
2567
  const owner = jobsSnapshot.sessionId;
2546
2568
  const mine = sessionId;
2547
2569
  if (
@@ -2557,8 +2579,8 @@ export default function (pi) {
2557
2579
  }
2558
2580
 
2559
2581
  // A job starting or ending is a state change: publish immediately so the
2560
- // sidebar and the native report follow it, and keep the beat alive while
2561
- // jobs run (the marker has its own TTL).
2582
+ // `gentle` wait and the finish gate follow it. `at` is the arrival time the
2583
+ // freshness bound measures from.
2562
2584
  function onJobsSnapshot(value) {
2563
2585
  if (!isRecord(value) || !isRecord(value.snapshot) || !Array.isArray(value.snapshot.jobs)) return;
2564
2586
  const jobs = value.snapshot.jobs.filter(
@@ -2567,14 +2589,14 @@ export default function (pi) {
2567
2589
  jobsSnapshot = {
2568
2590
  sessionId: typeof value.sessionId === "string" ? value.sessionId : undefined,
2569
2591
  jobs,
2592
+ at: Date.now(),
2570
2593
  };
2571
2594
  schedulePublish();
2572
2595
  }
2573
2596
 
2574
2597
  // Subscribed before the `enabled()` guard would matter: the bus event is
2575
- // session-scoped display data, so it is safe to observe anywhere. Hosts
2576
- // whose runtime has no event bus simply never see it (jobs stay at zero,
2577
- // which is today's behavior).
2598
+ // session-scoped display data, so it is safe to observe anywhere. Hosts whose
2599
+ // runtime has no event bus never see it (jobs stay at zero).
2578
2600
  if (typeof pi?.events?.on === "function") pi.events.on(JOBS_SIDEBAR_EVENT, onJobsSnapshot);
2579
2601
 
2580
2602
  function moshiCapture(ctx) {
@@ -2718,7 +2740,7 @@ export default function (pi) {
2718
2740
  try {
2719
2741
  const cwd = ctx?.cwd;
2720
2742
  if (typeof cwd === "string" && cwd.length > 0) sessionCwd = cwd;
2721
- } catch {}
2743
+ } catch { /* best effort: a failure here is non-fatal */ }
2722
2744
  try {
2723
2745
  const file = ctx?.sessionManager?.getSessionFile?.();
2724
2746
  if (typeof file === "string" && file.length > 0) {
@@ -2731,7 +2753,7 @@ export default function (pi) {
2731
2753
  try {
2732
2754
  const id = ctx?.sessionManager?.getSessionId?.();
2733
2755
  if (typeof id === "string" && id.length > 0) sessionId = id;
2734
- } catch {}
2756
+ } catch { /* best effort: a failure here is non-fatal */ }
2735
2757
  }
2736
2758
 
2737
2759
  function askActiveNow() {
@@ -2783,7 +2805,7 @@ export default function (pi) {
2783
2805
  emittedLabel = undefined;
2784
2806
  try {
2785
2807
  pi.events.emit(BLOCKED_EVENT, { active: false });
2786
- } catch {}
2808
+ } catch { /* best effort: a failure here is non-fatal */ }
2787
2809
  }
2788
2810
  return;
2789
2811
  }
@@ -3024,14 +3046,17 @@ export default function (pi) {
3024
3046
  // emitted by the root Pi session while the main session is actively
3025
3047
  // working (agentActive, even with zero subagents), retaining coverage
3026
3048
  // while an authoritative running|queued subagent exists or a
3027
- // subagent_run/subagent_continue launch is pending; null (clear) once
3028
- // the main session settles (or any non-root session) so a settled
3029
- // session never retains it. Carries no count and never alters the work
3030
- // total or the roles CSV — the consumer reduces a fresh marker to the
3049
+ // subagent_run/subagent_continue launch is pending, or while a fresh
3050
+ // background-job snapshot shows a live job (the settled wait on a
3051
+ // `bash_background` / `monitor` job renders the same pink generic
3052
+ // `gentle`); null (clear) once the main session settles (or any non-root
3053
+ // session) so a settled session never retains it. Carries no count and
3054
+ // never alters the work total or the roles CSV — the consumer reduces a
3055
+ // fresh marker to the
3031
3056
  // `orchestrating` display only when no recognized role is active (below
3032
3057
  // attention, terminal `done`, and recognized roles; ahead of main
3033
3058
  // `working`).
3034
- if (rootSession && (agentActive || subs.length > 0 || pendingCalls.size > 0 || runningJobCount() > 0)) {
3059
+ if (rootSession && (agentActive || subs.length > 0 || pendingCalls.size > 0 || freshRunningJobCount() > 0)) {
3035
3060
  tokens.gentle_orchestrating_v1 = `${sessionHash}:${expiry}`;
3036
3061
  } else {
3037
3062
  tokens.gentle_orchestrating_v1 = null;
@@ -3050,13 +3075,14 @@ export default function (pi) {
3050
3075
  // launch, no live background job, and no human-wait, review, or error leg
3051
3076
  // — then republished with the SAME expiry so the hold can never be
3052
3077
  // extended. Any work appearing during the hold clears it on that beat, so
3053
- // the row moves straight back to the role/job state. A session that never
3054
- // worked never mints one.
3078
+ // the row moves straight back to the role state. A session that never
3079
+ // worked never mints one. A live background job counts as activity: the
3080
+ // finish waits while the session still waits on it.
3055
3081
  const activity =
3056
3082
  agentActive ||
3057
3083
  subs.length > 0 ||
3058
3084
  pendingCalls.size > 0 ||
3059
- runningJobCount() > 0 ||
3085
+ freshRunningJobCount() > 0 ||
3060
3086
  askActiveNow() ||
3061
3087
  reviewActive ||
3062
3088
  !!errorCode;
@@ -3079,19 +3105,6 @@ export default function (pi) {
3079
3105
  donePending = false;
3080
3106
  }
3081
3107
  tokens[DONE_TOKEN] = doneExpiry === undefined ? null : `${sessionHash}:${doneExpiry}`;
3082
- // Pending background jobs (S5/D4): display-only count, published only while
3083
- // the session waits on them. `nativeSettledPending` is included because a
3084
- // launch that was in flight when the principal settled has already left
3085
- // `pendingCalls` — it is still pending work, never a job wait.
3086
- const jobCount =
3087
- !agentActive &&
3088
- settled &&
3089
- !nativeSettledPending &&
3090
- subs.length === 0 &&
3091
- pendingCalls.size === 0
3092
- ? runningJobCount()
3093
- : 0;
3094
- tokens[JOBS_TOKEN] = jobCount > 0 ? `${sessionHash}:${jobCount}:${expiry}` : null;
3095
3108
  if (changes.files > 0) {
3096
3109
  const files = String(changes.files);
3097
3110
  const added = String(changes.added);
@@ -3123,12 +3136,15 @@ export default function (pi) {
3123
3136
  // holds the beat the same way while its span is open. Effective
3124
3137
  // review (executing acknowledged capture/group calls) keeps the beat
3125
3138
  // alive so `review:` and the durable review token publish — NO GRACE:
3126
- // the leg drops when the last execution ends or resolves.
3139
+ // the leg drops when the last execution ends or resolves. A live
3140
+ // background job keeps the beat alive too: that is what lets the wait end
3141
+ // on its own when the snapshot goes stale instead of the beat stopping
3142
+ // with the row still painted `gentle`.
3127
3143
  return (
3128
3144
  agentActive ||
3129
3145
  activeSubs().length > 0 ||
3130
3146
  pendingCalls.size > 0 ||
3131
- runningJobCount() > 0 ||
3147
+ freshRunningJobCount() > 0 ||
3132
3148
  askToolCalls.size > 0 ||
3133
3149
  uiPromptActive ||
3134
3150
  reviewActive ||
@@ -3170,7 +3186,6 @@ export default function (pi) {
3170
3186
  settled,
3171
3187
  activeCount: activeSubs().length,
3172
3188
  pendingCount: pendingCalls.size + (nativeSettledPending ? 1 : 0),
3173
- jobCount: runningJobCount(),
3174
3189
  askActive: askActiveNow(),
3175
3190
  reviewActive,
3176
3191
  hasError: !!errorCode,
@@ -3237,7 +3252,9 @@ export default function (pi) {
3237
3252
  params.session_start_source = sessionStartSource;
3238
3253
  }
3239
3254
  const base = `${SOURCE}:session:${seq}`;
3240
- await sendRequestAttempt(
3255
+ // The result is deliberately discarded: this is the fire-and-forget
3256
+ // session binding, and `void` states that intent for the linter.
3257
+ void (await sendRequestAttempt(
3241
3258
  {
3242
3259
  id: `${base}:0:${randomUUID()}`,
3243
3260
  method: "pane.report_agent_session",
@@ -3252,7 +3269,7 @@ export default function (pi) {
3252
3269
  params,
3253
3270
  },
3254
3271
  1500,
3255
- ).catch(() => false));
3272
+ ).catch(() => false)));
3256
3273
  }
3257
3274
 
3258
3275
  // Start the session binding without waiting for it (see
@@ -3395,6 +3412,9 @@ export default function (pi) {
3395
3412
  try {
3396
3413
  const ok = await sendTokens(tokens);
3397
3414
  if (ok) {
3415
+ // One coalesced wake per landed beat, after the tokens are in Herdr
3416
+ // (a request written first could render a frame over stale tokens).
3417
+ requestStatusRefresh();
3398
3418
  if (donePending) {
3399
3419
  donePending = false;
3400
3420
  emitFinish();
@@ -3496,7 +3516,7 @@ export default function (pi) {
3496
3516
  const top = probe.stdout.trim();
3497
3517
  if (top.length > 0) cwdRoot = top;
3498
3518
  }
3499
- } catch {}
3519
+ } catch { /* best effort: a failure here is non-fatal */ }
3500
3520
  }
3501
3521
  const roots = liveResolveScopeRoots(entries, sessionId, cwdRoot);
3502
3522
  const summary = await liveSummarizeRoots(roots);
@@ -3535,6 +3555,7 @@ export default function (pi) {
3535
3555
  doneExpiry = undefined;
3536
3556
  donePending = false;
3537
3557
  sawActivity = false;
3558
+ jobsSnapshot = undefined;
3538
3559
  errorCode = undefined;
3539
3560
  liveGen += 1;
3540
3561
  liveInFlight = false;
@@ -3551,7 +3572,7 @@ export default function (pi) {
3551
3572
  emittedLabel = undefined;
3552
3573
  try {
3553
3574
  pi.events.emit(BLOCKED_EVENT, { active: false });
3554
- } catch {}
3575
+ } catch { /* best effort: a failure here is non-fatal */ }
3555
3576
  }
3556
3577
 
3557
3578
  // -- ask legs -------------------------------------------------------------
@@ -3984,7 +4005,7 @@ export default function (pi) {
3984
4005
  emittedLabel = undefined;
3985
4006
  try {
3986
4007
  pi.events.emit(BLOCKED_EVENT, { active: false });
3987
- } catch {}
4008
+ } catch { /* best effort: a failure here is non-fatal */ }
3988
4009
  }
3989
4010
  resetSessionState();
3990
4011
  return moshiFlushSends(1000);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "herdr-gentle-shell",
3
- "version": "1.1.0",
3
+ "version": "1.3.0",
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",