herdr-gentle-shell 1.5.2 → 1.6.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 +79 -34
- package/README.md +35 -9
- package/docs/diagnostics.md +4 -3
- package/docs/performance-trace.md +2 -1
- package/docs/sidebar-control.md +4 -2
- package/docs/supervision.md +17 -3
- package/extensions/gentle-herdr-state.ts +464 -114
- package/lib/gentle-sidebar.js +87 -33
- package/lib/perf-trace.js +83 -13
- package/package.json +1 -1
package/DESIGN.md
CHANGED
|
@@ -177,7 +177,8 @@ an explicit writer-ownership decision. Rationale follows each choice.
|
|
|
177
177
|
### O5. `done`/`idle` freshness vs pi-tree done-hold + idle grace → TTL WINS; SWEEP OWN TOKENS ONLY
|
|
178
178
|
|
|
179
179
|
- **Chosen:** every gentle token carries an absolute `expiry <= now + 60000`
|
|
180
|
-
(same 60 s horizon as E4)
|
|
180
|
+
(same 60 s horizon as E4), except `gentle_done_v1`, which carries the unseen
|
|
181
|
+
cap (§4.3). The consumer treats missing or expired gentle
|
|
181
182
|
tokens as `unknown → idle` fallback (never holds `done` past expiry).
|
|
182
183
|
On handover (gentle disabled/uninstalled) the consumer sweeps only token
|
|
183
184
|
names it wrote (`gentle_*`, `herdr:blocked` labels it set); it never deletes
|
|
@@ -206,7 +207,7 @@ Sidecar only: ships beside `herdr-agent-state.ts`, never modifies it.
|
|
|
206
207
|
| Producer event (source) | Tokens written | v1 state contribution |
|
|
207
208
|
|---|---|---|
|
|
208
209
|
| `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 |
|
|
209
|
-
| TaskStore `running` non-empty (G3; queued/waiting never execute) | `gentle_work_v1=<hash>:<count>:<exp>` (running
|
|
210
|
+
| TaskStore `running` non-empty (G3; queued/waiting never execute) | `gentle_work_v1=<hash>:<count>:<exp>` (total delegates — snapshot-confirmed running records plus distinct in-flight `subagent_run`/`subagent_continue` calls, §4.2 — 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 |
|
|
210
211
|
| `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 `?`) |
|
|
211
212
|
| 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 |
|
|
212
213
|
| 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` |
|
|
@@ -218,9 +219,25 @@ Sidecar only: ships beside `herdr-agent-state.ts`, never modifies it.
|
|
|
218
219
|
never counts as executing for the visible role + total (T2b): only `running`
|
|
219
220
|
feeds `gentle_work_v1` and `gentle_roles_v1`. Liveness/marker coverage
|
|
220
221
|
retains `running`/`queued`/pending (the root marker still covers a queued
|
|
221
|
-
subagent or a pending launch). The count is
|
|
222
|
-
Gentle Shell TaskStore `running` records carried in
|
|
223
|
-
`event.details.gentleAgents
|
|
222
|
+
subagent or a pending launch). The count is the UNION of two live sources:
|
|
223
|
+
the Gentle Shell TaskStore `running` records carried in
|
|
224
|
+
`event.details.gentleAgents`, narrowed on every beat to the ids the read
|
|
225
|
+
presence snapshot lists running, and the DISTINCT
|
|
226
|
+
`subagent_run`/`subagent_continue` calls still in flight that record set does
|
|
227
|
+
not list yet, deduplicated by call id so one delegate is counted once. The
|
|
228
|
+
in-flight leg is why a synchronous (task-mode) launch now counts at all: it
|
|
229
|
+
creates no TaskStore record until it returns `tool_result`, so the records
|
|
230
|
+
alone read two live synchronous delegates as zero, while the union renders
|
|
231
|
+
`explorer (2)` for as long as both calls are in flight. It is not a
|
|
232
|
+
pending-call estimate: a call is counted exactly while it is in flight and
|
|
233
|
+
drops out on `tool_result`, cancellation, and settle, and a cancelled call
|
|
234
|
+
keeps blocking the terminal state only through the separate pending-call leg.
|
|
235
|
+
Names stay record-only (an in-flight call adds no name), and a record the
|
|
236
|
+
upstream store no longer lists contributes no name, no role word
|
|
237
|
+
and no count, even when the local map never received its final. When no
|
|
238
|
+
snapshot is usable (stale heartbeat, mismatched generation, inconsistent
|
|
239
|
+
counts) the local map stands in full, never at zero — a zero fallback would
|
|
240
|
+
flip the `done` gate and hide genuinely running work.
|
|
224
241
|
Background launches (`subagent_run` with `mode: background`) announce their
|
|
225
242
|
lifecycle over `message_end` custom results instead of `tool_result`
|
|
226
243
|
details: an ACTIVE status (running|queued) there promotes the background
|
|
@@ -244,20 +261,25 @@ the pink generic `gentle`, machine key `orchestrating`).
|
|
|
244
261
|
The consumer displays the oldest role word (known short word or unknown
|
|
245
262
|
sanitized name) whenever the principal itself is not working, regardless of
|
|
246
263
|
how many delegates run; a working principal renders the pink `gentle` instead.
|
|
247
|
-
Role labels carry
|
|
248
|
-
than one.
|
|
264
|
+
Role labels carry that total count in parentheses when greater
|
|
265
|
+
than one — the §4.2 union, so two in-flight synchronous delegates of one role
|
|
266
|
+
render `explorer (2)` while the roles CSV still names `explorer` once. Role
|
|
267
|
+
order is immutable first-seen (progress reads never reorder;
|
|
249
268
|
sound same-session presence createdAt/startedAt may correct a late local
|
|
250
|
-
first-sighting, otherwise the local firstSeen stands)
|
|
269
|
+
first-sighting, otherwise the local firstSeen stands); the in-flight launches
|
|
270
|
+
sort after the running records, both oldest-first, so the oldest-role choice
|
|
271
|
+
is unchanged.
|
|
251
272
|
Pending subagent tool calls are label correlation state for a later
|
|
252
273
|
`gentleAgents.taskId` result and a role-only display hint while the call is
|
|
253
|
-
in flight
|
|
274
|
+
in flight; the marker itself carries no count. WHY the hint stays role-only:
|
|
275
|
+
task-mode `subagent_run` stays in
|
|
254
276
|
flight with no TaskStore record until it returns `tool_result`, so the exact
|
|
255
277
|
agent name in the pending `tool_call` input is the only live role evidence;
|
|
256
|
-
|
|
257
|
-
estimate, while publishing its role slug as a bounded-CSV hint keeps the
|
|
278
|
+
publishing its role slug as a bounded-CSV hint keeps the
|
|
258
279
|
sidebar on the active role (`worker`, never the amber `working` cell —
|
|
259
|
-
generic activity reads the pink `gentle`)
|
|
260
|
-
|
|
280
|
+
generic activity reads the pink `gentle`), while the total itself comes from
|
|
281
|
+
the §4.2 union (one entry per in-flight call id), never from the hint. The
|
|
282
|
+
hint merges with authoritative active TaskStore roles
|
|
261
283
|
(oldest-first) and clears when the tool result arrives, the call is
|
|
262
284
|
cancelled, or the agent settles. On a tool
|
|
263
285
|
result the producer reads the pending record before deleting it and uses it
|
|
@@ -318,6 +340,8 @@ sessionHash = 43*[A-Za-z0-9_-] ; base64url(sha256(agent_session path))
|
|
|
318
340
|
expiry = 1*15DIGIT ; unix-ms, MUST satisfy expiry <= now+60000 at write
|
|
319
341
|
count = "0" / [1-9] 0*15DIGIT
|
|
320
342
|
gentle_work_v1 = sessionHash ":" count ":" expiry
|
|
343
|
+
; count = the §4.2 union: snapshot-confirmed running
|
|
344
|
+
; records plus distinct in-flight launches, deduped
|
|
321
345
|
gentle_changes_v1 = sessionHash ":" count ":" count ":" expiry
|
|
322
346
|
; <hash>:<files>:<added+deleted>:<expiry> — LEGACY, see below
|
|
323
347
|
gentle_changes_v2 = sessionHash ":" count ":" count ":" count ":" expiry
|
|
@@ -375,15 +399,28 @@ gentle_done_v1 = sessionHash ":" expiry
|
|
|
375
399
|
; live background jobs, no ask/review/error leg), then
|
|
376
400
|
; republished with the SAME expiry (never refreshed) until
|
|
377
401
|
; it lapses; null (clear) whenever work reappears or the
|
|
378
|
-
; session resets. Its expiry IS the
|
|
379
|
-
;
|
|
380
|
-
;
|
|
381
|
-
;
|
|
382
|
-
;
|
|
383
|
-
;
|
|
384
|
-
;
|
|
385
|
-
;
|
|
386
|
-
;
|
|
402
|
+
; session resets. Its expiry IS the unseen cap: default
|
|
403
|
+
; 900000 ms (15 min, S8), overridden by
|
|
404
|
+
; GENTLE_DONE_UNSEEN_CAP_MS clamped to [100, 3600000], so a
|
|
405
|
+
; finish nobody looks at recedes at the cap. The consumer
|
|
406
|
+
; accepts no expiry beyond now+3600000 at read (the only
|
|
407
|
+
; token whose ceiling is not the 60 s TTL). A VIEWED finish
|
|
408
|
+
; recedes far sooner: the daemon starts one 5 s dwell
|
|
409
|
+
; (DONE_VIEW_DWELL_MS) at the first frame that observes the
|
|
410
|
+
; pane focused and then renders `idle` (§5.2). That ledger
|
|
411
|
+
; of views is keyed by the token's absolute expiry and is
|
|
412
|
+
; daemon memory only: a cleared token (reactivation,
|
|
413
|
+
; session reset) drops its view and a new mint starts a new
|
|
414
|
+
; episode, while a restart during a still-fresh token can
|
|
415
|
+
; show `done` once more for one dwell and never mints a
|
|
416
|
+
; second finish. The daemon also caps its next sleep at
|
|
417
|
+
; that expiry and at the
|
|
418
|
+
; pending dwell deadline (§8). The settle-edge hold that
|
|
419
|
+
; withholds the mint while an in-flight launch may still
|
|
420
|
+
; report back is a DIFFERENT bound:
|
|
421
|
+
; GENTLE_HERDR_DONE_HOLD_MS, default 5 s, clamped
|
|
422
|
+
; [1000, 300000]. A session that never worked never mints
|
|
423
|
+
; one.
|
|
387
424
|
gentle_ask_v1 = sessionHash ":" intentId ":" expiry
|
|
388
425
|
; durable ask signal, session-bound + TTL-fresh like
|
|
389
426
|
; gentle_orchestrating_v1 — emitted on every beat while
|
|
@@ -420,8 +457,9 @@ left it.
|
|
|
420
457
|
Validation: consumers MUST reject tokens failing the grammar (wrong hash
|
|
421
458
|
length, `expiry` in the past or `> now+60000` at read, non-numeric counts)
|
|
422
459
|
and treat the pane as `unknown → idle` for that signal (§7). `gentle_done_v1`
|
|
423
|
-
is the one ceiling exception: it is validated against `now+
|
|
424
|
-
overridden
|
|
460
|
+
is the one ceiling exception: it is validated against `now+3600000` so an
|
|
461
|
+
overridden unseen cap stays readable, and it still fails closed on a past
|
|
462
|
+
expiry.
|
|
425
463
|
|
|
426
464
|
### 4.4 Examples
|
|
427
465
|
|
|
@@ -500,8 +538,10 @@ because delegates run.
|
|
|
500
538
|
ordinary tool edge reaches the row through the host's own truth rather than
|
|
501
539
|
by re-arming it. A settle recovered this way is not an observed turn, so it
|
|
502
540
|
mints no `gentle_done_v1` and sends no finish notification.
|
|
503
|
-
- The settle-time pending latch (`pendingCount`) is bounded by
|
|
504
|
-
|
|
541
|
+
- The settle-time pending latch (`pendingCount`) is bounded by that settle's
|
|
542
|
+
finish hold (`GENTLE_HERDR_DONE_HOLD_MS`, default 5 s, clamped
|
|
543
|
+
[1000, 300000]) — the settle-edge bound, not the finish token's unseen cap:
|
|
544
|
+
past that hold a launch that never reports
|
|
505
545
|
back stops counting, so it cannot pin the native report at `working`.
|
|
506
546
|
- Session-change tokens are refreshed/cleared from the current Gentle Shell
|
|
507
547
|
session model every beat and never carried across sessions: zero changed
|
|
@@ -531,8 +571,9 @@ gate for the working-vs-idle decision — never rendered as a count),
|
|
|
531
571
|
`gentle_pending_v1` (blocking-delegate role marker + freshness gate for the
|
|
532
572
|
in-flight synchronous launch — renders the child's role word while the
|
|
533
573
|
principal's own turn is blocked on it),
|
|
534
|
-
`gentle_done_v1` (synthesized finish signal + its own
|
|
535
|
-
for the reachable `done` display
|
|
574
|
+
`gentle_done_v1` (synthesized finish signal + its own unseen-cap freshness
|
|
575
|
+
gate for the reachable `done` display, receded by the daemon after the viewed
|
|
576
|
+
dwell — the host never reports `done`, §4.3),
|
|
536
577
|
`gentle_error_v1` (durable run-error signal + freshness gate for the `error`
|
|
537
578
|
display — repairs a missed `error:` label edge, §4.3),
|
|
538
579
|
`gentle_roles_v1` (authoritative activity roles,
|
|
@@ -599,8 +640,10 @@ done := (native done OR fresh gentle_done_v1) AND gentle_work_v1
|
|
|
599
640
|
marker still covers; a fresh marker, any roles, or a working
|
|
600
641
|
principal veto terminal (queued cover, pending-launch hint).
|
|
601
642
|
The producer's finish token is the reachable path (the host
|
|
602
|
-
never emits done);
|
|
603
|
-
|
|
643
|
+
never emits done); the daemon holds `done` until it first
|
|
644
|
+
views the pane focused (one DONE_VIEW_DWELL_MS dwell) or the
|
|
645
|
+
unseen cap lapses, so `done` recedes to `idle` then and is
|
|
646
|
+
never skipped in between
|
|
604
647
|
idle := otherwise (native fallback; also all-gentle-tokens-missing-or-expired)
|
|
605
648
|
```
|
|
606
649
|
|
|
@@ -632,8 +675,8 @@ signal (it stays live while the principal is idle with queued or running
|
|
|
632
675
|
delegates), so it never outranks a role word. An in-flight attention `review`
|
|
633
676
|
(fresh `review:` label or durable `gentle_review_v1` token) overrides the
|
|
634
677
|
role list; a settled session renders `done` even against a stale-fresh
|
|
635
|
-
marker, and only after the
|
|
636
|
-
`idle` (§4.3).
|
|
678
|
+
marker, and only after the pane has been viewed for one dwell, or its unseen
|
|
679
|
+
cap has lapsed, does it recede to `idle` (§4.3).
|
|
637
680
|
|
|
638
681
|
### 5.3 Publication (sidebar tokens)
|
|
639
682
|
|
|
@@ -1074,9 +1117,11 @@ exactly one mechanism writes each piece of state.
|
|
|
1074
1117
|
marker, read from local git plus `agent.list` — plus the presence prefix,
|
|
1075
1118
|
because Herdr emits no event for either. That is why the fast cycle is armed
|
|
1076
1119
|
by a rendered non-idle display, and why polling is never removed.
|
|
1077
|
-
The sleep is also capped at the nearest live `gentle_done_v1` expiry
|
|
1120
|
+
The sleep is also capped at the nearest live `gentle_done_v1` expiry AND the
|
|
1121
|
+
nearest pending view-dwell deadline (`DONE_VIEW_DWELL_MS`) among
|
|
1078
1122
|
the panes just rendered (never below the 250 ms floor), so a held `done`
|
|
1079
|
-
row reaches `idle` when the
|
|
1123
|
+
row reaches `idle` when the cap or the dwell lapses rather than up to one
|
|
1124
|
+
poll later.
|
|
1080
1125
|
A pending expiry may only SHORTEN the delay: with no pending expiry the
|
|
1081
1126
|
delay is exactly the adaptive value above, and an already-expired or
|
|
1082
1127
|
unparseable value falls to the floor (fail closed, like every parser)
|
package/README.md
CHANGED
|
@@ -13,7 +13,9 @@ sanitized name on the amber `working` cell `#f9e2af` — never the word
|
|
|
13
13
|
`working`, never `gentle` — and a recognized gentle role keeps its
|
|
14
14
|
abbreviation — `explorer`, `worker`,
|
|
15
15
|
`verify`, `judge`, `rdd` — with the total running count in parentheses when
|
|
16
|
-
two or more subagents run, for example `explorer (3)
|
|
16
|
+
two or more subagents run, for example `explorer (3)`, and a synchronous
|
|
17
|
+
(task-mode) delegate counted while its launch is still in flight, so two
|
|
18
|
+
in-flight explorers read `explorer (2)`). The principal's own
|
|
17
19
|
activity marker (`gentle_principal_v1`, published while the principal session
|
|
18
20
|
itself works and cleared when it settles) decides the row — never the
|
|
19
21
|
delegate count, and never Herdr's aggregate native status (which reads
|
|
@@ -289,13 +291,26 @@ settled-plus-empty (principal settled with no running delegates and no
|
|
|
289
291
|
pending launches; a settled principal with running delegates keeps the role
|
|
290
292
|
word, never `done`). A role word is not a subagent label; it carries the
|
|
291
293
|
total running delegate count in parentheses when that count exceeds one. The
|
|
292
|
-
work total is
|
|
294
|
+
work total is the union of the
|
|
293
295
|
Gentle Shell TaskStore `running` records (only `running` counts as
|
|
294
|
-
executing; queued/waiting never count),
|
|
295
|
-
|
|
296
|
+
executing; queued/waiting never count), narrowed the same way to the ids the
|
|
297
|
+
session's presence snapshot lists running, and the distinct in-flight
|
|
298
|
+
`subagent_run`/`subagent_continue` calls the record set does not list yet,
|
|
299
|
+
deduplicated by call id so one delegate counts once. The in-flight leg is
|
|
300
|
+
what makes a synchronous (task-mode) launch count: it creates no TaskStore
|
|
301
|
+
record until it returns its `tool_result`, so two in-flight synchronous
|
|
302
|
+
delegates of one role render `explorer (2)` instead of a bare `explorer`,
|
|
303
|
+
and a call drops out on `tool_result`, cancellation, and settle. A cancelled
|
|
304
|
+
call is not counted, though it still blocks `done` through the pending-call
|
|
305
|
+
leg, which is separate. Names stay record-only (an in-flight call adds no
|
|
306
|
+
name), and the oldest-role order is unchanged: snapshot-confirmed running
|
|
307
|
+
records first, then in-flight launches, both oldest-first by first sighting.
|
|
308
|
+
A run that finished without a
|
|
309
|
+
delivered final contributes no count, no role and no name; with no usable
|
|
310
|
+
snapshot the local map stands in full, never at zero. Pending tool calls are
|
|
311
|
+
otherwise role-only display hints (exact
|
|
296
312
|
in-flight subagent agent -> role slug, resolved from the tool input or, for a
|
|
297
|
-
resume, from the tracked task record
|
|
298
|
-
role even at count 0) plus label correlation, and
|
|
313
|
+
resume, from the tracked task record) plus label correlation, and
|
|
299
314
|
true concurrent tasks all count. A live `running` record is never regressed
|
|
300
315
|
by a racy non-final status read (only the authoritative launch outcomes,
|
|
301
316
|
completions, and presence terminals move it), so principal activity with
|
|
@@ -363,9 +378,20 @@ repaints for wakes the same single frame loop (bounded reconnect, floored at
|
|
|
363
378
|
250 ms, no second loop, no per-event frame), and the producer requests that same
|
|
364
379
|
coalesced refresh after every landed token beat, so a status change
|
|
365
380
|
it publishes is drawn at once, and the daemon caps each sleep at the nearest
|
|
366
|
-
live `done` expiry
|
|
367
|
-
|
|
368
|
-
|
|
381
|
+
live `done` expiry and the nearest pending view-dwell deadline, so a row
|
|
382
|
+
reaches `idle` on time instead of one poll later. `done` is held until viewed:
|
|
383
|
+
a real finish stays `done` until the pane is first observed as the focused
|
|
384
|
+
pane in the daemon's own snapshot, then one 5 s dwell (`DONE_VIEW_DWELL_MS`,
|
|
385
|
+
consumer-side, not an override) and the recede to `idle`; a finish nobody
|
|
386
|
+
looks at recedes at `GENTLE_DONE_UNSEEN_CAP_MS` (default 900000 ms = 15
|
|
387
|
+
minutes, clamped [100, 3600000]), which is the finish token's expiry. A new
|
|
388
|
+
turn that reactivates the producer and a session reset clear the held `done`,
|
|
389
|
+
and a new mint is a new episode; the ledger of views is daemon memory only,
|
|
390
|
+
so a daemon restart while the token is still fresh can show `done` once more
|
|
391
|
+
for one dwell. `GENTLE_HERDR_DONE_HOLD_MS` no longer bounds this: it bounds
|
|
392
|
+
only the settle-edge hold that withholds the terminal state while an in-flight
|
|
393
|
+
launch may still report back (default 5 s, clamped [1000, 300000]). The
|
|
394
|
+
producer's own beat is 15 s by default and
|
|
369
395
|
`GENTLE_HERDR_BEAT_MS`-overridable for tests and debugging (clamped to
|
|
370
396
|
[100, 300000]); the override changes the cadence only, never the 60 s token
|
|
371
397
|
TTL. Reports in one window collapse into one frame, and refresh-driven frames
|
package/docs/diagnostics.md
CHANGED
|
@@ -43,9 +43,10 @@ distinct from an empty-but-successful view.
|
|
|
43
43
|
## Environment
|
|
44
44
|
|
|
45
45
|
- `HERDR_BIN_PATH` — Herdr binary (default `herdr`).
|
|
46
|
-
- `GENTLE_STATUS_STATE_DIR` (else `HERDR_PLUGIN_STATE_DIR
|
|
47
|
-
|
|
48
|
-
`gentle-
|
|
46
|
+
- `GENTLE_STATUS_STATE_DIR` (else `HERDR_PLUGIN_STATE_DIR` only when it is
|
|
47
|
+
the directory this package derives for that name under the resolved state
|
|
48
|
+
home, else the default plugins state dir) — read for `gentle-status.pid`,
|
|
49
|
+
the `gentle-sidebar-mode.json` (`{version:1,enabled:boolean}`; missing defaults
|
|
49
50
|
to Gentle mode), and the `gentle-interruptions.json` ledger
|
|
50
51
|
(`{version:1,panes:{...}}` with only
|
|
51
52
|
identity hash, whitelisted unfinished displays, finite timestamps, and
|
|
@@ -216,7 +216,8 @@ hook for it.
|
|
|
216
216
|
|
|
217
217
|
Both live in the plugin state directory, the same one the other Gentle flags
|
|
218
218
|
use (`GENTLE_STATUS_STATE_DIR`, else the Herdr-injected
|
|
219
|
-
`HERDR_PLUGIN_STATE_DIR` when it
|
|
219
|
+
`HERDR_PLUGIN_STATE_DIR` when it is the directory this package derives for
|
|
220
|
+
that name under the resolved state home and already holds our files, else
|
|
220
221
|
`$XDG_STATE_HOME/herdr/plugins/herdr-gentle-agents`, else
|
|
221
222
|
`~/.local/state/herdr/plugins/herdr-gentle-agents`):
|
|
222
223
|
|
package/docs/sidebar-control.md
CHANGED
|
@@ -55,8 +55,10 @@ queued acceptance.
|
|
|
55
55
|
|
|
56
56
|
## Mode file
|
|
57
57
|
|
|
58
|
-
Shared flag under the
|
|
59
|
-
|
|
58
|
+
Shared flag under the resolved state directory — the stored canonical plugins
|
|
59
|
+
dir, with `$GENTLE_STATUS_STATE_DIR` as the unconditional explicit override and
|
|
60
|
+
`$HERDR_PLUGIN_STATE_DIR` honoured only when it is the directory this package
|
|
61
|
+
derives for that name under the resolved state home (canonically compared):
|
|
60
62
|
`gentle-sidebar-mode.json` containing exactly
|
|
61
63
|
`{version:1,enabled:boolean}`. Missing means **enabled** (current
|
|
62
64
|
installs keep working with no file). A malformed file is reported, never
|
package/docs/supervision.md
CHANGED
|
@@ -46,6 +46,15 @@ tokens carrying private data are added here.
|
|
|
46
46
|
(`GENTLE_STATUS_POLL_MS`), 2 s fast cycle while recent ask activity or
|
|
47
47
|
send/publish failures are observed, N quiet frames or a TTL-bounded
|
|
48
48
|
window to recover, 250 ms floor, single dynamic `setTimeout` chain.
|
|
49
|
+
- `done` is held until viewed. The producer stamps the unseen cap as the
|
|
50
|
+
finish token's expiry (`GENTLE_DONE_UNSEEN_CAP_MS`, producer-side, default
|
|
51
|
+
900000 ms = 15 min, clamped [100, 3600000]); the daemon owns the earlier
|
|
52
|
+
recede, because `focused` rides the same snapshot it already reads: the
|
|
53
|
+
first frame that sees the pane focused starts one 5 s dwell
|
|
54
|
+
(`DONE_VIEW_DWELL_MS`, a consumer constant, not an override) and the row
|
|
55
|
+
then renders `idle`. A second look changes nothing, and the per-pane view
|
|
56
|
+
ledger is daemon memory only, so a daemon restart while the token is still
|
|
57
|
+
fresh can show `done` once more for one dwell; it never mints a finish.
|
|
49
58
|
- Failed snapshots are "no data", never "empty": nothing is published,
|
|
50
59
|
swept, or recorded on a failed read. A failed pane list is
|
|
51
60
|
distinguishable from an empty list (null vs `[]`): sweeps report
|
|
@@ -86,9 +95,14 @@ The daemon never writes the flag.
|
|
|
86
95
|
|
|
87
96
|
## Environment
|
|
88
97
|
|
|
89
|
-
- `GENTLE_STATUS_STATE_DIR` (else `HERDR_PLUGIN_STATE_DIR
|
|
90
|
-
|
|
91
|
-
|
|
98
|
+
- `GENTLE_STATUS_STATE_DIR` (else `HERDR_PLUGIN_STATE_DIR` only when it is
|
|
99
|
+
the directory this package derives for that name under the resolved state
|
|
100
|
+
home — canonically compared, so a symlinked or relative spelling of it
|
|
101
|
+
still qualifies — else the default plugins state dir) — pidfile, refresh
|
|
102
|
+
request, ledger, err log, sidebar flag. All fixtures in tests; never live
|
|
103
|
+
global state. An install whose Herdr state home differs from the Pi/XDG
|
|
104
|
+
state home therefore ignores Herdr's injected path and uses the derived
|
|
105
|
+
stored directory, which is what keeps a single publisher.
|
|
92
106
|
- `HERDR_BIN_PATH`, `HERDR_SOCKET_PATH` — Herdr transport (socket with
|
|
93
107
|
one CLI fallback each).
|
|
94
108
|
- `GENTLE_STATUS_POLL_MS` / `GENTLE_STATUS_FAST_POLL_MS` /
|