herdr-gentle-shell 1.1.0 → 1.2.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 +33 -64
- package/README.md +3 -3
- package/extensions/gentle-herdr-state.ts +61 -69
- package/package.json +1 -1
package/DESIGN.md
CHANGED
|
@@ -275,7 +275,7 @@ active (`agentActive`) and clears it (null) the moment the principal
|
|
|
275
275
|
settles, keeping the same binding/TTL discipline. This is the principal-only
|
|
276
276
|
signal: it carries exactly the principal input of `computeNativeState`, never
|
|
277
277
|
the delegate aggregate, because the native status answers `working` for a
|
|
278
|
-
running delegate
|
|
278
|
+
running delegate or a pending launch — neither of which says the
|
|
279
279
|
principal itself works. The native status keeps that aggregate meaning for
|
|
280
280
|
Herdr's own pane state; the row's working-vs-idle decision reads only
|
|
281
281
|
`gentle_principal_v1` (§5.2). It carries no count and alters neither the work
|
|
@@ -309,8 +309,9 @@ gentle_roles_v1 = role *("," role) ; total <= 512 UTF-8 bytes; null (cle
|
|
|
309
309
|
gentle_orchestrating_v1 = sessionHash ":" expiry
|
|
310
310
|
; root-only presence marker, no count — fresh while the
|
|
311
311
|
; root main session actively works (even with zero subs),
|
|
312
|
-
; retaining running/queued-sub
|
|
313
|
-
; null (clear) once the main
|
|
312
|
+
; retaining running/queued-sub, pending-launch, or live
|
|
313
|
+
; background-job coverage; null (clear) once the main
|
|
314
|
+
; session settles
|
|
314
315
|
gentle_principal_v1 = sessionHash ":" expiry
|
|
315
316
|
; principal-only activity marker, no count — fresh while
|
|
316
317
|
; the principal session's own agent is active
|
|
@@ -318,7 +319,7 @@ gentle_principal_v1 = sessionHash ":" expiry
|
|
|
318
319
|
; never its delegate aggregate), null (clear) once the
|
|
319
320
|
; principal settles; decides working vs idle in §5.2
|
|
320
321
|
; while the native status keeps its aggregate meaning
|
|
321
|
-
; (running delegate / pending launch
|
|
322
|
+
; (running delegate / pending launch = working)
|
|
322
323
|
gentle_done_v1 = sessionHash ":" expiry
|
|
323
324
|
; synthesized finish signal, no count — minted ONCE at the
|
|
324
325
|
; settled-and-empty edge (principal settled, zero
|
|
@@ -332,16 +333,6 @@ gentle_done_v1 = sessionHash ":" expiry
|
|
|
332
333
|
; now+300000 at read (the only token whose ceiling is not
|
|
333
334
|
; the 60 s TTL). A session that never worked never mints
|
|
334
335
|
; one.
|
|
335
|
-
gentle_jobs_v1 = sessionHash ":" count ":" expiry
|
|
336
|
-
; pending background-job count (bash_background /
|
|
337
|
-
; monitor) from Gentle Shell's own session-scoped bus
|
|
338
|
-
; snapshot, session-bound + TTL-fresh like gentle_work_v1;
|
|
339
|
-
; emitted ONLY while the session is purely waiting on those
|
|
340
|
-
; jobs — principal settled, no running/queued delegate, no
|
|
341
|
-
; pending launch — and null (clear) the beat the principal
|
|
342
|
-
; resumes, a delegate starts, or the last job ends. Never
|
|
343
|
-
; a delegate count and never a finish: a settled session
|
|
344
|
-
; with a job pending is unfinished work.
|
|
345
336
|
gentle_ask_v1 = sessionHash ":" intentId ":" expiry
|
|
346
337
|
; durable ask signal, session-bound + TTL-fresh like
|
|
347
338
|
; gentle_orchestrating_v1 — emitted on every beat while
|
|
@@ -449,9 +440,6 @@ count), `gentle_principal_v1` (principal-only activity marker + freshness
|
|
|
449
440
|
gate for the working-vs-idle decision — never rendered as a count),
|
|
450
441
|
`gentle_done_v1` (synthesized finish signal + its own hold freshness gate
|
|
451
442
|
for the reachable `done` display — the host never reports `done`, §4.3),
|
|
452
|
-
`gentle_jobs_v1` (pending background-job count + freshness gate for the pink
|
|
453
|
-
`job` wait — published only while the principal is settled with no delegate
|
|
454
|
-
running or launching, §4.3),
|
|
455
443
|
`gentle_roles_v1` (authoritative activity roles,
|
|
456
444
|
oldest-first by immutable firstSeen), `gentle_names_v1` (compat transport only — never
|
|
457
445
|
rendered), `gentle_changes_v2` (normative; a
|
|
@@ -470,7 +458,7 @@ review := herdr:blocked has review:* (fresh)
|
|
|
470
458
|
principalWorking := fresh gentle_principal_v1 (session-bound, TTL-fresh) —
|
|
471
459
|
the principal's OWN activity, never the delegate count and
|
|
472
460
|
never the aggregate native status (which reads working for
|
|
473
|
-
any running delegate
|
|
461
|
+
any running delegate or pending launch); renders
|
|
474
462
|
`orchestrating` while a fresh gentle_orchestrating_v1 is
|
|
475
463
|
live, otherwise working(main); outranks every delegate role
|
|
476
464
|
word; stale, foreign, or absent falls through to the
|
|
@@ -483,22 +471,13 @@ role := gentle_work_v1 fresh AND gentle_roles_v1 yields a
|
|
|
483
471
|
least two delegates run. Tool-only review has no suffix.
|
|
484
472
|
orchestrating := gentle_orchestrating_v1 fresh with no role word above
|
|
485
473
|
(root-only per §4.2: fresh while the main session actively
|
|
486
|
-
works, even with zero subagents, retaining running/queued-sub
|
|
487
|
-
|
|
474
|
+
works, even with zero subagents, retaining running/queued-sub,
|
|
475
|
+
pending-launch, or live background-job coverage; absent/stale
|
|
476
|
+
falls through to the
|
|
488
477
|
branches below; attention, terminal `done`/native-`blocked`,
|
|
489
478
|
a working principal, and role words stay higher)
|
|
490
479
|
working(main) := gentle_work_v1 fresh AND count > 0 with no role word
|
|
491
480
|
OR (gentle_work_v1 fresh AND count = 0 AND agent not settled)
|
|
492
|
-
job := fresh `gentle_jobs_v1` with count > 0 AND `gentle_work_v1`
|
|
493
|
-
fresh with count = 0 (no running delegates) AND no roles AND
|
|
494
|
-
no fresh `gentle_principal_v1` — the principal settled with no
|
|
495
|
-
delegate running or launching while at least one background
|
|
496
|
-
job still waits. Evaluated BEFORE `done` (a finish with a job
|
|
497
|
-
pending is not finished) and below every attention state; a
|
|
498
|
-
fresh `gentle_orchestrating_v1` does not block it (the marker
|
|
499
|
-
stays live while the job runs). Any stale count, or a count
|
|
500
|
-
that arrives beside a working principal/role, is ignored
|
|
501
|
-
(fail closed).
|
|
502
481
|
done := (native done OR fresh gentle_done_v1) AND gentle_work_v1
|
|
503
482
|
fresh with count = 0 (no running delegates) AND no roles AND
|
|
504
483
|
no fresh gentle_orchestrating_v1 AND no fresh
|
|
@@ -512,17 +491,14 @@ done := (native done OR fresh gentle_done_v1) AND gentle_work_v1
|
|
|
512
491
|
idle := otherwise (native fallback; also all-gentle-tokens-missing-or-expired)
|
|
513
492
|
```
|
|
514
493
|
|
|
515
|
-
Priority: `error > ask > review >
|
|
516
|
-
`
|
|
517
|
-
|
|
518
|
-
|
|
519
|
-
together.
|
|
494
|
+
Priority: `error > ask > review > done > principal working > role > orchestrating > working(main) > idle`.
|
|
495
|
+
`done` is matched before the principal/role branches in the reducer; it is
|
|
496
|
+
listed here below the activity branches only so its settled-and-empty
|
|
497
|
+
precondition reads together.
|
|
520
498
|
`blocked` labels are namespaced, so simultaneous
|
|
521
499
|
`ask:` + `review:` resolves deterministically to `ask`. Attention states
|
|
522
500
|
(error/ask/review) and the terminal `done` state always outrank principal
|
|
523
|
-
status and activity roles.
|
|
524
|
-
terminal `done` and below every attention state and every live activity
|
|
525
|
-
signal. Below them the principal's own activity decides,
|
|
501
|
+
status and activity roles. Below them the principal's own activity decides,
|
|
526
502
|
never the delegate count and never the aggregate native status: a **working
|
|
527
503
|
principal** renders `gentle` (pink
|
|
528
504
|
`orchestrating` while a fresh root marker is live) and outranks every
|
|
@@ -547,19 +523,17 @@ marker, and only after the minted finish hold lapses does it recede to
|
|
|
547
523
|
custom `$gentle_heading_*` / `$gentle_project` / `$gentle_agent` cells
|
|
548
524
|
stay published and owned for compatibility but are wired into no visible
|
|
549
525
|
row. Deleted lines stay red and added lines stay green (never swapped).
|
|
550
|
-
The visible second row is structural, with no rules: the
|
|
526
|
+
The visible second row is structural, with no rules: the eleven
|
|
551
527
|
presence-encoded
|
|
552
|
-
`gentle_title_<working|orchestrating|
|
|
528
|
+
`gentle_title_<working|orchestrating|explorer|worker|verify|judge|ask|review|error|done|idle>`
|
|
553
529
|
state tokens (state word only: `working` / `gentle` (machine key
|
|
554
|
-
`orchestrating`) / `
|
|
530
|
+
`orchestrating`) / `explorer` / `worker` /
|
|
555
531
|
`verify` / `judge` / `ask` / `blocked` / `done` / `idle` / `review`;
|
|
556
|
-
role words carry a running-count suffix above one
|
|
557
|
-
the pending-job count the same way).
|
|
532
|
+
role words carry a running-count suffix above one).
|
|
558
533
|
Only the current display's title token carries a value; the rest are null.
|
|
559
534
|
Each state cell carries its state's semantic color as its base fg with
|
|
560
535
|
no rules — working/worker golden `#f9e2af`, orchestrating pink fuchsia
|
|
561
|
-
`#f5c2e7`,
|
|
562
|
-
distinct by wording from `gentle`), explorer blue `#89b4fa`, verify teal `#94e2d5`, judge purple
|
|
536
|
+
`#f5c2e7`, explorer blue `#89b4fa`, verify teal `#94e2d5`, judge purple
|
|
563
537
|
`#cba6f7` (distinct from explorer blue, verify teal, orchestrating pink),
|
|
564
538
|
ask orange `#fab387`, blocked red `#f38ba8`, done green `#a6e3a1`,
|
|
565
539
|
idle grey `#7c7f93` (recedes), review blue `#89b4fa` (same as
|
|
@@ -577,11 +551,7 @@ marker, and only after the minted finish hold lapses does it recede to
|
|
|
577
551
|
unsalvageable role shapes) |
|
|
578
552
|
`gentle` (user-facing word for the `orchestrating` machine key — fresh
|
|
579
553
|
root-session marker while the principal works, with or without active
|
|
580
|
-
delegation, even with zero subagents; pink palette unchanged) | `
|
|
581
|
-
pending background-job wait: principal settled, no delegate running or
|
|
582
|
-
launching, at least one `bash_background` / `monitor` job still live; pink,
|
|
583
|
-
with the pending total in parentheses above one; gone the beat the principal
|
|
584
|
-
resumes or a delegate starts) | `explorer` / `worker` / `verify` / `judge` (oldest
|
|
554
|
+
delegation, even with zero subagents; pink palette unchanged) | `explorer` / `worker` / `verify` / `judge` (oldest
|
|
585
555
|
TaskStore role word while the principal itself is idle, however many
|
|
586
556
|
delegates run) | `ask` | `rdd` (user-facing word for the `review`
|
|
587
557
|
machine key; a delegated rdd and a tool-only review both render `rdd` —
|
|
@@ -592,7 +562,7 @@ marker, and only after the minted finish hold lapses does it recede to
|
|
|
592
562
|
running delegates keeps the role word) | `idle`. Role labels append the
|
|
593
563
|
total count when at least two delegates run.
|
|
594
564
|
- Row-2 changes: the nonempty `+N`/`-N`/`↑N` segments ride as their own
|
|
595
|
-
structural row-2 cells after the
|
|
565
|
+
structural row-2 cells after the eleven title cells (each its own color
|
|
596
566
|
cell with no rules — added green, deleted red, pull blue, never
|
|
597
567
|
swapped; empty segments collapse so nothing renders). `+N`/`-N` come
|
|
598
568
|
from fresh `gentle_changes_v2`
|
|
@@ -612,8 +582,8 @@ marker, and only after the minted finish hold lapses does it recede to
|
|
|
612
582
|
badge is never emitted (see the §4.3 versioning rule).
|
|
613
583
|
- Placement: exactly two pi-only rows — row 1 the native `state_icon` +
|
|
614
584
|
`workspace` + `agent` strings (3 cells, no custom wiring, no plugin
|
|
615
|
-
colors), row 2 the
|
|
616
|
-
change-segment cells (
|
|
585
|
+
colors), row 2 the eleven `gentle_title_*` state cells plus the three
|
|
586
|
+
change-segment cells (14 cells: 11 state + 3 changes), each row within
|
|
617
587
|
Herdr's 16-token per-row ceiling — with the
|
|
618
588
|
herdr-pi-tree palette (added green `#a6e3a1`,
|
|
619
589
|
removed red `#f38ba8`, pull blue `#89b4fa`, working golden `#f9e2af`, ask
|
|
@@ -732,7 +702,7 @@ report after a Pi restart or `/new` (both recreate the extension runtime)
|
|
|
732
702
|
lose, freezing the pane's `agent_session` binding at the old session while
|
|
733
703
|
the producer keeps beating for the new one — the consumer then rejects those
|
|
734
704
|
fresh tokens as a session-hash mismatch and the pane stays on `idle` until a
|
|
735
|
-
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; an absent Gentle Shell simply reports none (today's behavior). While such a job waits with the principal settled and no delegate running or launching, the producer
|
|
705
|
+
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). 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 a real principal-stopped error or an actual human-wait intervention leg with its label (review/RDD execution stays `working`, silent). 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 the delegate role word rather than `gentle`. Single publisher by design: the managed native extension file is excluded
|
|
736
706
|
reversibly (`-extensions/herdr-agent-state.ts` in Pi settings, bytes
|
|
737
707
|
preserved on disk, never auto-loaded next to ours). `node
|
|
738
708
|
bin/gentle-sidebar.js (enable|disable|status|toggle)` selects the
|
|
@@ -801,18 +771,18 @@ exactly one mechanism writes each piece of state.
|
|
|
801
771
|
## 8. Limits
|
|
802
772
|
|
|
803
773
|
- Token budget: ≤ 16 tokens per report per pane (E8 discipline); the
|
|
804
|
-
producer emits at most
|
|
774
|
+
producer emits at most 11 tokens per beat (including the retired
|
|
775
|
+
`gentle_subs_v1` clear) (`gentle_work_v1`,
|
|
805
776
|
`gentle_roles_v1`, `gentle_names_v1`,
|
|
806
777
|
`gentle_orchestrating_v1`, `gentle_principal_v1`, `gentle_done_v1`,
|
|
807
|
-
`
|
|
808
|
-
`gentle_changes_v1`) and the daemon publishes its
|
|
778
|
+
`gentle_ask_v1`, `gentle_review_v1`, `gentle_changes_v2`,
|
|
779
|
+
`gentle_changes_v1`) and the daemon publishes its 72-token owned family
|
|
809
780
|
chunked ≤ 16 per report (row 1 is the 3 native tokens
|
|
810
|
-
`state_icon`/`workspace`/`agent`; the legacy
|
|
811
|
-
family stays published but wired into no visible row. Row 2 wires
|
|
812
|
-
title + 3 change cells =
|
|
781
|
+
`state_icon`/`workspace`/`agent`; the legacy 11 `gentle_heading_*` compat
|
|
782
|
+
family stays published but wired into no visible row. Row 2 wires 11
|
|
783
|
+
title + 3 change cells = 14 — each within the per-row ceiling). Names are
|
|
813
784
|
advisory; roles are authoritative for display and role labels carry the
|
|
814
|
-
running total as a suffix when at least two delegates run
|
|
815
|
-
pending-job total the same way.
|
|
785
|
+
running total as a suffix when at least two delegates run.
|
|
816
786
|
- TTL: `expiry <= now + 60000` at write; readers use `now` at read.
|
|
817
787
|
Clock skew assumption ≤ 5 s (documented; not compensated).
|
|
818
788
|
- Field bounds: `count` ≤ 16 digits; `label` ≤ 64 chars; names/roles
|
|
@@ -839,12 +809,11 @@ exactly one mechanism writes each piece of state.
|
|
|
839
809
|
- Additive only in v1: new token names (`gentle_work_v1`,
|
|
840
810
|
`gentle_roles_v1`, `gentle_names_v1`,
|
|
841
811
|
`gentle_orchestrating_v1`, `gentle_principal_v1`, `gentle_done_v1`,
|
|
842
|
-
`gentle_jobs_v1`,
|
|
843
812
|
`gentle_ask_v1`, `gentle_review_v1`, `gentle_changes_v1`, `gentle_changes_v2`,
|
|
844
813
|
`gentle_state_*`, `gentle_title_*`, `gentle_agent_*`, `gentle_agent`,
|
|
845
814
|
`gentle_icon_*`,
|
|
846
815
|
`gentle_heading_*`, `gentle_project`, `gentle_row_*` (each family now
|
|
847
|
-
includes the `judge`
|
|
816
|
+
includes the `judge` display alongside the original ten), plus display-only
|
|
848
817
|
`gentle_changes_added`, `gentle_changes_deleted`,
|
|
849
818
|
`gentle_changes_pull`, `gentle_changes_summary`); no change to `pi_subagents_work_v1`, `state_*`,
|
|
850
819
|
`title_*`, or native `working`/`blocked`/`idle` semantics.
|
package/README.md
CHANGED
|
@@ -222,7 +222,7 @@ acceptable. Row 1 holds 3 native cells and row 2 holds 14 cells (11 state
|
|
|
222
222
|
# row 1 native state_icon + workspace + agent, row 2 state word + changes.
|
|
223
223
|
# The parent [ui.sidebar.agents] table is user-owned and never touched here.
|
|
224
224
|
[ui.sidebar.agents.rows_by_agent]
|
|
225
|
-
pi = [["state_icon", "workspace", "agent"], [{ token = "$gentle_title_working", fg = "#f9e2af" }, { token = "$gentle_title_orchestrating", fg = "#f5c2e7" }, { token = "$
|
|
225
|
+
pi = [["state_icon", "workspace", "agent"], [{ token = "$gentle_title_working", fg = "#f9e2af" }, { token = "$gentle_title_orchestrating", fg = "#f5c2e7" }, { token = "$gentle_title_explorer", fg = "#89b4fa" }, { token = "$gentle_title_worker", fg = "#f9e2af" }, { token = "$gentle_title_verify", fg = "#94e2d5" }, { token = "$gentle_title_judge", fg = "#cba6f7" }, { token = "$gentle_title_ask", fg = "#fab387" }, { token = "$gentle_title_review", fg = "#89b4fa" }, { token = "$gentle_title_error", fg = "#f38ba8" }, { token = "$gentle_title_done", fg = "#a6e3a1" }, { token = "$gentle_title_idle", fg = "#7c7f93" }, { token = "$gentle_changes_added", fg = "#a6e3a1" }, { token = "$gentle_changes_deleted", fg = "#f38ba8" }, { token = "$gentle_changes_pull", fg = "#89b4fa" }]]
|
|
226
226
|
# END herdr-gentle-agents
|
|
227
227
|
```
|
|
228
228
|
|
|
@@ -241,8 +241,8 @@ renders for generic activity (machine key `working`): the main agent when settle
|
|
|
241
241
|
retaining running-subagent or pending-launch coverage. The principal's own
|
|
242
242
|
activity decides the row, never the delegate count and never Herdr's
|
|
243
243
|
aggregate native status (the work token counts running delegates, and the
|
|
244
|
-
native status reads `working` for any running delegate
|
|
245
|
-
|
|
244
|
+
native status reads `working` for any running delegate or pending launch — so
|
|
245
|
+
neither can say the principal works): the dedicated
|
|
246
246
|
`gentle_principal_v1` marker is published while the principal session itself
|
|
247
247
|
works and cleared when it settles. A **working principal** reads `gentle` —
|
|
248
248
|
pink
|
|
@@ -706,14 +706,17 @@ const DONE_HOLD_MS = 60000;
|
|
|
706
706
|
const DONE_HOLD_MIN_MS = 1000;
|
|
707
707
|
export const DONE_HOLD_MAX_MS = 300000;
|
|
708
708
|
const DONE_HOLD_ENV = "GENTLE_HERDR_DONE_HOLD_MS";
|
|
709
|
-
//
|
|
710
|
-
//
|
|
711
|
-
//
|
|
712
|
-
//
|
|
713
|
-
//
|
|
714
|
-
//
|
|
715
|
-
//
|
|
716
|
-
|
|
709
|
+
// Staleness bound for the background-job snapshot. Gentle Shell emits
|
|
710
|
+
// `gentle-ai:jobs-sidebar` on job EDGES only — start, monitor line batch, stop,
|
|
711
|
+
// exit, session shutdown (`refreshJobStatus` in extensions/gentle-agents.ts has
|
|
712
|
+
// no periodic caller) — so a silent `bash_background` job never refreshes it. A
|
|
713
|
+
// snapshot older than this bound therefore counts as ZERO jobs: fail OPEN.
|
|
714
|
+
// Finishing while a job silently runs is a nuisance; latching the session
|
|
715
|
+
// non-terminal on a snapshot that no longer describes the session is the
|
|
716
|
+
// incident this bound exists to prevent (odd/tasks/restore-done-idle.md). Five
|
|
717
|
+
// minutes is the generous end of the [30 s, 5 min] band: a job longer than this
|
|
718
|
+
// fails open early, and a missed exit event delays `done` by at most this long.
|
|
719
|
+
export const JOBS_SNAPSHOT_TTL_MS = 300000;
|
|
717
720
|
const MAX_TOKENS_PER_REPORT = 16;
|
|
718
721
|
const MAX_LABEL_CHARS = 64;
|
|
719
722
|
// Herdr's wire ceiling for a single pane-metadata token value, measured in
|
|
@@ -738,9 +741,7 @@ const QUESTIONNAIRE_EVENT = "rpiv:ask-user:blocked";
|
|
|
738
741
|
const PERMISSION_EVENT = "pi-permission-system:permission-request";
|
|
739
742
|
// Gentle Shell's live background jobs (`bash_background` / `monitor`) are
|
|
740
743
|
// published on the Pi event bus, session-scoped and display-only:
|
|
741
|
-
// `{ sessionId, snapshot: { jobs: [{ id, label, startedAt }] } }`.
|
|
742
|
-
// is pending work exactly like a running delegate, so it must keep the
|
|
743
|
-
// session non-terminal.
|
|
744
|
+
// `{ sessionId, snapshot: { jobs: [{ id, label, startedAt }] } }`.
|
|
744
745
|
const JOBS_SIDEBAR_EVENT = "gentle-ai:jobs-sidebar";
|
|
745
746
|
// Neither `gentle-pi:review:blocked` (reserved hook: no producer exists) nor
|
|
746
747
|
// `gentle-ai:review-sidebar` snapshots (entry publishes fire before the
|
|
@@ -939,7 +940,7 @@ function sendRequestAttempt(request, timeoutMs) {
|
|
|
939
940
|
if (timeout) clearTimeout(timeout);
|
|
940
941
|
try {
|
|
941
942
|
socket.destroy();
|
|
942
|
-
} catch {}
|
|
943
|
+
} catch { /* best effort: a failure here is non-fatal */ }
|
|
943
944
|
resolve(delivered);
|
|
944
945
|
};
|
|
945
946
|
let socket;
|
|
@@ -1043,7 +1044,7 @@ function cliFallback(patch) {
|
|
|
1043
1044
|
const timer = setTimeout(() => {
|
|
1044
1045
|
try {
|
|
1045
1046
|
child.kill();
|
|
1046
|
-
} catch {}
|
|
1047
|
+
} catch { /* best effort: a failure here is non-fatal */ }
|
|
1047
1048
|
finish(false);
|
|
1048
1049
|
}, CLI_FALLBACK_TIMEOUT_MS);
|
|
1049
1050
|
if (timer.unref) timer.unref();
|
|
@@ -1093,25 +1094,16 @@ export function computeNativeState({
|
|
|
1093
1094
|
settled,
|
|
1094
1095
|
activeCount,
|
|
1095
1096
|
pendingCount,
|
|
1096
|
-
jobCount = 0,
|
|
1097
1097
|
askActive,
|
|
1098
1098
|
reviewActive,
|
|
1099
1099
|
hasError,
|
|
1100
1100
|
}) {
|
|
1101
1101
|
if (hasError) return "blocked";
|
|
1102
1102
|
if (askActive) return "blocked";
|
|
1103
|
-
if (agentActive || activeCount > 0 || pendingCount > 0 ||
|
|
1103
|
+
if (agentActive || activeCount > 0 || pendingCount > 0 || reviewActive) {
|
|
1104
1104
|
return "working";
|
|
1105
1105
|
}
|
|
1106
|
-
if (
|
|
1107
|
-
settled &&
|
|
1108
|
-
!agentActive &&
|
|
1109
|
-
activeCount === 0 &&
|
|
1110
|
-
pendingCount === 0 &&
|
|
1111
|
-
jobCount === 0 &&
|
|
1112
|
-
!askActive &&
|
|
1113
|
-
!reviewActive
|
|
1114
|
-
) {
|
|
1106
|
+
if (settled && !agentActive && activeCount === 0 && pendingCount === 0 && !askActive && !reviewActive) {
|
|
1115
1107
|
return "idle";
|
|
1116
1108
|
}
|
|
1117
1109
|
return undefined;
|
|
@@ -1420,7 +1412,7 @@ function liveRunGit(root, args) {
|
|
|
1420
1412
|
}
|
|
1421
1413
|
let stdout = "";
|
|
1422
1414
|
const timer = setTimeout(() => {
|
|
1423
|
-
try { child.kill(); } catch {}
|
|
1415
|
+
try { child.kill(); } catch { /* best effort: a failure here is non-fatal */ }
|
|
1424
1416
|
finish({ stdout, code: 1, error: `timed out after ${LIVE_GIT_TIMEOUT_MS}ms` });
|
|
1425
1417
|
}, LIVE_GIT_TIMEOUT_MS + 500);
|
|
1426
1418
|
if (timer.unref) timer.unref();
|
|
@@ -1675,7 +1667,7 @@ function moshiSendEnvelope(envelope) {
|
|
|
1675
1667
|
sock.on("error", () => {
|
|
1676
1668
|
try {
|
|
1677
1669
|
sock.destroy();
|
|
1678
|
-
} catch {}
|
|
1670
|
+
} catch { /* best effort: a failure here is non-fatal */ }
|
|
1679
1671
|
});
|
|
1680
1672
|
sock.once("connect", () => {
|
|
1681
1673
|
sock.write(`${JSON.stringify(envelope)}\n`);
|
|
@@ -1790,7 +1782,7 @@ function moshiSessionIsChild(file) {
|
|
|
1790
1782
|
} finally {
|
|
1791
1783
|
try {
|
|
1792
1784
|
fs.closeSync(fd);
|
|
1793
|
-
} catch {}
|
|
1785
|
+
} catch { /* best effort: a failure here is non-fatal */ }
|
|
1794
1786
|
}
|
|
1795
1787
|
moshiChildCache.set(file, child);
|
|
1796
1788
|
return child;
|
|
@@ -2151,7 +2143,7 @@ function writeSettingsDoc(path, doc) {
|
|
|
2151
2143
|
} catch (error) {
|
|
2152
2144
|
try {
|
|
2153
2145
|
fs.rmSync(temp, { force: true });
|
|
2154
|
-
} catch {}
|
|
2146
|
+
} catch { /* best effort: a failure here is non-fatal */ }
|
|
2155
2147
|
throw error;
|
|
2156
2148
|
}
|
|
2157
2149
|
}
|
|
@@ -2535,13 +2527,17 @@ export default function (pi) {
|
|
|
2535
2527
|
let moshiCtxRef;
|
|
2536
2528
|
let lastAskToolName;
|
|
2537
2529
|
|
|
2538
|
-
// Live background jobs (Gentle Shell `bash_background` / `monitor`)
|
|
2539
|
-
//
|
|
2540
|
-
//
|
|
2530
|
+
// Live background jobs (Gentle Shell `bash_background` / `monitor`) from the
|
|
2531
|
+
// bus snapshot: session-scoped, edge-emitted, and therefore a hint with a
|
|
2532
|
+
// freshness bound rather than proof. A live job is PENDING WORK — it holds
|
|
2533
|
+
// the finish mint and keeps the row on the pink generic `gentle` wait — but
|
|
2534
|
+
// it is never a display state of its own: no job count is published and no
|
|
2535
|
+
// `job` token exists to render (odd/tasks/restore-done-idle.md).
|
|
2541
2536
|
let jobsSnapshot;
|
|
2542
2537
|
|
|
2543
|
-
function
|
|
2538
|
+
function freshRunningJobCount() {
|
|
2544
2539
|
if (!jobsSnapshot) return 0;
|
|
2540
|
+
if (Date.now() - jobsSnapshot.at > JOBS_SNAPSHOT_TTL_MS) return 0;
|
|
2545
2541
|
const owner = jobsSnapshot.sessionId;
|
|
2546
2542
|
const mine = sessionId;
|
|
2547
2543
|
if (
|
|
@@ -2557,8 +2553,8 @@ export default function (pi) {
|
|
|
2557
2553
|
}
|
|
2558
2554
|
|
|
2559
2555
|
// A job starting or ending is a state change: publish immediately so the
|
|
2560
|
-
//
|
|
2561
|
-
//
|
|
2556
|
+
// `gentle` wait and the finish gate follow it. `at` is the arrival time the
|
|
2557
|
+
// freshness bound measures from.
|
|
2562
2558
|
function onJobsSnapshot(value) {
|
|
2563
2559
|
if (!isRecord(value) || !isRecord(value.snapshot) || !Array.isArray(value.snapshot.jobs)) return;
|
|
2564
2560
|
const jobs = value.snapshot.jobs.filter(
|
|
@@ -2567,14 +2563,14 @@ export default function (pi) {
|
|
|
2567
2563
|
jobsSnapshot = {
|
|
2568
2564
|
sessionId: typeof value.sessionId === "string" ? value.sessionId : undefined,
|
|
2569
2565
|
jobs,
|
|
2566
|
+
at: Date.now(),
|
|
2570
2567
|
};
|
|
2571
2568
|
schedulePublish();
|
|
2572
2569
|
}
|
|
2573
2570
|
|
|
2574
2571
|
// Subscribed before the `enabled()` guard would matter: the bus event is
|
|
2575
|
-
// session-scoped display data, so it is safe to observe anywhere. Hosts
|
|
2576
|
-
//
|
|
2577
|
-
// which is today's behavior).
|
|
2572
|
+
// session-scoped display data, so it is safe to observe anywhere. Hosts whose
|
|
2573
|
+
// runtime has no event bus never see it (jobs stay at zero).
|
|
2578
2574
|
if (typeof pi?.events?.on === "function") pi.events.on(JOBS_SIDEBAR_EVENT, onJobsSnapshot);
|
|
2579
2575
|
|
|
2580
2576
|
function moshiCapture(ctx) {
|
|
@@ -2718,7 +2714,7 @@ export default function (pi) {
|
|
|
2718
2714
|
try {
|
|
2719
2715
|
const cwd = ctx?.cwd;
|
|
2720
2716
|
if (typeof cwd === "string" && cwd.length > 0) sessionCwd = cwd;
|
|
2721
|
-
} catch {}
|
|
2717
|
+
} catch { /* best effort: a failure here is non-fatal */ }
|
|
2722
2718
|
try {
|
|
2723
2719
|
const file = ctx?.sessionManager?.getSessionFile?.();
|
|
2724
2720
|
if (typeof file === "string" && file.length > 0) {
|
|
@@ -2731,7 +2727,7 @@ export default function (pi) {
|
|
|
2731
2727
|
try {
|
|
2732
2728
|
const id = ctx?.sessionManager?.getSessionId?.();
|
|
2733
2729
|
if (typeof id === "string" && id.length > 0) sessionId = id;
|
|
2734
|
-
} catch {}
|
|
2730
|
+
} catch { /* best effort: a failure here is non-fatal */ }
|
|
2735
2731
|
}
|
|
2736
2732
|
|
|
2737
2733
|
function askActiveNow() {
|
|
@@ -2783,7 +2779,7 @@ export default function (pi) {
|
|
|
2783
2779
|
emittedLabel = undefined;
|
|
2784
2780
|
try {
|
|
2785
2781
|
pi.events.emit(BLOCKED_EVENT, { active: false });
|
|
2786
|
-
} catch {}
|
|
2782
|
+
} catch { /* best effort: a failure here is non-fatal */ }
|
|
2787
2783
|
}
|
|
2788
2784
|
return;
|
|
2789
2785
|
}
|
|
@@ -3024,14 +3020,17 @@ export default function (pi) {
|
|
|
3024
3020
|
// emitted by the root Pi session while the main session is actively
|
|
3025
3021
|
// working (agentActive, even with zero subagents), retaining coverage
|
|
3026
3022
|
// while an authoritative running|queued subagent exists or a
|
|
3027
|
-
// subagent_run/subagent_continue launch is pending
|
|
3028
|
-
//
|
|
3029
|
-
//
|
|
3030
|
-
//
|
|
3023
|
+
// subagent_run/subagent_continue launch is pending, or while a fresh
|
|
3024
|
+
// background-job snapshot shows a live job (the settled wait on a
|
|
3025
|
+
// `bash_background` / `monitor` job renders the same pink generic
|
|
3026
|
+
// `gentle`); null (clear) once the main session settles (or any non-root
|
|
3027
|
+
// session) so a settled session never retains it. Carries no count and
|
|
3028
|
+
// never alters the work total or the roles CSV — the consumer reduces a
|
|
3029
|
+
// fresh marker to the
|
|
3031
3030
|
// `orchestrating` display only when no recognized role is active (below
|
|
3032
3031
|
// attention, terminal `done`, and recognized roles; ahead of main
|
|
3033
3032
|
// `working`).
|
|
3034
|
-
if (rootSession && (agentActive || subs.length > 0 || pendingCalls.size > 0 ||
|
|
3033
|
+
if (rootSession && (agentActive || subs.length > 0 || pendingCalls.size > 0 || freshRunningJobCount() > 0)) {
|
|
3035
3034
|
tokens.gentle_orchestrating_v1 = `${sessionHash}:${expiry}`;
|
|
3036
3035
|
} else {
|
|
3037
3036
|
tokens.gentle_orchestrating_v1 = null;
|
|
@@ -3050,13 +3049,14 @@ export default function (pi) {
|
|
|
3050
3049
|
// launch, no live background job, and no human-wait, review, or error leg
|
|
3051
3050
|
// — then republished with the SAME expiry so the hold can never be
|
|
3052
3051
|
// extended. Any work appearing during the hold clears it on that beat, so
|
|
3053
|
-
// the row moves straight back to the role
|
|
3054
|
-
// worked never mints one.
|
|
3052
|
+
// the row moves straight back to the role state. A session that never
|
|
3053
|
+
// worked never mints one. A live background job counts as activity: the
|
|
3054
|
+
// finish waits while the session still waits on it.
|
|
3055
3055
|
const activity =
|
|
3056
3056
|
agentActive ||
|
|
3057
3057
|
subs.length > 0 ||
|
|
3058
3058
|
pendingCalls.size > 0 ||
|
|
3059
|
-
|
|
3059
|
+
freshRunningJobCount() > 0 ||
|
|
3060
3060
|
askActiveNow() ||
|
|
3061
3061
|
reviewActive ||
|
|
3062
3062
|
!!errorCode;
|
|
@@ -3079,19 +3079,6 @@ export default function (pi) {
|
|
|
3079
3079
|
donePending = false;
|
|
3080
3080
|
}
|
|
3081
3081
|
tokens[DONE_TOKEN] = doneExpiry === undefined ? null : `${sessionHash}:${doneExpiry}`;
|
|
3082
|
-
// Pending background jobs (S5/D4): display-only count, published only while
|
|
3083
|
-
// the session waits on them. `nativeSettledPending` is included because a
|
|
3084
|
-
// launch that was in flight when the principal settled has already left
|
|
3085
|
-
// `pendingCalls` — it is still pending work, never a job wait.
|
|
3086
|
-
const jobCount =
|
|
3087
|
-
!agentActive &&
|
|
3088
|
-
settled &&
|
|
3089
|
-
!nativeSettledPending &&
|
|
3090
|
-
subs.length === 0 &&
|
|
3091
|
-
pendingCalls.size === 0
|
|
3092
|
-
? runningJobCount()
|
|
3093
|
-
: 0;
|
|
3094
|
-
tokens[JOBS_TOKEN] = jobCount > 0 ? `${sessionHash}:${jobCount}:${expiry}` : null;
|
|
3095
3082
|
if (changes.files > 0) {
|
|
3096
3083
|
const files = String(changes.files);
|
|
3097
3084
|
const added = String(changes.added);
|
|
@@ -3123,12 +3110,15 @@ export default function (pi) {
|
|
|
3123
3110
|
// holds the beat the same way while its span is open. Effective
|
|
3124
3111
|
// review (executing acknowledged capture/group calls) keeps the beat
|
|
3125
3112
|
// alive so `review:` and the durable review token publish — NO GRACE:
|
|
3126
|
-
// the leg drops when the last execution ends or resolves.
|
|
3113
|
+
// the leg drops when the last execution ends or resolves. A live
|
|
3114
|
+
// background job keeps the beat alive too: that is what lets the wait end
|
|
3115
|
+
// on its own when the snapshot goes stale instead of the beat stopping
|
|
3116
|
+
// with the row still painted `gentle`.
|
|
3127
3117
|
return (
|
|
3128
3118
|
agentActive ||
|
|
3129
3119
|
activeSubs().length > 0 ||
|
|
3130
3120
|
pendingCalls.size > 0 ||
|
|
3131
|
-
|
|
3121
|
+
freshRunningJobCount() > 0 ||
|
|
3132
3122
|
askToolCalls.size > 0 ||
|
|
3133
3123
|
uiPromptActive ||
|
|
3134
3124
|
reviewActive ||
|
|
@@ -3170,7 +3160,6 @@ export default function (pi) {
|
|
|
3170
3160
|
settled,
|
|
3171
3161
|
activeCount: activeSubs().length,
|
|
3172
3162
|
pendingCount: pendingCalls.size + (nativeSettledPending ? 1 : 0),
|
|
3173
|
-
jobCount: runningJobCount(),
|
|
3174
3163
|
askActive: askActiveNow(),
|
|
3175
3164
|
reviewActive,
|
|
3176
3165
|
hasError: !!errorCode,
|
|
@@ -3237,7 +3226,9 @@ export default function (pi) {
|
|
|
3237
3226
|
params.session_start_source = sessionStartSource;
|
|
3238
3227
|
}
|
|
3239
3228
|
const base = `${SOURCE}:session:${seq}`;
|
|
3240
|
-
|
|
3229
|
+
// The result is deliberately discarded: this is the fire-and-forget
|
|
3230
|
+
// session binding, and `void` states that intent for the linter.
|
|
3231
|
+
void (await sendRequestAttempt(
|
|
3241
3232
|
{
|
|
3242
3233
|
id: `${base}:0:${randomUUID()}`,
|
|
3243
3234
|
method: "pane.report_agent_session",
|
|
@@ -3252,7 +3243,7 @@ export default function (pi) {
|
|
|
3252
3243
|
params,
|
|
3253
3244
|
},
|
|
3254
3245
|
1500,
|
|
3255
|
-
).catch(() => false));
|
|
3246
|
+
).catch(() => false)));
|
|
3256
3247
|
}
|
|
3257
3248
|
|
|
3258
3249
|
// Start the session binding without waiting for it (see
|
|
@@ -3496,7 +3487,7 @@ export default function (pi) {
|
|
|
3496
3487
|
const top = probe.stdout.trim();
|
|
3497
3488
|
if (top.length > 0) cwdRoot = top;
|
|
3498
3489
|
}
|
|
3499
|
-
} catch {}
|
|
3490
|
+
} catch { /* best effort: a failure here is non-fatal */ }
|
|
3500
3491
|
}
|
|
3501
3492
|
const roots = liveResolveScopeRoots(entries, sessionId, cwdRoot);
|
|
3502
3493
|
const summary = await liveSummarizeRoots(roots);
|
|
@@ -3535,6 +3526,7 @@ export default function (pi) {
|
|
|
3535
3526
|
doneExpiry = undefined;
|
|
3536
3527
|
donePending = false;
|
|
3537
3528
|
sawActivity = false;
|
|
3529
|
+
jobsSnapshot = undefined;
|
|
3538
3530
|
errorCode = undefined;
|
|
3539
3531
|
liveGen += 1;
|
|
3540
3532
|
liveInFlight = false;
|
|
@@ -3551,7 +3543,7 @@ export default function (pi) {
|
|
|
3551
3543
|
emittedLabel = undefined;
|
|
3552
3544
|
try {
|
|
3553
3545
|
pi.events.emit(BLOCKED_EVENT, { active: false });
|
|
3554
|
-
} catch {}
|
|
3546
|
+
} catch { /* best effort: a failure here is non-fatal */ }
|
|
3555
3547
|
}
|
|
3556
3548
|
|
|
3557
3549
|
// -- ask legs -------------------------------------------------------------
|
|
@@ -3984,7 +3976,7 @@ export default function (pi) {
|
|
|
3984
3976
|
emittedLabel = undefined;
|
|
3985
3977
|
try {
|
|
3986
3978
|
pi.events.emit(BLOCKED_EVENT, { active: false });
|
|
3987
|
-
} catch {}
|
|
3979
|
+
} catch { /* best effort: a failure here is non-fatal */ }
|
|
3988
3980
|
}
|
|
3989
3981
|
resetSessionState();
|
|
3990
3982
|
return moshiFlushSends(1000);
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "herdr-gentle-shell",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.2.0",
|
|
4
4
|
"description": "Pi package for Herdr sidebar states: the Pi extension sidecar that publishes session facts as Herdr pane-metadata tokens, the optional Moshi notification channel, and the Pi-side helpers the Herdr Gentle Shell plugin drives.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"pi-package",
|