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/DESIGN.md
CHANGED
|
@@ -17,11 +17,15 @@ explicitly in §10 and are not decided here.
|
|
|
17
17
|
- Herdr sidebar (`[ui.sidebar.agents]` + `[ui.sidebar.spaces]` blocks): shows
|
|
18
18
|
one state label per pane plus an optional session-changes badge.
|
|
19
19
|
- The human operator watching Pi + Gentle Shell agents: needs to distinguish
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
20
|
+
the principal session's own pink `gentle` (machine key `orchestrating` —
|
|
21
|
+
its working status and its generic status) from a delegate's own word: the
|
|
22
|
+
active TaskStore role abbreviation (`explorer`, `worker`, `verify`,
|
|
23
|
+
`judge`, `rdd`) or, for a non-contemplated subagent, that subagent's
|
|
24
|
+
sanitized name on the amber `working` cell — plus `ask` (blocked on user
|
|
25
|
+
input), `blocked` (the row word for the `error` key), `done`, and `idle` at
|
|
26
|
+
a glance. No visible text ever carries a subagent count, exactly one
|
|
27
|
+
user-facing `gentle` exists (the pink one), the amber `working` cell never
|
|
28
|
+
renders that word, and `gentle` never renders on an idle session.
|
|
25
29
|
|
|
26
30
|
### Current boundary and interaction
|
|
27
31
|
|
|
@@ -173,7 +177,8 @@ an explicit writer-ownership decision. Rationale follows each choice.
|
|
|
173
177
|
### O5. `done`/`idle` freshness vs pi-tree done-hold + idle grace → TTL WINS; SWEEP OWN TOKENS ONLY
|
|
174
178
|
|
|
175
179
|
- **Chosen:** every gentle token carries an absolute `expiry <= now + 60000`
|
|
176
|
-
(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
|
|
177
182
|
tokens as `unknown → idle` fallback (never holds `done` past expiry).
|
|
178
183
|
On handover (gentle disabled/uninstalled) the consumer sweeps only token
|
|
179
184
|
names it wrote (`gentle_*`, `herdr:blocked` labels it set); it never deletes
|
|
@@ -201,22 +206,38 @@ Sidecar only: ships beside `herdr-agent-state.ts`, never modifies it.
|
|
|
201
206
|
|
|
202
207
|
| Producer event (source) | Tokens written | v1 state contribution |
|
|
203
208
|
|---|---|---|
|
|
204
|
-
| `agent_start` / `isIdle=false` (main actively working, incl. 0 active subs) | `gentle_work_v1=<hash>:0:<exp>` + `gentle_principal_v1=<hash>:<exp>` (principal-only activity marker) + `gentle_orchestrating_v1=<hash>:<exp>` (root marker while main actively works) + clear `herdr:blocked` labels | `gentle` (machine key `
|
|
205
|
-
| TaskStore `running` non-empty (G3; queued/waiting never execute) | `gentle_work_v1=<hash>:<count>:<exp>` (running
|
|
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 |
|
|
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 |
|
|
206
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 `?`) |
|
|
207
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 |
|
|
208
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` |
|
|
209
214
|
| a tool call fails, a delegate record ends `failed`, or a beat transport fails | nothing — detection only (a counter and a debug line under `GENTLE_HERDR_DEBUG=1`) | nothing: no label, no native state, no finish hold, no notification |
|
|
210
|
-
| `agent_settled` + 0 active subs | `gentle_work_v1=<hash>:0:<exp>`; clear `blocked` labels | `done` |
|
|
215
|
+
| `agent_settled` + 0 active subs | `gentle_work_v1=<hash>:0:<exp>`; clear `blocked` labels | `done` — an observed turn only: the settle the beat reconciles from the host's live truth mints no finish (§4.5) |
|
|
211
216
|
| `SESSION_CHANGE_ENTRY` `gentle-pi.session-change/v1` tool outcome (G1/G2) | `gentle_changes_v2=<hash>:<files>:<added>:<deleted>:<exp>` (+ legacy `gentle_changes_v1` dual-emit, §4.3) | change segments only (orthogonal to state) |
|
|
212
217
|
|
|
213
218
|
`waiting`/`finished` TaskStore entries never count as active, and `queued`
|
|
214
219
|
never counts as executing for the visible role + total (T2b): only `running`
|
|
215
220
|
feeds `gentle_work_v1` and `gentle_roles_v1`. Liveness/marker coverage
|
|
216
221
|
retains `running`/`queued`/pending (the root marker still covers a queued
|
|
217
|
-
subagent or a pending launch). The count is
|
|
218
|
-
Gentle Shell TaskStore `running` records carried in
|
|
219
|
-
`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.
|
|
220
241
|
Background launches (`subagent_run` with `mode: background`) announce their
|
|
221
242
|
lifecycle over `message_end` custom results instead of `tool_result`
|
|
222
243
|
details: an ACTIVE status (running|queued) there promotes the background
|
|
@@ -234,24 +255,31 @@ exact `gentle-ai-worker` → `worker`, exact `gentle-ai-verify` → `verify`,
|
|
|
234
255
|
`jd-fix-` families) → the distinct `judge` slug (never `rdd`), and a
|
|
235
256
|
review agent / `gentle-ai-review*` / any role containing `review` → `rdd`;
|
|
236
257
|
any other agent keeps its original sanitized name (lowercase `[a-z0-9_-]`
|
|
237
|
-
slug, 32-char bound — never a generic collapse; unsalvageable shapes
|
|
238
|
-
|
|
258
|
+
slug, 32-char bound — never a generic collapse; unsalvageable shapes and the
|
|
259
|
+
reserved slugs `gentle`, `working`, and `subagent` read
|
|
260
|
+
the pink generic `gentle`, machine key `orchestrating`).
|
|
239
261
|
The consumer displays the oldest role word (known short word or unknown
|
|
240
262
|
sanitized name) whenever the principal itself is not working, regardless of
|
|
241
|
-
how many delegates run; a working principal renders `gentle` instead.
|
|
242
|
-
Role labels carry
|
|
243
|
-
than one.
|
|
263
|
+
how many delegates run; a working principal renders the pink `gentle` instead.
|
|
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;
|
|
244
268
|
sound same-session presence createdAt/startedAt may correct a late local
|
|
245
|
-
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.
|
|
246
272
|
Pending subagent tool calls are label correlation state for a later
|
|
247
273
|
`gentleAgents.taskId` result and a role-only display hint while the call is
|
|
248
|
-
in flight
|
|
274
|
+
in flight; the marker itself carries no count. WHY the hint stays role-only:
|
|
275
|
+
task-mode `subagent_run` stays in
|
|
249
276
|
flight with no TaskStore record until it returns `tool_result`, so the exact
|
|
250
277
|
agent name in the pending `tool_call` input is the only live role evidence;
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
278
|
+
publishing its role slug as a bounded-CSV hint keeps the
|
|
279
|
+
sidebar on the active role (`worker`, never the amber `working` cell —
|
|
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
|
|
255
283
|
(oldest-first) and clears when the tool result arrives, the call is
|
|
256
284
|
cancelled, or the agent settles. On a tool
|
|
257
285
|
result the producer reads the pending record before deleting it and uses it
|
|
@@ -264,7 +292,7 @@ launch outcomes keep `running` (and its agent) against `queued`/`waiting`/
|
|
|
264
292
|
re-resolve oldest-first — so a working principal with live delegates keeps
|
|
265
293
|
`gentle`, and a settle with running delegates keeps the oldest role word
|
|
266
294
|
instead of settling to `idle`/`done`. A sanitized unknown slug exactly equal to
|
|
267
|
-
`working` degrades to no role (generic `gentle`) on both the producer
|
|
295
|
+
`working` degrades to no role (the pink generic `gentle`) on both the producer
|
|
268
296
|
(`agentToRole`) and the consumer (`roleToDisplay`) sides. No local
|
|
269
297
|
age/staleness timeout is applied — Gentle Shell owns lifecycle/status truth.
|
|
270
298
|
Finished/failed/cancelled records may linger in the map but never count;
|
|
@@ -276,10 +304,11 @@ coverage while the authoritative active list is non-empty or any
|
|
|
276
304
|
once the main session settles — settled, or any non-root session. The marker carries no
|
|
277
305
|
count and changes neither the work total nor the roles CSV: it is a pure
|
|
278
306
|
freshness-bound presence flag (`<hash>:<exp>`, same binding/TTL style as
|
|
279
|
-
gentle_work_v1) that the consumer reduces to `
|
|
280
|
-
|
|
281
|
-
terminal `done`/native-`blocked`, and
|
|
282
|
-
|
|
307
|
+
gentle_work_v1) that the consumer reduces to the same pink `gentle` the
|
|
308
|
+
principal's own activity renders, only with no role word above it (§5.2):
|
|
309
|
+
below attention (error/ask/review), terminal `done`/native-`blocked`, and
|
|
310
|
+
role words; ahead of the positive-count generic fallback only, which renders
|
|
311
|
+
that same pink `gentle`.
|
|
283
312
|
The root session also emits `gentle_principal_v1` while its own agent is
|
|
284
313
|
active (`agentActive`) and clears it (null) the moment the principal
|
|
285
314
|
settles, keeping the same binding/TTL discipline. This is the principal-only
|
|
@@ -290,7 +319,7 @@ principal itself works. The native status keeps that aggregate meaning for
|
|
|
290
319
|
Herdr's own pane state; the row's working-vs-idle decision reads only
|
|
291
320
|
`gentle_principal_v1` (§5.2). It carries no count and alters neither the work
|
|
292
321
|
total nor the roles CSV. `agentActive` alone would render that blocked call
|
|
293
|
-
as generic `gentle`.
|
|
322
|
+
as the pink generic `gentle`.
|
|
294
323
|
The root session additionally emits `gentle_pending_v1` (`<hash>:<role>:<exp>`)
|
|
295
324
|
while a synchronous (task mode) `subagent_run`/`subagent_continue` tool call
|
|
296
325
|
is still in flight: such a call blocks the principal's own turn, so the
|
|
@@ -311,6 +340,8 @@ sessionHash = 43*[A-Za-z0-9_-] ; base64url(sha256(agent_session path))
|
|
|
311
340
|
expiry = 1*15DIGIT ; unix-ms, MUST satisfy expiry <= now+60000 at write
|
|
312
341
|
count = "0" / [1-9] 0*15DIGIT
|
|
313
342
|
gentle_work_v1 = sessionHash ":" count ":" expiry
|
|
343
|
+
; count = the §4.2 union: snapshot-confirmed running
|
|
344
|
+
; records plus distinct in-flight launches, deduped
|
|
314
345
|
gentle_changes_v1 = sessionHash ":" count ":" count ":" expiry
|
|
315
346
|
; <hash>:<files>:<added+deleted>:<expiry> — LEGACY, see below
|
|
316
347
|
gentle_changes_v2 = sessionHash ":" count ":" count ":" count ":" expiry
|
|
@@ -326,7 +357,10 @@ role = "explorer" / "worker" / "verify" / "judge" / "rdd" / passthrou
|
|
|
326
357
|
; stays distinct, never `rdd`)
|
|
327
358
|
; passthrough = 1*32 lowercase [a-z0-9_-], leading [a-z0-9]
|
|
328
359
|
; (unknown delegation keeps its sanitized original name —
|
|
329
|
-
; never a generic collapse; producer truncates to 32
|
|
360
|
+
; never a generic collapse; producer truncates to 32;
|
|
361
|
+
; the reserved words `gentle`, `working`, and `subagent`
|
|
362
|
+
; resolve to no role on both sides — producer and reducer —
|
|
363
|
+
; so they degrade to the pink generic `gentle`)
|
|
330
364
|
gentle_roles_v1 = role *("," role) ; total <= 512 UTF-8 bytes; null (clear)
|
|
331
365
|
; when no delegation is active (no role words)
|
|
332
366
|
gentle_orchestrating_v1 = sessionHash ":" expiry
|
|
@@ -365,15 +399,28 @@ gentle_done_v1 = sessionHash ":" expiry
|
|
|
365
399
|
; live background jobs, no ask/review/error leg), then
|
|
366
400
|
; republished with the SAME expiry (never refreshed) until
|
|
367
401
|
; it lapses; null (clear) whenever work reappears or the
|
|
368
|
-
; session resets. Its expiry IS the
|
|
369
|
-
;
|
|
370
|
-
;
|
|
371
|
-
;
|
|
372
|
-
;
|
|
373
|
-
;
|
|
374
|
-
;
|
|
375
|
-
;
|
|
376
|
-
;
|
|
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.
|
|
377
424
|
gentle_ask_v1 = sessionHash ":" intentId ":" expiry
|
|
378
425
|
; durable ask signal, session-bound + TTL-fresh like
|
|
379
426
|
; gentle_orchestrating_v1 — emitted on every beat while
|
|
@@ -410,8 +457,9 @@ left it.
|
|
|
410
457
|
Validation: consumers MUST reject tokens failing the grammar (wrong hash
|
|
411
458
|
length, `expiry` in the past or `> now+60000` at read, non-numeric counts)
|
|
412
459
|
and treat the pane as `unknown → idle` for that signal (§7). `gentle_done_v1`
|
|
413
|
-
is the one ceiling exception: it is validated against `now+
|
|
414
|
-
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.
|
|
415
463
|
|
|
416
464
|
### 4.4 Examples
|
|
417
465
|
|
|
@@ -435,17 +483,19 @@ explorers with count 3 → `explorer (3)`; 5 files
|
|
|
435
483
|
`● myproj +110 -22` (` +` green for added, ` -` red for deleted with a
|
|
436
484
|
leading-space match, zero `·` separators because exactly one heading cell
|
|
437
485
|
is nonempty).
|
|
438
|
-
A review label renders `rdd` with a blue `●` (`#89b4fa`, same as explorer/pull). A
|
|
439
|
-
`gentle_orchestrating_v1` marker renders pink `gentle` (machine display
|
|
440
|
-
`orchestrating`, pink palette unchanged)
|
|
441
|
-
|
|
442
|
-
attention (`ask`/`review`/`blocked`) and terminal `done` states.
|
|
443
|
-
|
|
444
|
-
|
|
445
|
-
|
|
446
|
-
|
|
447
|
-
|
|
448
|
-
`gentle`
|
|
486
|
+
A review label renders `rdd` with a blue `●` (`#89b4fa`, same as explorer/pull). A
|
|
487
|
+
`gentle_orchestrating_v1` marker renders the pink `gentle` (machine display
|
|
488
|
+
key `orchestrating`, pink palette unchanged): it covers the principal's
|
|
489
|
+
queued/running subs and pending launches, and it yields to a delegate role
|
|
490
|
+
word and to attention (`ask`/`review`/`blocked`) and terminal `done` states.
|
|
491
|
+
The marker is not a principal-working signal: it stays live while the
|
|
492
|
+
principal is idle with queued or running delegates, so it never decides the
|
|
493
|
+
working state. That state comes from `gentle_principal_v1` alone, and it is
|
|
494
|
+
the same pink `gentle` with or without a fresh root marker: the amber
|
|
495
|
+
`working` cell is never the principal's own. With no fresh principal marker
|
|
496
|
+
the pane shows the oldest role word, the pink generic `gentle` when a running
|
|
497
|
+
delegate has no resolvable name, or `idle` — but never an amber generic
|
|
498
|
+
because delegates run.
|
|
449
499
|
|
|
450
500
|
### 4.5 Publication and chunking
|
|
451
501
|
|
|
@@ -470,6 +520,29 @@ principal marker the pane shows the oldest role word (or `idle`), never
|
|
|
470
520
|
- Writes are idempotent full-state snapshots per pane (all gentle tokens
|
|
471
521
|
re-emitted each beat), never deltas — a lost report is repaired by the next
|
|
472
522
|
beat.
|
|
523
|
+
- The producer beats every 15 s by default; `GENTLE_HERDR_BEAT_MS` overrides
|
|
524
|
+
the cadence for tests and debugging (clamped to [100, 300000]). The
|
|
525
|
+
override changes no TTL: the write horizon stays `now+60000` (§8).
|
|
526
|
+
- Every beat first reconciles the settle from the host's own live truth: with
|
|
527
|
+
no turn active and no work evidence (no running/queued delegate, no pending
|
|
528
|
+
launch, no live background job), the retained context's `isIdle()` flips
|
|
529
|
+
`settled`, so a run whose `agent_settled` never reached the producer still
|
|
530
|
+
reaches native `idle` instead of republishing a fresh count-0 work token
|
|
531
|
+
forever. A turn this producer saw start is never overridden from there.
|
|
532
|
+
When the host offers no truth at all, a producer that observed no turn stops
|
|
533
|
+
beating after a bounded budget (three beats) instead of publishing a native
|
|
534
|
+
state the host never confirmed; a turn this producer saw start is never
|
|
535
|
+
bounded, so the budget cannot trade a truthful `working` for a false `idle`
|
|
536
|
+
on a host with no truth to settle on. The beat is re-armed by the edges that
|
|
537
|
+
schedule a publish (ask, review, launch, session changes, jobs), while an
|
|
538
|
+
ordinary tool edge reaches the row through the host's own truth rather than
|
|
539
|
+
by re-arming it. A settle recovered this way is not an observed turn, so it
|
|
540
|
+
mints no `gentle_done_v1` and sends no finish notification.
|
|
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
|
|
545
|
+
back stops counting, so it cannot pin the native report at `working`.
|
|
473
546
|
- Session-change tokens are refreshed/cleared from the current Gentle Shell
|
|
474
547
|
session model every beat and never carried across sessions: zero changed
|
|
475
548
|
files publishes a clear (null over socket metadata, `--clear-token <name>`
|
|
@@ -498,8 +571,9 @@ gate for the working-vs-idle decision — never rendered as a count),
|
|
|
498
571
|
`gentle_pending_v1` (blocking-delegate role marker + freshness gate for the
|
|
499
572
|
in-flight synchronous launch — renders the child's role word while the
|
|
500
573
|
principal's own turn is blocked on it),
|
|
501
|
-
`gentle_done_v1` (synthesized finish signal + its own
|
|
502
|
-
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),
|
|
503
577
|
`gentle_error_v1` (durable run-error signal + freshness gate for the `error`
|
|
504
578
|
display — repairs a missed `error:` label edge, §4.3),
|
|
505
579
|
`gentle_roles_v1` (authoritative activity roles,
|
|
@@ -532,17 +606,20 @@ blockingRole := fresh gentle_pending_v1 (session-bound, TTL-fresh) whose
|
|
|
532
606
|
principalWorking := fresh gentle_principal_v1 (session-bound, TTL-fresh) —
|
|
533
607
|
the principal's OWN activity, never the delegate count and
|
|
534
608
|
never the aggregate native status (which reads working for
|
|
535
|
-
any running delegate or pending launch); renders
|
|
536
|
-
`orchestrating`
|
|
537
|
-
|
|
609
|
+
any running delegate or pending launch); renders the pink
|
|
610
|
+
`gentle` (machine key `orchestrating`) with or without a
|
|
611
|
+
fresh gentle_orchestrating_v1; outranks every delegate role
|
|
538
612
|
word; stale, foreign, or absent falls through to the
|
|
539
613
|
branches below
|
|
540
614
|
role := gentle_work_v1 fresh AND gentle_roles_v1 yields a
|
|
541
615
|
recognized role (oldest first, incl. the in-flight pending
|
|
542
616
|
role hint at count = 0 for task-mode launches with no
|
|
543
617
|
TaskStore record yet) — the principal is not working, so the
|
|
544
|
-
delegate word wins
|
|
545
|
-
|
|
618
|
+
delegate word wins. A non-contemplated subagent renders on
|
|
619
|
+
the `working` display, whose label is that subagent's own
|
|
620
|
+
sanitized name (never `gentle`). Role and name labels append
|
|
621
|
+
the total when at least two delegates run. Tool-only review
|
|
622
|
+
has no suffix.
|
|
546
623
|
orchestrating := gentle_orchestrating_v1 fresh with no role word above
|
|
547
624
|
(root-only per §4.2: fresh while the main session actively
|
|
548
625
|
works, even with zero subagents, retaining running/queued-sub,
|
|
@@ -550,8 +627,11 @@ orchestrating := gentle_orchestrating_v1 fresh with no role word above
|
|
|
550
627
|
falls through to the
|
|
551
628
|
branches below; attention, terminal `done`/native-`blocked`,
|
|
552
629
|
a working principal, and role words stay higher)
|
|
553
|
-
|
|
554
|
-
|
|
630
|
+
generic := gentle_work_v1 fresh AND count > 0 with no role word —
|
|
631
|
+
renders the pink `gentle` (machine key `orchestrating`), the
|
|
632
|
+
principal session's generic status; a count = 0 beat asserts
|
|
633
|
+
no activity — it reaches `done` only through the terminal
|
|
634
|
+
gate, otherwise `idle`
|
|
555
635
|
done := (native done OR fresh gentle_done_v1) AND gentle_work_v1
|
|
556
636
|
fresh with count = 0 (no running delegates) AND no roles AND
|
|
557
637
|
no fresh gentle_orchestrating_v1 AND no fresh
|
|
@@ -560,12 +640,14 @@ done := (native done OR fresh gentle_done_v1) AND gentle_work_v1
|
|
|
560
640
|
marker still covers; a fresh marker, any roles, or a working
|
|
561
641
|
principal veto terminal (queued cover, pending-launch hint).
|
|
562
642
|
The producer's finish token is the reachable path (the host
|
|
563
|
-
never emits done);
|
|
564
|
-
|
|
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
|
|
565
647
|
idle := otherwise (native fallback; also all-gentle-tokens-missing-or-expired)
|
|
566
648
|
```
|
|
567
649
|
|
|
568
|
-
Priority: `error > ask > review > done > blockingRole > principal working > role > orchestrating >
|
|
650
|
+
Priority: `error > ask > review > done > blockingRole > principal working > role > orchestrating > generic > idle`.
|
|
569
651
|
`done` is matched before the principal/role branches in the reducer; it is
|
|
570
652
|
listed here below the activity branches only so its settled-and-empty
|
|
571
653
|
precondition reads together.
|
|
@@ -574,11 +656,15 @@ precondition reads together.
|
|
|
574
656
|
(error/ask/review) and the terminal `done` state always outrank principal
|
|
575
657
|
status and activity roles. Below them the principal's own activity decides,
|
|
576
658
|
never the delegate count and never the aggregate native status: a **working
|
|
577
|
-
principal** renders `gentle` (
|
|
578
|
-
|
|
579
|
-
|
|
659
|
+
principal** renders the pink `gentle` (machine key `orchestrating`, fresh
|
|
660
|
+
root marker or not) and outranks every delegate role word; an **idle
|
|
661
|
+
principal** shows the oldest running role word
|
|
580
662
|
(`explorer`, `worker`, `verify`, `judge`, or `rdd` when it is the oldest)
|
|
581
|
-
however many delegates run
|
|
663
|
+
however many delegates run, and falls back to that same pink `gentle` when a
|
|
664
|
+
running delegate has no resolvable name (that row is not idle: a delegate
|
|
665
|
+
runs). A live count-0 work token asserts no activity: it reaches `done` only
|
|
666
|
+
through the terminal gate above, otherwise `idle`, so `gentle` never renders
|
|
667
|
+
on an idle session. The one exception sits between them and is
|
|
582
668
|
evidence-based, never a precedence guess: while a **synchronous**
|
|
583
669
|
`subagent_run`/`subagent_continue` call is in flight the principal's own turn
|
|
584
670
|
is blocked on the child, so the fresh `gentle_pending_v1` role word decides
|
|
@@ -589,8 +675,8 @@ signal (it stays live while the principal is idle with queued or running
|
|
|
589
675
|
delegates), so it never outranks a role word. An in-flight attention `review`
|
|
590
676
|
(fresh `review:` label or durable `gentle_review_v1` token) overrides the
|
|
591
677
|
role list; a settled session renders `done` even against a stale-fresh
|
|
592
|
-
marker, and only after the
|
|
593
|
-
`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).
|
|
594
680
|
|
|
595
681
|
### 5.3 Publication (sidebar tokens)
|
|
596
682
|
|
|
@@ -606,10 +692,13 @@ marker, and only after the minted finish hold lapses does it recede to
|
|
|
606
692
|
The visible second row is structural, with no rules: the eleven
|
|
607
693
|
presence-encoded
|
|
608
694
|
`gentle_title_<working|orchestrating|explorer|worker|verify|judge|ask|review|error|done|idle>`
|
|
609
|
-
state tokens (state word only: `
|
|
695
|
+
state tokens (a state word only: `gentle` (pink, machine key
|
|
610
696
|
`orchestrating`) / `explorer` / `worker` /
|
|
611
|
-
`verify` / `judge` / `ask` / `blocked` / `done` / `idle` / `review
|
|
612
|
-
|
|
697
|
+
`verify` / `judge` / `ask` / `blocked` / `done` / `idle` / `review` — with
|
|
698
|
+
the one exception that the amber `working` cell carries a
|
|
699
|
+
non-contemplated subagent's own sanitized name, never the word `working`
|
|
700
|
+
and never `gentle`; role and name words carry a running-count suffix above
|
|
701
|
+
one).
|
|
613
702
|
Only the current display's title token carries a value; the rest are null.
|
|
614
703
|
Each state cell carries its state's semantic color as its base fg with
|
|
615
704
|
no rules — working/worker golden `#f9e2af`, orchestrating pink fuchsia
|
|
@@ -625,13 +714,17 @@ marker, and only after the minted finish hold lapses does it recede to
|
|
|
625
714
|
tokens plus the row-2 title and change-segment tokens to
|
|
626
715
|
the pi-only `rows_by_agent` override (E10); exact block wiring is
|
|
627
716
|
install configuration, not protocol.
|
|
628
|
-
- Label shapes: `gentle`
|
|
629
|
-
principal's own working
|
|
630
|
-
with or without
|
|
631
|
-
|
|
632
|
-
|
|
633
|
-
root-session marker
|
|
634
|
-
|
|
717
|
+
- Label shapes: exactly one `gentle` — pink `#f5c2e7`, machine key
|
|
718
|
+
`orchestrating`: the principal session's own working status (asserted by a
|
|
719
|
+
fresh `gentle_principal_v1`, with or without a fresh root marker and with
|
|
720
|
+
or without delegated roles) and its generic status (a positive running
|
|
721
|
+
count with no resolvable name, only unsalvageable role shapes, or a fresh
|
|
722
|
+
root-session marker covering queued/running subs and pending launches);
|
|
723
|
+
never rendered on an idle session | the amber `working` cell (`#f9e2af`)
|
|
724
|
+
carries a non-contemplated subagent's own sanitized name from
|
|
725
|
+
`gentle_roles_v1` / `gentle_pending_v1` — never the word `working` and
|
|
726
|
+
never `gentle`, so a bare `working` display fails closed to the pink
|
|
727
|
+
`gentle` | `explorer` / `worker` / `verify` / `judge` (oldest
|
|
635
728
|
TaskStore role word while the principal itself is idle, however many
|
|
636
729
|
delegates run) | `ask` | `rdd` (user-facing word for the `review`
|
|
637
730
|
machine key; a delegated rdd and a tool-only review both render `rdd` —
|
|
@@ -782,7 +875,9 @@ gentle-ai concern and explicitly out of scope for this plugin.
|
|
|
782
875
|
next landed beat resets the counter. The one real error leg — the run
|
|
783
876
|
itself stopping on an error — is released by the next non-error beat
|
|
784
877
|
(`agent_start`, any tool activity, or a non-error assistant message), never
|
|
785
|
-
latched; no exception path ever stops the producer beat
|
|
878
|
+
latched; no exception path ever stops the producer beat (a quiet producer
|
|
879
|
+
with no host truth and no work evidence ends its own bounded budget instead,
|
|
880
|
+
§4.5). While the leg
|
|
786
881
|
stands it publishes the durable `gentle_error_v1` token on every beat, so
|
|
787
882
|
an error the sidebar missed on one beat is repaired by the next, and the
|
|
788
883
|
release beat clears it (the missed-beat discipline of the ask/review
|
|
@@ -881,7 +976,7 @@ report after a Pi restart or `/new` (both recreate the extension runtime)
|
|
|
881
976
|
lose, freezing the pane's `agent_session` binding at the old session while
|
|
882
977
|
the producer keeps beating for the new one — the consumer then rejects those
|
|
883
978
|
fresh tokens as a session-hash mismatch and the pane stays on `idle` until a
|
|
884
|
-
report with a higher seq lands. Parity contract: `working` carries the specific working role in the message (oldest running role word from the same roles resolution — known short word, unknown sanitized name, or `gentle` with no delegation; never bare generic `working`; machine keys unchanged); terminal `idle` only on a truly empty settle (principal settled plus zero running/queued plus zero pending plus zero live background jobs plus no human-wait prompt; settle-with-delegates/pending/jobs stays `working`, emitted once with no re-emit on repeat settles). Live background jobs come from Gentle Shell's own bus event `gentle-ai:jobs-sidebar` (`bash_background` / `monitor`), session-scoped and emitted on job edges only, so a snapshot counts only while it is fresh — a stale or foreign snapshot is zero jobs; an absent Gentle Shell simply reports none (today's behavior). Only an entry with no `status` is pending work: Gentle Shell keeps a finished job in the array as a result tail (`status: exited|stopped|failed`), and counting that tail is what pinned the row on the pink generic `gentle` — and blocked `done` — while the panel read no running job. One `unref()`-ed timer per live snapshot publishes a single beat at the instant the snapshot goes stale, so a missed exit event cannot leave the settle without a beat. While such a job waits with the principal settled and no delegate running or launching, the producer keeps the root marker live so the row stays on the pink generic `gentle` (§5.2) and the finish is held back; the wait ends on the beat the principal resumes, a delegate starts, the last job ends, or the snapshot ages past its staleness bound. `blocked` only for an actual human-wait intervention leg with its label (review/RDD execution stays `working`, silent); an error never claims native `blocked` — while our `error:` label stands the pane reports `working`, the only native state that raises no host attention, and returns to the lifecycle state on the next non-error beat. The native status keeps its aggregate meaning (it reads `working` while any delegate runs, which is what Herdr's own pane state means): the sidebar row's working-vs-idle decision reads the principal-only `gentle_principal_v1` instead (§5.2), so an idle principal with a running delegate shows
|
|
979
|
+
report with a higher seq lands. Parity contract: `working` carries the specific working role in the message (oldest running role word from the same roles resolution — known short word, unknown sanitized name, or the pink generic `gentle` with no delegation; never bare generic `working`; machine keys unchanged); terminal `idle` only on a truly empty settle (principal settled plus zero running/queued plus zero pending plus zero live background jobs plus no human-wait prompt; settle-with-delegates/pending/jobs stays `working`, emitted once with no re-emit on repeat settles). A settle the producer missed is recovered from the host's own live truth: a beat with nothing active and no work evidence reconciles `settled` from `isIdle()`, a quiet producer the host never answers stops beating after a bounded budget instead of republishing a count-0 work token forever, and only an observed turn mints `done`, so a reconciled settle announces nothing. Live background jobs come from Gentle Shell's own bus event `gentle-ai:jobs-sidebar` (`bash_background` / `monitor`), session-scoped and emitted on job edges only, so a snapshot counts only while it is fresh — a stale or foreign snapshot is zero jobs; an absent Gentle Shell simply reports none (today's behavior). Only an entry with no `status` is pending work: Gentle Shell keeps a finished job in the array as a result tail (`status: exited|stopped|failed`), and counting that tail is what pinned the row on the pink generic `gentle` — and blocked `done` — while the panel read no running job. One `unref()`-ed timer per live snapshot publishes a single beat at the instant the snapshot goes stale, so a missed exit event cannot leave the settle without a beat. While such a job waits with the principal settled and no delegate running or launching, the producer keeps the root marker live so the row stays on the pink generic `gentle` (§5.2) and the finish is held back; the wait ends on the beat the principal resumes, a delegate starts, the last job ends, or the snapshot ages past its staleness bound. `blocked` only for an actual human-wait intervention leg with its label (review/RDD execution stays `working`, silent); an error never claims native `blocked` — while our `error:` label stands the pane reports `working`, the only native state that raises no host attention, and returns to the lifecycle state on the next non-error beat. The native status keeps its aggregate meaning (it reads `working` while any delegate runs, which is what Herdr's own pane state means): the sidebar row's working-vs-idle decision reads the principal-only `gentle_principal_v1` instead (§5.2), so an idle principal with a running delegate shows that delegate's own role word or name rather than the principal's `gentle`. Single publisher by design: the managed native extension file is excluded
|
|
885
980
|
reversibly (`-extensions/herdr-agent-state.ts` in Pi settings, bytes
|
|
886
981
|
preserved on disk, never auto-loaded next to ours). `node
|
|
887
982
|
bin/gentle-sidebar.js (enable|disable|status|toggle)` selects the
|
|
@@ -1022,9 +1117,11 @@ exactly one mechanism writes each piece of state.
|
|
|
1022
1117
|
marker, read from local git plus `agent.list` — plus the presence prefix,
|
|
1023
1118
|
because Herdr emits no event for either. That is why the fast cycle is armed
|
|
1024
1119
|
by a rendered non-idle display, and why polling is never removed.
|
|
1025
|
-
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
|
|
1026
1122
|
the panes just rendered (never below the 250 ms floor), so a held `done`
|
|
1027
|
-
row reaches `idle` when the
|
|
1123
|
+
row reaches `idle` when the cap or the dwell lapses rather than up to one
|
|
1124
|
+
poll later.
|
|
1028
1125
|
A pending expiry may only SHORTEN the delay: with no pending expiry the
|
|
1029
1126
|
delay is exactly the adaptive value above, and an already-expired or
|
|
1030
1127
|
unparseable value falls to the floor (fail closed, like every parser)
|
|
@@ -1054,7 +1151,10 @@ exactly one mechanism writes each piece of state.
|
|
|
1054
1151
|
user-facing value is `blocked` (§5.3). `gentle_title_review` likewise
|
|
1055
1152
|
keeps its machine-key-derived token name; only its user-facing value is
|
|
1056
1153
|
now `rdd` (aligned from `review` by the native-owner T1). `gentle_title_orchestrating` likewise keeps its machine-key-derived
|
|
1057
|
-
token name; only its user-facing value is `gentle`.
|
|
1154
|
+
token name; only its user-facing value is `gentle`. `gentle_title_working`
|
|
1155
|
+
likewise keeps its machine-key-derived token name; its user-facing value is
|
|
1156
|
+
a non-contemplated subagent's own sanitized name, never the word `working`.
|
|
1157
|
+
The retired `*_working_subs` token family (the old `working (n)`
|
|
1058
1158
|
count display) is swept, never written.
|
|
1059
1159
|
- Coexistence: `herdr-pi-tree` stays installed but disabled for gentle-owned
|
|
1060
1160
|
panes (O1). No uninstall, no token migration, no dual-run merge — ownership
|