herdr-gentle-shell 1.5.1 → 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/README.md CHANGED
@@ -6,21 +6,25 @@ 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` for generic activity — machine key
10
- `working` — e.g. the orchestrator/main agent when settled with no fresh
11
- root marker; `gentle` in pink while the principal
12
- session actively works — even with zero
13
- subagents — (machine display key
14
- `orchestrating`, pink palette unchanged). The principal's own activity marker
15
- (`gentle_principal_v1`, published while the principal session itself works and
16
- cleared when it settles) decides the row — never the delegate count, and
17
- never Herdr's aggregate native status (which reads `working` whenever any
18
- delegate runs): the default is still the principal's own state, so while the
19
- principal works its own turn it reads `gentle` and no delegate role word
20
- wins; while the principal is idle
21
- the oldest running delegate role shows — `explorer`, `worker`, `verify`,
22
- `judge`, `rdd` — with the total running count in parentheses when two or
23
- more subagents run, for example `explorer (3)`). The single exception is a
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)`, 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
19
+ activity marker (`gentle_principal_v1`, published while the principal session
20
+ itself works and cleared when it settles) decides the row — never the
21
+ delegate count, and never Herdr's aggregate native status (which reads
22
+ `working` whenever any delegate runs): the default is still the principal's
23
+ own state, so while the principal works its own turn it reads pink `gentle`,
24
+ with or without a fresh root marker, and no delegate word wins; while the
25
+ principal is idle the oldest running delegate role shows, or that subagent's
26
+ own name when no role word is recognized. `gentle` never renders on an idle
27
+ session. The single exception is a
24
28
  blocking synchronous subagent call (`gentle_pending_v1`): a task-mode
25
29
  `subagent_run`/`subagent_continue` holds the principal's turn open until the
26
30
  child returns, so the principal is waiting on that child rather than working
@@ -214,8 +218,10 @@ sidebar-only, DESIGN §7; it rides the durable session-bound
214
218
  `gentle_error_v1` token, republished on every beat while the run-error leg
215
219
  stands and cleared the beat it releases, so a beat the sidebar missed is
216
220
  repaired by the next one); the orchestrating
217
- leg renders the user-facing word `gentle` (machine key stays
218
- `orchestrating`, pink `#f5c2e7`). Remaining state colors:
221
+ leg renders the one user-facing `gentle` (machine key stays
222
+ `orchestrating`, pink `#f5c2e7`), while the `working` leg (amber `#f9e2af`)
223
+ carries a non-contemplated subagent's own sanitized name and never renders
224
+ the word `gentle` or `working`. Remaining state colors:
219
225
  working/worker amber `#f9e2af`, explorer blue `#89b4fa`, verify teal
220
226
  `#94e2d5`, ask orange `#fab387`, error red `#f38ba8`, done green `#a6e3a1`,
221
227
  idle grey `#7c7f93`. Added stays green and deleted stays red; the mapping
@@ -250,19 +256,24 @@ unavailable counts (unavailable files stay in the file count with 0/0); `↑N` s
250
256
  branch is behind its upstream (branch-ab status only, no diff). `gentle_project`,
251
257
  `gentle_changes_summary`, and the segment
252
258
  tokens (`gentle_changes_added`/`_deleted`/`_pull`) stay published for
253
- compatibility but render no visible row. `gentle`
254
- renders for generic activity (machine key `working`): the main agent when settled with no fresh root marker or roles
255
- (or active subs with an unsalvageable role shape and no fresh marker); pink
256
- `gentle` (machine key `orchestrating`, pink palette unchanged) renders while the principal session actively works — even with zero subagents —
257
- retaining running-subagent or pending-launch coverage. The principal's own
259
+ compatibility but render no visible row. Pink `gentle` (machine key
260
+ `orchestrating`, pink palette unchanged) is the
261
+ only user-facing `gentle`: it renders while the principal session actively
262
+ works — even with zero subagents, with or without a fresh root marker — and
263
+ as its generic status when a running delegate has no resolvable name, when
264
+ only unsalvageable role shapes remain, or when the root marker covers a
265
+ queued/running sub or a pending launch; it never renders on an idle session.
266
+ A non-contemplated subagent renders its own sanitized name on the amber
267
+ `working` cell instead, and a recognized gentle role keeps its abbreviation
268
+ (`explorer`, `worker`, `verify`, `judge`, `rdd`). The principal's own
258
269
  activity decides the row, never the delegate count and never Herdr's
259
270
  aggregate native status (the work token counts running delegates, and the
260
271
  native status reads `working` for any running delegate or pending launch — so
261
272
  neither can say the principal works): the dedicated
262
273
  `gentle_principal_v1` marker is published while the principal session itself
263
274
  works and cleared when it settles. That is the default: a **working
264
- principal** reads `gentle` — pink
265
- `orchestrating` while a fresh root marker is live — and no delegate role word
275
+ principal** reads the pink `gentle` — machine key `orchestrating`, fresh root
276
+ marker or not — and no delegate role word
266
277
  wins; an **idle principal** shows the oldest running TaskStore role
267
278
  (`explorer`, `worker`, `verify`, `judge`, `rdd`), however many delegates run.
268
279
  The one exception is a blocking synchronous subagent call: while a task-mode
@@ -280,19 +291,32 @@ settled-plus-empty (principal settled with no running delegates and no
280
291
  pending launches; a settled principal with running delegates keeps the role
281
292
  word, never `done`). A role word is not a subagent label; it carries the
282
293
  total running delegate count in parentheses when that count exceeds one. The
283
- work total is a direct projection of the
294
+ work total is the union of the
284
295
  Gentle Shell TaskStore `running` records (only `running` counts as
285
- executing; queued/waiting never count), never a calculated
286
- 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
287
312
  in-flight subagent agent -> role slug, resolved from the tool input or, for a
288
- resume, from the tracked task record, so task-mode launches show the active
289
- role even at count 0) plus label correlation, and
313
+ resume, from the tracked task record) plus label correlation, and
290
314
  true concurrent tasks all count. A live `running` record is never regressed
291
315
  by a racy non-final status read (only the authoritative launch outcomes,
292
316
  completions, and presence terminals move it), so principal activity with
293
317
  live delegates keeps `gentle` while an idle principal keeps the role word; a
294
318
  sanitized unknown slug exactly
295
- equal to `working` or `subagent` degrades to `gentle` (neither bare word ever
319
+ equal to `working` or `subagent` degrades to the pink `gentle` (neither bare word ever
296
320
  renders; `subagent` is the producer's launch-correlation placeholder, never
297
321
  an agent name).
298
322
  Background launches (`subagent_run` with `mode: background`) announce
@@ -323,10 +347,13 @@ herdr server reload-config
323
347
  Live check: with the daemon running and the override applied, open a Pi pane
324
348
  and confirm row 2 shows pink `gentle` (machine key
325
349
  `orchestrating`) while
326
- the principal session actively works — even with zero subagents — and keeps
327
- `gentle` while its delegates run (a role word such as `worker`, `explorer`,
328
- `verify`, `judge` shows once the principal itself is idle — and also while a
329
- task-mode subagent call blocks the principal's turn, until it returns), row 1
350
+ the principal session actively works — even with zero subagents, and with or
351
+ without a fresh root marker — and keeps `gentle` while its delegates run (a
352
+ role word such as `worker`, `explorer`,
353
+ `verify`, `judge`, or a non-contemplated subagent's own name in amber, shows
354
+ once the principal itself is idle — and also while a
355
+ task-mode subagent call blocks the principal's turn, until it returns), that
356
+ a row never reads `gentle` on an idle pane; row 1
330
357
  shows the single heading cell (`● <project>` plus ` +N`/` -N`/` ↑N` inline, zero `·`) after edits / when behind upstream; then `ask` on an open
331
358
  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
359
  `HERDR_CONFIG_PATH` on a temp file for apply/uninstall checks.
@@ -351,9 +378,23 @@ repaints for wakes the same single frame loop (bounded reconnect, floored at
351
378
  250 ms, no second loop, no per-event frame), and the producer requests that same
352
379
  coalesced refresh after every landed token beat, so a status change
353
380
  it publishes is drawn at once, and the daemon caps each sleep at the nearest
354
- live `done` expiry, so a settled row reaches `idle` when its short hold (5 s by
355
- default, `GENTLE_HERDR_DONE_HOLD_MS`-overridable) lapses instead of one poll
356
- later. Reports in one window collapse into one frame, and refresh-driven frames
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
395
+ `GENTLE_HERDR_BEAT_MS`-overridable for tests and debugging (clamped to
396
+ [100, 300000]); the override changes the cadence only, never the 60 s token
397
+ TTL. Reports in one window collapse into one frame, and refresh-driven frames
357
398
  are floored at 250 ms, so a burst can never spin the daemon. Polling stays the
358
399
  fallback for every lifecycle signal and the only source for what no Herdr event
359
400
  carries (the git-derived `+N/-N` and `↑N` row data and the presence prefix), so a
@@ -367,10 +408,12 @@ See [DESIGN.md](DESIGN.md) §4 (producer) and §5 (consumer), and
367
408
  ## Key Features You Should Know About
368
409
 
369
410
  - Full v1 state matrix including the root-session `orchestrating` marker
370
- (pink `●` + user-facing word `gentle`, while the principal session actively
371
- works — even with zero subagents — retaining subagent/pending coverage;
372
- yielding only to `ask`/`rdd`/`blocked` and terminal `done` (done needs
373
- settled-plus-empty)) and the authoritative TaskStore role signal
411
+ (pink `●` + the one user-facing word `gentle`, the principal session's
412
+ working and generic status: it shows while the principal actively works —
413
+ even with zero subagents and with or without a fresh root marker — and
414
+ covers queued/running subagents and pending launches; yielding only to
415
+ `ask`/`rdd`/`blocked` and terminal `done` (done needs settled-plus-empty);
416
+ never on an idle session) and the authoritative TaskStore role signal
374
417
  (`explorer` / `worker` / `verify` / `judge` / `rdd` from `TaskRecord.agent`,
375
418
  oldest running first by immutable first-seen, shown while the principal
376
419
  itself is idle — a working principal's own turn keeps `gentle`, asserted by
@@ -379,10 +422,12 @@ See [DESIGN.md](DESIGN.md) §4 (producer) and §5 (consumer), and
379
422
  synchronous `subagent_run`/`subagent_continue` call holds the principal's
380
423
  turn open, so the in-flight child's role shows instead (the
381
424
  `gentle_pending_v1` role marker) until that call resolves, while a
382
- background delegate never takes that path; `gentle` (machine
383
- key `working`) for the principal's own working state; an unknown delegation
425
+ background delegate never takes that path; an unknown delegation
384
426
  keeps its original sanitized name, 32-char bound — never a generic
385
- collapse), with a running-count suffix on role labels when two or more
427
+ collapse (the reserved words `gentle`, `working`, and `subagent` are no name
428
+ and degrade to the pink generic) — and renders on the amber `working` cell,
429
+ which never carries the
430
+ word `gentle`), with a running-count suffix on role labels when two or more
386
431
  delegates run, `ask` on blocked user input,
387
432
  `rdd` during native review execution (machine key stays `review`; execution
388
433
  is silent — desktop attention fires only for a waiting `ask` intent, as
@@ -428,7 +473,7 @@ See [DESIGN.md](DESIGN.md) §4 (producer) and §5 (consumer), and
428
473
  nothing and logs one line per reason. The gs pane's own live state stays
429
474
  unobservable until the isolated install forwards `HERDR_ENV` to its agent (a
430
475
  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 the delegate role word instead of `gentle`. Our code never emits `done`/`finished` native states or a Herdr notification (the opt-in Moshi replacement below is a separate, off-by-default channel): the host owns finished text on `done`, `blocked`/unknown presentation, sound, and all desktop attention toasts (ask + finish) — there is no consumer toast path left to dedup. Single publisher by design: the managed native extension file stays on disk and is excluded through an ownership-bound Pi settings entry while Gentle mode is selected. `node bin/gentle-sidebar.js disable` removes only our owned exclusion and managed rows, gates our producer/daemon, and hands the sidebar back to the native publisher (running Pi sessions need `/reload`); never run both publishers on the same pane. Limits (unverified, host-owned): the host `idle`→`done`→`finished` mapping and unknown-state handling are owned by Herdr.
476
+ - 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
477
  - Sidebar switch (`enable` / `disable` / `status` / `toggle`):
433
478
  `node bin/gentle-sidebar.js <verb>` picks between this plugin's sidebar rows
434
479
  and the native Herdr sidebar. `status` is read-only; `enable` converges the
@@ -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` /