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 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). The consumer treats missing or expired gentle
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 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 |
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 a direct projection of the
222
- Gentle Shell TaskStore `running` records carried in
223
- `event.details.gentleAgents` — never a calculated pending-call estimate.
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 the total running-delegate count in parentheses when greater
248
- than one. Role order is immutable first-seen (progress reads never reorder;
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 — never a count. WHY role-only: task-mode `subagent_run` stays in
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
- counting it would inflate the normative `gentle_work_v1` total with an
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`) with the count
260
- authoritative at 0. The hint merges with authoritative active TaskStore roles
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 done hold: default
379
- ; 5 s (short on purpose — the hold only makes a finish
380
- ; visible, it never pins a settled row, so `idle` follows
381
- ; within seconds), overridden by
382
- ; GENTLE_HERDR_DONE_HOLD_MS clamped to [1000, 300000], and
383
- ; the consumer accepts no expiry beyond now+300000 at read
384
- ; (the only token whose ceiling is not the 60 s TTL). The
385
- ; daemon also caps its next sleep at that expiry (§8). A
386
- ; session that never worked never mints one.
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+300000` so an
424
- overridden hold stays readable, and it still fails closed on a past expiry.
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 the finish hold
504
- of the settle that raised it: past that hold a launch that never reports
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 hold freshness gate
535
- for the reachable `done` display — the host never reports `done`, §4.3),
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); its expiry is the hold, so `done` recedes
603
- to `idle` when it lapses and is never skipped in between
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 minted finish hold lapses does it recede to
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 among
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 hold lapses rather than up to one poll later.
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)`). The principal's own
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 a direct projection of the
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), never a calculated
295
- pending-call estimate: pending tool calls are role-only display hints (exact
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, so task-mode launches show the active
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, so a settled row reaches `idle` when its short hold (5 s by
367
- default, `GENTLE_HERDR_DONE_HOLD_MS`-overridable) lapses instead of one poll
368
- later. The producer's own beat is 15 s by default and
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
@@ -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`, else the
47
- default plugins state dir) — read for `gentle-status.pid` and the
48
- `gentle-sidebar-mode.json` (`{version:1,enabled:boolean}`; missing defaults
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 already holds our files, else
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
 
@@ -55,8 +55,10 @@ queued acceptance.
55
55
 
56
56
  ## Mode file
57
57
 
58
- Shared flag under the existing resolved state directory
59
- (`$GENTLE_STATUS_STATE_DIR`, else the Herdr plugin state dir):
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
@@ -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`, else the
90
- default plugins state dir) — pidfile, refresh request, ledger, err
91
- log, sidebar flag. All fixtures in tests; never live global state.
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` /