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 +186 -77
- package/README.md +48 -7
- package/extensions/gentle-herdr-state.ts +95 -74
- package/package.json +1 -1
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
|
|
32
|
-
|
|
33
|
-
|
|
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
|
|
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
|
|
313
|
-
; null (clear) once the main
|
|
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
|
|
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
|
-
;
|
|
331
|
-
;
|
|
332
|
-
;
|
|
333
|
-
;
|
|
334
|
-
;
|
|
335
|
-
|
|
336
|
-
;
|
|
337
|
-
;
|
|
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
|
|
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
|
-
|
|
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 >
|
|
516
|
-
`
|
|
517
|
-
|
|
518
|
-
|
|
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.
|
|
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
|
|
536
|
+
The visible second row is structural, with no rules: the eleven
|
|
551
537
|
presence-encoded
|
|
552
|
-
`gentle_title_<working|orchestrating|
|
|
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`) / `
|
|
540
|
+
`orchestrating`) / `explorer` / `worker` /
|
|
555
541
|
`verify` / `judge` / `ask` / `blocked` / `done` / `idle` / `review`;
|
|
556
|
-
role words carry a running-count suffix above one
|
|
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`,
|
|
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) | `
|
|
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
|
|
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
|
|
616
|
-
change-segment cells (
|
|
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
|
|
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
|
|
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
|
-
`
|
|
808
|
-
`gentle_changes_v1`) and the daemon publishes its
|
|
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
|
|
811
|
-
family stays published but wired into no visible row. Row 2 wires
|
|
812
|
-
title + 3 change cells =
|
|
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
|
|
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
|
|
825
|
-
failures are observed, recovering after
|
|
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`
|
|
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.
|
|
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 = "$
|
|
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
|
|
245
|
-
|
|
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);
|
|
314
|
-
"pane.agent_detected"`, `pane.agent_status_changed`,
|
|
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.
|
|
319
|
-
|
|
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
|
|
702
|
-
//
|
|
703
|
-
//
|
|
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 =
|
|
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
|
-
//
|
|
710
|
-
//
|
|
711
|
-
//
|
|
712
|
-
//
|
|
713
|
-
//
|
|
714
|
-
//
|
|
715
|
-
//
|
|
716
|
-
|
|
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 }] } }`.
|
|
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
|
|
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 ||
|
|
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`)
|
|
2539
|
-
//
|
|
2540
|
-
//
|
|
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
|
|
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
|
-
//
|
|
2561
|
-
//
|
|
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
|
-
//
|
|
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
|
|
3028
|
-
//
|
|
3029
|
-
//
|
|
3030
|
-
//
|
|
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 ||
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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.
|
|
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",
|