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/DESIGN.md +185 -85
- package/README.md +90 -45
- 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 +734 -128
- package/lib/gentle-sidebar.js +87 -33
- package/lib/perf-trace.js +83 -13
- package/package.json +1 -1
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`
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
`
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
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)`, 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
|
|
218
|
-
`orchestrating`, pink `#f5c2e7`)
|
|
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
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
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` —
|
|
265
|
-
|
|
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
|
|
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),
|
|
286
|
-
|
|
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
|
|
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
|
|
327
|
-
`gentle` while its delegates run (a
|
|
328
|
-
|
|
329
|
-
|
|
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
|
|
355
|
-
|
|
356
|
-
|
|
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`,
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
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;
|
|
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
|
|
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
|
|
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
|
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` /
|