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 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, a pending launch, or a live job — none of which say the
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 or pending-launch coverage;
313
- ; null (clear) once the main session settles
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 / live job = working)
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, pending launch, or live job); renders
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
- or pending-launch coverage; absent/stale falls through to the
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 > job > done > principal working > role > orchestrating > working(main) > idle`.
516
- `job` is matched before `done` (a pending job is unfinished work) and both are
517
- matched before the principal/role branches in the reducer; they are listed here
518
- below the activity branches only so their settled-and-empty preconditions read
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. The pending-job `job` wait sits just above the
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 twelve
526
+ The visible second row is structural, with no rules: the eleven
551
527
  presence-encoded
552
- `gentle_title_<working|orchestrating|job|explorer|worker|verify|judge|ask|review|error|done|idle>`
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`) / `job` / `explorer` / `worker` /
530
+ `orchestrating`) / `explorer` / `worker` /
555
531
  `verify` / `judge` / `ask` / `blocked` / `done` / `idle` / `review`;
556
- role words carry a running-count suffix above one, and the `job` word carries
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`, job the same pink fuchsia `#f5c2e7` (a second pink wait state,
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) | `job` (the
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 twelve title cells (each its own color
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 twelve `gentle_title_*` state cells plus the three
616
- change-segment cells (15 cells: 12 state + 3 changes), each row within
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 publishes the pending count as `gentle_jobs_v1` so the sidebar shows the pink `job` wait (§5.2); the count clears on the beat the principal resumes, a delegate starts, or the last job ends. `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
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 12 tokens per beat (including the retired-token clear) (`gentle_work_v1`,
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
- `gentle_jobs_v1`, `gentle_ask_v1`, `gentle_review_v1`, `gentle_changes_v2`,
808
- `gentle_changes_v1`) and the daemon publishes its 78-token owned family
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 12 `gentle_heading_*` compat
811
- family stays published but wired into no visible row. Row 2 wires 12
812
- title + 3 change cells = 15 — each within the per-row ceiling). Names are
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, the job label the
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` and `job` displays alongside the original ten), plus display-only
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 = "$gentle_title_job", 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" }]]
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, pending launch, or
245
- live job — so neither can say the principal works): the dedicated
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
- // Pending background-job count (DESIGN §4.3, S5/D4): the same
710
- // `<hash>:<count>:<expiry>` shape as gentle_work_v1, but carrying the number of
711
- // live `bash_background` / `monitor` jobs from Gentle Shell's own snapshot and
712
- // published ONLY while the session is purely waiting for them — the principal
713
- // settled, no delegate running, no launch pending — so the sidebar can show the
714
- // pink `job` state instead of generic activity. Cleared on the next beat once
715
- // the principal resumes, a delegate starts, or the last job ends.
716
- const JOBS_TOKEN = "gentle_jobs_v1";
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 }] } }`. A live job
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 || jobCount > 0 || reviewActive) {
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`), from
2539
- // the bus snapshot. Session-scoped: a snapshot owned by another session
2540
- // never counts here.
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 runningJobCount() {
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
- // sidebar and the native report follow it, and keep the beat alive while
2561
- // jobs run (the marker has its own TTL).
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
- // whose runtime has no event bus simply never see it (jobs stay at zero,
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; null (clear) once
3028
- // the main session settles (or any non-root session) so a settled
3029
- // session never retains it. Carries no count and never alters the work
3030
- // total or the roles CSV — the consumer reduces a fresh marker to the
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 || runningJobCount() > 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/job state. A session that never
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
- runningJobCount() > 0 ||
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
- runningJobCount() > 0 ||
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
- await sendRequestAttempt(
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.1.0",
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",