herdr-gentle-shell 1.2.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 +153 -13
- package/README.md +45 -4
- package/extensions/gentle-herdr-state.ts +34 -5
- 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
|
|
@@ -328,11 +335,14 @@ gentle_done_v1 = sessionHash ":" expiry
|
|
|
328
335
|
; republished with the SAME expiry (never refreshed) until
|
|
329
336
|
; it lapses; null (clear) whenever work reappears or the
|
|
330
337
|
; session resets. Its expiry IS the done hold: default
|
|
331
|
-
;
|
|
332
|
-
;
|
|
333
|
-
;
|
|
334
|
-
;
|
|
335
|
-
;
|
|
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.
|
|
336
346
|
gentle_ask_v1 = sessionHash ":" intentId ":" expiry
|
|
337
347
|
; durable ask signal, session-bound + TTL-fresh like
|
|
338
348
|
; gentle_orchestrating_v1 — emitted on every beat while
|
|
@@ -600,6 +610,84 @@ A signal is *fresh* iff its token parses (§4.3) and `expiry > now`. Stale or
|
|
|
600
610
|
unparseable signals are dropped individually (one bad token never poisons the
|
|
601
611
|
other two). All gentle signals stale/missing → `idle` (native fallback, O5).
|
|
602
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
|
+
|
|
603
691
|
## 6. Failure, retry, idempotency
|
|
604
692
|
|
|
605
693
|
- Delivery is at-least-once snapshots over an unreliable beat: producer
|
|
@@ -791,11 +879,58 @@ exactly one mechanism writes each piece of state.
|
|
|
791
879
|
- Poll cadence: resolved — must be ≪ 60 s TTL to avoid flapping
|
|
792
880
|
(see §10 U2). The daemon runs an adaptive poll (10 s baseline,
|
|
793
881
|
`GENTLE_STATUS_POLL_MS`-overridable, 2 s fast cycle
|
|
794
|
-
(`GENTLE_STATUS_FAST_POLL_MS`) while recent ask activity
|
|
795
|
-
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
|
|
796
885
|
(`GENTLE_STATUS_FAST_QUIET_FRAMES`) or a TTL-bounded window
|
|
797
886
|
(`GENTLE_STATUS_FAST_WINDOW_MS`), 250 ms floor, single dynamic
|
|
798
|
-
`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.
|
|
799
934
|
The four lifecycle hooks (`pane.agent_detected`, `pane.agent_status_changed`,
|
|
800
935
|
`pane.exited`, `pane.closed`) each run `node bin/gentle-status.js --refresh`
|
|
801
936
|
(daemon ensure plus one coalesced immediate frame), not the cadence itself;
|
|
@@ -874,7 +1009,12 @@ exactly one mechanism writes each piece of state.
|
|
|
874
1009
|
— each invoke `node bin/gentle-status.js --refresh` (L6: daemon ensure
|
|
875
1010
|
plus one coalesced immediate frame, never a second writer loop), while
|
|
876
1011
|
`[[startup]]` (no args) remains the polling-daemon bootstrap and polling
|
|
877
|
-
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
|
|
878
1018
|
existing one-frame public behavior for manual use and is not wired as a
|
|
879
1019
|
hook. Runtime proofs of the `--refresh` contract belong to the lifecycle
|
|
880
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)
|
|
@@ -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,11 +698,13 @@ 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";
|
|
@@ -852,7 +854,7 @@ function utf8Bytes(value) {
|
|
|
852
854
|
return Buffer.byteLength(value, "utf8");
|
|
853
855
|
}
|
|
854
856
|
|
|
855
|
-
// Finish-hold override: an absent or unparseable value keeps the
|
|
857
|
+
// Finish-hold override: an absent or unparseable value keeps the 5 s
|
|
856
858
|
// default, and anything outside the ceiling is clamped, so the producer can
|
|
857
859
|
// never publish an expiry the consumer reads as foreign.
|
|
858
860
|
export function doneHoldMs(raw = process.env[DONE_HOLD_ENV]) {
|
|
@@ -1565,6 +1567,30 @@ function sidebarEffectiveDir() {
|
|
|
1565
1567
|
return injected;
|
|
1566
1568
|
}
|
|
1567
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
|
+
|
|
1568
1594
|
// Optional Moshi notification mirror (DESIGN §7): one flag file, read per
|
|
1569
1595
|
// event. The producer extension owns it; the consumer daemon never publishes
|
|
1570
1596
|
// to Moshi (single emitter). Enabling is the flag plus, while
|
|
@@ -3386,6 +3412,9 @@ export default function (pi) {
|
|
|
3386
3412
|
try {
|
|
3387
3413
|
const ok = await sendTokens(tokens);
|
|
3388
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();
|
|
3389
3418
|
if (donePending) {
|
|
3390
3419
|
donePending = false;
|
|
3391
3420
|
emitFinish();
|
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",
|