herdr-gentle-shell 1.5.1 → 1.5.2
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 +109 -54
- package/README.md +57 -38
- package/extensions/gentle-herdr-state.ts +285 -29
- package/package.json +1 -1
package/DESIGN.md
CHANGED
|
@@ -17,11 +17,15 @@ explicitly in §10 and are not decided here.
|
|
|
17
17
|
- Herdr sidebar (`[ui.sidebar.agents]` + `[ui.sidebar.spaces]` blocks): shows
|
|
18
18
|
one state label per pane plus an optional session-changes badge.
|
|
19
19
|
- The human operator watching Pi + Gentle Shell agents: needs to distinguish
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
20
|
+
the principal session's own pink `gentle` (machine key `orchestrating` —
|
|
21
|
+
its working status and its generic status) from a delegate's own word: the
|
|
22
|
+
active TaskStore role abbreviation (`explorer`, `worker`, `verify`,
|
|
23
|
+
`judge`, `rdd`) or, for a non-contemplated subagent, that subagent's
|
|
24
|
+
sanitized name on the amber `working` cell — plus `ask` (blocked on user
|
|
25
|
+
input), `blocked` (the row word for the `error` key), `done`, and `idle` at
|
|
26
|
+
a glance. No visible text ever carries a subagent count, exactly one
|
|
27
|
+
user-facing `gentle` exists (the pink one), the amber `working` cell never
|
|
28
|
+
renders that word, and `gentle` never renders on an idle session.
|
|
25
29
|
|
|
26
30
|
### Current boundary and interaction
|
|
27
31
|
|
|
@@ -201,13 +205,13 @@ Sidecar only: ships beside `herdr-agent-state.ts`, never modifies it.
|
|
|
201
205
|
|
|
202
206
|
| Producer event (source) | Tokens written | v1 state contribution |
|
|
203
207
|
|---|---|---|
|
|
204
|
-
| `agent_start` / `isIdle=false` (main actively working, incl. 0 active subs) | `gentle_work_v1=<hash>:0:<exp>` + `gentle_principal_v1=<hash>:<exp>` (principal-only activity marker) + `gentle_orchestrating_v1=<hash>:<exp>` (root marker while main actively works) + clear `herdr:blocked` labels | `gentle` (machine key `
|
|
208
|
+
| `agent_start` / `isIdle=false` (main actively working, incl. 0 active subs) | `gentle_work_v1=<hash>:0:<exp>` + `gentle_principal_v1=<hash>:<exp>` (principal-only activity marker) + `gentle_orchestrating_v1=<hash>:<exp>` (root marker while main actively works) + clear `herdr:blocked` labels | the pink `gentle` (machine key `orchestrating`, with or without a fresh root marker) while the principal session actively works, even with zero subagents |
|
|
205
209
|
| 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 |
|
|
206
210
|
| `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 `?`) |
|
|
207
211
|
| 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 |
|
|
208
212
|
| 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
213
|
| 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 |
|
|
210
|
-
| `agent_settled` + 0 active subs | `gentle_work_v1=<hash>:0:<exp>`; clear `blocked` labels | `done` |
|
|
214
|
+
| `agent_settled` + 0 active subs | `gentle_work_v1=<hash>:0:<exp>`; clear `blocked` labels | `done` — an observed turn only: the settle the beat reconciles from the host's live truth mints no finish (§4.5) |
|
|
211
215
|
| `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) |
|
|
212
216
|
|
|
213
217
|
`waiting`/`finished` TaskStore entries never count as active, and `queued`
|
|
@@ -234,11 +238,12 @@ exact `gentle-ai-worker` → `worker`, exact `gentle-ai-verify` → `verify`,
|
|
|
234
238
|
`jd-fix-` families) → the distinct `judge` slug (never `rdd`), and a
|
|
235
239
|
review agent / `gentle-ai-review*` / any role containing `review` → `rdd`;
|
|
236
240
|
any other agent keeps its original sanitized name (lowercase `[a-z0-9_-]`
|
|
237
|
-
slug, 32-char bound — never a generic collapse; unsalvageable shapes
|
|
238
|
-
|
|
241
|
+
slug, 32-char bound — never a generic collapse; unsalvageable shapes and the
|
|
242
|
+
reserved slugs `gentle`, `working`, and `subagent` read
|
|
243
|
+
the pink generic `gentle`, machine key `orchestrating`).
|
|
239
244
|
The consumer displays the oldest role word (known short word or unknown
|
|
240
245
|
sanitized name) whenever the principal itself is not working, regardless of
|
|
241
|
-
how many delegates run; a working principal renders `gentle` instead.
|
|
246
|
+
how many delegates run; a working principal renders the pink `gentle` instead.
|
|
242
247
|
Role labels carry the total running-delegate count in parentheses when greater
|
|
243
248
|
than one. Role order is immutable first-seen (progress reads never reorder;
|
|
244
249
|
sound same-session presence createdAt/startedAt may correct a late local
|
|
@@ -250,7 +255,8 @@ flight with no TaskStore record until it returns `tool_result`, so the exact
|
|
|
250
255
|
agent name in the pending `tool_call` input is the only live role evidence;
|
|
251
256
|
counting it would inflate the normative `gentle_work_v1` total with an
|
|
252
257
|
estimate, while publishing its role slug as a bounded-CSV hint keeps the
|
|
253
|
-
sidebar on the active role (`worker`, never
|
|
258
|
+
sidebar on the active role (`worker`, never the amber `working` cell —
|
|
259
|
+
generic activity reads the pink `gentle`) with the count
|
|
254
260
|
authoritative at 0. The hint merges with authoritative active TaskStore roles
|
|
255
261
|
(oldest-first) and clears when the tool result arrives, the call is
|
|
256
262
|
cancelled, or the agent settles. On a tool
|
|
@@ -264,7 +270,7 @@ launch outcomes keep `running` (and its agent) against `queued`/`waiting`/
|
|
|
264
270
|
re-resolve oldest-first — so a working principal with live delegates keeps
|
|
265
271
|
`gentle`, and a settle with running delegates keeps the oldest role word
|
|
266
272
|
instead of settling to `idle`/`done`. A sanitized unknown slug exactly equal to
|
|
267
|
-
`working` degrades to no role (generic `gentle`) on both the producer
|
|
273
|
+
`working` degrades to no role (the pink generic `gentle`) on both the producer
|
|
268
274
|
(`agentToRole`) and the consumer (`roleToDisplay`) sides. No local
|
|
269
275
|
age/staleness timeout is applied — Gentle Shell owns lifecycle/status truth.
|
|
270
276
|
Finished/failed/cancelled records may linger in the map but never count;
|
|
@@ -276,10 +282,11 @@ coverage while the authoritative active list is non-empty or any
|
|
|
276
282
|
once the main session settles — settled, or any non-root session. The marker carries no
|
|
277
283
|
count and changes neither the work total nor the roles CSV: it is a pure
|
|
278
284
|
freshness-bound presence flag (`<hash>:<exp>`, same binding/TTL style as
|
|
279
|
-
gentle_work_v1) that the consumer reduces to `
|
|
280
|
-
|
|
281
|
-
terminal `done`/native-`blocked`, and
|
|
282
|
-
|
|
285
|
+
gentle_work_v1) that the consumer reduces to the same pink `gentle` the
|
|
286
|
+
principal's own activity renders, only with no role word above it (§5.2):
|
|
287
|
+
below attention (error/ask/review), terminal `done`/native-`blocked`, and
|
|
288
|
+
role words; ahead of the positive-count generic fallback only, which renders
|
|
289
|
+
that same pink `gentle`.
|
|
283
290
|
The root session also emits `gentle_principal_v1` while its own agent is
|
|
284
291
|
active (`agentActive`) and clears it (null) the moment the principal
|
|
285
292
|
settles, keeping the same binding/TTL discipline. This is the principal-only
|
|
@@ -290,7 +297,7 @@ principal itself works. The native status keeps that aggregate meaning for
|
|
|
290
297
|
Herdr's own pane state; the row's working-vs-idle decision reads only
|
|
291
298
|
`gentle_principal_v1` (§5.2). It carries no count and alters neither the work
|
|
292
299
|
total nor the roles CSV. `agentActive` alone would render that blocked call
|
|
293
|
-
as generic `gentle`.
|
|
300
|
+
as the pink generic `gentle`.
|
|
294
301
|
The root session additionally emits `gentle_pending_v1` (`<hash>:<role>:<exp>`)
|
|
295
302
|
while a synchronous (task mode) `subagent_run`/`subagent_continue` tool call
|
|
296
303
|
is still in flight: such a call blocks the principal's own turn, so the
|
|
@@ -326,7 +333,10 @@ role = "explorer" / "worker" / "verify" / "judge" / "rdd" / passthrou
|
|
|
326
333
|
; stays distinct, never `rdd`)
|
|
327
334
|
; passthrough = 1*32 lowercase [a-z0-9_-], leading [a-z0-9]
|
|
328
335
|
; (unknown delegation keeps its sanitized original name —
|
|
329
|
-
; never a generic collapse; producer truncates to 32
|
|
336
|
+
; never a generic collapse; producer truncates to 32;
|
|
337
|
+
; the reserved words `gentle`, `working`, and `subagent`
|
|
338
|
+
; resolve to no role on both sides — producer and reducer —
|
|
339
|
+
; so they degrade to the pink generic `gentle`)
|
|
330
340
|
gentle_roles_v1 = role *("," role) ; total <= 512 UTF-8 bytes; null (clear)
|
|
331
341
|
; when no delegation is active (no role words)
|
|
332
342
|
gentle_orchestrating_v1 = sessionHash ":" expiry
|
|
@@ -435,17 +445,19 @@ explorers with count 3 → `explorer (3)`; 5 files
|
|
|
435
445
|
`● myproj +110 -22` (` +` green for added, ` -` red for deleted with a
|
|
436
446
|
leading-space match, zero `·` separators because exactly one heading cell
|
|
437
447
|
is nonempty).
|
|
438
|
-
A review label renders `rdd` with a blue `●` (`#89b4fa`, same as explorer/pull). A
|
|
439
|
-
`gentle_orchestrating_v1` marker renders pink `gentle` (machine display
|
|
440
|
-
`orchestrating`, pink palette unchanged)
|
|
441
|
-
|
|
442
|
-
attention (`ask`/`review`/`blocked`) and terminal `done` states.
|
|
443
|
-
|
|
444
|
-
|
|
445
|
-
|
|
446
|
-
|
|
447
|
-
|
|
448
|
-
`gentle`
|
|
448
|
+
A review label renders `rdd` with a blue `●` (`#89b4fa`, same as explorer/pull). A
|
|
449
|
+
`gentle_orchestrating_v1` marker renders the pink `gentle` (machine display
|
|
450
|
+
key `orchestrating`, pink palette unchanged): it covers the principal's
|
|
451
|
+
queued/running subs and pending launches, and it yields to a delegate role
|
|
452
|
+
word and to attention (`ask`/`review`/`blocked`) and terminal `done` states.
|
|
453
|
+
The marker is not a principal-working signal: it stays live while the
|
|
454
|
+
principal is idle with queued or running delegates, so it never decides the
|
|
455
|
+
working state. That state comes from `gentle_principal_v1` alone, and it is
|
|
456
|
+
the same pink `gentle` with or without a fresh root marker: the amber
|
|
457
|
+
`working` cell is never the principal's own. With no fresh principal marker
|
|
458
|
+
the pane shows the oldest role word, the pink generic `gentle` when a running
|
|
459
|
+
delegate has no resolvable name, or `idle` — but never an amber generic
|
|
460
|
+
because delegates run.
|
|
449
461
|
|
|
450
462
|
### 4.5 Publication and chunking
|
|
451
463
|
|
|
@@ -470,6 +482,27 @@ principal marker the pane shows the oldest role word (or `idle`), never
|
|
|
470
482
|
- Writes are idempotent full-state snapshots per pane (all gentle tokens
|
|
471
483
|
re-emitted each beat), never deltas — a lost report is repaired by the next
|
|
472
484
|
beat.
|
|
485
|
+
- The producer beats every 15 s by default; `GENTLE_HERDR_BEAT_MS` overrides
|
|
486
|
+
the cadence for tests and debugging (clamped to [100, 300000]). The
|
|
487
|
+
override changes no TTL: the write horizon stays `now+60000` (§8).
|
|
488
|
+
- Every beat first reconciles the settle from the host's own live truth: with
|
|
489
|
+
no turn active and no work evidence (no running/queued delegate, no pending
|
|
490
|
+
launch, no live background job), the retained context's `isIdle()` flips
|
|
491
|
+
`settled`, so a run whose `agent_settled` never reached the producer still
|
|
492
|
+
reaches native `idle` instead of republishing a fresh count-0 work token
|
|
493
|
+
forever. A turn this producer saw start is never overridden from there.
|
|
494
|
+
When the host offers no truth at all, a producer that observed no turn stops
|
|
495
|
+
beating after a bounded budget (three beats) instead of publishing a native
|
|
496
|
+
state the host never confirmed; a turn this producer saw start is never
|
|
497
|
+
bounded, so the budget cannot trade a truthful `working` for a false `idle`
|
|
498
|
+
on a host with no truth to settle on. The beat is re-armed by the edges that
|
|
499
|
+
schedule a publish (ask, review, launch, session changes, jobs), while an
|
|
500
|
+
ordinary tool edge reaches the row through the host's own truth rather than
|
|
501
|
+
by re-arming it. A settle recovered this way is not an observed turn, so it
|
|
502
|
+
mints no `gentle_done_v1` and sends no finish notification.
|
|
503
|
+
- The settle-time pending latch (`pendingCount`) is bounded by the finish hold
|
|
504
|
+
of the settle that raised it: past that hold a launch that never reports
|
|
505
|
+
back stops counting, so it cannot pin the native report at `working`.
|
|
473
506
|
- Session-change tokens are refreshed/cleared from the current Gentle Shell
|
|
474
507
|
session model every beat and never carried across sessions: zero changed
|
|
475
508
|
files publishes a clear (null over socket metadata, `--clear-token <name>`
|
|
@@ -532,17 +565,20 @@ blockingRole := fresh gentle_pending_v1 (session-bound, TTL-fresh) whose
|
|
|
532
565
|
principalWorking := fresh gentle_principal_v1 (session-bound, TTL-fresh) —
|
|
533
566
|
the principal's OWN activity, never the delegate count and
|
|
534
567
|
never the aggregate native status (which reads working for
|
|
535
|
-
any running delegate or pending launch); renders
|
|
536
|
-
`orchestrating`
|
|
537
|
-
|
|
568
|
+
any running delegate or pending launch); renders the pink
|
|
569
|
+
`gentle` (machine key `orchestrating`) with or without a
|
|
570
|
+
fresh gentle_orchestrating_v1; outranks every delegate role
|
|
538
571
|
word; stale, foreign, or absent falls through to the
|
|
539
572
|
branches below
|
|
540
573
|
role := gentle_work_v1 fresh AND gentle_roles_v1 yields a
|
|
541
574
|
recognized role (oldest first, incl. the in-flight pending
|
|
542
575
|
role hint at count = 0 for task-mode launches with no
|
|
543
576
|
TaskStore record yet) — the principal is not working, so the
|
|
544
|
-
delegate word wins
|
|
545
|
-
|
|
577
|
+
delegate word wins. A non-contemplated subagent renders on
|
|
578
|
+
the `working` display, whose label is that subagent's own
|
|
579
|
+
sanitized name (never `gentle`). Role and name labels append
|
|
580
|
+
the total when at least two delegates run. Tool-only review
|
|
581
|
+
has no suffix.
|
|
546
582
|
orchestrating := gentle_orchestrating_v1 fresh with no role word above
|
|
547
583
|
(root-only per §4.2: fresh while the main session actively
|
|
548
584
|
works, even with zero subagents, retaining running/queued-sub,
|
|
@@ -550,8 +586,11 @@ orchestrating := gentle_orchestrating_v1 fresh with no role word above
|
|
|
550
586
|
falls through to the
|
|
551
587
|
branches below; attention, terminal `done`/native-`blocked`,
|
|
552
588
|
a working principal, and role words stay higher)
|
|
553
|
-
|
|
554
|
-
|
|
589
|
+
generic := gentle_work_v1 fresh AND count > 0 with no role word —
|
|
590
|
+
renders the pink `gentle` (machine key `orchestrating`), the
|
|
591
|
+
principal session's generic status; a count = 0 beat asserts
|
|
592
|
+
no activity — it reaches `done` only through the terminal
|
|
593
|
+
gate, otherwise `idle`
|
|
555
594
|
done := (native done OR fresh gentle_done_v1) AND gentle_work_v1
|
|
556
595
|
fresh with count = 0 (no running delegates) AND no roles AND
|
|
557
596
|
no fresh gentle_orchestrating_v1 AND no fresh
|
|
@@ -565,7 +604,7 @@ done := (native done OR fresh gentle_done_v1) AND gentle_work_v1
|
|
|
565
604
|
idle := otherwise (native fallback; also all-gentle-tokens-missing-or-expired)
|
|
566
605
|
```
|
|
567
606
|
|
|
568
|
-
Priority: `error > ask > review > done > blockingRole > principal working > role > orchestrating >
|
|
607
|
+
Priority: `error > ask > review > done > blockingRole > principal working > role > orchestrating > generic > idle`.
|
|
569
608
|
`done` is matched before the principal/role branches in the reducer; it is
|
|
570
609
|
listed here below the activity branches only so its settled-and-empty
|
|
571
610
|
precondition reads together.
|
|
@@ -574,11 +613,15 @@ precondition reads together.
|
|
|
574
613
|
(error/ask/review) and the terminal `done` state always outrank principal
|
|
575
614
|
status and activity roles. Below them the principal's own activity decides,
|
|
576
615
|
never the delegate count and never the aggregate native status: a **working
|
|
577
|
-
principal** renders `gentle` (
|
|
578
|
-
|
|
579
|
-
|
|
616
|
+
principal** renders the pink `gentle` (machine key `orchestrating`, fresh
|
|
617
|
+
root marker or not) and outranks every delegate role word; an **idle
|
|
618
|
+
principal** shows the oldest running role word
|
|
580
619
|
(`explorer`, `worker`, `verify`, `judge`, or `rdd` when it is the oldest)
|
|
581
|
-
however many delegates run
|
|
620
|
+
however many delegates run, and falls back to that same pink `gentle` when a
|
|
621
|
+
running delegate has no resolvable name (that row is not idle: a delegate
|
|
622
|
+
runs). A live count-0 work token asserts no activity: it reaches `done` only
|
|
623
|
+
through the terminal gate above, otherwise `idle`, so `gentle` never renders
|
|
624
|
+
on an idle session. The one exception sits between them and is
|
|
582
625
|
evidence-based, never a precedence guess: while a **synchronous**
|
|
583
626
|
`subagent_run`/`subagent_continue` call is in flight the principal's own turn
|
|
584
627
|
is blocked on the child, so the fresh `gentle_pending_v1` role word decides
|
|
@@ -606,10 +649,13 @@ marker, and only after the minted finish hold lapses does it recede to
|
|
|
606
649
|
The visible second row is structural, with no rules: the eleven
|
|
607
650
|
presence-encoded
|
|
608
651
|
`gentle_title_<working|orchestrating|explorer|worker|verify|judge|ask|review|error|done|idle>`
|
|
609
|
-
state tokens (state word only: `
|
|
652
|
+
state tokens (a state word only: `gentle` (pink, machine key
|
|
610
653
|
`orchestrating`) / `explorer` / `worker` /
|
|
611
|
-
`verify` / `judge` / `ask` / `blocked` / `done` / `idle` / `review
|
|
612
|
-
|
|
654
|
+
`verify` / `judge` / `ask` / `blocked` / `done` / `idle` / `review` — with
|
|
655
|
+
the one exception that the amber `working` cell carries a
|
|
656
|
+
non-contemplated subagent's own sanitized name, never the word `working`
|
|
657
|
+
and never `gentle`; role and name words carry a running-count suffix above
|
|
658
|
+
one).
|
|
613
659
|
Only the current display's title token carries a value; the rest are null.
|
|
614
660
|
Each state cell carries its state's semantic color as its base fg with
|
|
615
661
|
no rules — working/worker golden `#f9e2af`, orchestrating pink fuchsia
|
|
@@ -625,13 +671,17 @@ marker, and only after the minted finish hold lapses does it recede to
|
|
|
625
671
|
tokens plus the row-2 title and change-segment tokens to
|
|
626
672
|
the pi-only `rows_by_agent` override (E10); exact block wiring is
|
|
627
673
|
install configuration, not protocol.
|
|
628
|
-
- Label shapes: `gentle`
|
|
629
|
-
principal's own working
|
|
630
|
-
with or without
|
|
631
|
-
|
|
632
|
-
|
|
633
|
-
root-session marker
|
|
634
|
-
|
|
674
|
+
- Label shapes: exactly one `gentle` — pink `#f5c2e7`, machine key
|
|
675
|
+
`orchestrating`: the principal session's own working status (asserted by a
|
|
676
|
+
fresh `gentle_principal_v1`, with or without a fresh root marker and with
|
|
677
|
+
or without delegated roles) and its generic status (a positive running
|
|
678
|
+
count with no resolvable name, only unsalvageable role shapes, or a fresh
|
|
679
|
+
root-session marker covering queued/running subs and pending launches);
|
|
680
|
+
never rendered on an idle session | the amber `working` cell (`#f9e2af`)
|
|
681
|
+
carries a non-contemplated subagent's own sanitized name from
|
|
682
|
+
`gentle_roles_v1` / `gentle_pending_v1` — never the word `working` and
|
|
683
|
+
never `gentle`, so a bare `working` display fails closed to the pink
|
|
684
|
+
`gentle` | `explorer` / `worker` / `verify` / `judge` (oldest
|
|
635
685
|
TaskStore role word while the principal itself is idle, however many
|
|
636
686
|
delegates run) | `ask` | `rdd` (user-facing word for the `review`
|
|
637
687
|
machine key; a delegated rdd and a tool-only review both render `rdd` —
|
|
@@ -782,7 +832,9 @@ gentle-ai concern and explicitly out of scope for this plugin.
|
|
|
782
832
|
next landed beat resets the counter. The one real error leg — the run
|
|
783
833
|
itself stopping on an error — is released by the next non-error beat
|
|
784
834
|
(`agent_start`, any tool activity, or a non-error assistant message), never
|
|
785
|
-
latched; no exception path ever stops the producer beat
|
|
835
|
+
latched; no exception path ever stops the producer beat (a quiet producer
|
|
836
|
+
with no host truth and no work evidence ends its own bounded budget instead,
|
|
837
|
+
§4.5). While the leg
|
|
786
838
|
stands it publishes the durable `gentle_error_v1` token on every beat, so
|
|
787
839
|
an error the sidebar missed on one beat is repaired by the next, and the
|
|
788
840
|
release beat clears it (the missed-beat discipline of the ask/review
|
|
@@ -881,7 +933,7 @@ report after a Pi restart or `/new` (both recreate the extension runtime)
|
|
|
881
933
|
lose, freezing the pane's `agent_session` binding at the old session while
|
|
882
934
|
the producer keeps beating for the new one — the consumer then rejects those
|
|
883
935
|
fresh tokens as a session-hash mismatch and the pane stays on `idle` until a
|
|
884
|
-
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
|
|
936
|
+
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 the pink generic `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). A settle the producer missed is recovered from the host's own live truth: a beat with nothing active and no work evidence reconciles `settled` from `isIdle()`, a quiet producer the host never answers stops beating after a bounded budget instead of republishing a count-0 work token forever, and only an observed turn mints `done`, so a reconciled settle announces nothing. 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 that delegate's own role word or name rather than the principal's `gentle`. Single publisher by design: the managed native extension file is excluded
|
|
885
937
|
reversibly (`-extensions/herdr-agent-state.ts` in Pi settings, bytes
|
|
886
938
|
preserved on disk, never auto-loaded next to ours). `node
|
|
887
939
|
bin/gentle-sidebar.js (enable|disable|status|toggle)` selects the
|
|
@@ -1054,7 +1106,10 @@ exactly one mechanism writes each piece of state.
|
|
|
1054
1106
|
user-facing value is `blocked` (§5.3). `gentle_title_review` likewise
|
|
1055
1107
|
keeps its machine-key-derived token name; only its user-facing value is
|
|
1056
1108
|
now `rdd` (aligned from `review` by the native-owner T1). `gentle_title_orchestrating` likewise keeps its machine-key-derived
|
|
1057
|
-
token name; only its user-facing value is `gentle`.
|
|
1109
|
+
token name; only its user-facing value is `gentle`. `gentle_title_working`
|
|
1110
|
+
likewise keeps its machine-key-derived token name; its user-facing value is
|
|
1111
|
+
a non-contemplated subagent's own sanitized name, never the word `working`.
|
|
1112
|
+
The retired `*_working_subs` token family (the old `working (n)`
|
|
1058
1113
|
count display) is swept, never written.
|
|
1059
1114
|
- Coexistence: `herdr-pi-tree` stays installed but disabled for gentle-owned
|
|
1060
1115
|
panes (O1). No uninstall, no token migration, no dual-run merge — ownership
|
package/README.md
CHANGED
|
@@ -6,21 +6,23 @@ Local Herdr plugin so the sidebar recognises Pi + Gentle Shell agents.
|
|
|
6
6
|
|
|
7
7
|
## What It Does
|
|
8
8
|
|
|
9
|
-
Reports per-pane agent state (`gentle`
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
`
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
the
|
|
22
|
-
|
|
23
|
-
|
|
9
|
+
Reports per-pane agent state (exactly one user-facing `gentle` — pink
|
|
10
|
+
`#f5c2e7`, machine key `orchestrating`: the principal session's own working
|
|
11
|
+
status and its generic status; a non-contemplated subagent renders its own
|
|
12
|
+
sanitized name on the amber `working` cell `#f9e2af` — never the word
|
|
13
|
+
`working`, never `gentle` — and a recognized gentle role keeps its
|
|
14
|
+
abbreviation — `explorer`, `worker`,
|
|
15
|
+
`verify`, `judge`, `rdd` — with the total running count in parentheses when
|
|
16
|
+
two or more subagents run, for example `explorer (3)`). The principal's own
|
|
17
|
+
activity marker (`gentle_principal_v1`, published while the principal session
|
|
18
|
+
itself works and cleared when it settles) decides the row — never the
|
|
19
|
+
delegate count, and never Herdr's aggregate native status (which reads
|
|
20
|
+
`working` whenever any delegate runs): the default is still the principal's
|
|
21
|
+
own state, so while the principal works its own turn it reads pink `gentle`,
|
|
22
|
+
with or without a fresh root marker, and no delegate word wins; while the
|
|
23
|
+
principal is idle the oldest running delegate role shows, or that subagent's
|
|
24
|
+
own name when no role word is recognized. `gentle` never renders on an idle
|
|
25
|
+
session. The single exception is a
|
|
24
26
|
blocking synchronous subagent call (`gentle_pending_v1`): a task-mode
|
|
25
27
|
`subagent_run`/`subagent_continue` holds the principal's turn open until the
|
|
26
28
|
child returns, so the principal is waiting on that child rather than working
|
|
@@ -214,8 +216,10 @@ sidebar-only, DESIGN §7; it rides the durable session-bound
|
|
|
214
216
|
`gentle_error_v1` token, republished on every beat while the run-error leg
|
|
215
217
|
stands and cleared the beat it releases, so a beat the sidebar missed is
|
|
216
218
|
repaired by the next one); the orchestrating
|
|
217
|
-
leg renders the user-facing
|
|
218
|
-
`orchestrating`, pink `#f5c2e7`)
|
|
219
|
+
leg renders the one user-facing `gentle` (machine key stays
|
|
220
|
+
`orchestrating`, pink `#f5c2e7`), while the `working` leg (amber `#f9e2af`)
|
|
221
|
+
carries a non-contemplated subagent's own sanitized name and never renders
|
|
222
|
+
the word `gentle` or `working`. Remaining state colors:
|
|
219
223
|
working/worker amber `#f9e2af`, explorer blue `#89b4fa`, verify teal
|
|
220
224
|
`#94e2d5`, ask orange `#fab387`, error red `#f38ba8`, done green `#a6e3a1`,
|
|
221
225
|
idle grey `#7c7f93`. Added stays green and deleted stays red; the mapping
|
|
@@ -250,19 +254,24 @@ unavailable counts (unavailable files stay in the file count with 0/0); `↑N` s
|
|
|
250
254
|
branch is behind its upstream (branch-ab status only, no diff). `gentle_project`,
|
|
251
255
|
`gentle_changes_summary`, and the segment
|
|
252
256
|
tokens (`gentle_changes_added`/`_deleted`/`_pull`) stay published for
|
|
253
|
-
compatibility but render no visible row. `gentle`
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
257
|
+
compatibility but render no visible row. Pink `gentle` (machine key
|
|
258
|
+
`orchestrating`, pink palette unchanged) is the
|
|
259
|
+
only user-facing `gentle`: it renders while the principal session actively
|
|
260
|
+
works — even with zero subagents, with or without a fresh root marker — and
|
|
261
|
+
as its generic status when a running delegate has no resolvable name, when
|
|
262
|
+
only unsalvageable role shapes remain, or when the root marker covers a
|
|
263
|
+
queued/running sub or a pending launch; it never renders on an idle session.
|
|
264
|
+
A non-contemplated subagent renders its own sanitized name on the amber
|
|
265
|
+
`working` cell instead, and a recognized gentle role keeps its abbreviation
|
|
266
|
+
(`explorer`, `worker`, `verify`, `judge`, `rdd`). The principal's own
|
|
258
267
|
activity decides the row, never the delegate count and never Herdr's
|
|
259
268
|
aggregate native status (the work token counts running delegates, and the
|
|
260
269
|
native status reads `working` for any running delegate or pending launch — so
|
|
261
270
|
neither can say the principal works): the dedicated
|
|
262
271
|
`gentle_principal_v1` marker is published while the principal session itself
|
|
263
272
|
works and cleared when it settles. That is the default: a **working
|
|
264
|
-
principal** reads `gentle` —
|
|
265
|
-
|
|
273
|
+
principal** reads the pink `gentle` — machine key `orchestrating`, fresh root
|
|
274
|
+
marker or not — and no delegate role word
|
|
266
275
|
wins; an **idle principal** shows the oldest running TaskStore role
|
|
267
276
|
(`explorer`, `worker`, `verify`, `judge`, `rdd`), however many delegates run.
|
|
268
277
|
The one exception is a blocking synchronous subagent call: while a task-mode
|
|
@@ -292,7 +301,7 @@ by a racy non-final status read (only the authoritative launch outcomes,
|
|
|
292
301
|
completions, and presence terminals move it), so principal activity with
|
|
293
302
|
live delegates keeps `gentle` while an idle principal keeps the role word; a
|
|
294
303
|
sanitized unknown slug exactly
|
|
295
|
-
equal to `working` or `subagent` degrades to `gentle` (neither bare word ever
|
|
304
|
+
equal to `working` or `subagent` degrades to the pink `gentle` (neither bare word ever
|
|
296
305
|
renders; `subagent` is the producer's launch-correlation placeholder, never
|
|
297
306
|
an agent name).
|
|
298
307
|
Background launches (`subagent_run` with `mode: background`) announce
|
|
@@ -323,10 +332,13 @@ herdr server reload-config
|
|
|
323
332
|
Live check: with the daemon running and the override applied, open a Pi pane
|
|
324
333
|
and confirm row 2 shows pink `gentle` (machine key
|
|
325
334
|
`orchestrating`) while
|
|
326
|
-
the principal session actively works — even with zero subagents
|
|
327
|
-
`gentle` while its delegates run (a
|
|
328
|
-
|
|
329
|
-
|
|
335
|
+
the principal session actively works — even with zero subagents, and with or
|
|
336
|
+
without a fresh root marker — and keeps `gentle` while its delegates run (a
|
|
337
|
+
role word such as `worker`, `explorer`,
|
|
338
|
+
`verify`, `judge`, or a non-contemplated subagent's own name in amber, shows
|
|
339
|
+
once the principal itself is idle — and also while a
|
|
340
|
+
task-mode subagent call blocks the principal's turn, until it returns), that
|
|
341
|
+
a row never reads `gentle` on an idle pane; row 1
|
|
330
342
|
shows the single heading cell (`● <project>` plus ` +N`/` -N`/` ↑N` inline, zero `·`) after edits / when behind upstream; then `ask` on an open
|
|
331
343
|
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
|
|
332
344
|
`HERDR_CONFIG_PATH` on a temp file for apply/uninstall checks.
|
|
@@ -353,7 +365,10 @@ coalesced refresh after every landed token beat, so a status change
|
|
|
353
365
|
it publishes is drawn at once, and the daemon caps each sleep at the nearest
|
|
354
366
|
live `done` expiry, so a settled row reaches `idle` when its short hold (5 s by
|
|
355
367
|
default, `GENTLE_HERDR_DONE_HOLD_MS`-overridable) lapses instead of one poll
|
|
356
|
-
later.
|
|
368
|
+
later. The producer's own beat is 15 s by default and
|
|
369
|
+
`GENTLE_HERDR_BEAT_MS`-overridable for tests and debugging (clamped to
|
|
370
|
+
[100, 300000]); the override changes the cadence only, never the 60 s token
|
|
371
|
+
TTL. Reports in one window collapse into one frame, and refresh-driven frames
|
|
357
372
|
are floored at 250 ms, so a burst can never spin the daemon. Polling stays the
|
|
358
373
|
fallback for every lifecycle signal and the only source for what no Herdr event
|
|
359
374
|
carries (the git-derived `+N/-N` and `↑N` row data and the presence prefix), so a
|
|
@@ -367,10 +382,12 @@ See [DESIGN.md](DESIGN.md) §4 (producer) and §5 (consumer), and
|
|
|
367
382
|
## Key Features You Should Know About
|
|
368
383
|
|
|
369
384
|
- Full v1 state matrix including the root-session `orchestrating` marker
|
|
370
|
-
(pink `●` + user-facing word `gentle`,
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
385
|
+
(pink `●` + the one user-facing word `gentle`, the principal session's
|
|
386
|
+
working and generic status: it shows while the principal actively works —
|
|
387
|
+
even with zero subagents and with or without a fresh root marker — and
|
|
388
|
+
covers queued/running subagents and pending launches; yielding only to
|
|
389
|
+
`ask`/`rdd`/`blocked` and terminal `done` (done needs settled-plus-empty);
|
|
390
|
+
never on an idle session) and the authoritative TaskStore role signal
|
|
374
391
|
(`explorer` / `worker` / `verify` / `judge` / `rdd` from `TaskRecord.agent`,
|
|
375
392
|
oldest running first by immutable first-seen, shown while the principal
|
|
376
393
|
itself is idle — a working principal's own turn keeps `gentle`, asserted by
|
|
@@ -379,10 +396,12 @@ See [DESIGN.md](DESIGN.md) §4 (producer) and §5 (consumer), and
|
|
|
379
396
|
synchronous `subagent_run`/`subagent_continue` call holds the principal's
|
|
380
397
|
turn open, so the in-flight child's role shows instead (the
|
|
381
398
|
`gentle_pending_v1` role marker) until that call resolves, while a
|
|
382
|
-
background delegate never takes that path;
|
|
383
|
-
key `working`) for the principal's own working state; an unknown delegation
|
|
399
|
+
background delegate never takes that path; an unknown delegation
|
|
384
400
|
keeps its original sanitized name, 32-char bound — never a generic
|
|
385
|
-
collapse
|
|
401
|
+
collapse (the reserved words `gentle`, `working`, and `subagent` are no name
|
|
402
|
+
and degrade to the pink generic) — and renders on the amber `working` cell,
|
|
403
|
+
which never carries the
|
|
404
|
+
word `gentle`), with a running-count suffix on role labels when two or more
|
|
386
405
|
delegates run, `ask` on blocked user input,
|
|
387
406
|
`rdd` during native review execution (machine key stays `review`; execution
|
|
388
407
|
is silent — desktop attention fires only for a waiting `ask` intent, as
|
|
@@ -428,7 +447,7 @@ See [DESIGN.md](DESIGN.md) §4 (producer) and §5 (consumer), and
|
|
|
428
447
|
nothing and logs one line per reason. The gs pane's own live state stays
|
|
429
448
|
unobservable until the isolated install forwards `HERDR_ENV` to its agent (a
|
|
430
449
|
gentle-ai concern, out of scope here).
|
|
431
|
-
- 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
|
|
450
|
+
- 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 the pink generic `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). A settle is reconciled from the host's own live truth (`isIdle()`) whenever nothing is active and no work evidence remains, so a run whose settle never reached the producer still reaches `idle` instead of freezing the pane on native `working`; a quiet producer the host never answers stops beating after a bounded budget instead of republishing a count-0 work token forever — but only when it observed no turn, while a turn it saw start keeps beating so the budget never trades a truthful `working` for a false `idle` on a truth-less host; the beat is re-armed by the edges that schedule a publish (ask, review, launch, session changes, jobs), while an ordinary tool edge reaches the row through the host's own truth rather than by re-arming it; the settle-time pending latch is bounded by that settle's finish hold. A reconciled settle is not an observed turn, so it mints no `done` and sends no `task_complete`. 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 that delegate's own role word or name instead of the principal's `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.
|
|
432
451
|
- Sidebar switch (`enable` / `disable` / `status` / `toggle`):
|
|
433
452
|
`node bin/gentle-sidebar.js <verb>` picks between this plugin's sidebar rows
|
|
434
453
|
and the native Herdr sidebar. `status` is read-only; `enable` converges the
|
|
@@ -731,6 +731,23 @@ const paneId = process.env.HERDR_PANE_ID;
|
|
|
731
731
|
|
|
732
732
|
const TTL_MS = 60000;
|
|
733
733
|
const BEAT_MS = 15000;
|
|
734
|
+
const BEAT_MIN_MS = 100;
|
|
735
|
+
const BEAT_MAX_MS = 300000;
|
|
736
|
+
const BEAT_ENV = "GENTLE_HERDR_BEAT_MS";
|
|
737
|
+
// Bounded budget of quiet beats a producer may publish while it has no work
|
|
738
|
+
// evidence and no host truth to settle on (`quietWithoutTruth` in the
|
|
739
|
+
// factory): three beats, one BEAT_MS each. See the comment there.
|
|
740
|
+
const QUIET_BEAT_LIMIT = 3;
|
|
741
|
+
// Consecutive beats a producer must see the lost-settle contradiction (it
|
|
742
|
+
// believes a turn is running, the host answers `isIdle() === true`, and
|
|
743
|
+
// nothing else keeps the session busy) before it applies the settle the host
|
|
744
|
+
// already reports (`reconcileSettled` in the factory). One beat is not enough:
|
|
745
|
+
// the host flips to idle at the very end of a run, so a genuine `agent_settled`
|
|
746
|
+
// can reach the producer one host tick later, and a single sample would repaint
|
|
747
|
+
// a still-settling turn as idle. Two consecutive samples — 30 s of
|
|
748
|
+
// host-confirmed idle at the 15 s beat — cannot be that race, and a lost edge
|
|
749
|
+
// still recovers within one beat period after the window closes.
|
|
750
|
+
const LOST_SETTLE_BEATS = 2;
|
|
734
751
|
// Synthesized finish signal (DESIGN §4.3, S2/D2). The host never reports
|
|
735
752
|
// `done`, so the producer mints the finish itself: one session-bound
|
|
736
753
|
// `<hash>:<expiry>` token per finish at the settled-and-empty edge, carrying
|
|
@@ -931,6 +948,20 @@ export function doneHoldMs(raw = process.env[DONE_HOLD_ENV]) {
|
|
|
931
948
|
return Math.min(DONE_HOLD_MAX_MS, Math.max(DONE_HOLD_MIN_MS, Math.round(parsed)));
|
|
932
949
|
}
|
|
933
950
|
|
|
951
|
+
// Beat cadence override, the same discipline as doneHoldMs: an absent or
|
|
952
|
+
// unparseable value keeps the 15 s default and anything outside the band is
|
|
953
|
+
// clamped, so a debugging session (or a test that cannot wait 15 s per beat)
|
|
954
|
+
// can shorten the beat without touching the 60 s token TTL or the transport's
|
|
955
|
+
// own 500/1500 ms bounds. The 100 ms floor keeps every beat far slower than a
|
|
956
|
+
// single send.
|
|
957
|
+
function beatMs(raw = process.env[BEAT_ENV]) {
|
|
958
|
+
const text = typeof raw === "string" ? raw.trim() : "";
|
|
959
|
+
if (text.length === 0) return BEAT_MS;
|
|
960
|
+
const parsed = Number(text);
|
|
961
|
+
if (!Number.isFinite(parsed)) return BEAT_MS;
|
|
962
|
+
return Math.min(BEAT_MAX_MS, Math.max(BEAT_MIN_MS, Math.round(parsed)));
|
|
963
|
+
}
|
|
964
|
+
|
|
934
965
|
// Cap a label at MAX_LABEL_CHARS UTF-16 units — the same unit the consumer's
|
|
935
966
|
// `parseNames` checks, so a label the producer writes is never one the
|
|
936
967
|
// consumer drops — while backing off one unit when the cut would split a
|
|
@@ -1140,6 +1171,15 @@ function cliFallback(patch) {
|
|
|
1140
1171
|
// unverified) and no new imports (self-contained single file). Do NOT
|
|
1141
1172
|
// reinstall the native publisher from Herdr: two publishers for the same
|
|
1142
1173
|
// pane collide (dual-publish).
|
|
1174
|
+
//
|
|
1175
|
+
// T2 (the pane must never freeze at `working`): the settle this owner gates on
|
|
1176
|
+
// is reconciled from the host's own live truth on every beat instead of being
|
|
1177
|
+
// inferred — including when a turn was seen to start but its settle edge was
|
|
1178
|
+
// lost, which needs a bounded window of contradictory beats rather than a
|
|
1179
|
+
// single sample; a quiet producer the host never confirms stops beating after a
|
|
1180
|
+
// bounded budget instead of republishing a count-0 work token forever; and the
|
|
1181
|
+
// settle-time pending latch stops counting once the finish hold that raised it
|
|
1182
|
+
// expires.
|
|
1143
1183
|
// ---------------------------------------------------------------------------
|
|
1144
1184
|
|
|
1145
1185
|
export const NATIVE_STATES = ["working", "blocked", "idle"];
|
|
@@ -1160,6 +1200,11 @@ const NATIVE_MAX_ATTEMPTS = 2;
|
|
|
1160
1200
|
// done/finished (only working|blocked|idle) and never a notification
|
|
1161
1201
|
// method — the host owns finished text plus toast/sound, and desktop ask
|
|
1162
1202
|
// attention (including toast dedup) is host-owned (DESIGN §7).
|
|
1203
|
+
//
|
|
1204
|
+
// The `settled` input is never inferred here: the beat reconciles it from the
|
|
1205
|
+
// host's own live truth (`ctx.isIdle()`), so a missed `agent_settled` cannot
|
|
1206
|
+
// leave this producer unable to reach `idle` — not when no turn was observed,
|
|
1207
|
+
// and not when a turn this producer saw start never delivered its settle edge.
|
|
1163
1208
|
export function computeNativeState({
|
|
1164
1209
|
agentActive,
|
|
1165
1210
|
settled,
|
|
@@ -2635,6 +2680,10 @@ export default function (pi) {
|
|
|
2635
2680
|
// opened the current ask episode.
|
|
2636
2681
|
let moshiContext;
|
|
2637
2682
|
let moshiCtxRef;
|
|
2683
|
+
// Last context the host handed us, retained so a beat can ask the host's own
|
|
2684
|
+
// live truth (`isIdle()`) instead of inferring a settle. Kept apart from
|
|
2685
|
+
// `moshiCtxRef`, whose capture leg owns that reference.
|
|
2686
|
+
let settleCtx;
|
|
2638
2687
|
let lastAskToolName;
|
|
2639
2688
|
|
|
2640
2689
|
// Live background jobs (Gentle Shell `bash_background` / `monitor`) from the
|
|
@@ -2694,6 +2743,7 @@ export default function (pi) {
|
|
|
2694
2743
|
// freshness bound measures from.
|
|
2695
2744
|
function onJobsSnapshot(value) {
|
|
2696
2745
|
if (!isRecord(value) || !isRecord(value.snapshot) || !Array.isArray(value.snapshot.jobs)) return;
|
|
2746
|
+
noteActivity();
|
|
2697
2747
|
const jobs = value.snapshot.jobs.filter(
|
|
2698
2748
|
(entry) => isRecord(entry) && typeof entry.id === "string" && entry.id.length > 0,
|
|
2699
2749
|
);
|
|
@@ -2830,6 +2880,13 @@ export default function (pi) {
|
|
|
2830
2880
|
let presenceReconciler = createPresenceReconciler();
|
|
2831
2881
|
let transportFails = 0;
|
|
2832
2882
|
let beatTimer;
|
|
2883
|
+
// Consecutive quiet beats published without host truth (see
|
|
2884
|
+
// `quietWithoutTruth`); bounded by QUIET_BEAT_LIMIT and reset by work.
|
|
2885
|
+
let quietBeats = 0;
|
|
2886
|
+
// Consecutive beats that contradict a turn this producer saw start (see
|
|
2887
|
+
// `lostSettleContradiction`); bounded by LOST_SETTLE_BEATS and reset by any
|
|
2888
|
+
// activity edge.
|
|
2889
|
+
let lostSettleBeats = 0;
|
|
2833
2890
|
let publishQueued = false;
|
|
2834
2891
|
let publishInFlight = false;
|
|
2835
2892
|
// Native owner queue (always on): monotonic seq per logical report,
|
|
@@ -2852,7 +2909,17 @@ export default function (pi) {
|
|
|
2852
2909
|
// beat arriving mid-send is describing.
|
|
2853
2910
|
let nativeSending = null;
|
|
2854
2911
|
let nativeLastOk = undefined;
|
|
2912
|
+
// T2 native-only terminal guard: agent_settled clears the metadata
|
|
2913
|
+
// pending-launch hint below, but a settle that observes in-flight launches
|
|
2914
|
+
// retains pending evidence here so native idle gating stays working until
|
|
2915
|
+
// those launches resolve. Metadata/tasks untouched; the guard clears when a
|
|
2916
|
+
// launch resolves, on agent_start, with the session, and — when a launch
|
|
2917
|
+
// never reports back — at `nativeSettledPendingUntil`, the finish-hold
|
|
2918
|
+
// deadline of the settle that raised it. Past that hold the evidence stops
|
|
2919
|
+
// counting, so a lost launch result can never pin the native report at
|
|
2920
|
+
// `working` for good (seq itself never resets).
|
|
2855
2921
|
let nativeSettledPending = false;
|
|
2922
|
+
let nativeSettledPendingUntil = 0;
|
|
2856
2923
|
// Finish-hold episode (S2): minted once at the settled-and-empty edge so the
|
|
2857
2924
|
// row reads `done`, then republished unchanged (never refreshed) until the
|
|
2858
2925
|
// hold expires. `donePending` carries the unannounced finish to the beat
|
|
@@ -2862,6 +2929,12 @@ export default function (pi) {
|
|
|
2862
2929
|
let doneExpiry;
|
|
2863
2930
|
let donePending = false;
|
|
2864
2931
|
let sawActivity = false;
|
|
2932
|
+
// Whether the settle this row sits in came from an observed turn
|
|
2933
|
+
// (`agent_settled`) rather than from the host-truth reconcile: only an
|
|
2934
|
+
// observed turn can mint a finish, so non-turn activity (an ask, a review, a
|
|
2935
|
+
// job) on a producer that never saw a turn can never announce `done` or the
|
|
2936
|
+
// phone's `task_complete`.
|
|
2937
|
+
let turnSettled = false;
|
|
2865
2938
|
// LIVE-1 startup latency: the session binding is still INITIATED on
|
|
2866
2939
|
// session_start (so Herdr can attribute the pane from the first frame), but
|
|
2867
2940
|
// the host no longer waits for it. The host awaits every session_start
|
|
@@ -2871,12 +2944,117 @@ export default function (pi) {
|
|
|
2871
2944
|
// unchanged, only the host's startup return is freed. Reset with the session
|
|
2872
2945
|
// so a stale binding can never gate the next one.
|
|
2873
2946
|
let sessionReportPending = null;
|
|
2874
|
-
|
|
2875
|
-
//
|
|
2876
|
-
//
|
|
2877
|
-
//
|
|
2878
|
-
|
|
2879
|
-
|
|
2947
|
+
|
|
2948
|
+
// Retain the host context the settle reconcile reads (`isIdle()`), next to
|
|
2949
|
+
// the Moshi capture reference it already replaced. A lifecycle event that
|
|
2950
|
+
// arrives without a context must not erase the last truth we hold.
|
|
2951
|
+
function retainContext(ctx) {
|
|
2952
|
+
moshiCtxRef = ctx;
|
|
2953
|
+
if (ctx) settleCtx = ctx;
|
|
2954
|
+
}
|
|
2955
|
+
|
|
2956
|
+
function clearSettledPending() {
|
|
2957
|
+
nativeSettledPending = false;
|
|
2958
|
+
nativeSettledPendingUntil = 0;
|
|
2959
|
+
}
|
|
2960
|
+
|
|
2961
|
+
// Past the finish hold of the settle that raised it, the retained pending
|
|
2962
|
+
// evidence stops counting: the hold is the span it exists to cover.
|
|
2963
|
+
function settledPendingHeld() {
|
|
2964
|
+
return nativeSettledPending && Date.now() < nativeSettledPendingUntil;
|
|
2965
|
+
}
|
|
2966
|
+
|
|
2967
|
+
// The settle state `agent_settled` applies, shared with the reconcile below
|
|
2968
|
+
// so both paths agree on every field except the finish episode.
|
|
2969
|
+
function applySettled(fromTurn) {
|
|
2970
|
+
agentActive = false;
|
|
2971
|
+
settled = true;
|
|
2972
|
+
turnSettled = fromTurn === true;
|
|
2973
|
+
lostSettleBeats = 0;
|
|
2974
|
+
clearSettledPending();
|
|
2975
|
+
}
|
|
2976
|
+
|
|
2977
|
+
// Every activity edge restarts the lost-settle window: a tool call, a
|
|
2978
|
+
// delegate, a job, an ask/review/error leg (the contradiction predicate reads
|
|
2979
|
+
// those legs directly) or a new `agent_start`. Only consecutive beats that
|
|
2980
|
+
// still contradict the host may settle.
|
|
2981
|
+
function noteActivity() {
|
|
2982
|
+
lostSettleBeats = 0;
|
|
2983
|
+
}
|
|
2984
|
+
|
|
2985
|
+
// Nothing observable keeps this session busy: no authoritative
|
|
2986
|
+
// running|queued delegate, no launch in flight, no live background job.
|
|
2987
|
+
// `agentActive` is not part of this evidence: it is this producer's own
|
|
2988
|
+
// inference from turn events, so the reconcile guards it separately and
|
|
2989
|
+
// never overrides a turn it saw start.
|
|
2990
|
+
function noWorkEvidence() {
|
|
2991
|
+
return (
|
|
2992
|
+
activeSubs().length === 0 &&
|
|
2993
|
+
pendingCalls.size === 0 &&
|
|
2994
|
+
freshRunningJobCount() === 0
|
|
2995
|
+
);
|
|
2996
|
+
}
|
|
2997
|
+
|
|
2998
|
+
// Live host truth for the settle decision: the retained context's `isIdle()`.
|
|
2999
|
+
// `undefined` means the host offers no truth (no context yet, or one without
|
|
3000
|
+
// the method); `false` means the host still considers the agent busy, which
|
|
3001
|
+
// is never this producer's to override.
|
|
3002
|
+
function hostIdleTruth() {
|
|
3003
|
+
const probe = settleCtx?.isIdle;
|
|
3004
|
+
if (typeof probe !== "function") return undefined;
|
|
3005
|
+
try {
|
|
3006
|
+
return probe.call(settleCtx) === true;
|
|
3007
|
+
} catch {
|
|
3008
|
+
return undefined;
|
|
3009
|
+
}
|
|
3010
|
+
}
|
|
3011
|
+
|
|
3012
|
+
// The lost-settle contradiction: this producer still believes its turn runs,
|
|
3013
|
+
// the host answers that nothing is processing, and no work evidence or
|
|
3014
|
+
// owning leg keeps the session busy. Both sides are live truth re-read on
|
|
3015
|
+
// every beat, so the contradiction is never remembered from a stale sample.
|
|
3016
|
+
function lostSettleContradiction() {
|
|
3017
|
+
return (
|
|
3018
|
+
agentActive &&
|
|
3019
|
+
hostIdleTruth() === true &&
|
|
3020
|
+
noWorkEvidence() &&
|
|
3021
|
+
!askActiveNow() &&
|
|
3022
|
+
!reviewActive &&
|
|
3023
|
+
errorCode === undefined
|
|
3024
|
+
);
|
|
3025
|
+
}
|
|
3026
|
+
|
|
3027
|
+
// Recover a settle this producer missed. `settled` flips only in
|
|
3028
|
+
// `agent_settled`, which early-returns unless the host already reports idle,
|
|
3029
|
+
// so a session first observed while idle — or an aborted or failed run whose
|
|
3030
|
+
// `agent_settled` never arrived — leaves `settled` false: `computeNativeState`
|
|
3031
|
+
// returns undefined and the pane keeps the last native `working`. The host
|
|
3032
|
+
// answers the same question `agent_settled` asks, so read its live truth here
|
|
3033
|
+
// instead of inferring a terminal from a timeout or from a count.
|
|
3034
|
+
function reconcileSettled() {
|
|
3035
|
+
if (!rootSession || settled) return;
|
|
3036
|
+
// No turn edge was ever observed: nothing local contradicts the host, so
|
|
3037
|
+
// its answer settles the producer on the same beat.
|
|
3038
|
+
if (!agentActive) {
|
|
3039
|
+
if (!noWorkEvidence()) return;
|
|
3040
|
+
if (hostIdleTruth() !== true) return;
|
|
3041
|
+
applySettled(false);
|
|
3042
|
+
return;
|
|
3043
|
+
}
|
|
3044
|
+
// A turn the producer itself saw start is local evidence of a running
|
|
3045
|
+
// agent, and `isIdle()` turns true at the end of the run — so a genuine
|
|
3046
|
+
// settle edge can still be in flight. Only a bounded window of consecutive
|
|
3047
|
+
// contradictory beats proves the edge was lost.
|
|
3048
|
+
if (!lostSettleContradiction()) {
|
|
3049
|
+
lostSettleBeats = 0;
|
|
3050
|
+
return;
|
|
3051
|
+
}
|
|
3052
|
+
lostSettleBeats += 1;
|
|
3053
|
+
if (lostSettleBeats < LOST_SETTLE_BEATS) return;
|
|
3054
|
+
// `fromTurn` false: a recovered settle is never a turn, so it can mint no
|
|
3055
|
+
// finish episode (no `gentle_done_v1`, no finish notification).
|
|
3056
|
+
applySettled(false);
|
|
3057
|
+
}
|
|
2880
3058
|
|
|
2881
3059
|
function refreshSessionRef(ctx) {
|
|
2882
3060
|
try {
|
|
@@ -3150,13 +3328,15 @@ export default function (pi) {
|
|
|
3150
3328
|
) {
|
|
3151
3329
|
return "rdd";
|
|
3152
3330
|
}
|
|
3153
|
-
// The bare visible words `working` and `
|
|
3154
|
-
// unknown slug exactly equal to
|
|
3155
|
-
// `gentle`) in metadata roles and the native message alike.
|
|
3156
|
-
// the launch-correlation placeholder, never an agent name, so
|
|
3157
|
-
// never reach the wire as a role word.
|
|
3331
|
+
// The bare visible words `working`, `subagent`, and `gentle` are banned: a
|
|
3332
|
+
// sanitized unknown slug exactly equal to one of them degrades to no role
|
|
3333
|
+
// (generic `gentle`) in metadata roles and the native message alike.
|
|
3334
|
+
// `subagent` is the launch-correlation placeholder, never an agent name, so
|
|
3335
|
+
// it must never reach the wire as a role word. `gentle` is the pink
|
|
3336
|
+
// generic's own word (S1), so an agent literally named `gentle` must not
|
|
3337
|
+
// become a second one on the amber cell.
|
|
3158
3338
|
const slug = sanitizeAgentSlug(agent);
|
|
3159
|
-
return slug === "working" || slug === "subagent" ? undefined : slug;
|
|
3339
|
+
return slug === "working" || slug === "subagent" || slug === "gentle" ? undefined : slug;
|
|
3160
3340
|
}
|
|
3161
3341
|
|
|
3162
3342
|
// Bounded CSV of role words, oldest-first (subs already arrive
|
|
@@ -3300,7 +3480,7 @@ export default function (pi) {
|
|
|
3300
3480
|
sawActivity = true;
|
|
3301
3481
|
doneExpiry = undefined;
|
|
3302
3482
|
donePending = false;
|
|
3303
|
-
} else if (settled) {
|
|
3483
|
+
} else if (settled && turnSettled) {
|
|
3304
3484
|
if (doneExpiry === undefined && sawActivity) {
|
|
3305
3485
|
doneExpiry = Date.now() + doneHoldMs();
|
|
3306
3486
|
donePending = true;
|
|
@@ -3371,16 +3551,73 @@ export default function (pi) {
|
|
|
3371
3551
|
if (beatTimer || !rootSession) return;
|
|
3372
3552
|
if (!interesting() && settled) return;
|
|
3373
3553
|
beatTimer = setInterval(() => {
|
|
3554
|
+
// A tick with nothing interesting to publish has nothing to do. Stopping
|
|
3555
|
+
// here (instead of only after a landed publish) is what keeps a slow
|
|
3556
|
+
// send from re-arming the interval through `publishQueued` and spinning
|
|
3557
|
+
// a beat nobody needs.
|
|
3558
|
+
if (!interesting()) {
|
|
3559
|
+
stopBeat();
|
|
3560
|
+
return;
|
|
3561
|
+
}
|
|
3562
|
+
// T2 quiet bound: a beat with no work evidence, no host truth, and no
|
|
3563
|
+
// leg that still owns the row has nothing confirmed to publish — every
|
|
3564
|
+
// such beat republishes a fresh count-0 `gentle_work_v1`, and that
|
|
3565
|
+
// eternal fresh work token is what keeps the row from ever reaching
|
|
3566
|
+
// idle. The beat spends a bounded budget of quiet beats (one BEAT_MS
|
|
3567
|
+
// each) and then stops. Stopping is the honest outcome: a native state
|
|
3568
|
+
// the host never confirmed must not be published in its place. The
|
|
3569
|
+
// bound never applies to a turn this producer saw start (see
|
|
3570
|
+
// `quietWithoutTruth`), so it cannot leave live work unpainted; the
|
|
3571
|
+
// edges that schedule a publish (ask, review, launch, session changes,
|
|
3572
|
+
// jobs) re-arm the beat, while an ordinary tool edge reaches the row
|
|
3573
|
+
// through the host's own truth rather than by re-arming it.
|
|
3574
|
+
if (quietWithoutTruth()) {
|
|
3575
|
+
quietBeats += 1;
|
|
3576
|
+
if (quietBeats >= QUIET_BEAT_LIMIT) {
|
|
3577
|
+
stopBeat();
|
|
3578
|
+
return;
|
|
3579
|
+
}
|
|
3580
|
+
} else {
|
|
3581
|
+
quietBeats = 0;
|
|
3582
|
+
}
|
|
3374
3583
|
void publishNow();
|
|
3375
|
-
},
|
|
3584
|
+
}, beatMs());
|
|
3376
3585
|
if (beatTimer.unref) beatTimer.unref();
|
|
3377
3586
|
}
|
|
3378
3587
|
|
|
3588
|
+
function stopBeat() {
|
|
3589
|
+
if (!beatTimer) return;
|
|
3590
|
+
clearInterval(beatTimer);
|
|
3591
|
+
beatTimer = undefined;
|
|
3592
|
+
}
|
|
3593
|
+
|
|
3379
3594
|
function maybeStopBeat() {
|
|
3380
|
-
if (beatTimer && !interesting())
|
|
3381
|
-
|
|
3382
|
-
|
|
3383
|
-
|
|
3595
|
+
if (beatTimer && !interesting()) stopBeat();
|
|
3596
|
+
}
|
|
3597
|
+
|
|
3598
|
+
// T2 quiet bound predicate (see the budget applied inside `ensureBeat`): the
|
|
3599
|
+
// host offers no truth at all, nothing is active by evidence, and no leg
|
|
3600
|
+
// still owns the row. A host that answers `false` is not quiet — it says the
|
|
3601
|
+
// agent is still running — and a host that answers `true` settles through
|
|
3602
|
+
// `reconcileSettled` instead. No native state is ever inferred here.
|
|
3603
|
+
//
|
|
3604
|
+
// `agentActive` is excluded on purpose: a turn this producer saw start is
|
|
3605
|
+
// live work, and the host offers no way to confirm its settle. Bounding that
|
|
3606
|
+
// beat would stop painting a running turn, which is exactly the pin the bound
|
|
3607
|
+
// exists to avoid (S2) — the bound must never trade a truthful "still
|
|
3608
|
+
// working" for a false `idle`. It therefore covers only a producer with no
|
|
3609
|
+
// observed turn behind it and no host truth to settle on.
|
|
3610
|
+
function quietWithoutTruth() {
|
|
3611
|
+
return (
|
|
3612
|
+
!agentActive &&
|
|
3613
|
+
!settled &&
|
|
3614
|
+
hostIdleTruth() === undefined &&
|
|
3615
|
+
noWorkEvidence() &&
|
|
3616
|
+
!askActiveNow() &&
|
|
3617
|
+
!reviewActive &&
|
|
3618
|
+
errorCode === undefined &&
|
|
3619
|
+
doneExpiry === undefined
|
|
3620
|
+
);
|
|
3384
3621
|
}
|
|
3385
3622
|
|
|
3386
3623
|
// N1 parity report: state + message. Working carries the SPECIFIC
|
|
@@ -3407,7 +3644,7 @@ export default function (pi) {
|
|
|
3407
3644
|
agentActive,
|
|
3408
3645
|
settled,
|
|
3409
3646
|
activeCount: activeSubs().length,
|
|
3410
|
-
pendingCount: pendingCalls.size + (
|
|
3647
|
+
pendingCount: pendingCalls.size + (settledPendingHeld() ? 1 : 0),
|
|
3411
3648
|
askActive: askActiveNow(),
|
|
3412
3649
|
reviewActive,
|
|
3413
3650
|
});
|
|
@@ -3622,6 +3859,9 @@ export default function (pi) {
|
|
|
3622
3859
|
// flight publishes nothing: `rootSession` is re-read after the wait.
|
|
3623
3860
|
await awaitSessionBinding();
|
|
3624
3861
|
if (!rootSession || !sidebarPublishingEnabled()) return;
|
|
3862
|
+
// Host truth first: a settle this producer missed must be visible to both
|
|
3863
|
+
// the native report and the tokens built below.
|
|
3864
|
+
reconcileSettled();
|
|
3625
3865
|
reconcilePresence();
|
|
3626
3866
|
queueNative();
|
|
3627
3867
|
const tokens = buildTokens();
|
|
@@ -3773,10 +4013,11 @@ export default function (pi) {
|
|
|
3773
4013
|
nativePending = null;
|
|
3774
4014
|
nativeSending = null;
|
|
3775
4015
|
nativeLastOk = undefined;
|
|
3776
|
-
|
|
4016
|
+
clearSettledPending();
|
|
3777
4017
|
doneExpiry = undefined;
|
|
3778
4018
|
donePending = false;
|
|
3779
4019
|
sawActivity = false;
|
|
4020
|
+
turnSettled = false;
|
|
3780
4021
|
jobsSnapshot = undefined;
|
|
3781
4022
|
clearJobsExpiry();
|
|
3782
4023
|
errorCode = undefined;
|
|
@@ -3786,9 +4027,13 @@ export default function (pi) {
|
|
|
3786
4027
|
liveQueued = false;
|
|
3787
4028
|
sessionReportPending = null;
|
|
3788
4029
|
sessionCwd = undefined;
|
|
4030
|
+
settleCtx = undefined;
|
|
4031
|
+
quietBeats = 0;
|
|
4032
|
+
lostSettleBeats = 0;
|
|
3789
4033
|
changes = { files: 0, added: 0, deleted: 0 };
|
|
3790
4034
|
agentActive = false;
|
|
3791
4035
|
settled = false;
|
|
4036
|
+
turnSettled = false;
|
|
3792
4037
|
}
|
|
3793
4038
|
|
|
3794
4039
|
function clearEmittedLabel() {
|
|
@@ -3843,6 +4088,7 @@ export default function (pi) {
|
|
|
3843
4088
|
|
|
3844
4089
|
pi.on("tool_execution_start", (event) => {
|
|
3845
4090
|
if (!rootSession || !isRecord(event) || typeof event.toolCallId !== "string") return;
|
|
4091
|
+
noteActivity();
|
|
3846
4092
|
runningTools.add(event.toolCallId);
|
|
3847
4093
|
// Structured ask tools open ONLY on genuine execution (never on
|
|
3848
4094
|
// `tool_call` proposal), keyed by call id so the matching end or
|
|
@@ -3968,6 +4214,7 @@ export default function (pi) {
|
|
|
3968
4214
|
if (!rootSession || !isRecord(event) || typeof event.toolName !== "string") return;
|
|
3969
4215
|
// A tool starting proves a run is alive: an error left over from a run that
|
|
3970
4216
|
// already died is released here rather than sticking until the next turn.
|
|
4217
|
+
noteActivity();
|
|
3971
4218
|
clearRunError();
|
|
3972
4219
|
// Structured ask proposals never open ask (execution does); subagent
|
|
3973
4220
|
// launch correlation below is unchanged.
|
|
@@ -3997,6 +4244,7 @@ export default function (pi) {
|
|
|
3997
4244
|
|
|
3998
4245
|
pi.on("tool_result", (event) => {
|
|
3999
4246
|
if (!rootSession || !isRecord(event) || typeof event.toolName !== "string") return;
|
|
4247
|
+
noteActivity();
|
|
4000
4248
|
clearRunError();
|
|
4001
4249
|
if (typeof event.toolCallId === "string" && askToolCalls.delete(event.toolCallId)) {
|
|
4002
4250
|
updateBlocker();
|
|
@@ -4013,7 +4261,7 @@ export default function (pi) {
|
|
|
4013
4261
|
// outcome is now covered by the task record (working via activeSubs),
|
|
4014
4262
|
// the error latch (blocked), or genuine emptiness (idle on next beat).
|
|
4015
4263
|
if (event.toolName === "subagent_run" || event.toolName === "subagent_continue") {
|
|
4016
|
-
|
|
4264
|
+
clearSettledPending();
|
|
4017
4265
|
}
|
|
4018
4266
|
if (typeof event.toolCallId === "string" ? reviewCalls.delete(event.toolCallId) : false) {
|
|
4019
4267
|
// The ended id was a known acknowledged execution; remaining tracked
|
|
@@ -4123,6 +4371,7 @@ export default function (pi) {
|
|
|
4123
4371
|
// never passes through `tool_result` details.
|
|
4124
4372
|
pi.on("message_end", (event) => {
|
|
4125
4373
|
if (!rootSession || !isRecord(event)) return;
|
|
4374
|
+
noteActivity();
|
|
4126
4375
|
const message = event.message;
|
|
4127
4376
|
if (!isRecord(message)) return;
|
|
4128
4377
|
if (message.role === "assistant") {
|
|
@@ -4185,7 +4434,7 @@ export default function (pi) {
|
|
|
4185
4434
|
rootSession = true;
|
|
4186
4435
|
sessionManager = ctx.sessionManager;
|
|
4187
4436
|
refreshSessionRef(ctx);
|
|
4188
|
-
|
|
4437
|
+
retainContext(ctx);
|
|
4189
4438
|
if (moshiEnabled()) moshiEnsureContext();
|
|
4190
4439
|
// LIVE-1: bind the session before any state beat so Herdr attributes the
|
|
4191
4440
|
// pane from the first frame (mirrors the managed publisher). The binding is
|
|
@@ -4203,14 +4452,17 @@ export default function (pi) {
|
|
|
4203
4452
|
pi.on("agent_start", (_event, ctx) => {
|
|
4204
4453
|
if (!rootSession) return;
|
|
4205
4454
|
refreshSessionRef(ctx);
|
|
4206
|
-
|
|
4455
|
+
retainContext(ctx);
|
|
4207
4456
|
// LIVE-1: re-bind the session like the managed publisher did, so a
|
|
4208
4457
|
// restart or re-announcement never leaves the pane binding-less while
|
|
4209
4458
|
// metadata beats flow.
|
|
4210
4459
|
void reportSession();
|
|
4211
4460
|
agentActive = true;
|
|
4212
4461
|
settled = false;
|
|
4213
|
-
|
|
4462
|
+
turnSettled = false;
|
|
4463
|
+
clearSettledPending();
|
|
4464
|
+
quietBeats = 0;
|
|
4465
|
+
noteActivity();
|
|
4214
4466
|
clearRunError();
|
|
4215
4467
|
refreshChanges();
|
|
4216
4468
|
schedulePublish();
|
|
@@ -4218,13 +4470,17 @@ export default function (pi) {
|
|
|
4218
4470
|
|
|
4219
4471
|
pi.on("agent_settled", (_event, ctx) => {
|
|
4220
4472
|
if (!rootSession || ctx?.isIdle?.() !== true) return;
|
|
4221
|
-
|
|
4222
|
-
agentActive = false;
|
|
4223
|
-
settled = true;
|
|
4473
|
+
retainContext(ctx);
|
|
4224
4474
|
// Retain settle-time pending evidence for native gating before the
|
|
4225
|
-
// metadata hint clears (see nativeSettledPending above)
|
|
4226
|
-
|
|
4475
|
+
// metadata hint clears (see nativeSettledPending above), bounded by the
|
|
4476
|
+
// finish hold this settle opens.
|
|
4477
|
+
const pendingAtSettle = pendingCalls.size > 0;
|
|
4227
4478
|
pendingCalls.clear();
|
|
4479
|
+
applySettled(true);
|
|
4480
|
+
if (pendingAtSettle) {
|
|
4481
|
+
nativeSettledPending = true;
|
|
4482
|
+
nativeSettledPendingUntil = Date.now() + doneHoldMs();
|
|
4483
|
+
}
|
|
4228
4484
|
// S62 turn-end: the working tree may have changed without transcript
|
|
4229
4485
|
// evidence (external/untracked edits), so re-scan before publishing.
|
|
4230
4486
|
refreshChanges();
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "herdr-gentle-shell",
|
|
3
|
-
"version": "1.5.
|
|
3
|
+
"version": "1.5.2",
|
|
4
4
|
"description": "Pi package for Herdr sidebar states: the Pi extension sidecar that publishes session facts as Herdr pane-metadata tokens, the optional Moshi notification channel, and the Pi-side helpers the Herdr Gentle Shell plugin drives.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"pi-package",
|