herdr-gentle-shell 1.2.0 → 1.4.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 +217 -36
- package/README.md +75 -15
- package/extensions/gentle-herdr-state.ts +262 -69
- package/lib/customize-panel.js +96 -26
- package/package.json +1 -1
package/DESIGN.md
CHANGED
|
@@ -19,7 +19,8 @@ explicitly in §10 and are not decided here.
|
|
|
19
19
|
- The human operator watching Pi + Gentle Shell agents: needs to distinguish
|
|
20
20
|
generic activity (`gentle`, machine key `working`) vs the active TaskStore role (`explorer`,
|
|
21
21
|
`worker`, `verify`, `rdd`), `ask` (blocked on user input), `blocked`
|
|
22
|
-
(error), `done`, and `idle` at a glance. No
|
|
22
|
+
(the row word for the `error` key), `done`, and `idle` at a glance. No
|
|
23
|
+
visible text ever carries
|
|
23
24
|
a subagent count, and generic activity never reads `working`.
|
|
24
25
|
|
|
25
26
|
### Current boundary and interaction
|
|
@@ -28,9 +29,14 @@ explicitly in §10 and are not decided here.
|
|
|
28
29
|
per-pane key=value tokens via `pane.report_metadata` /
|
|
29
30
|
`workspace.report_metadata` over `HERDR_SOCKET_PATH`, with a CLI fallback
|
|
30
31
|
(`herdr pane report-metadata <pane> --source <src> --token name=value`).
|
|
31
|
-
- The consumer
|
|
32
|
-
|
|
33
|
-
|
|
32
|
+
- The consumer polls the Herdr snapshot and reduces pane tokens to sidebar
|
|
33
|
+
state. Drawing is subscription-driven: the daemon also holds ONE long-lived
|
|
34
|
+
socket `events.subscribe` for `pane.updated` (plus the roster kinds), which
|
|
35
|
+
only marks a dirty flag and wakes the existing sleep, so a landed token
|
|
36
|
+
report is drawn without waiting for the poll. Polling stays the fallback and
|
|
37
|
+
remains authoritative for everything no Herdr event can drive (§8). No new
|
|
38
|
+
socket, webhook, broker, or dependency is introduced: this is the existing
|
|
39
|
+
plugin socket, used read-only.
|
|
34
40
|
- The existing native producer `herdr-agent-state.ts` (managed-by-herdr, v9,
|
|
35
41
|
source `herdr:pi`) already reports main-agent `working`/`blocked`/`idle` +
|
|
36
42
|
session ref. It is **read-only evidence**: never edited, reinstalled, or
|
|
@@ -39,7 +45,9 @@ explicitly in §10 and are not decided here.
|
|
|
39
45
|
### Style choice and reason
|
|
40
46
|
|
|
41
47
|
- Style: **polled token sidecar** (same style as `herdr-pi-tree`): short-TTL
|
|
42
|
-
`name=value` tokens on the pane, reduced by a snapshot poller
|
|
48
|
+
`name=value` tokens on the pane, reduced by a snapshot poller, with one
|
|
49
|
+
`events.subscribe` wake so the drawing follows the report instead of the
|
|
50
|
+
clock (§8).
|
|
43
51
|
- Reason (smallest fitting style): the transport, snapshot source, 16-token
|
|
44
52
|
budget, TTL/expiry convention, and sidebar token-name mapping already exist
|
|
45
53
|
and are deployed. A new push channel (SSE/WebSocket/webhook) or a new RPC
|
|
@@ -123,7 +131,8 @@ an explicit writer-ownership decision. Rationale follows each choice.
|
|
|
123
131
|
`error:`) plus the native `pane.report_agent` state; desktop attention is
|
|
124
132
|
native Herdr exclusively (E9 unchanged): `Blocked` fires the `NeedsAttention`
|
|
125
133
|
toast and background `Working|Blocked → Idle` fires `Finished`, both
|
|
126
|
-
Herdr-owned.
|
|
134
|
+
Herdr-owned. Native `blocked` is emitted for an actual human-wait
|
|
135
|
+
intervention only: an error is sidebar-only, so no attention fires for it. The consumer emits `herdr notification` for nothing — its
|
|
127
136
|
former ask toast fired on the poll after the native one for the same
|
|
128
137
|
question, a systematic duplication, so the toast path, its copy, the
|
|
129
138
|
notification ledger and the send machinery were removed in v0.3.1. The ask
|
|
@@ -196,7 +205,8 @@ Sidecar only: ships beside `herdr-agent-state.ts`, never modifies it.
|
|
|
196
205
|
| TaskStore `running` non-empty (G3; queued/waiting never execute) | `gentle_work_v1=<hash>:<count>:<exp>` (running total of delegates — never a principal-working signal) + `gentle_roles_v1=<csv>` (roles from `TaskRecord.agent`, authoritative, oldest-first) + `gentle_names_v1=<csv>` (compat transport only, never rendered) + `gentle_orchestrating_v1=<hash>:<exp>` (root-only marker, §4.3) | the oldest running role word (known short word or unknown sanitized name) whenever the principal itself is not working; a working principal reads `gentle` instead; role labels show the total when two or more delegates run |
|
|
197
206
|
| `ASK_USER_CHOICE_BLOCKED_EVENT` / `gentle-pi:ask-user-choice:blocked` (G4), incl. questionnaire + tool-gated `ui_prompt` dialog spans (`kind` other than `custom` — a panel or overlay such as the agents view, ODD viewer, changes view or design canvas never counts, because opening a panel is navigation, not a question), plus direct Pi in-process `tool_execution_start` opens / `tool_execution_end` / `tool_result` closes for the exact tools `ask_user_question` and `ask_user_choice`, tracked by `toolCallId` in a call-id set (a `tool_call` proposal alone never opens; an abort/error end with no result still closes; overlapping calls correct; cleared on result/end/reset/shutdown; event legs and error > ask > review precedence unchanged; boundary: only what Pi emits as execution events is observable — a host ask UI that never emits one stays covered by the event legs only). `gentle_review` starts (any operation) never enter ask: the former consent-eligible pending signal fired before any outcome/UI and falsely blocked pre-granted sessions | `herdr:blocked` label `ask:<intentId>` + durable `gentle_ask_v1=<hash>:<intentId>:<exp>` on every beat while ask is active (null/clear when inactive — repairs a missed label edge; §4.3) | `ask` (existing machine key, user-facing `ask`, amber/orange, native `?`) |
|
|
198
207
|
| Pi in-process `tool_execution_start` opens / `tool_execution_end` / `tool_result` closes (by `toolCallId`; a `tool_call` proposal alone never opens) for the exact tools `gentle_review_capture`, `gentle_review_capture_group` with `reviewerRunAcknowledged: true` in the runtime args; `correctionLines` (native planning, never a reviewer), forecast-only calls, `gentle_review` (any operation), `gentle_review_scope`, and all sidebar/hook signals never enter — unknown legacy shapes stay dark (conservative) | `herdr:blocked` label `review:<reviewId>` | `review` (machine key `review`) — during a capture-group run the single parent capture-group call stays in flight across the whole multi-reviewer span, so that one call alone holds the label. Bounded approximation: the acknowledged capture interval contains preparation and admission; no exact reviewer internal events exist today |
|
|
199
|
-
| agent error
|
|
208
|
+
| the agent run itself stops on an error (an assistant message whose `stopReason` is `error` — the same signal Pi derives `turn_end.outcome === "error"` from) | durable `gentle_error_v1=<hash>:run-failed:<exp>` on every beat while the leg stands (null/clear the beat it releases, §4.3) + `herdr:blocked` label `error:run-failed`; no native state is derived from it (the pane stays on its lifecycle state — `working` — while the leg stands, so the host raises no NeedsAttention toast or sound) | `error` (row word `blocked`) — never a native `blocked` |
|
|
209
|
+
| a tool call fails, a delegate record ends `failed`, or a beat transport fails | nothing — detection only (a counter and a debug line under `GENTLE_HERDR_DEBUG=1`) | nothing: no label, no native state, no finish hold, no notification |
|
|
200
210
|
| `agent_settled` + 0 active subs | `gentle_work_v1=<hash>:0:<exp>`; clear `blocked` labels | `done` |
|
|
201
211
|
| `SESSION_CHANGE_ENTRY` `gentle-pi.session-change/v1` tool outcome (G1/G2) | `gentle_changes_v2=<hash>:<files>:<added>:<deleted>:<exp>` (+ legacy `gentle_changes_v1` dual-emit, §4.3) | change segments only (orthogonal to state) |
|
|
202
212
|
|
|
@@ -328,11 +338,14 @@ gentle_done_v1 = sessionHash ":" expiry
|
|
|
328
338
|
; republished with the SAME expiry (never refreshed) until
|
|
329
339
|
; it lapses; null (clear) whenever work reappears or the
|
|
330
340
|
; session resets. Its expiry IS the done hold: default
|
|
331
|
-
;
|
|
332
|
-
;
|
|
333
|
-
;
|
|
334
|
-
;
|
|
335
|
-
;
|
|
341
|
+
; 5 s (short on purpose — the hold only makes a finish
|
|
342
|
+
; visible, it never pins a settled row, so `idle` follows
|
|
343
|
+
; within seconds), overridden by
|
|
344
|
+
; GENTLE_HERDR_DONE_HOLD_MS clamped to [1000, 300000], and
|
|
345
|
+
; the consumer accepts no expiry beyond now+300000 at read
|
|
346
|
+
; (the only token whose ceiling is not the 60 s TTL). The
|
|
347
|
+
; daemon also caps its next sleep at that expiry (§8). A
|
|
348
|
+
; session that never worked never mints one.
|
|
336
349
|
gentle_ask_v1 = sessionHash ":" intentId ":" expiry
|
|
337
350
|
; durable ask signal, session-bound + TTL-fresh like
|
|
338
351
|
; gentle_orchestrating_v1 — emitted on every beat while
|
|
@@ -344,6 +357,17 @@ gentle_review_v1 = sessionHash ":" reviewId ":" expiry
|
|
|
344
357
|
; execution is in flight, null (clear) otherwise; silent
|
|
345
358
|
; working natively, never a notification (full def:
|
|
346
359
|
; extensions/gentle-herdr-state.ts, herdr-plugin/lib/gentle-tokens.js)
|
|
360
|
+
gentle_error_v1 = sessionHash ":" code ":" expiry
|
|
361
|
+
; durable run-error signal, session-bound + TTL-fresh —
|
|
362
|
+
; emitted on every beat while the run-error leg stands
|
|
363
|
+
; (the agent run itself stopped on an error), null
|
|
364
|
+
; (clear) the beat it releases; the sidebar's ONLY error
|
|
365
|
+
; carrier (the native report never claims `blocked`, so
|
|
366
|
+
; no toast, no sound, no phone envelope). Tool-level
|
|
367
|
+
; failures never reach it (they are telemetry only).
|
|
368
|
+
; Consumer: fresh token => `error` display (row word
|
|
369
|
+
; `blocked`, silent) with the same
|
|
370
|
+
; error > ask > review priority as the label leg.
|
|
347
371
|
herdr:blocked = "ask:" intentId / "review:" reviewId / "error:" code
|
|
348
372
|
```
|
|
349
373
|
|
|
@@ -370,7 +394,8 @@ pane.report_metadata --source gentle:v1 --token gentle_orchestrating_v1=Ab3_xK9q
|
|
|
370
394
|
pane.report_metadata --source gentle:v1 --token gentle_principal_v1=Ab3_xK9q2mZ7QwErTyUiOpAsDfGhJkL012345678:1789000000000
|
|
371
395
|
pane.report_metadata --source gentle:v1 --token gentle_names_v1=planner,code-writer
|
|
372
396
|
pane.report_metadata --source gentle:v1 --token gentle_changes_v2=Ab3_xK9q2mZ7QwErTyUiOpAsDfGhJkL012345678:5:110:22:1789000000000
|
|
373
|
-
|
|
397
|
+
pane.report_metadata --source gentle:v1 --token gentle_error_v1=Ab3_xK9q2mZ7QwErTyUiOpAsDfGhJkL012345678:run-failed:1789000000000
|
|
398
|
+
herdr:blocked labels: ["ask:q-7f3a"] | ["review:r-42"] | ["error:run-failed"]
|
|
374
399
|
```
|
|
375
400
|
|
|
376
401
|
Example reads: worker oldest + explorer active with count 2 → sidebar
|
|
@@ -440,6 +465,8 @@ count), `gentle_principal_v1` (principal-only activity marker + freshness
|
|
|
440
465
|
gate for the working-vs-idle decision — never rendered as a count),
|
|
441
466
|
`gentle_done_v1` (synthesized finish signal + its own hold freshness gate
|
|
442
467
|
for the reachable `done` display — the host never reports `done`, §4.3),
|
|
468
|
+
`gentle_error_v1` (durable run-error signal + freshness gate for the `error`
|
|
469
|
+
display — repairs a missed `error:` label edge, §4.3),
|
|
443
470
|
`gentle_roles_v1` (authoritative activity roles,
|
|
444
471
|
oldest-first by immutable firstSeen), `gentle_names_v1` (compat transport only — never
|
|
445
472
|
rendered), `gentle_changes_v2` (normative; a
|
|
@@ -451,7 +478,9 @@ ignore them under O1 (never parsed for state, never deleted).
|
|
|
451
478
|
### 5.2 Reducer (priority order, first match wins)
|
|
452
479
|
|
|
453
480
|
```text
|
|
454
|
-
error :=
|
|
481
|
+
error := fresh `gentle_error_v1` (durable per-beat token, §4.3)
|
|
482
|
+
OR herdr:blocked has error:* (fresh, §5.4) — one shared
|
|
483
|
+
priority: error > ask > review
|
|
455
484
|
ask := fresh `gentle_ask_v1` (durable per-beat token, §4.3)
|
|
456
485
|
OR herdr:blocked has ask:* (fresh)
|
|
457
486
|
review := herdr:blocked has review:* (fresh)
|
|
@@ -556,8 +585,9 @@ marker, and only after the minted finish hold lapses does it recede to
|
|
|
556
585
|
delegates run) | `ask` | `rdd` (user-facing word for the `review`
|
|
557
586
|
machine key; a delegated rdd and a tool-only review both render `rdd` —
|
|
558
587
|
review execution is silent, never a notification; only
|
|
559
|
-
a waiting `ask` intent notifies once) | `blocked` (user-facing word for the `error`
|
|
560
|
-
machine key
|
|
588
|
+
a waiting `ask` intent notifies once) | `blocked` (user-facing row word for the `error`
|
|
589
|
+
machine key; carried by the durable `gentle_error_v1` token or the `error:`
|
|
590
|
+
label, and the pane's native state never claims `blocked` for it) | `done` (settled-plus-empty only: principal settled with no
|
|
561
591
|
running delegates and no pending launches; a settled principal with
|
|
562
592
|
running delegates keeps the role word) | `idle`. Role labels append the
|
|
563
593
|
total count when at least two delegates run.
|
|
@@ -600,6 +630,84 @@ A signal is *fresh* iff its token parses (§4.3) and `expiry > now`. Stale or
|
|
|
600
630
|
unparseable signals are dropped individually (one bad token never poisons the
|
|
601
631
|
other two). All gentle signals stale/missing → `idle` (native fallback, O5).
|
|
602
632
|
|
|
633
|
+
### 5.5 `gs`: the label for an isolated Gentle Shell pane
|
|
634
|
+
|
|
635
|
+
Herdr identifies an agent from the pane's foreground process group, and its
|
|
636
|
+
canonical aliases include `pi` and `gentle-shell` but never `gs`; a path prefix
|
|
637
|
+
is never consulted. An isolated Gentle Shell pane therefore has no Agents row
|
|
638
|
+
of its own unless this plugin supplies a label, which is why the label follows
|
|
639
|
+
a strict ladder that never lies about who owns the pane:
|
|
640
|
+
|
|
641
|
+
**Which panes belong to an isolated install.** The verified installation shape
|
|
642
|
+
is a user install under the XDG data dir — `<data>/gentle-shell/install`
|
|
643
|
+
(`$XDG_DATA_HOME/gentle-shell/install`, else
|
|
644
|
+
`~/.local/share/gentle-shell/install`), anchored by
|
|
645
|
+
`install/installation.json` (`gentle-shell-user-install/v1`, `Mode:
|
|
646
|
+
"separate"`), whose launcher starts the pane as `node
|
|
647
|
+
<root>/runtime/<channel>/bin/gentle-shell.mjs`. Qualification uses the same
|
|
648
|
+
input Herdr's detection reads, in this order:
|
|
649
|
+
|
|
650
|
+
- **Primary — the foreground process group.** A pane qualifies when any member
|
|
651
|
+
of its foreground process group exposes an argv / `argv0` / cmdline path that
|
|
652
|
+
resolves at or under the install root (a relative script path resolves
|
|
653
|
+
against that process's own cwd). This is what real panes look like: the
|
|
654
|
+
isolated pane is launched from the user's PROJECT directory, so its cwd is
|
|
655
|
+
never inside the install. A readable group with no install member is an
|
|
656
|
+
authoritative "no" — a cwd inside the root cannot override it.
|
|
657
|
+
- **Secondary — cwd.** Only when the group cannot be read at all (no
|
|
658
|
+
`pane.process-info` answer) does `cwd` / `foreground_cwd` at or under the root
|
|
659
|
+
decide, and an unreadable group never throws and never logs more than one
|
|
660
|
+
bounded line.
|
|
661
|
+
|
|
662
|
+
The root resolves from `GENTLE_SHELL_INSTALL_ROOT`, else the launcher's
|
|
663
|
+
`GENTLE_SHELL_HOME`, else the XDG data dir default. Windows keeps its own user
|
|
664
|
+
data dir (mirroring Herdr's `LOCALAPPDATA` state-dir convention) but is
|
|
665
|
+
unverified, which is why the manifest ships linux-only.
|
|
666
|
+
|
|
667
|
+
1. **Detection first: display agent only.** A qualifying pane Herdr already
|
|
668
|
+
detects keeps Herdr's own truthful identity and live state. The plugin only
|
|
669
|
+
reports `--display-agent gs` through `pane.report-metadata`, which is
|
|
670
|
+
presentation-only and changes nothing about the state Herdr publishes.
|
|
671
|
+
2. **Reported label as the last resort.** A qualifying pane Herdr does not
|
|
672
|
+
detect gets `pane report-agent --agent gs --state idle --source
|
|
673
|
+
plugin:<plugin-id>:gs`, because a row exists only for an agent terminal and
|
|
674
|
+
an undetected pane is not one. This is the only case in which the plugin
|
|
675
|
+
states an agent identity, and it states `gs` — never `pi`.
|
|
676
|
+
3. **The report is reversible, never a mask.** Detection is a function of the
|
|
677
|
+
pane's foreground process group, so an unchanged group owes no re-check
|
|
678
|
+
while a changed one means a real agent may now be present. On that change the
|
|
679
|
+
plugin releases exactly its own authority (`pane release-agent`, same
|
|
680
|
+
source, label `gs`) and re-decides, keeping the display label: `gs` never
|
|
681
|
+
masks a real `pi` / `gentle-shell` detection for longer than one beat.
|
|
682
|
+
4. **Release on the way out.** `pane.exited` / `pane.closed`, a pane that
|
|
683
|
+
leaves the qualifying set, a disabled sidebar, and daemon shutdown all clear
|
|
684
|
+
what this plugin reported — authority first, then the display label.
|
|
685
|
+
Authority this plugin did not set is never touched: both the source and the
|
|
686
|
+
label are part of every release.
|
|
687
|
+
|
|
688
|
+
`gs` is not a canonical Herdr agent, so `rows_by_agent.gs` is a configuration
|
|
689
|
+
error rather than an inert key: `rows_by_agent` stays keyed by a canonical
|
|
690
|
+
agent (`pi`), and `gs` exists only as a label.
|
|
691
|
+
|
|
692
|
+
Discovery — one bounded `pane list` read plus one `pane.process-info` per pane
|
|
693
|
+
(the read qualification needs; capped, and a scan pays for no answer twice) —
|
|
694
|
+
runs at daemon start, on an explicit `--refresh` (a separate request marker, so
|
|
695
|
+
the producer's per-beat refresh never triggers one), and on a roster event
|
|
696
|
+
(`pane.created`, `pane.closed`, `pane.moved`, `pane.exited`,
|
|
697
|
+
`pane.agent_detected`); never per frame. The only per-frame call is the
|
|
698
|
+
foreground re-check of a pane this plugin currently reports. Every write is
|
|
699
|
+
deduped against what the plugin already reported, every interpolated value is
|
|
700
|
+
checked against a strict identifier grammar before it reaches a fixed argv, and
|
|
701
|
+
any failure (no `pane list`, a CLI error, a disabled sidebar, an unreadable mode
|
|
702
|
+
flag) does nothing to the existing behavior and logs one bounded line per
|
|
703
|
+
distinct reason.
|
|
704
|
+
|
|
705
|
+
One thing this design cannot fix: the gs pane's own live state. Herdr reports
|
|
706
|
+
state for an agent terminal it knows, and the isolated install does not forward
|
|
707
|
+
`HERDR_ENV` to the pane's agent, so `gs` is a label on a row whose state is
|
|
708
|
+
Herdr's own (`idle` in the reported fallback). Forwarding that environment is a
|
|
709
|
+
gentle-ai concern and explicitly out of scope for this plugin.
|
|
710
|
+
|
|
603
711
|
## 6. Failure, retry, idempotency
|
|
604
712
|
|
|
605
713
|
- Delivery is at-least-once snapshots over an unreliable beat: producer
|
|
@@ -617,10 +725,17 @@ other two). All gentle signals stale/missing → `idle` (native fallback, O5).
|
|
|
617
725
|
id is a new sidebar ask episode (and a new native toast edge). The
|
|
618
726
|
`intentId` doubles as the Moshi `approval_required` action id when the
|
|
619
727
|
phone channel is enabled (§7).
|
|
620
|
-
- Error containment: transport
|
|
621
|
-
|
|
622
|
-
|
|
623
|
-
|
|
728
|
+
- Error containment: a failed beat transport is telemetry (a counter and a
|
|
729
|
+
debug line), never state: it is our own report mechanism failing, not the
|
|
730
|
+
agent, so it neither paints `error:` nor raises native `blocked`, and the
|
|
731
|
+
next landed beat resets the counter. The one real error leg — the run
|
|
732
|
+
itself stopping on an error — is released by the next non-error beat
|
|
733
|
+
(`agent_start`, any tool activity, or a non-error assistant message), never
|
|
734
|
+
latched; no exception path ever stops the producer beat. While the leg
|
|
735
|
+
stands it publishes the durable `gentle_error_v1` token on every beat, so
|
|
736
|
+
an error the sidebar missed on one beat is repaired by the next, and the
|
|
737
|
+
release beat clears it (the missed-beat discipline of the ask/review
|
|
738
|
+
tokens).
|
|
624
739
|
- No exactly-once end-to-end claim: at-least-once beats + TTL expiry is the
|
|
625
740
|
engineered scope (consistent with the async/events guidance: never claim
|
|
626
741
|
exactly-once without a deliberate mechanism). Desktop toast dedup is
|
|
@@ -639,9 +754,12 @@ other two). All gentle signals stale/missing → `idle` (native fallback, O5).
|
|
|
639
754
|
duplication. The ask token still drives the sidebar ask display; sounds,
|
|
640
755
|
suppression, and delay stay Herdr's.
|
|
641
756
|
- `review` and `error` never emit a plugin notification: `review` attention
|
|
642
|
-
stays in-flow/native; `error` is
|
|
643
|
-
|
|
644
|
-
toast
|
|
757
|
+
stays in-flow/native; `error` is sidebar state only — our own `error:` label
|
|
758
|
+
with the pane left on native `working`, so neither the `NeedsAttention`
|
|
759
|
+
toast nor its sound fires and no phone envelope is sent. Tool-level failures
|
|
760
|
+
(a failed tool call, a delegate record ending `failed`, a failed beat
|
|
761
|
+
transport) never touch state at all: they are detected and logged, nothing
|
|
762
|
+
more.
|
|
645
763
|
- Optional Moshi replacement (off by default): one flag file,
|
|
646
764
|
`gentle-moshi.json` in the plugin state root, holding
|
|
647
765
|
`{"enabled":true}` and re-read per event by the producer extension. While
|
|
@@ -663,7 +781,12 @@ other two). All gentle signals stale/missing → `idle` (native fallback, O5).
|
|
|
663
781
|
running/queued plus zero pending plus zero live background jobs plus no
|
|
664
782
|
human wait — never a raw native `working → idle` transition, which fires
|
|
665
783
|
with work still left and skipped `done` entirely),
|
|
666
|
-
never per prompt and never per turn.
|
|
784
|
+
never per prompt and never per turn. Every envelope path requires the flag at
|
|
785
|
+
send time: a context captured for Chat View while the channel was on is
|
|
786
|
+
prefill only and never authorizes a notification after it is turned off, and
|
|
787
|
+
`task_complete` is announced at the minted `done` edge itself rather than
|
|
788
|
+
after a successful Herdr publish, so a failed token beat cannot drop it. A
|
|
789
|
+
`session.closed` (`session_ended`)
|
|
667
790
|
envelope closes the row on shutdown, and the host-awaited handler flushes
|
|
668
791
|
in-flight sends. `task_complete` carries title `Gentle finished: <project>`
|
|
669
792
|
and names the last finished task: `<project> finished — <label>. Return to
|
|
@@ -685,7 +808,8 @@ other two). All gentle signals stale/missing → `idle` (native fallback, O5).
|
|
|
685
808
|
publishes to Moshi (single emitter). Moshi owns pairing and credentials
|
|
686
809
|
(host secret in its own store); the plugin never reads or stores a token,
|
|
687
810
|
and an absent daemon or unpaired host is a silent no-op that never
|
|
688
|
-
interrupts Pi. `review` and `error` never notify
|
|
811
|
+
interrupts Pi. `review` and `error` never notify; a failed tool never even
|
|
812
|
+
changes state. Limits (host-owned,
|
|
689
813
|
unverified): the phone-side approval round-trip through Moshi's TUI bridge,
|
|
690
814
|
the Live Activity lifecycle, and whether a `task_complete` renders as a
|
|
691
815
|
separate banner or only updates a running Live Activity are Moshi's.
|
|
@@ -702,7 +826,7 @@ report after a Pi restart or `/new` (both recreate the extension runtime)
|
|
|
702
826
|
lose, freezing the pane's `agent_session` binding at the old session while
|
|
703
827
|
the producer keeps beating for the new one — the consumer then rejects those
|
|
704
828
|
fresh tokens as a session-hash mismatch and the pane stays on `idle` until a
|
|
705
|
-
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
|
|
829
|
+
report with a higher seq lands. Parity contract: `working` carries the specific working role in the message (oldest running role word from the same roles resolution — known short word, unknown sanitized name, or `gentle` with no delegation; never bare generic `working`; machine keys unchanged); terminal `idle` only on a truly empty settle (principal settled plus zero running/queued plus zero pending plus zero live background jobs plus no human-wait prompt; settle-with-delegates/pending/jobs stays `working`, emitted once with no re-emit on repeat settles). Live background jobs come from Gentle Shell's own bus event `gentle-ai:jobs-sidebar` (`bash_background` / `monitor`), session-scoped and emitted on job edges only, so a snapshot counts only while it is fresh — a stale or foreign snapshot is zero jobs; an absent Gentle Shell simply reports none (today's behavior). Only an entry with no `status` is pending work: Gentle Shell keeps a finished job in the array as a result tail (`status: exited|stopped|failed`), and counting that tail is what pinned the row on the pink generic `gentle` — and blocked `done` — while the panel read no running job. One `unref()`-ed timer per live snapshot publishes a single beat at the instant the snapshot goes stale, so a missed exit event cannot leave the settle without a beat. While such a job waits with the principal settled and no delegate running or launching, the producer keeps the root marker live so the row stays on the pink generic `gentle` (§5.2) and the finish is held back; the wait ends on the beat the principal resumes, a delegate starts, the last job ends, or the snapshot ages past its staleness bound. `blocked` only for an actual human-wait intervention leg with its label (review/RDD execution stays `working`, silent); an error never claims native `blocked` — while our `error:` label stands the pane reports `working`, the only native state that raises no host attention, and returns to the lifecycle state on the next non-error beat. The native status keeps its aggregate meaning (it reads `working` while any delegate runs, which is what Herdr's own pane state means): the sidebar row's working-vs-idle decision reads the principal-only `gentle_principal_v1` instead (§5.2), so an idle principal with a running delegate shows the delegate role word rather than `gentle`. Single publisher by design: the managed native extension file is excluded
|
|
706
830
|
reversibly (`-extensions/herdr-agent-state.ts` in Pi settings, bytes
|
|
707
831
|
preserved on disk, never auto-loaded next to ours). `node
|
|
708
832
|
bin/gentle-sidebar.js (enable|disable|status|toggle)` selects the
|
|
@@ -743,11 +867,15 @@ argument, Esc, or a cancelled menu writes nothing. With no argument the
|
|
|
743
867
|
command opens the floating panel (`lib/customize-panel.js`, painted through its
|
|
744
868
|
own palette) over `ctx.ui.custom` in Gentle Shell's own layout: one left
|
|
745
869
|
`CATEGORIES` list, one right pane headed `<Category> · n/m` with its setting
|
|
746
|
-
rows, each row painting the stored value with `●` and the other with
|
|
747
|
-
the footer
|
|
748
|
-
|
|
870
|
+
rows, each row painting the stored value with `●` and the other with `○`; one
|
|
871
|
+
line above the footer describes the focused setting
|
|
872
|
+
(`<setting> — <what it changes>`), and the footer
|
|
873
|
+
`←/→ or Tab panes · ↑/↓ move · Enter apply · Esc close`. There is no
|
|
874
|
+
`Click` token and no
|
|
749
875
|
`Preview · …` band and no `p profiles` key: this plugin owns no profiles
|
|
750
|
-
concept, so the footer advertises nothing it cannot do
|
|
876
|
+
concept, so the footer advertises nothing it cannot do — every token in it is a
|
|
877
|
+
key the panel answers to, and a narrow card compacts the legend instead of
|
|
878
|
+
wrapping it. `←/→` or `Tab` moves
|
|
751
879
|
between the category and value panes, `↑/↓` or `j/k` moves the cursor, `Enter`
|
|
752
880
|
applies the focused row and `Esc` closes without a write; a click on a category
|
|
753
881
|
selects it, a click on a row applies it, and a click outside the panes is
|
|
@@ -771,11 +899,12 @@ exactly one mechanism writes each piece of state.
|
|
|
771
899
|
## 8. Limits
|
|
772
900
|
|
|
773
901
|
- Token budget: ≤ 16 tokens per report per pane (E8 discipline); the
|
|
774
|
-
producer emits at most
|
|
902
|
+
producer emits at most 12 tokens per beat (including the retired
|
|
775
903
|
`gentle_subs_v1` clear) (`gentle_work_v1`,
|
|
776
904
|
`gentle_roles_v1`, `gentle_names_v1`,
|
|
777
905
|
`gentle_orchestrating_v1`, `gentle_principal_v1`, `gentle_done_v1`,
|
|
778
|
-
`gentle_ask_v1`, `gentle_review_v1`, `
|
|
906
|
+
`gentle_ask_v1`, `gentle_review_v1`, `gentle_error_v1`,
|
|
907
|
+
`gentle_changes_v2`,
|
|
779
908
|
`gentle_changes_v1`) and the daemon publishes its 72-token owned family
|
|
780
909
|
chunked ≤ 16 per report (row 1 is the 3 native tokens
|
|
781
910
|
`state_icon`/`workspace`/`agent`; the legacy 11 `gentle_heading_*` compat
|
|
@@ -791,11 +920,58 @@ exactly one mechanism writes each piece of state.
|
|
|
791
920
|
- Poll cadence: resolved — must be ≪ 60 s TTL to avoid flapping
|
|
792
921
|
(see §10 U2). The daemon runs an adaptive poll (10 s baseline,
|
|
793
922
|
`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
|
|
923
|
+
(`GENTLE_STATUS_FAST_POLL_MS`) while recent ask activity, a rendered
|
|
924
|
+
non-idle display, or send/publish failures are observed, recovering after
|
|
925
|
+
N quiet frames
|
|
796
926
|
(`GENTLE_STATUS_FAST_QUIET_FRAMES`) or a TTL-bounded window
|
|
797
927
|
(`GENTLE_STATUS_FAST_WINDOW_MS`), 250 ms floor, single dynamic
|
|
798
|
-
`setTimeout` chain.
|
|
928
|
+
`setTimeout` chain. The active-display trigger exists because the row data
|
|
929
|
+
the daemon derives by itself — the `+N/-N` changes summary and the `↑N`
|
|
930
|
+
pull marker, read from local git plus `agent.list` — cannot be driven by a
|
|
931
|
+
producer report; only `idle` counts as settled, so an idle pane keeps the
|
|
932
|
+
baseline exactly.
|
|
933
|
+
Drawing is event-synchronized; polling is only the fallback. Every landed
|
|
934
|
+
producer beat requests the daemon's ONE coalesced refresh (the same request
|
|
935
|
+
file `--refresh` touches, §10 U2), so a report that changes state draws an
|
|
936
|
+
immediate frame instead of waiting for the next poll — the event lands on
|
|
937
|
+
time AND the drawing follows it. N reports in one window collapse into one
|
|
938
|
+
frame, and refresh-driven frames are floored at 250 ms after the frame that
|
|
939
|
+
started the sleep, so a report storm can never spin the loop.
|
|
940
|
+
The token path is also subscription-driven: the daemon holds exactly ONE
|
|
941
|
+
long-lived socket `events.subscribe` for `pane.updated` (plus the roster
|
|
942
|
+
kinds `pane.created`, `pane.closed`, `pane.moved`), because
|
|
943
|
+
`pane.report_metadata` bumps the pane revision and Herdr then emits
|
|
944
|
+
`pane.updated` with the full pane payload. Herdr repaints push-driven on that
|
|
945
|
+
write plus its metadata-TTL expiry, so a token write no longer waits for the
|
|
946
|
+
poll. An event does nothing but set ONE dirty flag and wake that
|
|
947
|
+
same sleep: the flag is consumed with the refresh request into a single
|
|
948
|
+
frame, so a burst collapses to one frame, there is no second frame loop, no
|
|
949
|
+
timer, no per-event frame, no queue (bounded memory is that one boolean) and
|
|
950
|
+
no frame sooner than the same `refreshGateMs`/`POLL_MIN_MS` floor. A
|
|
951
|
+
manifest `[[events]]` hook cannot do this and must not be tried again:
|
|
952
|
+
`pane.updated` is deliberately excluded from the 22-name hook surface
|
|
953
|
+
(`PLUGIN_HOOK_EVENT_KINDS`), and the runtime filter drops non-hook kinds, so
|
|
954
|
+
`on = "pane.updated"` in `herdr-plugin.toml` is inert. Reconnect is bounded
|
|
955
|
+
and single-flight: 1 s doubling to a 60 s cap, reset only after a connection
|
|
956
|
+
that stayed live 5 s, so a Herdr restart reconnects promptly while a server
|
|
957
|
+
that accepts and drops climbs to the cap instead of flapping. A rejected,
|
|
958
|
+
closed, or unanswered subscription logs one line per distinct reason and
|
|
959
|
+
changes nothing else — the poll below is unchanged and correct without it.
|
|
960
|
+
Shutdown closes the socket and its retry timer, and neither keeps the process
|
|
961
|
+
alive. Idle cost with no events is exactly today's: an idle subscription is
|
|
962
|
+
silent and the loop sleeps as before.
|
|
963
|
+
What the subscription can never drive stays poll-only: the row data the
|
|
964
|
+
daemon derives by itself — the `+N/-N` changes summary and the `↑N` pull
|
|
965
|
+
marker, read from local git plus `agent.list` — plus the presence prefix,
|
|
966
|
+
because Herdr emits no event for either. That is why the fast cycle is armed
|
|
967
|
+
by a rendered non-idle display, and why polling is never removed.
|
|
968
|
+
The sleep is also capped at the nearest live `gentle_done_v1` expiry among
|
|
969
|
+
the panes just rendered (never below the 250 ms floor), so a held `done`
|
|
970
|
+
row reaches `idle` when the hold lapses rather than up to one poll later.
|
|
971
|
+
A pending expiry may only SHORTEN the delay: with no pending expiry the
|
|
972
|
+
delay is exactly the adaptive value above, and an already-expired or
|
|
973
|
+
unparseable value falls to the floor (fail closed, like every parser)
|
|
974
|
+
rather than returning 0.
|
|
799
975
|
The four lifecycle hooks (`pane.agent_detected`, `pane.agent_status_changed`,
|
|
800
976
|
`pane.exited`, `pane.closed`) each run `node bin/gentle-status.js --refresh`
|
|
801
977
|
(daemon ensure plus one coalesced immediate frame), not the cadence itself;
|
|
@@ -874,7 +1050,12 @@ exactly one mechanism writes each piece of state.
|
|
|
874
1050
|
— each invoke `node bin/gentle-status.js --refresh` (L6: daemon ensure
|
|
875
1051
|
plus one coalesced immediate frame, never a second writer loop), while
|
|
876
1052
|
`[[startup]]` (no args) remains the polling-daemon bootstrap and polling
|
|
877
|
-
remains the fallback for every lifecycle signal.
|
|
1053
|
+
remains the fallback for every lifecycle signal. The producer extension is
|
|
1054
|
+
the second requester of that same coalesced refresh — it requests one after
|
|
1055
|
+
every landed token beat, so a status change it publishes is drawn at once
|
|
1056
|
+
rather than at the next poll — and the daemon caps each sleep at the nearest
|
|
1057
|
+
live `gentle_done_v1` expiry (§8), so `idle` does not wait for a poll either.
|
|
1058
|
+
Neither requester renders a frame or writes tokens. `--once` keeps its
|
|
878
1059
|
existing one-frame public behavior for manual use and is not wired as a
|
|
879
1060
|
hook. Runtime proofs of the `--refresh` contract belong to the lifecycle
|
|
880
1061
|
unit's tests, not this protocol record.
|
package/README.md
CHANGED
|
@@ -201,7 +201,12 @@ and token names stay `review` — review execution is silent, never a
|
|
|
201
201
|
notification; only an actual waiting prompt renders `ask` (desktop attention
|
|
202
202
|
is Herdr's native `blocked` toast); the judge delegate role renders `judge` in
|
|
203
203
|
purple `#cba6f7` (distinct from explorer blue, verify teal, and
|
|
204
|
-
orchestrating pink); the error value renders `blocked
|
|
204
|
+
orchestrating pink); the error value renders `blocked` as the row word for
|
|
205
|
+
the `error` machine key (never the pane's native state — an error is
|
|
206
|
+
sidebar-only, DESIGN §7; it rides the durable session-bound
|
|
207
|
+
`gentle_error_v1` token, republished on every beat while the run-error leg
|
|
208
|
+
stands and cleared the beat it releases, so a beat the sidebar missed is
|
|
209
|
+
repaired by the next one); the orchestrating
|
|
205
210
|
leg renders the user-facing word `gentle` (machine key stays
|
|
206
211
|
`orchestrating`, pink `#f5c2e7`). Remaining state colors:
|
|
207
212
|
working/worker amber `#f9e2af`, explorer blue `#89b4fa`, verify teal
|
|
@@ -215,6 +220,10 @@ encoding), so row 2 shows the current state word plus any nonempty change
|
|
|
215
220
|
segments while the rest render empty; native separators on row 2 are
|
|
216
221
|
acceptable. Row 1 holds 3 native cells and row 2 holds 14 cells (11 state
|
|
217
222
|
+ 3 changes), each within Herdr's 16-token per-row ceiling (full block below).
|
|
223
|
+
The `gs` label of an isolated Gentle Shell pane needs no key here: `gs` is not
|
|
224
|
+
one of Herdr's canonical agents, so `rows_by_agent.gs` is a configuration error
|
|
225
|
+
rather than an inert key. Only the daemon's label ladder (DESIGN.md §5.5)
|
|
226
|
+
makes that row appear, and `rows_by_agent` stays keyed by the canonical `pi`.
|
|
218
227
|
|
|
219
228
|
```toml
|
|
220
229
|
# BEGIN herdr-gentle-agents (managed; do not edit)
|
|
@@ -299,7 +308,7 @@ the principal session actively works — even with zero subagents — and keeps
|
|
|
299
308
|
`gentle` while its delegates run (a role word such as `worker`, `explorer`,
|
|
300
309
|
`verify`, `judge` shows once the principal itself is idle), row 1 shows
|
|
301
310
|
the single heading cell (`● <project>` plus ` +N`/` -N`/` ↑N` inline, zero `·`) after edits / when behind upstream; then `ask` on an open
|
|
302
|
-
question (choice / native-questionnaire / legacy event legs, executed `ask_user_question`/`ask_user_choice`, tool-gated `ui_prompt` dialog spans (a `custom` panel — agents view, ODD viewer, changes view, design canvas — never counts, because opening a panel is navigation, not a question), or permission waiting; `gentle_review` starts never speculate ask
|
|
311
|
+
question (choice / native-questionnaire / legacy event legs, executed `ask_user_question`/`ask_user_choice`, tool-gated `ui_prompt` dialog spans (a `custom` panel — agents view, ODD viewer, changes view, design canvas — never counts, because opening a panel is navigation, not a question), or permission waiting; `gentle_review` starts never speculate ask, and no failed tool ever does either: a tool error changes nothing, see the error rule below). `rdd` (machine key `review`) applies during acknowledged native capture/group execution only (`reviewerRunAcknowledged: true` at execution start — never proposal, never forecast-only, never `correctionLines` planning, never `gentle_review`/`gentle_review_scope` in any operation; no hook/sidebar signal observed; unknown legacy shapes stay dark; call-id tracked so thrown/cancelled calls still clear, read-only `assess` excluded). Bounded approximation: the acknowledged interval contains preparation and admission; no exact reviewer internal events exist today. The orchestrator-host `ask_user_choice` prompt emits no Pi tool/event observable by this extension and stays covered only by the event legs above. Never point the fixture commands at the live config: keep
|
|
303
312
|
`HERDR_CONFIG_PATH` on a temp file for apply/uninstall checks.
|
|
304
313
|
|
|
305
314
|
## Core Workflow
|
|
@@ -310,13 +319,25 @@ and TTL discipline as `herdr-pi-tree`, new token names, no new socket or
|
|
|
310
319
|
webhook. `[[startup]] node bin/gentle-status.js` (no args) is the polling-daemon
|
|
311
320
|
bootstrap (ensures the adaptive poll daemon is running: 10 s baseline,
|
|
312
321
|
`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`,
|
|
322
|
+
activity, a rendered non-idle display, or send/publish failures are observed);
|
|
323
|
+
`[[events]] on = "pane.agent_detected"`, `pane.agent_status_changed`,
|
|
324
|
+
`pane.exited`, and
|
|
315
325
|
`pane.closed` each run `node bin/gentle-status.js --refresh`, which ensures the
|
|
316
326
|
adaptive poll daemon is running and requests one coalesced immediate frame
|
|
317
327
|
so a newly opened project name/state renders without waiting for the next
|
|
318
|
-
poll tick.
|
|
319
|
-
|
|
328
|
+
poll tick. Drawing follows the report, not the clock: the daemon also holds one
|
|
329
|
+
long-lived `events.subscribe` for `pane.updated`, so a token write Herdr already
|
|
330
|
+
repaints for wakes the same single frame loop (bounded reconnect, floored at
|
|
331
|
+
250 ms, no second loop, no per-event frame), and the producer requests that same
|
|
332
|
+
coalesced refresh after every landed token beat, so a status change
|
|
333
|
+
it publishes is drawn at once, and the daemon caps each sleep at the nearest
|
|
334
|
+
live `done` expiry, so a settled row reaches `idle` when its short hold (5 s by
|
|
335
|
+
default, `GENTLE_HERDR_DONE_HOLD_MS`-overridable) lapses instead of one poll
|
|
336
|
+
later. Reports in one window collapse into one frame, and refresh-driven frames
|
|
337
|
+
are floored at 250 ms, so a burst can never spin the daemon. Polling stays the
|
|
338
|
+
fallback for every lifecycle signal and the only source for what no Herdr event
|
|
339
|
+
carries (the git-derived `+N/-N` and `↑N` row data and the presence prefix), so a
|
|
340
|
+
missed, undelivered, or rejected event never sticks. Read-only
|
|
320
341
|
supervision triage ships beside it: the `doctor` and `whois` plugin actions
|
|
321
342
|
(`node bin/gentle-doctor.js`, `node bin/gentle-whois.js`) plus the explicit-pane
|
|
322
343
|
`node bin/gentle-trace.js <pane-id>` CLI — all read-only, none mutating state.
|
|
@@ -342,7 +363,11 @@ See [DESIGN.md](DESIGN.md) §4 (producer) and §5 (consumer), and
|
|
|
342
363
|
`rdd` during native review execution (machine key stays `review`; execution
|
|
343
364
|
is silent — desktop attention fires only for a waiting `ask` intent, as
|
|
344
365
|
Herdr's native toast), and
|
|
345
|
-
user-facing `blocked` for
|
|
366
|
+
user-facing `blocked` as the row word for the `error` machine key (an
|
|
367
|
+
error never claims the native `blocked` state — that is the host's
|
|
368
|
+
NeedsAttention toast and sound, so the sidebar carries the error on the
|
|
369
|
+
durable `gentle_error_v1` token while the pane stays quiet on `working`,
|
|
370
|
+
and no phone envelope is sent).
|
|
346
371
|
- Single-cell row-1 heading (`<icon> <project>` plus ` +N`/` -N`/` ↑N`
|
|
347
372
|
inline, exactly one nonempty cell so zero `·` separators; white base with
|
|
348
373
|
`contains` rules keeping ` +` green (added), ` -` red (deleted,
|
|
@@ -354,7 +379,32 @@ See [DESIGN.md](DESIGN.md) §4 (producer) and §5 (consumer), and
|
|
|
354
379
|
session model and never carried across sessions.
|
|
355
380
|
- Single-writer coexistence with `herdr-pi-tree`: no shared token names, no
|
|
356
381
|
dual-write, scoped sweep of own tokens on handover.
|
|
357
|
-
-
|
|
382
|
+
- An isolated Gentle Shell pane gets a `gs` row in the Agents sidebar, and the
|
|
383
|
+
label never lies. Herdr identifies an agent from the pane's foreground
|
|
384
|
+
process group, whose canonical aliases are `pi` and `gentle-shell` — never
|
|
385
|
+
`gs` — so an isolated pane is detected only when its foreground group exposes
|
|
386
|
+
the gentle-shell process, and otherwise has no row at all. Qualification uses
|
|
387
|
+
that same input first: a pane belongs to the isolated install when a member of
|
|
388
|
+
its foreground process group exposes an argv/`argv0`/cmdline path under
|
|
389
|
+
`$XDG_DATA_HOME/gentle-shell/install` (else
|
|
390
|
+
`~/.local/share/gentle-shell/install`, anchored by `install/installation.json`)
|
|
391
|
+
— a real pane is launched from the user's project directory, so its cwd is
|
|
392
|
+
never the install, and cwd is only the fallback for an unreadable group. When
|
|
393
|
+
Herdr detects the pane, the daemon keeps Herdr's truthful identity and state
|
|
394
|
+
and only reports the presentation-only `--display-agent gs` label; when Herdr
|
|
395
|
+
detects nothing, it reports `pane report-agent --agent gs --state idle` from a
|
|
396
|
+
stable per-session source (`plugin:<plugin-id>:gs`) so the row exists at all.
|
|
397
|
+
That reported label is the last resort and is reversible: a changed foreground
|
|
398
|
+
group (the only thing that can make a new detection appear) releases exactly
|
|
399
|
+
this plugin's authority and re-decides within one beat, and `pane.exited` /
|
|
400
|
+
`pane.closed`, a pane leaving the install, a disabled sidebar, and daemon
|
|
401
|
+
shutdown all release it too. Discovery is one bounded `pane list` read plus
|
|
402
|
+
one `pane.process-info` per pane at start, on an explicit `--refresh`, and on
|
|
403
|
+
roster events — never per frame; writes are deduped, and a failure does
|
|
404
|
+
nothing and logs one line per reason. The gs pane's own live state stays
|
|
405
|
+
unobservable until the isolated install forwards `HERDR_ENV` to its agent (a
|
|
406
|
+
gentle-ai concern, out of scope here).
|
|
407
|
+
- Gentle mode is enabled by default: while selected, this extension is the single publisher of native `pane.report_agent` (`working`/`blocked`/`idle`) alongside its metadata beats, with session path-or-id binding, monotonic seq, and a serial latest-wins coalesced queue. Parity contract: `working` carries the specific working role in the message (oldest running role word — known short word, unknown sanitized name, or `gentle` with no delegation; never bare generic `working`; machine keys unchanged); terminal `idle` fires only on a truly empty settle (principal settled plus zero running/queued plus zero pending plus zero live background jobs plus no human-wait prompt; settle-with-delegates/pending/jobs stays `working`, emitted once). Live background jobs (`bash_background` / `monitor`) are read from Gentle Shell's session-scoped `gentle-ai:jobs-sidebar` bus event, so waiting on a CI run or a long command keeps the row on `gentle` and never reaches `done`; `blocked` fires only for an actual human-wait intervention leg with its label (review/RDD execution stays `working`, silent). `blocked` is never derived from an error: native `blocked` is what fires the host's NeedsAttention toast and sound, so a failed run shows our own `error` state — the durable, session-bound `gentle_error_v1` token (republished every beat while the leg stands, cleared when it releases) that the sidebar reduces to the `error` row word — while the pane stays on `working`, and a failed tool call (or a delegate that ended `failed`, or a failed beat transport) changes nothing at all: it is detected and logged, never published, and never reaches the error token. The native status keeps its aggregate meaning — it reads `working` while any delegate runs — while the sidebar row's working-vs-idle decision reads the principal-only `gentle_principal_v1` marker, so an idle principal with a running delegate shows the delegate role word instead of `gentle`. Our code never emits `done`/`finished` native states or a Herdr notification (the opt-in Moshi replacement below is a separate, off-by-default channel): the host owns finished text on `done`, `blocked`/unknown presentation, sound, and all desktop attention toasts (ask + finish) — there is no consumer toast path left to dedup. Single publisher by design: the managed native extension file stays on disk and is excluded through an ownership-bound Pi settings entry while Gentle mode is selected. `node bin/gentle-sidebar.js disable` removes only our owned exclusion and managed rows, gates our producer/daemon, and hands the sidebar back to the native publisher (running Pi sessions need `/reload`); never run both publishers on the same pane. Limits (unverified, host-owned): the host `idle`→`done`→`finished` mapping and unknown-state handling are owned by Herdr.
|
|
358
408
|
- Sidebar switch (`enable` / `disable` / `status` / `toggle`):
|
|
359
409
|
`node bin/gentle-sidebar.js <verb>` picks between this plugin's sidebar rows
|
|
360
410
|
and the native Herdr sidebar. `status` is read-only; `enable` converges the
|
|
@@ -366,12 +416,17 @@ See [DESIGN.md](DESIGN.md) §4 (producer) and §5 (consumer), and
|
|
|
366
416
|
no argument the command opens the floating panel in Gentle Shell's own
|
|
367
417
|
layout: one left `CATEGORIES` list (`Herdr Sidebar`, `Moshi notifications`)
|
|
368
418
|
and one right pane headed `<Category> · n/m` with its setting rows, each row
|
|
369
|
-
painting the stored value with `●` and the other with `○`;
|
|
370
|
-
|
|
419
|
+
painting the stored value with `●` and the other with `○`; one line above the
|
|
420
|
+
footer describes the focused setting (`<setting> — <what it changes>`), and
|
|
421
|
+
the footer reads
|
|
422
|
+
`←/→ or Tab panes · ↑/↓ move · Enter apply · Esc close`, while `←/→` or
|
|
371
423
|
`Tab` moves between the category and value panes, `↑/↓` or `j/k` moves the
|
|
372
|
-
cursor
|
|
373
|
-
|
|
374
|
-
|
|
424
|
+
cursor, `Enter` applies the focused row and `Esc` closes without a write. The
|
|
425
|
+
legend names only keys: it never advertises `Click`, because every token in
|
|
426
|
+
it is a key the panel answers to, and a narrow card compacts it instead of
|
|
427
|
+
wrapping. Pointer input still works without being advertised — a click on a
|
|
428
|
+
category selects it, a click on a row applies it, and a click outside the
|
|
429
|
+
panes is ignored. The notifications switch appears twice — as its own
|
|
375
430
|
`Moshi notifications` category and as a `Notifications` row inside
|
|
376
431
|
`Herdr Sidebar` — and both rows read the one flag below, so the state they
|
|
377
432
|
show can never disagree. The plain two-step menu stays as the fallback
|
|
@@ -410,7 +465,10 @@ See [DESIGN.md](DESIGN.md) §4 (producer) and §5 (consumer), and
|
|
|
410
465
|
session row, terminal context, phone-side approvals) keeps working, but
|
|
411
466
|
notifications follow this plugin's policy — one when Pi really needs your
|
|
412
467
|
input (`ask`) and one when Pi really finishes. Nothing per prompt, nothing per
|
|
413
|
-
turn
|
|
468
|
+
turn, and nothing at all while the flag is off: every envelope path requires
|
|
469
|
+
the flag at send time, so a context captured for Chat View while the channel
|
|
470
|
+
was on can never authorize a notification after it is turned off. If
|
|
471
|
+
`extensions/moshi-hooks.ts` is installed, add
|
|
414
472
|
`-extensions/moshi-hooks.ts` to the `extensions` list in your Pi
|
|
415
473
|
`settings.json` so the Moshi-managed hook cannot notify in parallel; that edit
|
|
416
474
|
leaves every other settings key and entry untouched. Removal of the flag (or
|
|
@@ -427,7 +485,9 @@ See [DESIGN.md](DESIGN.md) §4 (producer) and §5 (consumer), and
|
|
|
427
485
|
heartbeat tick). Ambiguous, stale, or oversize snapshots never clear
|
|
428
486
|
tasks. Known limits: delegates that launch and finish between presence
|
|
429
487
|
publications never appear and still depend on chat delivery, and
|
|
430
|
-
absence-driven completion records `completed` without
|
|
488
|
+
absence-driven completion records `completed` without touching the error
|
|
489
|
+
leg; a delegate that ended `failed` is detected and logged, never published
|
|
490
|
+
as state.
|
|
431
491
|
- TTL-bounded tokens: stale panes fall back to native `idle`.
|
|
432
492
|
- Herdr session opener (`herdr_session_open`): opens a Herdr panel running a
|
|
433
493
|
Pi session at a path. A linked Git worktree opens as a **worktree panel**
|