herdr-gentle-shell 1.3.0 → 1.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/DESIGN.md CHANGED
@@ -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 visible text ever carries
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
@@ -130,7 +131,8 @@ an explicit writer-ownership decision. Rationale follows each choice.
130
131
  `error:`) plus the native `pane.report_agent` state; desktop attention is
131
132
  native Herdr exclusively (E9 unchanged): `Blocked` fires the `NeedsAttention`
132
133
  toast and background `Working|Blocked → Idle` fires `Finished`, both
133
- Herdr-owned. The consumer emits `herdr notification` for nothing — its
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
134
136
  former ask toast fired on the poll after the native one for the same
135
137
  question, a systematic duplication, so the toast path, its copy, the
136
138
  notification ledger and the send machinery were removed in v0.3.1. The ask
@@ -203,7 +205,8 @@ Sidecar only: ships beside `herdr-agent-state.ts`, never modifies it.
203
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 |
204
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 `?`) |
205
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 |
206
- | agent error / task failed / transport failure | `herdr:blocked` label `error:<code>` | `blocked` (machine key `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 |
207
210
  | `agent_settled` + 0 active subs | `gentle_work_v1=<hash>:0:<exp>`; clear `blocked` labels | `done` |
208
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) |
209
212
 
@@ -286,7 +289,20 @@ running delegate or a pending launch — neither of which says the
286
289
  principal itself works. The native status keeps that aggregate meaning for
287
290
  Herdr's own pane state; the row's working-vs-idle decision reads only
288
291
  `gentle_principal_v1` (§5.2). It carries no count and alters neither the work
289
- total nor the roles CSV.
292
+ total nor the roles CSV. `agentActive` alone would render that blocked call
293
+ as generic `gentle`.
294
+ The root session additionally emits `gentle_pending_v1` (`<hash>:<role>:<exp>`)
295
+ while a synchronous (task mode) `subagent_run`/`subagent_continue` tool call
296
+ is still in flight: such a call blocks the principal's own turn, so the
297
+ session is executing a tool call and waiting on the child rather than doing
298
+ its own model work. The value is the role word of the OLDEST in-flight
299
+ recognized launch (`agentToRole` of the pending record), republished on every
300
+ beat so a long child run stays covered by the ordinary beat, and cleared to
301
+ null the beat the call resolves, the agent settles, or the session resets.
302
+ It carries no count and alters neither the work total nor the roles CSV. A
303
+ background launch resolves its tool call immediately, so a queued or running
304
+ background delegate never publishes this marker and never changes the
305
+ principal's own display (S3).
290
306
 
291
307
  ### 4.3 Token formats (ABNF-ish, strict)
292
308
 
@@ -327,6 +343,21 @@ gentle_principal_v1 = sessionHash ":" expiry
327
343
  ; principal settles; decides working vs idle in §5.2
328
344
  ; while the native status keeps its aggregate meaning
329
345
  ; (running delegate / pending launch = working)
346
+ ; caveat: a synchronous launch keeps it fresh for the
347
+ ; whole blocked call — gentle_pending_v1 below carries the
348
+ ; child's role for that window
349
+ gentle_pending_v1 = sessionHash ":" role ":" expiry
350
+ ; blocking-delegate marker — fresh while a synchronous
351
+ ; (task mode) subagent_run/subagent_continue tool call is
352
+ ; in flight, carrying the role word of the OLDEST
353
+ ; in-flight recognized launch; republished on every beat
354
+ ; (same TTL discipline as gentle_work_v1) and null (clear)
355
+ ; the beat the call resolves, the agent settles, or the
356
+ ; session resets. Renders at role precedence in §5.2:
357
+ ; below attention and terminal done, above the principal
358
+ ; marker — the principal's turn is blocked on that child.
359
+ ; Background launches resolve immediately and never
360
+ ; publish it, so they never change the principal's row.
330
361
  gentle_done_v1 = sessionHash ":" expiry
331
362
  ; synthesized finish signal, no count — minted ONCE at the
332
363
  ; settled-and-empty edge (principal settled, zero
@@ -354,6 +385,17 @@ gentle_review_v1 = sessionHash ":" reviewId ":" expiry
354
385
  ; execution is in flight, null (clear) otherwise; silent
355
386
  ; working natively, never a notification (full def:
356
387
  ; extensions/gentle-herdr-state.ts, herdr-plugin/lib/gentle-tokens.js)
388
+ gentle_error_v1 = sessionHash ":" code ":" expiry
389
+ ; durable run-error signal, session-bound + TTL-fresh —
390
+ ; emitted on every beat while the run-error leg stands
391
+ ; (the agent run itself stopped on an error), null
392
+ ; (clear) the beat it releases; the sidebar's ONLY error
393
+ ; carrier (the native report never claims `blocked`, so
394
+ ; no toast, no sound, no phone envelope). Tool-level
395
+ ; failures never reach it (they are telemetry only).
396
+ ; Consumer: fresh token => `error` display (row word
397
+ ; `blocked`, silent) with the same
398
+ ; error > ask > review priority as the label leg.
357
399
  herdr:blocked = "ask:" intentId / "review:" reviewId / "error:" code
358
400
  ```
359
401
 
@@ -378,9 +420,11 @@ pane.report_metadata --source gentle:v1 --token gentle_work_v1=Ab3_xK9q2mZ7QwErT
378
420
  pane.report_metadata --source gentle:v1 --token gentle_roles_v1=worker,explorer
379
421
  pane.report_metadata --source gentle:v1 --token gentle_orchestrating_v1=Ab3_xK9q2mZ7QwErTyUiOpAsDfGhJkL012345678:1789000000000
380
422
  pane.report_metadata --source gentle:v1 --token gentle_principal_v1=Ab3_xK9q2mZ7QwErTyUiOpAsDfGhJkL012345678:1789000000000
423
+ pane.report_metadata --source gentle:v1 --token gentle_pending_v1=Ab3_xK9q2mZ7QwErTyUiOpAsDfGhJkL012345678:worker:1789000000000
381
424
  pane.report_metadata --source gentle:v1 --token gentle_names_v1=planner,code-writer
382
425
  pane.report_metadata --source gentle:v1 --token gentle_changes_v2=Ab3_xK9q2mZ7QwErTyUiOpAsDfGhJkL012345678:5:110:22:1789000000000
383
- herdr:blocked labels: ["ask:q-7f3a"] | ["review:r-42"] | ["error:transport-timeout"]
426
+ pane.report_metadata --source gentle:v1 --token gentle_error_v1=Ab3_xK9q2mZ7QwErTyUiOpAsDfGhJkL012345678:run-failed:1789000000000
427
+ herdr:blocked labels: ["ask:q-7f3a"] | ["review:r-42"] | ["error:run-failed"]
384
428
  ```
385
429
 
386
430
  Example reads: worker oldest + explorer active with count 2 → sidebar
@@ -433,7 +477,10 @@ principal marker the pane shows the oldest role word (or `idle`), never
433
477
  new/reloaded session under a different session hash cannot retain the prior
434
478
  session's change token. `gentle_names_v1` clears the same way when the
435
479
  authoritative active TaskStore list has no labels, and `gentle_roles_v1`
436
- clears (null) when no delegation is active. The retired disclosure token is
480
+ clears (null) when no delegation is active. `gentle_pending_v1` clears
481
+ (null) on the first beat after the blocking call resolves, the agent
482
+ settles, or the session resets — the same full-state discipline, never a
483
+ lingering edge. The retired disclosure token is
437
484
  cleared to remove any stale metadata. v2 stays the visible
438
485
  normative source; v1 remains legacy only.
439
486
 
@@ -448,8 +495,13 @@ carry it as a suffix only when above one), `gentle_orchestrating_v1` (root-only
448
495
  + freshness gate for the `orchestrating` display — never rendered as a
449
496
  count), `gentle_principal_v1` (principal-only activity marker + freshness
450
497
  gate for the working-vs-idle decision — never rendered as a count),
498
+ `gentle_pending_v1` (blocking-delegate role marker + freshness gate for the
499
+ in-flight synchronous launch — renders the child's role word while the
500
+ principal's own turn is blocked on it),
451
501
  `gentle_done_v1` (synthesized finish signal + its own hold freshness gate
452
502
  for the reachable `done` display — the host never reports `done`, §4.3),
503
+ `gentle_error_v1` (durable run-error signal + freshness gate for the `error`
504
+ display — repairs a missed `error:` label edge, §4.3),
453
505
  `gentle_roles_v1` (authoritative activity roles,
454
506
  oldest-first by immutable firstSeen), `gentle_names_v1` (compat transport only — never
455
507
  rendered), `gentle_changes_v2` (normative; a
@@ -461,10 +513,22 @@ ignore them under O1 (never parsed for state, never deleted).
461
513
  ### 5.2 Reducer (priority order, first match wins)
462
514
 
463
515
  ```text
464
- error := herdr:blocked has error:* (fresh, §5.4)
516
+ error := fresh `gentle_error_v1` (durable per-beat token, §4.3)
517
+ OR herdr:blocked has error:* (fresh, §5.4) — one shared
518
+ priority: error > ask > review
465
519
  ask := fresh `gentle_ask_v1` (durable per-beat token, §4.3)
466
520
  OR herdr:blocked has ask:* (fresh)
467
521
  review := herdr:blocked has review:* (fresh)
522
+ blockingRole := fresh gentle_pending_v1 (session-bound, TTL-fresh) whose
523
+ role word is recognized — a synchronous subagent call is in
524
+ flight, so the principal's turn is blocked on that child;
525
+ renders exactly like the role branch below (display +
526
+ label via the role helpers, count suffix unchanged) and
527
+ outranks the principal marker, which stays fresh for the
528
+ whole blocked call. Stale, foreign, malformed, or
529
+ unrecognized evidence falls through. Background launches
530
+ resolve their tool call immediately, so a running background
531
+ delegate never reaches this branch.
468
532
  principalWorking := fresh gentle_principal_v1 (session-bound, TTL-fresh) —
469
533
  the principal's OWN activity, never the delegate count and
470
534
  never the aggregate native status (which reads working for
@@ -501,7 +565,7 @@ done := (native done OR fresh gentle_done_v1) AND gentle_work_v1
501
565
  idle := otherwise (native fallback; also all-gentle-tokens-missing-or-expired)
502
566
  ```
503
567
 
504
- Priority: `error > ask > review > done > principal working > role > orchestrating > working(main) > idle`.
568
+ Priority: `error > ask > review > done > blockingRole > principal working > role > orchestrating > working(main) > idle`.
505
569
  `done` is matched before the principal/role branches in the reducer; it is
506
570
  listed here below the activity branches only so its settled-and-empty
507
571
  precondition reads together.
@@ -514,7 +578,13 @@ principal** renders `gentle` (pink
514
578
  `orchestrating` while a fresh root marker is live) and outranks every
515
579
  delegate role word; an **idle principal** shows the oldest running role word
516
580
  (`explorer`, `worker`, `verify`, `judge`, or `rdd` when it is the oldest)
517
- however many delegates run. The fresh marker is not a principal-working
581
+ however many delegates run. The one exception sits between them and is
582
+ evidence-based, never a precedence guess: while a **synchronous**
583
+ `subagent_run`/`subagent_continue` call is in flight the principal's own turn
584
+ is blocked on the child, so the fresh `gentle_pending_v1` role word decides
585
+ the row (below attention and the terminal `done`, above the principal
586
+ marker). Background launches resolve their tool call immediately, so a queued
587
+ or running background delegate never changes the principal's own display. The fresh marker is not a principal-working
518
588
  signal (it stays live while the principal is idle with queued or running
519
589
  delegates), so it never outranks a role word. An in-flight attention `review`
520
590
  (fresh `review:` label or durable `gentle_review_v1` token) overrides the
@@ -566,8 +636,9 @@ marker, and only after the minted finish hold lapses does it recede to
566
636
  delegates run) | `ask` | `rdd` (user-facing word for the `review`
567
637
  machine key; a delegated rdd and a tool-only review both render `rdd` —
568
638
  review execution is silent, never a notification; only
569
- a waiting `ask` intent notifies once) | `blocked` (user-facing word for the `error`
570
- machine key) | `done` (settled-plus-empty only: principal settled with no
639
+ a waiting `ask` intent notifies once) | `blocked` (user-facing row word for the `error`
640
+ machine key; carried by the durable `gentle_error_v1` token or the `error:`
641
+ label, and the pane's native state never claims `blocked` for it) | `done` (settled-plus-empty only: principal settled with no
571
642
  running delegates and no pending launches; a settled principal with
572
643
  running delegates keeps the role word) | `idle`. Role labels append the
573
644
  total count when at least two delegates run.
@@ -705,10 +776,17 @@ gentle-ai concern and explicitly out of scope for this plugin.
705
776
  id is a new sidebar ask episode (and a new native toast edge). The
706
777
  `intentId` doubles as the Moshi `approval_required` action id when the
707
778
  phone channel is enabled (§7).
708
- - Error containment: transport failure surfaces as `herdr:blocked`
709
- `error:<code>` (itself a token, subject to the same TTL), never as an
710
- exception path that stops the producer beat. `error` state clears only on a
711
- fresh non-error snapshot, not on silence.
779
+ - Error containment: a failed beat transport is telemetry (a counter and a
780
+ debug line), never state: it is our own report mechanism failing, not the
781
+ agent, so it neither paints `error:` nor raises native `blocked`, and the
782
+ next landed beat resets the counter. The one real error leg — the run
783
+ itself stopping on an error — is released by the next non-error beat
784
+ (`agent_start`, any tool activity, or a non-error assistant message), never
785
+ latched; no exception path ever stops the producer beat. While the leg
786
+ stands it publishes the durable `gentle_error_v1` token on every beat, so
787
+ an error the sidebar missed on one beat is repaired by the next, and the
788
+ release beat clears it (the missed-beat discipline of the ask/review
789
+ tokens).
712
790
  - No exactly-once end-to-end claim: at-least-once beats + TTL expiry is the
713
791
  engineered scope (consistent with the async/events guidance: never claim
714
792
  exactly-once without a deliberate mechanism). Desktop toast dedup is
@@ -727,9 +805,12 @@ gentle-ai concern and explicitly out of scope for this plugin.
727
805
  duplication. The ask token still drives the sidebar ask display; sounds,
728
806
  suppression, and delay stay Herdr's.
729
807
  - `review` and `error` never emit a plugin notification: `review` attention
730
- stays in-flow/native; `error` is visible as sidebar state (native `blocked`
731
- attention on `herdr:blocked` already fires per E9 — the plugin adds no
732
- toast path).
808
+ stays in-flow/native; `error` is sidebar state only — our own `error:` label
809
+ with the pane left on native `working`, so neither the `NeedsAttention`
810
+ toast nor its sound fires and no phone envelope is sent. Tool-level failures
811
+ (a failed tool call, a delegate record ending `failed`, a failed beat
812
+ transport) never touch state at all: they are detected and logged, nothing
813
+ more.
733
814
  - Optional Moshi replacement (off by default): one flag file,
734
815
  `gentle-moshi.json` in the plugin state root, holding
735
816
  `{"enabled":true}` and re-read per event by the producer extension. While
@@ -751,7 +832,12 @@ gentle-ai concern and explicitly out of scope for this plugin.
751
832
  running/queued plus zero pending plus zero live background jobs plus no
752
833
  human wait — never a raw native `working → idle` transition, which fires
753
834
  with work still left and skipped `done` entirely),
754
- never per prompt and never per turn. A `session.closed` (`session_ended`)
835
+ never per prompt and never per turn. Every envelope path requires the flag at
836
+ send time: a context captured for Chat View while the channel was on is
837
+ prefill only and never authorizes a notification after it is turned off, and
838
+ `task_complete` is announced at the minted `done` edge itself rather than
839
+ after a successful Herdr publish, so a failed token beat cannot drop it. A
840
+ `session.closed` (`session_ended`)
755
841
  envelope closes the row on shutdown, and the host-awaited handler flushes
756
842
  in-flight sends. `task_complete` carries title `Gentle finished: <project>`
757
843
  and names the last finished task: `<project> finished — <label>. Return to
@@ -773,7 +859,8 @@ gentle-ai concern and explicitly out of scope for this plugin.
773
859
  publishes to Moshi (single emitter). Moshi owns pairing and credentials
774
860
  (host secret in its own store); the plugin never reads or stores a token,
775
861
  and an absent daemon or unpaired host is a silent no-op that never
776
- interrupts Pi. `review` and `error` never notify. Limits (host-owned,
862
+ interrupts Pi. `review` and `error` never notify; a failed tool never even
863
+ changes state. Limits (host-owned,
777
864
  unverified): the phone-side approval round-trip through Moshi's TUI bridge,
778
865
  the Live Activity lifecycle, and whether a `task_complete` renders as a
779
866
  separate banner or only updates a running Live Activity are Moshi's.
@@ -790,7 +877,7 @@ report after a Pi restart or `/new` (both recreate the extension runtime)
790
877
  lose, freezing the pane's `agent_session` binding at the old session while
791
878
  the producer keeps beating for the new one — the consumer then rejects those
792
879
  fresh tokens as a session-hash mismatch and the pane stays on `idle` until a
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
880
+ 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
794
881
  reversibly (`-extensions/herdr-agent-state.ts` in Pi settings, bytes
795
882
  preserved on disk, never auto-loaded next to ours). `node
796
883
  bin/gentle-sidebar.js (enable|disable|status|toggle)` selects the
@@ -831,21 +918,27 @@ argument, Esc, or a cancelled menu writes nothing. With no argument the
831
918
  command opens the floating panel (`lib/customize-panel.js`, painted through its
832
919
  own palette) over `ctx.ui.custom` in Gentle Shell's own layout: one left
833
920
  `CATEGORIES` list, one right pane headed `<Category> · n/m` with its setting
834
- rows, each row painting the stored value with `●` and the other with `○`, and
835
- the footer
836
- `Click · ←/→ or Tab panes · ↑/↓ move · Enter apply · Esc close`. There is no
921
+ rows, each row painting the stored value with `●` and the other with `○`; one
922
+ line above the footer describes the focused setting
923
+ (`<setting> — <what it changes>`), and the footer
924
+ `←/→ or Tab panes · ↑/↓ move · Enter apply · Esc close`. There is no
925
+ `Click` token and no
837
926
  `Preview · …` band and no `p profiles` key: this plugin owns no profiles
838
- concept, so the footer advertises nothing it cannot do. `←/→` or `Tab` moves
927
+ concept, so the footer advertises nothing it cannot do — every token in it is a
928
+ key the panel answers to, and a narrow card compacts the legend instead of
929
+ wrapping it. `←/→` or `Tab` moves
839
930
  between the category and value panes, `↑/↓` or `j/k` moves the cursor, `Enter`
840
931
  applies the focused row and `Esc` closes without a write; a click on a category
841
932
  selects it, a click on a row applies it, and a click outside the panes is
842
933
  ignored (a press only captures the gesture, so a drag never applies a row).
843
934
  Each switch is one row that paints the stored state and carries the opposite
844
- value. The notifications switch appears under both `Herdr Sidebar` (as
845
- `Notifications`, where the plugin's own switches are looked for) and its own
846
- `Moshi notifications` category: a row names the switch it drives, so both
847
- apply the one `gentle-moshi.json` flag through `applyMoshiNotifications` and
848
- whosever change it was is what both rows read on the next render.
935
+ value. Each category owns exactly one switch: `Herdr Sidebar` shows the single
936
+ `Sidebar agent rows` row and its description names the managed agent rows only,
937
+ while the only Moshi switch is the `Notifications` row under
938
+ `Moshi notifications`, which applies the `gentle-moshi.json` flag through
939
+ `applyMoshiNotifications`. The two channels are never mixed: the sidebar-rows
940
+ switch neither reads nor writes that flag, so disabling the agent rows leaves
941
+ the notification channel exactly as it was.
849
942
  An inconclusive sidebar verdict (`unknown`) renders as `● Unknown` with a note
850
943
  instead of hiding the row: toggling still attempts the repair and reports the
851
944
  apply step's own error, exactly like the menu. The plain
@@ -859,11 +952,12 @@ exactly one mechanism writes each piece of state.
859
952
  ## 8. Limits
860
953
 
861
954
  - Token budget: ≤ 16 tokens per report per pane (E8 discipline); the
862
- producer emits at most 11 tokens per beat (including the retired
955
+ producer emits at most 12 tokens per beat (including the retired
863
956
  `gentle_subs_v1` clear) (`gentle_work_v1`,
864
957
  `gentle_roles_v1`, `gentle_names_v1`,
865
958
  `gentle_orchestrating_v1`, `gentle_principal_v1`, `gentle_done_v1`,
866
- `gentle_ask_v1`, `gentle_review_v1`, `gentle_changes_v2`,
959
+ `gentle_ask_v1`, `gentle_review_v1`, `gentle_error_v1`,
960
+ `gentle_changes_v2`,
867
961
  `gentle_changes_v1`) and the daemon publishes its 72-token owned family
868
962
  chunked ≤ 16 per report (row 1 is the 3 native tokens
869
963
  `state_icon`/`workspace`/`agent`; the legacy 11 `gentle_heading_*` compat
package/README.md CHANGED
@@ -15,11 +15,18 @@ subagents — (machine display key
15
15
  (`gentle_principal_v1`, published while the principal session itself works and
16
16
  cleared when it settles) decides the row — never the delegate count, and
17
17
  never Herdr's aggregate native status (which reads `working` whenever any
18
- delegate runs): while the principal is working it
19
- reads `gentle` and no delegate role word wins; while the principal is idle
18
+ delegate runs): the default is still the principal's own state, so while the
19
+ principal works its own turn it reads `gentle` and no delegate role word
20
+ wins; while the principal is idle
20
21
  the oldest running delegate role shows — `explorer`, `worker`, `verify`,
21
22
  `judge`, `rdd` — with the total running count in parentheses when two or
22
- more subagents run, for example `explorer (3)`),
23
+ more subagents run, for example `explorer (3)`). The single exception is a
24
+ blocking synchronous subagent call (`gentle_pending_v1`): a task-mode
25
+ `subagent_run`/`subagent_continue` holds the principal's turn open until the
26
+ child returns, so the principal is waiting on that child rather than working
27
+ and the in-flight child's role renders instead. A queued or running
28
+ background delegate publishes no such marker and leaves the principal's
29
+ display untouched),
23
30
  `ask` (three independent event legs — choice, native questionnaire, legacy rpiv — plus
24
31
  executed `ask_user_question`/`ask_user_choice` tool calls (execution opens, end/result closes;
25
32
  proposals never block), tool-gated `ui_prompt` dialog spans (a `custom` panel — agents view, ODD
@@ -201,7 +208,12 @@ and token names stay `review` — review execution is silent, never a
201
208
  notification; only an actual waiting prompt renders `ask` (desktop attention
202
209
  is Herdr's native `blocked` toast); the judge delegate role renders `judge` in
203
210
  purple `#cba6f7` (distinct from explorer blue, verify teal, and
204
- orchestrating pink); the error value renders `blocked`; the orchestrating
211
+ orchestrating pink); the error value renders `blocked` as the row word for
212
+ the `error` machine key (never the pane's native state — an error is
213
+ sidebar-only, DESIGN §7; it rides the durable session-bound
214
+ `gentle_error_v1` token, republished on every beat while the run-error leg
215
+ stands and cleared the beat it releases, so a beat the sidebar missed is
216
+ repaired by the next one); the orchestrating
205
217
  leg renders the user-facing word `gentle` (machine key stays
206
218
  `orchestrating`, pink `#f5c2e7`). Remaining state colors:
207
219
  working/worker amber `#f9e2af`, explorer blue `#89b4fa`, verify teal
@@ -248,12 +260,19 @@ aggregate native status (the work token counts running delegates, and the
248
260
  native status reads `working` for any running delegate or pending launch — so
249
261
  neither can say the principal works): the dedicated
250
262
  `gentle_principal_v1` marker is published while the principal session itself
251
- works and cleared when it settles. A **working principal** reads `gentle` —
252
- pink
263
+ works and cleared when it settles. That is the default: a **working
264
+ principal** reads `gentle` — pink
253
265
  `orchestrating` while a fresh root marker is live — and no delegate role word
254
266
  wins; an **idle principal** shows the oldest running TaskStore role
255
267
  (`explorer`, `worker`, `verify`, `judge`, `rdd`), however many delegates run.
256
- Both yield to `ask`/`rdd`/`blocked` and terminal `done` — where `done` needs
268
+ The one exception is a blocking synchronous subagent call: while a task-mode
269
+ `subagent_run`/`subagent_continue` is in flight the principal's own turn is
270
+ blocked on the child, so the producer publishes that child's role in
271
+ `gentle_pending_v1` and it renders instead of `gentle`, for as long as the
272
+ call lasts. Background launches resolve their tool call immediately, so a
273
+ queued or running background delegate publishes no such marker and leaves
274
+ the principal's own display untouched. These yield to `ask`/`rdd`/`blocked`
275
+ and terminal `done` — where `done` needs
257
276
  settled-plus-empty (principal settled with no running delegates and no
258
277
  pending launches; a settled principal with running delegates keeps the role
259
278
  word, never `done`). A role word is not a subagent label; it carries the
@@ -301,9 +320,10 @@ and confirm row 2 shows pink `gentle` (machine key
301
320
  `orchestrating`) while
302
321
  the principal session actively works — even with zero subagents — and keeps
303
322
  `gentle` while its delegates run (a role word such as `worker`, `explorer`,
304
- `verify`, `judge` shows once the principal itself is idle), row 1 shows
305
- the single heading cell (`● <project>` plus ` +N`/` -N`/` ↑N` inline, zero `·`) after edits / when behind upstream; then `ask` on an open
306
- 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 `blocked` on error. `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
323
+ `verify`, `judge` shows once the principal itself is idle — and also while a
324
+ task-mode subagent call blocks the principal's turn, until it returns), row 1
325
+ shows the single heading cell (`● <project>` plus ` +N`/` -N`/` ↑N` inline, zero `·`) after edits / when behind upstream; then `ask` on an open
326
+ 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
307
327
  `HERDR_CONFIG_PATH` on a temp file for apply/uninstall checks.
308
328
 
309
329
  ## Core Workflow
@@ -348,9 +368,13 @@ See [DESIGN.md](DESIGN.md) §4 (producer) and §5 (consumer), and
348
368
  settled-plus-empty)) and the authoritative TaskStore role signal
349
369
  (`explorer` / `worker` / `verify` / `judge` / `rdd` from `TaskRecord.agent`,
350
370
  oldest running first by immutable first-seen, shown while the principal
351
- itself is idle — a working principal keeps `gentle`, asserted by the
352
- principal-only `gentle_principal_v1` marker rather than by the delegate
353
- count or Herdr's aggregate native status; `gentle` (machine
371
+ itself is idle — a working principal's own turn keeps `gentle`, asserted by
372
+ the principal-only `gentle_principal_v1` marker rather than by the delegate
373
+ count or Herdr's aggregate native status, with one exception: a blocking
374
+ synchronous `subagent_run`/`subagent_continue` call holds the principal's
375
+ turn open, so the in-flight child's role shows instead (the
376
+ `gentle_pending_v1` role marker) until that call resolves, while a
377
+ background delegate never takes that path; `gentle` (machine
354
378
  key `working`) for the principal's own working state; an unknown delegation
355
379
  keeps its original sanitized name, 32-char bound — never a generic
356
380
  collapse), with a running-count suffix on role labels when two or more
@@ -358,7 +382,11 @@ See [DESIGN.md](DESIGN.md) §4 (producer) and §5 (consumer), and
358
382
  `rdd` during native review execution (machine key stays `review`; execution
359
383
  is silent — desktop attention fires only for a waiting `ask` intent, as
360
384
  Herdr's native toast), and
361
- user-facing `blocked` for errors.
385
+ user-facing `blocked` as the row word for the `error` machine key (an
386
+ error never claims the native `blocked` state — that is the host's
387
+ NeedsAttention toast and sound, so the sidebar carries the error on the
388
+ durable `gentle_error_v1` token while the pane stays quiet on `working`,
389
+ and no phone envelope is sent).
362
390
  - Single-cell row-1 heading (`<icon> <project>` plus ` +N`/` -N`/` ↑N`
363
391
  inline, exactly one nonempty cell so zero `·` separators; white base with
364
392
  `contains` rules keeping ` +` green (added), ` -` red (deleted,
@@ -395,7 +423,7 @@ See [DESIGN.md](DESIGN.md) §4 (producer) and §5 (consumer), and
395
423
  nothing and logs one line per reason. The gs pane's own live state stays
396
424
  unobservable until the isolated install forwards `HERDR_ENV` to its agent (a
397
425
  gentle-ai concern, out of scope here).
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.
426
+ - 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.
399
427
  - Sidebar switch (`enable` / `disable` / `status` / `toggle`):
400
428
  `node bin/gentle-sidebar.js <verb>` picks between this plugin's sidebar rows
401
429
  and the native Herdr sidebar. `status` is read-only; `enable` converges the
@@ -407,15 +435,22 @@ See [DESIGN.md](DESIGN.md) §4 (producer) and §5 (consumer), and
407
435
  no argument the command opens the floating panel in Gentle Shell's own
408
436
  layout: one left `CATEGORIES` list (`Herdr Sidebar`, `Moshi notifications`)
409
437
  and one right pane headed `<Category> · n/m` with its setting rows, each row
410
- painting the stored value with `●` and the other with `○`; the footer reads
411
- `Click · ←/→ or Tab panes · ↑/↓ move · Enter apply · Esc close`, and `←/→` or
438
+ painting the stored value with `●` and the other with `○`; one line above the
439
+ footer describes the focused setting (`<setting> — <what it changes>`), and
440
+ the footer reads
441
+ `←/→ or Tab panes · ↑/↓ move · Enter apply · Esc close`, while `←/→` or
412
442
  `Tab` moves between the category and value panes, `↑/↓` or `j/k` moves the
413
- cursor while `Esc` closes. A click on a category selects it and a click on a
414
- row applies it, exactly like `Enter` on the focused row; clicks outside the
415
- panes are ignored. The notifications switch appears twice — as its own
416
- `Moshi notifications` category and as a `Notifications` row inside
417
- `Herdr Sidebar` — and both rows read the one flag below, so the state they
418
- show can never disagree. The plain two-step menu stays as the fallback
443
+ cursor, `Enter` applies the focused row and `Esc` closes without a write. The
444
+ legend names only keys: it never advertises `Click`, because every token in
445
+ it is a key the panel answers to, and a narrow card compacts it instead of
446
+ wrapping. Pointer input still works without being advertised — a click on a
447
+ category selects it, a click on a row applies it, and a click outside the
448
+ panes is ignored. Each category owns exactly one switch: `Herdr Sidebar`
449
+ shows the single `Sidebar agent rows` row, and the only Moshi switch is the
450
+ `Notifications` row under `Moshi notifications`. The two are never mixed —
451
+ `Sidebar agent rows` neither reads nor writes `gentle-moshi.json`, so turning
452
+ the agent rows off never turns the notification channel off. The plain
453
+ two-step menu stays as the fallback
419
454
  when the TUI helpers or `ctx.ui.custom` are unavailable.
420
455
  `Sidebar agent rows` drives the Herdr plugin's own `bin/configure.js`
421
456
  (`--check` to read, `--apply --reload` / `--uninstall --reload` to change) and
@@ -440,8 +475,8 @@ See [DESIGN.md](DESIGN.md) §4 (producer) and §5 (consumer), and
440
475
  mkdir -p "$dir" && echo '{"enabled":true}' > "$dir/gentle-moshi.json"
441
476
  ```
442
477
 
443
- `/herdr-gentle:customize` → `Moshi notifications` (or the `Notifications` row
444
- inside `Herdr Sidebar`) writes this flag for you, and enabling there first
478
+ `/herdr-gentle:customize` → `Moshi notifications` writes this flag for you,
479
+ and enabling there first
445
480
  requires the `moshi-hook` CLI on `PATH` with `moshi-hook status --json`
446
481
  reporting `paired: true` (an unpaired host is refused and nothing is
447
482
  written).
@@ -451,7 +486,10 @@ See [DESIGN.md](DESIGN.md) §4 (producer) and §5 (consumer), and
451
486
  session row, terminal context, phone-side approvals) keeps working, but
452
487
  notifications follow this plugin's policy — one when Pi really needs your
453
488
  input (`ask`) and one when Pi really finishes. Nothing per prompt, nothing per
454
- turn. If `extensions/moshi-hooks.ts` is installed, add
489
+ turn, and nothing at all while the flag is off: every envelope path requires
490
+ the flag at send time, so a context captured for Chat View while the channel
491
+ was on can never authorize a notification after it is turned off. If
492
+ `extensions/moshi-hooks.ts` is installed, add
455
493
  `-extensions/moshi-hooks.ts` to the `extensions` list in your Pi
456
494
  `settings.json` so the Moshi-managed hook cannot notify in parallel; that edit
457
495
  leaves every other settings key and entry untouched. Removal of the flag (or
@@ -468,7 +506,9 @@ See [DESIGN.md](DESIGN.md) §4 (producer) and §5 (consumer), and
468
506
  heartbeat tick). Ambiguous, stale, or oversize snapshots never clear
469
507
  tasks. Known limits: delegates that launch and finish between presence
470
508
  publications never appear and still depend on chat delivery, and
471
- absence-driven completion records `completed` without latching an error.
509
+ absence-driven completion records `completed` without touching the error
510
+ leg; a delegate that ended `failed` is detected and logged, never published
511
+ as state.
472
512
  - TTL-bounded tokens: stale panes fall back to native `idle`.
473
513
  - Herdr session opener (`herdr_session_open`): opens a Herdr panel running a
474
514
  Pi session at a path. A linked Git worktree opens as a **worktree panel**