herdr-gentle-shell 0.5.0 → 1.1.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
@@ -319,6 +319,29 @@ gentle_principal_v1 = sessionHash ":" expiry
319
319
  ; principal settles; decides working vs idle in §5.2
320
320
  ; while the native status keeps its aggregate meaning
321
321
  ; (running delegate / pending launch / live job = working)
322
+ gentle_done_v1 = sessionHash ":" expiry
323
+ ; synthesized finish signal, no count — minted ONCE at the
324
+ ; settled-and-empty edge (principal settled, zero
325
+ ; running/queued delegates, zero pending launches, zero
326
+ ; live background jobs, no ask/review/error leg), then
327
+ ; republished with the SAME expiry (never refreshed) until
328
+ ; it lapses; null (clear) whenever work reappears or the
329
+ ; session resets. Its expiry IS the done hold: default
330
+ ; 60 s, overridden by GENTLE_HERDR_DONE_HOLD_MS clamped to
331
+ ; [1000, 300000], and the consumer accepts no expiry beyond
332
+ ; now+300000 at read (the only token whose ceiling is not
333
+ ; the 60 s TTL). A session that never worked never mints
334
+ ; 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.
322
345
  gentle_ask_v1 = sessionHash ":" intentId ":" expiry
323
346
  ; durable ask signal, session-bound + TTL-fresh like
324
347
  ; gentle_orchestrating_v1 — emitted on every beat while
@@ -343,7 +366,9 @@ left it.
343
366
 
344
367
  Validation: consumers MUST reject tokens failing the grammar (wrong hash
345
368
  length, `expiry` in the past or `> now+60000` at read, non-numeric counts)
346
- and treat the pane as `unknown → idle` for that signal (§7).
369
+ and treat the pane as `unknown → idle` for that signal (§7). `gentle_done_v1`
370
+ is the one ceiling exception: it is validated against `now+300000` so an
371
+ overridden hold stays readable, and it still fails closed on a past expiry.
347
372
 
348
373
  ### 4.4 Examples
349
374
 
@@ -422,6 +447,11 @@ carry it as a suffix only when above one), `gentle_orchestrating_v1` (root-only
422
447
  + freshness gate for the `orchestrating` display — never rendered as a
423
448
  count), `gentle_principal_v1` (principal-only activity marker + freshness
424
449
  gate for the working-vs-idle decision — never rendered as a count),
450
+ `gentle_done_v1` (synthesized finish signal + its own hold freshness gate
451
+ 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),
425
455
  `gentle_roles_v1` (authoritative activity roles,
426
456
  oldest-first by immutable firstSeen), `gentle_names_v1` (compat transport only — never
427
457
  rendered), `gentle_changes_v2` (normative; a
@@ -459,20 +489,40 @@ orchestrating := gentle_orchestrating_v1 fresh with no role word above
459
489
  a working principal, and role words stay higher)
460
490
  working(main) := gentle_work_v1 fresh AND count > 0 with no role word
461
491
  OR (gentle_work_v1 fresh AND count = 0 AND agent not settled)
462
- done := native done AND gentle_work_v1 fresh with count = 0
463
- (no running delegates) AND no roles AND no fresh
464
- gentle_orchestrating_v1 — count 0 alone never implies
465
- empty, since the running-only count excludes queued subs
466
- the fresh marker still covers; a fresh marker or any roles
467
- veto terminal (queued cover, pending-launch hint)
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
+ done := (native done OR fresh gentle_done_v1) AND gentle_work_v1
503
+ fresh with count = 0 (no running delegates) AND no roles AND
504
+ no fresh gentle_orchestrating_v1 AND no fresh
505
+ gentle_principal_v1 — count 0 alone never implies empty,
506
+ since the running-only count excludes queued subs the fresh
507
+ marker still covers; a fresh marker, any roles, or a working
508
+ principal veto terminal (queued cover, pending-launch hint).
509
+ The producer's finish token is the reachable path (the host
510
+ never emits done); its expiry is the hold, so `done` recedes
511
+ to `idle` when it lapses and is never skipped in between
468
512
  idle := otherwise (native fallback; also all-gentle-tokens-missing-or-expired)
469
513
  ```
470
514
 
471
- Priority: `error > ask > review > done > principal working > role > orchestrating > working(main) > idle`.
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.
472
520
  `blocked` labels are namespaced, so simultaneous
473
521
  `ask:` + `review:` resolves deterministically to `ask`. Attention states
474
522
  (error/ask/review) and the terminal `done` state always outrank principal
475
- status and activity roles. Below them the principal's own activity decides,
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,
476
526
  never the delegate count and never the aggregate native status: a **working
477
527
  principal** renders `gentle` (pink
478
528
  `orchestrating` while a fresh root marker is live) and outranks every
@@ -483,7 +533,8 @@ signal (it stays live while the principal is idle with queued or running
483
533
  delegates), so it never outranks a role word. An in-flight attention `review`
484
534
  (fresh `review:` label or durable `gentle_review_v1` token) overrides the
485
535
  role list; a settled session renders `done` even against a stale-fresh
486
- marker.
536
+ marker, and only after the minted finish hold lapses does it recede to
537
+ `idle` (§4.3).
487
538
 
488
539
  ### 5.3 Publication (sidebar tokens)
489
540
 
@@ -496,17 +547,19 @@ marker.
496
547
  custom `$gentle_heading_*` / `$gentle_project` / `$gentle_agent` cells
497
548
  stay published and owned for compatibility but are wired into no visible
498
549
  row. Deleted lines stay red and added lines stay green (never swapped).
499
- The visible second row is structural, with no rules: the eleven
550
+ The visible second row is structural, with no rules: the twelve
500
551
  presence-encoded
501
- `gentle_title_<working|orchestrating|explorer|worker|verify|judge|ask|review|error|done|idle>`
552
+ `gentle_title_<working|orchestrating|job|explorer|worker|verify|judge|ask|review|error|done|idle>`
502
553
  state tokens (state word only: `working` / `gentle` (machine key
503
- `orchestrating`) / `explorer` / `worker` /
554
+ `orchestrating`) / `job` / `explorer` / `worker` /
504
555
  `verify` / `judge` / `ask` / `blocked` / `done` / `idle` / `review`;
505
- role words carry a running-count suffix above one).
556
+ role words carry a running-count suffix above one, and the `job` word carries
557
+ the pending-job count the same way).
506
558
  Only the current display's title token carries a value; the rest are null.
507
559
  Each state cell carries its state's semantic color as its base fg with
508
560
  no rules — working/worker golden `#f9e2af`, orchestrating pink fuchsia
509
- `#f5c2e7`, explorer blue `#89b4fa`, verify teal `#94e2d5`, judge purple
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
510
563
  `#cba6f7` (distinct from explorer blue, verify teal, orchestrating pink),
511
564
  ask orange `#fab387`, blocked red `#f38ba8`, done green `#a6e3a1`,
512
565
  idle grey `#7c7f93` (recedes), review blue `#89b4fa` (same as
@@ -524,7 +577,11 @@ marker.
524
577
  unsalvageable role shapes) |
525
578
  `gentle` (user-facing word for the `orchestrating` machine key — fresh
526
579
  root-session marker while the principal works, with or without active
527
- delegation, even with zero subagents; pink palette unchanged) | `explorer` / `worker` / `verify` / `judge` (oldest
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
528
585
  TaskStore role word while the principal itself is idle, however many
529
586
  delegates run) | `ask` | `rdd` (user-facing word for the `review`
530
587
  machine key; a delegated rdd and a tool-only review both render `rdd` —
@@ -535,7 +592,7 @@ marker.
535
592
  running delegates keeps the role word) | `idle`. Role labels append the
536
593
  total count when at least two delegates run.
537
594
  - Row-2 changes: the nonempty `+N`/`-N`/`↑N` segments ride as their own
538
- structural row-2 cells after the eleven title cells (each its own color
595
+ structural row-2 cells after the twelve title cells (each its own color
539
596
  cell with no rules — added green, deleted red, pull blue, never
540
597
  swapped; empty segments collapse so nothing renders). `+N`/`-N` come
541
598
  from fresh `gentle_changes_v2`
@@ -555,8 +612,8 @@ marker.
555
612
  badge is never emitted (see the §4.3 versioning rule).
556
613
  - Placement: exactly two pi-only rows — row 1 the native `state_icon` +
557
614
  `workspace` + `agent` strings (3 cells, no custom wiring, no plugin
558
- colors), row 2 the eleven `gentle_title_*` state cells plus the three
559
- change-segment cells (14 cells: 11 state + 3 changes), each row within
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
560
617
  Herdr's 16-token per-row ceiling — with the
561
618
  herdr-pi-tree palette (added green `#a6e3a1`,
562
619
  removed red `#f38ba8`, pull blue `#89b4fa`, working golden `#f9e2af`, ask
@@ -631,9 +688,11 @@ other two). All gentle signals stale/missing → `idle` (native fallback, O5).
631
688
  `intentId`, subtitle `Answer in terminal`, title `Gentle ask: <project>`,
632
689
  message `<project> has a question and is waiting for your answer. Return
633
690
  to Pi to respond.`) and
634
- `task_complete` once per real finish (the native transition into `idle`:
635
- settled plus zero running/queued plus zero pending plus zero live
636
- background jobs plus no human wait),
691
+ `task_complete` once per real finish (the synthesized `done` edge: the beat
692
+ that delivers a fresh minted `gentle_done_v1` — settled plus zero
693
+ running/queued plus zero pending plus zero live background jobs plus no
694
+ human wait — never a raw native `working → idle` transition, which fires
695
+ with work still left and skipped `done` entirely),
637
696
  never per prompt and never per turn. A `session.closed` (`session_ended`)
638
697
  envelope closes the row on shutdown, and the host-awaited handler flushes
639
698
  in-flight sends. `task_complete` carries title `Gentle finished: <project>`
@@ -673,7 +732,7 @@ report after a Pi restart or `/new` (both recreate the extension runtime)
673
732
  lose, freezing the pane's `agent_session` binding at the old session while
674
733
  the producer keeps beating for the new one — the consumer then rejects those
675
734
  fresh tokens as a session-hash mismatch and the pane stays on `idle` until a
676
- 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). `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
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
677
736
  reversibly (`-extensions/herdr-agent-state.ts` in Pi settings, bytes
678
737
  preserved on disk, never auto-loaded next to ours). `node
679
738
  bin/gentle-sidebar.js (enable|disable|status|toggle)` selects the
@@ -711,13 +770,25 @@ nothing:
711
770
 
712
771
  `/herdr-gentle:customize status` prints one read-only line; an unknown
713
772
  argument, Esc, or a cancelled menu writes nothing. With no argument the
714
- command opens the recovered floating two-pane panel
715
- (`lib/customize-panel.js`, painted through its own palette)
716
- over `ctx.ui.custom`: `←/→` or `Tab` moves between the category and value panes,
717
- `↑/↓` or `j/k` moves the cursor, `Enter` toggles the focused switch and `Esc`
718
- closes without a write. Each switch renders exactly one row that reads its
719
- stored state and carries the opposite value, so `Enter` is the whole toggle.
720
- An inconclusive sidebar verdict (`unknown`) renders as `Unknown` with a note
773
+ command opens the floating panel (`lib/customize-panel.js`, painted through its
774
+ own palette) over `ctx.ui.custom` in Gentle Shell's own layout: one left
775
+ `CATEGORIES` list, one right pane headed `<Category> · n/m` with its setting
776
+ rows, each row painting the stored value with `●` and the other with `○`, and
777
+ the footer
778
+ `Click · ←/→ or Tab panes · ↑/↓ move · Enter apply · Esc close`. There is no
779
+ `Preview · …` band and no `p profiles` key: this plugin owns no profiles
780
+ concept, so the footer advertises nothing it cannot do. `←/→` or `Tab` moves
781
+ between the category and value panes, `↑/↓` or `j/k` moves the cursor, `Enter`
782
+ applies the focused row and `Esc` closes without a write; a click on a category
783
+ selects it, a click on a row applies it, and a click outside the panes is
784
+ ignored (a press only captures the gesture, so a drag never applies a row).
785
+ Each switch is one row that paints the stored state and carries the opposite
786
+ value. The notifications switch appears under both `Herdr Sidebar` (as
787
+ `Notifications`, where the plugin's own switches are looked for) and its own
788
+ `Moshi notifications` category: a row names the switch it drives, so both
789
+ apply the one `gentle-moshi.json` flag through `applyMoshiNotifications` and
790
+ whosever change it was is what both rows read on the next render.
791
+ An inconclusive sidebar verdict (`unknown`) renders as `● Unknown` with a note
721
792
  instead of hiding the row: toggling still attempts the repair and reports the
722
793
  apply step's own error, exactly like the menu. The plain
723
794
  two-step `ctx.ui.select` menu remains the
@@ -730,17 +801,18 @@ exactly one mechanism writes each piece of state.
730
801
  ## 8. Limits
731
802
 
732
803
  - Token budget: ≤ 16 tokens per report per pane (E8 discipline); the
733
- producer emits at most 10 tokens per beat (including the retired-token clear) (`gentle_work_v1`,
804
+ producer emits at most 12 tokens per beat (including the retired-token clear) (`gentle_work_v1`,
734
805
  `gentle_roles_v1`, `gentle_names_v1`,
735
- `gentle_orchestrating_v1`, `gentle_principal_v1`,
736
- `gentle_ask_v1`, `gentle_review_v1`, `gentle_changes_v2`,
737
- `gentle_changes_v1`) and the daemon publishes its 72-token owned family
806
+ `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
738
809
  chunked ≤ 16 per report (row 1 is the 3 native tokens
739
- `state_icon`/`workspace`/`agent`; the legacy 11 `gentle_heading_*` compat
740
- family stays published but wired into no visible row. Row 2 wires 11
741
- title + 3 change cells = 14 — each within the per-row ceiling). Names are
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
742
813
  advisory; roles are authoritative for display and role labels carry the
743
- running total as a suffix when at least two delegates run.
814
+ running total as a suffix when at least two delegates run, the job label the
815
+ pending-job total the same way.
744
816
  - TTL: `expiry <= now + 60000` at write; readers use `now` at read.
745
817
  Clock skew assumption ≤ 5 s (documented; not compensated).
746
818
  - Field bounds: `count` ≤ 16 digits; `label` ≤ 64 chars; names/roles
@@ -766,12 +838,13 @@ exactly one mechanism writes each piece of state.
766
838
 
767
839
  - Additive only in v1: new token names (`gentle_work_v1`,
768
840
  `gentle_roles_v1`, `gentle_names_v1`,
769
- `gentle_orchestrating_v1`, `gentle_principal_v1`,
841
+ `gentle_orchestrating_v1`, `gentle_principal_v1`, `gentle_done_v1`,
842
+ `gentle_jobs_v1`,
770
843
  `gentle_ask_v1`, `gentle_review_v1`, `gentle_changes_v1`, `gentle_changes_v2`,
771
844
  `gentle_state_*`, `gentle_title_*`, `gentle_agent_*`, `gentle_agent`,
772
845
  `gentle_icon_*`,
773
846
  `gentle_heading_*`, `gentle_project`, `gentle_row_*` (each family now
774
- includes the `judge` display alongside the original ten), plus display-only
847
+ includes the `judge` and `job` displays alongside the original ten), plus display-only
775
848
  `gentle_changes_added`, `gentle_changes_deleted`,
776
849
  `gentle_changes_pull`, `gentle_changes_summary`); no change to `pi_subagents_work_v1`, `state_*`,
777
850
  `title_*`, or native `working`/`blocked`/`idle` semantics.
@@ -804,12 +877,13 @@ exactly one mechanism writes each piece of state.
804
877
  npm as `herdr-gentle-shell`, installed with
805
878
  `pi install`, updated with `pi update --extensions`) and the Herdr plugin
806
879
  in `herdr-plugin/` (installed with `herdr plugin install
807
- jonasotoaguilar/herdr-gentle-agents/herdr-plugin`, updated with
880
+ jonasotoaguilar/herdr-gentle-shell/herdr-plugin`, updated with
808
881
  `herdr plugin update herdr-gentle-shell`). Releases run on two tag
809
882
  series, `pi-vX.Y.Z` and `herdr-vX.Y.Z`; the Herdr side is not bumped when
810
- it carries no change. The old managed-copy install (the installer copying
811
- `extensions/gentle-herdr-state.ts` into the Pi agent dir) is retired: the
812
- installer installs both packages and migrates an owned legacy copy aside.
883
+ it carries no change. The repository ships no install script: the
884
+ documented path is the two plain package installs above. The old
885
+ managed-copy install (copying `extensions/gentle-herdr-state.ts` into the
886
+ Pi agent dir) is retired and needs no migration step of its own.
813
887
  Ownership split: the Pi package owns the Pi-side helpers (the extension,
814
888
  the exclusion helper, the sidebar bridge); the Herdr plugin owns the
815
889
  runtime Herdr consumes (manifest, daemon, configure, diagnostics, token
package/README.md CHANGED
@@ -51,40 +51,33 @@ Prerequisites: Linux, Node >= 18, Herdr meeting `min_herdr_version` in
51
51
  `herdr-pi-tree` installed (it stays installed but disabled for gentle-owned
52
52
  panes).
53
53
 
54
- One script installs two packages: the Herdr plugin (`herdr-plugin/`,
55
- installed with `herdr plugin install
56
- jonasotoaguilar/herdr-gentle-agents/herdr-plugin`) and the Pi package (the
57
- repository root, published to npm as `herdr-gentle-shell`
58
- with the `pi-package` keyword, installed with `pi install`). The two
54
+ Two packages install separately: the Herdr plugin (`herdr-plugin/`) and the
55
+ Pi package (the repository root, published to npm as `herdr-gentle-shell`
56
+ with the `pi-package` keyword). The two
59
57
  packages version independently and release from two tag series —
60
- `pi-vX.Y.Z` (npm publish) and `herdr-vX.Y.Z` (GitHub Release with the
61
- `install.sh` and `install.sh.sha256` assets) — so either side may lag the
62
- other; the Herdr side is not bumped when it carries no change.
58
+ `pi-vX.Y.Z` (npm publish) and `herdr-vX.Y.Z` (GitHub Release) — so either
59
+ side may lag the other; the Herdr side is not bumped when it carries no
60
+ change.
63
61
 
64
- Source repository: only the published names above were renamed. The code
65
- still lives at `github.com/jonasotoaguilar/herdr-gentle-agents`, so every
66
- GitHub URL below keeps that repository; no `herdr-gentle-shell` repository
67
- was created.
62
+ Source repository: `github.com/jonasotoaguilar/herdr-gentle-shell`, the
63
+ origin that publishes both packages and creates the releases.
68
64
 
69
- Installer usage:
70
- `install.sh [--ref REF] [--pi-source auto|npm|git] [--allow-downgrade] [--uninstall] [--help]`
65
+ ### Install the Herdr plugin (always)
71
66
 
72
- The stable entrypoint always resolves to the newest `herdr-vX.Y.Z` release,
73
- while each
74
- release freezes its uploaded asset bytes — the URL moves forward, the bytes
75
- it served for a given release never change.
67
+ ```sh
68
+ herdr plugin install jonasotoaguilar/herdr-gentle-shell/herdr-plugin
69
+ ```
76
70
 
77
- Review the script before piping it to a shell — fetch the URL
78
- (never `main`) and read it first. The installer never uses `sudo` and never
79
- handles credentials.
71
+ The Herdr side is always installed; the Pi package below is not optional
72
+ either, since the sidebar states come from it.
80
73
 
81
- ### Install in Pi
74
+ ### Install the Pi package
82
75
 
83
76
  ```sh
84
77
  pi install npm:herdr-gentle-shell
85
78
  ```
86
79
 
87
- ### Install in Gentle Shell
80
+ Inside a Gentle Shell session, the same package is installed through the shell's launcher:
88
81
 
89
82
  ```sh
90
83
  gentle-shell install npm:herdr-gentle-shell
@@ -93,83 +86,20 @@ gentle-shell install npm:herdr-gentle-shell
93
86
  Both hosts install the same npm package,
94
87
  `herdr-gentle-shell` — the Pi extension that publishes the
95
88
  session facts behind the sidebar states — and only the host command differs.
96
- These two commands install the Pi package only; the Herdr plugin side still
97
- comes from the installer script below or from
98
- `herdr plugin install jonasotoaguilar/herdr-gentle-agents/herdr-plugin`.
99
-
100
- ### Public install (stable, one command)
101
89
 
102
- ```sh
103
- curl -fsSL https://github.com/jonasotoaguilar/herdr-gentle-agents/releases/latest/download/install.sh | sh
104
- ```
90
+ Running Pi sessions still need `/reload` (or a restart) to pick up the
91
+ updated extension.
105
92
 
106
- With no `--ref` the installer resolves the newest `herdr-vX.Y.Z` release tag automatically.
107
-
108
- ### Pinned install (explicit tag)
93
+ ### Apply the sidebar override
109
94
 
110
95
  ```sh
111
- curl -fsSL https://raw.githubusercontent.com/jonasotoaguilar/herdr-gentle-agents/herdr-v0.4.0/install.sh | sh -s -- --ref herdr-v0.4.0
96
+ herdr plugin action invoke configure --plugin herdr-gentle-shell
112
97
  ```
113
98
 
114
- Pass `--ref <tag>` to pin an older `herdr-vX.Y.Z` release instead of following latest.
115
-
116
- What the installer does:
117
-
118
- - Installs and enables the Herdr plugin from the `herdr-plugin/`
119
- subdirectory at the resolved `--ref` (the newest `herdr-vX.Y.Z` release
120
- when `--ref` is omitted).
121
- - Installs the Pi package with `pi install`. `--pi-source` selects the
122
- source: `npm` installs `npm:herdr-gentle-shell`, `git`
123
- installs `git:github.com/jonasotoaguilar/herdr-gentle-agents`, and `auto`
124
- (the default) uses npm when the package resolves on the registry and
125
- otherwise falls back to git with a warning — so an install before the
126
- first published npm version still converges through the git source.
127
- - Migrates an owned legacy managed copy away instead of refreshing it in
128
- place: a previous install's `~/.pi/agent/extensions/gentle-herdr-state.ts`
129
- is moved aside to a timestamped backup, never silently destroyed. The
130
- managed-copy layout is retired; a conflicting destination — including a
131
- locally modified copy, symlink, directory, or special file — is likewise
132
- moved aside, never deleted.
133
- - Records the non-destructive force-exclusion `-extensions/herdr-agent-state.ts`
134
- in the global Pi settings (`~/.pi/agent/settings.json`, or `$PI_AGENT_DIR`
135
- when overridden) so the managed native base file stays on disk but is never
136
- auto-loaded next to our copy — one publisher. The entry is appended
137
- idempotently; unrelated settings and pre-existing exclusions are preserved,
138
- and invalid settings fail closed (the installer aborts without rewriting the
139
- file). Ownership is a bound record (exact entry plus canonical settings
140
- path): if the record cannot be written, the settings change is rolled back
141
- byte-identical, and if a later install step fails the exclusion is rolled
142
- back best-effort so the base is not left disabled with no replacement (an
143
- already-installed Pi package stays in place — re-run install to converge).
144
- Symlinked settings are updated atomically through the link with the link and
145
- mode preserved; fresh files are created 0600. Four limits: running Pi
146
- sessions still need `/reload` (or a restart) for the exclusion to take
147
- effect; an explicit project-level `extensions` entry can re-enable the base
148
- file for that project; a rollback that itself fails says so instead of
149
- claiming success; two agent dirs sharing one state dir fail closed on the
150
- second install — separate `XDG_STATE_HOME` or remove the stale record.
151
- - Runs the installed plugin's Herdr sidebar `configure --apply` plus `--check`, then best-effort
152
- `herdr server reload-config` and best-effort daemon ensure via the installed
153
- plugin's `bin/gentle-status.js`.
154
- Best-effort reload/daemon failures warn without rolling back the completed install
155
- and config. The `configure` action itself only writes the managed Herdr sidebar
156
- block described below.
157
- - Running Pi sessions still need `/reload` (or a restart) to pick up the updated extension.
158
-
159
- Environment overrides: `HERDR_BIN_PATH`, `PI_BIN_PATH`, `NPM_BIN_PATH`,
160
- `PI_AGENT_DIR`, `XDG_STATE_HOME`, `HERDR_GENTLE_PLUGIN_ROOT`,
161
- `HERDR_GENTLE_PI_SOURCE` (same values as `--pi-source`), and
162
- `HERDR_GENTLE_LATEST_URL` (release lookup for newest-tag resolution).
163
-
164
- ### Migration from a managed copy (pre-split installs)
165
-
166
- The pre-split installer refreshed a managed copy of
167
- `extensions/gentle-herdr-state.ts` inside the Pi agent dir; that layout is
168
- retired. The first two-package install migrates it: an owned legacy copy is
169
- moved aside to a timestamped backup (a locally modified copy is preserved
170
- with a warning, never deleted), the Pi package takes over the extension,
171
- and the ownership-bound exclusion entry is kept. Nothing needs doing by
172
- hand — re-run the installer to converge.
99
+ The action appends the managed pi-only `[ui.sidebar.agents.rows_by_agent]`
100
+ override described below and reloads the server; `herdr server reload-config`
101
+ and the daemon start (`node bin/gentle-status.js`) are the same commands run by
102
+ hand.
173
103
 
174
104
  ### Local development
175
105
 
@@ -185,9 +115,8 @@ The repository root is the Pi package (`herdr-gentle-shell`)
185
115
  and `herdr-plugin/` is the Herdr plugin. Then run `/reload` in Pi to pick up
186
116
  the local package.
187
117
 
188
- For isolated/local use the installer honors a `PI_AGENT_DIR` override (default
189
- `$HOME/.pi/agent`) without touching the live Pi dir, e.g.
190
- `PI_AGENT_DIR=/tmp/pi-agent-test sh install.sh --ref herdr-v0.4.0`.
118
+ For isolated/local use point Pi at a throwaway agent dir, e.g. from this
119
+ checkout `PI_AGENT_DIR=/tmp/pi-agent-test pi install .`.
191
120
 
192
121
  ### Update
193
122
 
@@ -203,16 +132,13 @@ and the Herdr plugin updates with:
203
132
  herdr plugin update herdr-gentle-shell
204
133
  ```
205
134
 
206
- To move the Herdr side to an explicitly older `herdr-vX.Y.Z` release, pass
207
- `--ref` with `--allow-downgrade`:
135
+ To move the Herdr side to an explicitly older `herdr-vX.Y.Z` release, install
136
+ that ref after removing the current one:
208
137
 
209
138
  ```sh
210
- curl -fsSL https://github.com/jonasotoaguilar/herdr-gentle-agents/releases/latest/download/install.sh | sh -s -- --ref herdr-vX.Y.Z --allow-downgrade
139
+ herdr plugin install jonasotoaguilar/herdr-gentle-shell/herdr-plugin --ref herdr-vX.Y.Z
211
140
  ```
212
141
 
213
- Without `--allow-downgrade`, installing an older Herdr version than the
214
- installed one aborts naming both versions.
215
-
216
142
  If the installed plugin is locally linked, the remote install replaces it
217
143
  automatically and warns naming the plugin id; to restore a checkout afterwards
218
144
  re-link it:
@@ -221,24 +147,20 @@ re-link it:
221
147
  herdr plugin link --enabled ./herdr-plugin
222
148
  ```
223
149
 
224
- `--force` is deprecated and a no-op kept only so older documented commands
225
- keep working; use `--allow-downgrade` for downgrades instead.
226
-
227
150
  ### Removal
228
151
 
229
152
  ```sh
230
- curl -fsSL https://github.com/jonasotoaguilar/herdr-gentle-agents/releases/latest/download/install.sh | sh -s -- --uninstall
153
+ herdr plugin action invoke unconfigure --plugin herdr-gentle-shell
154
+ pi remove npm:herdr-gentle-shell
155
+ herdr plugin uninstall herdr-gentle-shell
231
156
  ```
232
157
 
233
- Uninstall runs the installed plugin's `configure --uninstall`, best-effort daemon `--stop --purge` and
234
- `herdr server reload-config`, then removes both packages (the Herdr plugin and
235
- the Pi package), the owned native-extension exclusion entry, and the installer
236
- state. A legacy managed Pi copy
237
- is ownership-checked: a locally modified `~/.pi/agent/extensions/gentle-herdr-state.ts`
238
- is preserved with a warning, never deleted. The settings exclusion is likewise
239
- ownership-checked: only the entry this installer added is removed, while a
158
+ The `unconfigure` action takes the managed sidebar override out of the Herdr
159
+ config and reloads it; the user-owned `[ui.sidebar.agents]` table is left
160
+ intact. The settings exclusion is likewise
161
+ ownership-checked: only the entry this plugin added is removed, while a
240
162
  pre-existing identical entry and unrelated settings are preserved. A foreign,
241
- invalid, or misbound ownership record fails closed: uninstall warns, preserves
163
+ invalid, or misbound ownership record fails closed: removal warns, preserves
242
164
  the entry, and still removes the plugin.
243
165
 
244
166
  Path convention used below: `node bin/...` runs from the installed plugin
@@ -300,7 +222,7 @@ acceptable. Row 1 holds 3 native cells and row 2 holds 14 cells (11 state
300
222
  # row 1 native state_icon + workspace + agent, row 2 state word + changes.
301
223
  # The parent [ui.sidebar.agents] table is user-owned and never touched here.
302
224
  [ui.sidebar.agents.rows_by_agent]
303
- 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" }]]
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" }]]
304
226
  # END herdr-gentle-agents
305
227
  ```
306
228
 
@@ -439,13 +361,20 @@ See [DESIGN.md](DESIGN.md) §4 (producer) and §5 (consumer), and
439
361
  managed Herdr rows and records the owned native-extension exclusion;
440
362
  `disable` removes only our owned rows and exclusion, never a user table.
441
363
  See [docs/sidebar-control.md](docs/sidebar-control.md).
442
- - In-Pi switches (`/herdr-gentle:customize`): exactly two toggles, both local
364
+ - In-Pi switches (`/herdr-gentle:customize`): two switches, both local
443
365
  state and both reachable from a plain Pi session outside a Herdr pane. With
444
- no argument the command opens the restored floating two-pane panel
445
- (`Herdr Sidebar` and `Moshi notifications`; `←/→` or `Tab` moves between the
446
- category and value panes, `↑/↓` or `j/k` moves the cursor, `Enter` toggles the
447
- focused switch and `Esc` closes). Each switch is one row that reads its stored
448
- state, so `On` becomes `Off` and back in a single key press. The plain two-step menu stays as the fallback
366
+ no argument the command opens the floating panel in Gentle Shell's own
367
+ layout: one left `CATEGORIES` list (`Herdr Sidebar`, `Moshi notifications`)
368
+ and one right pane headed `<Category> · n/m` with its setting rows, each row
369
+ painting the stored value with `●` and the other with `○`; the footer reads
370
+ `Click · ←/→ or Tab panes · ↑/↓ move · Enter apply · Esc close`, and `←/→` or
371
+ `Tab` moves between the category and value panes, `↑/↓` or `j/k` moves the
372
+ cursor while `Esc` closes. A click on a category selects it and a click on a
373
+ row applies it, exactly like `Enter` on the focused row; clicks outside the
374
+ panes are ignored. The notifications switch appears twice — as its own
375
+ `Moshi notifications` category and as a `Notifications` row inside
376
+ `Herdr Sidebar` — and both rows read the one flag below, so the state they
377
+ show can never disagree. The plain two-step menu stays as the fallback
449
378
  when the TUI helpers or `ctx.ui.custom` are unavailable.
450
379
  `Sidebar agent rows` drives the Herdr plugin's own `bin/configure.js`
451
380
  (`--check` to read, `--apply --reload` / `--uninstall --reload` to change) and
@@ -470,10 +399,11 @@ See [DESIGN.md](DESIGN.md) §4 (producer) and §5 (consumer), and
470
399
  mkdir -p "$dir" && echo '{"enabled":true}' > "$dir/gentle-moshi.json"
471
400
  ```
472
401
 
473
- `/herdr-gentle:customize` → `Moshi notifications` writes this flag for you,
474
- and enabling there first requires the `moshi-hook` CLI on `PATH` with
475
- `moshi-hook status --json` reporting `paired: true` (an unpaired host is
476
- refused and nothing is written).
402
+ `/herdr-gentle:customize` → `Moshi notifications` (or the `Notifications` row
403
+ inside `Herdr Sidebar`) writes this flag for you, and enabling there first
404
+ requires the `moshi-hook` CLI on `PATH` with `moshi-hook status --json`
405
+ reporting `paired: true` (an unpaired host is refused and nothing is
406
+ written).
477
407
 
478
408
  With the flag on, this plugin **replaces the
479
409
  Moshi-managed Pi hook**: the same Moshi integration (Chat View, Live Activity,
@@ -30,7 +30,7 @@ HERDR_CONFIG_PATH=/tmp/c.toml node bin/gentle-sidebar.js status
30
30
  Herdr config to verify the managed pi-only rows are present. Only then
31
31
  it records the plugin-owned exclusion of the native integration
32
32
  (`-extensions/herdr-agent-state.ts` in the Pi `settings.json`
33
- `extensions` list, with the ownership marker from the installer) and
33
+ `extensions` list, with the plugin-owned ownership marker) and
34
34
  writes the shared mode file
35
35
  (`gentle-sidebar-mode.json`, `{version:1,enabled:true}`). A zero exit
36
36
  alone never commits state: without the verified row effect the apply
@@ -693,6 +693,27 @@ const paneId = process.env.HERDR_PANE_ID;
693
693
 
694
694
  const TTL_MS = 60000;
695
695
  const BEAT_MS = 15000;
696
+ // Synthesized finish signal (DESIGN §4.3, S2/D2). The host never reports
697
+ // `done`, so the producer mints the finish itself: one session-bound
698
+ // `<hash>:<expiry>` token per finish at the settled-and-empty edge, carrying
699
+ // the hold as its absolute expiry. The sidebar reads it as `done` while it is
700
+ // fresh and recedes to `idle` once it expires — the delay IS that expiry, so
701
+ // no timer and no extra idle hold exists. The hold defaults to 60 s and is
702
+ // overridden through GENTLE_HERDR_DONE_HOLD_MS, clamped to [1 s, 5 min]; the
703
+ // consumer rejects any expiry beyond the same ceiling.
704
+ const DONE_TOKEN = "gentle_done_v1";
705
+ const DONE_HOLD_MS = 60000;
706
+ const DONE_HOLD_MIN_MS = 1000;
707
+ export const DONE_HOLD_MAX_MS = 300000;
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";
696
717
  const MAX_TOKENS_PER_REPORT = 16;
697
718
  const MAX_LABEL_CHARS = 64;
698
719
  // Herdr's wire ceiling for a single pane-metadata token value, measured in
@@ -830,6 +851,17 @@ function utf8Bytes(value) {
830
851
  return Buffer.byteLength(value, "utf8");
831
852
  }
832
853
 
854
+ // Finish-hold override: an absent or unparseable value keeps the 60 s
855
+ // default, and anything outside the ceiling is clamped, so the producer can
856
+ // never publish an expiry the consumer reads as foreign.
857
+ export function doneHoldMs(raw = process.env[DONE_HOLD_ENV]) {
858
+ const text = typeof raw === "string" ? raw.trim() : "";
859
+ if (text.length === 0) return DONE_HOLD_MS;
860
+ const parsed = Number(text);
861
+ if (!Number.isFinite(parsed)) return DONE_HOLD_MS;
862
+ return Math.min(DONE_HOLD_MAX_MS, Math.max(DONE_HOLD_MIN_MS, Math.round(parsed)));
863
+ }
864
+
833
865
  // Cap a label at MAX_LABEL_CHARS UTF-16 units — the same unit the consumer's
834
866
  // `parseNames` checks, so a label the producer writes is never one the
835
867
  // consumer drops — while backing off one unit when the cut would split a
@@ -1836,8 +1868,9 @@ function lastFinishedLabel(taskMap) {
1836
1868
  }
1837
1869
 
1838
1870
  // ---------------------------------------------------------------------------
1839
- // `/herdr-gentle:customize`: exactly two switches, offered in the former
1840
- // floating two-pane panel (odd/tasks/restore-customize-panel.md T1).
1871
+ // `/herdr-gentle:customize`: exactly two switches, offered in the floating panel
1872
+ // shaped like Gentle Shell's own card (odd/tasks/restore-customize-panel.md T1;
1873
+ // odd/tasks/customize-parity-done-idle.md T1/T3).
1841
1874
  //
1842
1875
  // The command is registered BEFORE the `enabled()` gate in the factory below,
1843
1876
  // so it stays reachable from a plain Pi session outside a Herdr pane; the
@@ -2315,11 +2348,15 @@ async function applyCustomizeSwitch(id, value, ctx) {
2315
2348
  // The single apply path shared by the overlay and the menu fallback. An
2316
2349
  // inconclusive sidebar verdict is never a refusal: choosing On still attempts
2317
2350
  // the repair and reports the apply step's own error, exactly like the baseline
2318
- // menu did.
2319
- async function applyCustomizeChoice(categoryId, valueId, ctx) {
2320
- if (categoryId !== "sidebar" && categoryId !== "moshi") return;
2351
+ // menu did. `switchId` names the switch a row drives when it lives under
2352
+ // another category — the notifications row inside `Herdr Sidebar` applies the
2353
+ // same `moshi` switch as the `Moshi notifications` category, so the one flag
2354
+ // file stays the single source of truth.
2355
+ async function applyCustomizeChoice(categoryId, valueId, ctx, switchId) {
2356
+ const target = switchId === "sidebar" || switchId === "moshi" ? switchId : categoryId;
2357
+ if (target !== "sidebar" && target !== "moshi") return;
2321
2358
  if (valueId !== "on" && valueId !== "off") return;
2322
- await applyCustomizeSwitch(categoryId, valueId, ctx);
2359
+ await applyCustomizeSwitch(target, valueId, ctx);
2323
2360
  }
2324
2361
 
2325
2362
  // The former plain menu, kept as the fallback when the TUI helpers or
@@ -2416,7 +2453,7 @@ async function executeCustomize(rawArgs, ctx) {
2416
2453
  // Esc (null) does nothing at all: no notification, no write, no reload.
2417
2454
  // Anything else runs the single apply path once the overlay is disposed.
2418
2455
  if (!choice || typeof choice !== "object") return;
2419
- await applyCustomizeChoice(choice.categoryId, choice.valueId, ctx);
2456
+ await applyCustomizeChoice(choice.categoryId, choice.valueId, ctx, choice.switchId);
2420
2457
  return;
2421
2458
  }
2422
2459
  await runCustomizeFallback(ctx);
@@ -2652,6 +2689,15 @@ export default function (pi) {
2652
2689
  let nativeSending = null;
2653
2690
  let nativeLastOk = undefined;
2654
2691
  let nativeSettledPending = false;
2692
+ // Finish-hold episode (S2): minted once at the settled-and-empty edge so the
2693
+ // row reads `done`, then republished unchanged (never refreshed) until the
2694
+ // hold expires. `donePending` carries the unannounced finish to the beat
2695
+ // that actually delivers the token (S3), and `sawActivity` remembers that
2696
+ // the session did work, so a session that never ran a turn stays idle. All
2697
+ // three clear with the session and the moment any work reappears.
2698
+ let doneExpiry;
2699
+ let donePending = false;
2700
+ let sawActivity = false;
2655
2701
  // LIVE-1 startup latency: the session binding is still INITIATED on
2656
2702
  // session_start (so Herdr can attribute the pane from the first frame), but
2657
2703
  // the host no longer waits for it. The host awaits every session_start
@@ -2999,6 +3045,53 @@ export default function (pi) {
2999
3045
  // how many delegates keep running.
3000
3046
  if (agentActive) tokens[PRINCIPAL_TOKEN] = `${sessionHash}:${expiry}`;
3001
3047
  else tokens[PRINCIPAL_TOKEN] = null;
3048
+ // Synthesized finish signal (S2/D2): minted once at the settled-and-empty
3049
+ // edge — principal settled with no running/queued delegate, no pending
3050
+ // launch, no live background job, and no human-wait, review, or error leg
3051
+ // — then republished with the SAME expiry so the hold can never be
3052
+ // 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.
3055
+ const activity =
3056
+ agentActive ||
3057
+ subs.length > 0 ||
3058
+ pendingCalls.size > 0 ||
3059
+ runningJobCount() > 0 ||
3060
+ askActiveNow() ||
3061
+ reviewActive ||
3062
+ !!errorCode;
3063
+ if (activity) {
3064
+ sawActivity = true;
3065
+ doneExpiry = undefined;
3066
+ donePending = false;
3067
+ } else if (settled) {
3068
+ if (doneExpiry === undefined && sawActivity) {
3069
+ doneExpiry = Date.now() + doneHoldMs();
3070
+ donePending = true;
3071
+ sawActivity = false;
3072
+ }
3073
+ if (doneExpiry !== undefined && Date.now() >= doneExpiry) {
3074
+ doneExpiry = undefined;
3075
+ donePending = false;
3076
+ }
3077
+ } else {
3078
+ doneExpiry = undefined;
3079
+ donePending = false;
3080
+ }
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;
3002
3095
  if (changes.files > 0) {
3003
3096
  const files = String(changes.files);
3004
3097
  const added = String(changes.added);
@@ -3039,7 +3132,8 @@ export default function (pi) {
3039
3132
  askToolCalls.size > 0 ||
3040
3133
  uiPromptActive ||
3041
3134
  reviewActive ||
3042
- emittedLabel !== undefined
3135
+ emittedLabel !== undefined ||
3136
+ doneExpiry !== undefined
3043
3137
  );
3044
3138
  }
3045
3139
 
@@ -3189,6 +3283,24 @@ export default function (pi) {
3189
3283
  }
3190
3284
  }
3191
3285
 
3286
+ // Moshi replacement (DESIGN §7, S3): the finish notification hangs off the
3287
+ // synthesized `done` edge — the beat that delivered the finish token, minted
3288
+ // only when the principal settled with zero delegates, pending launches, and
3289
+ // live jobs — never off a raw native working->idle transition, which fires
3290
+ // with work still left and used to skip `done` entirely.
3291
+ function emitFinish() {
3292
+ const project = moshiContext?.project ?? "Gentle";
3293
+ const lastLabel = lastFinishedLabel(tasks);
3294
+ moshiEmit("AgentEnd", {
3295
+ category: "task_complete",
3296
+ title: `Gentle finished: ${project}`,
3297
+ message:
3298
+ lastLabel !== undefined
3299
+ ? `${project} finished \u2014 ${lastLabel}. Return to Pi for what\u2019s next.`
3300
+ : `${project} finished and is waiting for your next instruction.`,
3301
+ });
3302
+ }
3303
+
3192
3304
  async function drainNative() {
3193
3305
  if (!enabled()) return;
3194
3306
  if (nativeInFlight) return;
@@ -3233,25 +3345,7 @@ export default function (pi) {
3233
3345
  // transition (attempt loop above, then beats — never a re-queue here).
3234
3346
  if (nativeSending === next) nativeSending = null;
3235
3347
  }
3236
- if (ok) {
3237
- const wasWorking = nativeLastOk?.state === "working";
3238
- nativeLastOk = next;
3239
- // Moshi replacement (DESIGN §7): the real finish is the native
3240
- // transition into `idle` — settled plus zero running/queued plus
3241
- // zero pending plus no human wait — never a settle with work left.
3242
- if (wasWorking && next.state === "idle") {
3243
- const project = moshiContext?.project ?? "Gentle";
3244
- const lastLabel = lastFinishedLabel(tasks);
3245
- moshiEmit("AgentEnd", {
3246
- category: "task_complete",
3247
- title: `Gentle finished: ${project}`,
3248
- message:
3249
- lastLabel !== undefined
3250
- ? `${project} finished \u2014 ${lastLabel}. Return to Pi for what\u2019s next.`
3251
- : `${project} finished and is waiting for your next instruction.`,
3252
- });
3253
- }
3254
- }
3348
+ if (ok) nativeLastOk = next;
3255
3349
  }
3256
3350
  } finally {
3257
3351
  nativeInFlight = false;
@@ -3301,6 +3395,10 @@ export default function (pi) {
3301
3395
  try {
3302
3396
  const ok = await sendTokens(tokens);
3303
3397
  if (ok) {
3398
+ if (donePending) {
3399
+ donePending = false;
3400
+ emitFinish();
3401
+ }
3304
3402
  if (transportFails >= TRANSPORT_FAIL_LATCH && errorCode === "transport") {
3305
3403
  errorCode = undefined;
3306
3404
  updateBlocker();
@@ -3434,6 +3532,9 @@ export default function (pi) {
3434
3532
  nativeSending = null;
3435
3533
  nativeLastOk = undefined;
3436
3534
  nativeSettledPending = false;
3535
+ doneExpiry = undefined;
3536
+ donePending = false;
3537
+ sawActivity = false;
3437
3538
  errorCode = undefined;
3438
3539
  liveGen += 1;
3439
3540
  liveInFlight = false;
@@ -1,22 +1,23 @@
1
1
  'use strict';
2
2
 
3
3
  // The `/herdr-gentle:customize` floating panel, recovered from commit 0e92869
4
- // (odd/tasks/restore-customize-panel.md T1, S1/S2).
4
+ // (odd/tasks/restore-customize-panel.md T1, S1/S2) and shaped like Gentle
5
+ // Shell's own customize card (odd/tasks/customize-parity-done-idle.md T1, S1).
5
6
  //
6
- // It is the former two-pane card with the same layout, palette, keyboard
7
- // semantics and overlay behaviour, reduced to the two switches this package
8
- // still owns: the managed Herdr sidebar rows and the Moshi notification
9
- // channel. The removed worktree / ODD / Issues / Reset sections are gone, and
10
- // the panel reads the current state handed in by the extension instead of a
11
- // cross-extension provider slot.
7
+ // One left `CATEGORIES` list, one right pane headed `<Category> · n/m` holding
8
+ // the setting rows, and the Shell's footer keys. Each switch is ONE row that
9
+ // paints the stored value with `●` and the other with `○`, so Enter (or a click
10
+ // on the row) is still the whole toggle. The removed worktree / ODD / Issues /
11
+ // Reset sections are gone, and the panel reads the current state handed in by
12
+ // the extension instead of a cross-extension provider slot.
12
13
  //
13
14
  // The host component contract (pi-coding-agent `custom`): the factory receives
14
15
  // (hostTui, theme, keybindings, done) and returns
15
- // { render(width), handleInput(data), invalidate() }. Selection keys only move
16
- // local state and ask the host to repaint through hostTui.requestRender(); Esc
17
- // finishes with done(null) and Enter with done({categoryId, valueId}). This
18
- // module never writes, notifies, or reloads: the extension's single apply path
19
- // runs after the overlay resolves.
16
+ // { render(width), handleInput(data), handleMouse(event), invalidate() }.
17
+ // Selection keys and pointer hits only move local state and ask the host to
18
+ // repaint; Esc finishes with done(null) and Enter (or a row click) with
19
+ // done({categoryId, switchId, valueId}). This module never writes, notifies, or
20
+ // reloads: the extension's single apply path runs after the overlay resolves.
20
21
 
21
22
  const ROLE = Object.freeze({
22
23
  key: "accent",
@@ -85,6 +86,10 @@ function label(theme, text) {
85
86
  return paint(theme, ROLE.label, text);
86
87
  }
87
88
 
89
+ function accent(theme, text) {
90
+ return paint(theme, ROLE.key, text);
91
+ }
92
+
88
93
  function value(theme, text) {
89
94
  return paint(theme, ROLE.value, text);
90
95
  }
@@ -138,74 +143,79 @@ function legendRow(theme, entries, width, measure) {
138
143
  return selection.entries.map((entry) => entryCell(theme, entry, selection.field)).join(separator);
139
144
  }
140
145
 
141
- const palette = { ROLES: ROLE, count, description, key, label, legendRow, paint, title, value };
146
+ const palette = { ROLES: ROLE, accent, count, description, key, label, legendRow, paint, title, value };
142
147
 
143
148
  const CUSTOMIZE_TITLE = "Customize · Herdr Gentle Shell";
144
149
  const CUSTOMIZE_CARD_PADDING = 4;
145
150
  const CUSTOMIZE_NARROW_WIDTH = 60;
146
151
  const CUSTOMIZE_MAX_HEIGHT = 24;
152
+ // The Shell's row vocabulary: `●` is the stored value, `○` the other one.
153
+ const CUSTOMIZE_PILL_CURRENT = "●";
154
+ const CUSTOMIZE_PILL_OTHER = "○";
155
+
156
+ // The switches this package owns. `id` is the apply target the extension knows
157
+ // (the sidebar rows go through the Herdr plugin's own configure step,
158
+ // notifications through the `gentle-moshi.json` flag and its Pi settings
159
+ // exclusion) and `setting` is the row name the panel paints.
160
+ const CUSTOMIZE_SWITCHES = [
161
+ { id: "sidebar", setting: "Sidebar agent rows" },
162
+ { id: "moshi", setting: "Notifications" },
163
+ ];
147
164
 
148
- // The two surviving switches. `id` is the value the extension applies: the
149
- // sidebar rows go through the Herdr plugin's own configure step, Moshi through
150
- // its flag file and Pi settings exclusion. Each switch is ONE row: it reads the
151
- // stored state and the row's id is the opposite value, so Enter is the toggle.
165
+ // Categories only group rows for display. Notifications appears under both
166
+ // headings on purpose: `Herdr Sidebar` is where the plugin's own switches are
167
+ // looked for, and `Moshi notifications` keeps the switch the user already
168
+ // knows. Both rows read the one flag, so they can never disagree.
152
169
  const CUSTOMIZE_CATEGORIES = [
153
- {
154
- id: "sidebar",
155
- title: "Herdr Sidebar",
156
- onDetail: "adds the managed agent rows to Herdr's plugin config",
157
- offDetail: "removes the managed rows and hands the pane back to Herdr",
158
- unknownDetail: "state unreadable; On re-runs the managed rows and reports the result",
159
- },
160
- {
161
- id: "moshi",
162
- title: "Moshi notifications",
163
- onDetail: "notifies ask and finish episodes through Moshi",
164
- offDetail: "leaves notifications to the host",
165
- unknownDetail: "state unreadable; On runs the moshi-hook check and reports the result",
166
- },
170
+ { id: "sidebar", title: "Herdr Sidebar", switches: ["sidebar", "moshi"] },
171
+ { id: "moshi", title: "Moshi notifications", switches: ["moshi"] },
167
172
  ];
168
173
 
169
- // One row per switch: it shows the CURRENT state and carries the value Enter
170
- // applies. `Unknown` keeps the row actionable instead of blocking the repair,
171
- // so an inconclusive check can always be re-run from here.
172
- function toggleRow(category, active) {
173
- const label = active === "on" ? "On" : active === "off" ? "Off" : "Unknown";
174
- const detail =
175
- active === "on" ? category.onDetail : active === "off" ? category.offDetail : category.unknownDetail;
176
- return { id: active === "on" ? "off" : "on", label, detail, mark: "→ " };
174
+ // One row per switch: it paints the stored value and carries the value Enter
175
+ // applies, so a single key press is the whole toggle. `Unknown` keeps the row
176
+ // actionable instead of blocking the repair, so an inconclusive check can
177
+ // always be re-run from here.
178
+ function toggleRow(definition, active) {
179
+ const current = active === "on" || active === "off" ? active : null;
180
+ return {
181
+ id: current === "on" ? "off" : "on",
182
+ switchId: definition.id,
183
+ setting: definition.setting,
184
+ current,
185
+ currentLabel: current === "on" ? "On" : current === "off" ? "Off" : "Unknown",
186
+ otherLabel: current === "on" ? "Off" : "On",
187
+ note: current === null ? "state unknown; Enter re-runs the managed rows" : undefined,
188
+ };
177
189
  }
178
190
 
179
191
  // The current stored values as the extension read them. A sidebar state of
180
192
  // `unknown` (unresolvable plugin root or inconclusive `--check`) is never a
181
193
  // guessed value and never blocks the repair: the row stays selectable and a
182
- // note explains that On re-runs the managed rows. Moshi is always a readable
183
- // local flag.
194
+ // note explains that On re-runs the managed rows. Notifications are always a
195
+ // readable local flag.
184
196
  function customizePanelModel({ sidebar, moshi } = {}) {
185
197
  const stored = (value) => (value === "on" || value === "off" ? value : null);
186
- const byId = (id) => CUSTOMIZE_CATEGORIES.find((entry) => entry.id === id);
187
- const sidebarActive = stored(sidebar);
188
- const moshiActive = stored(moshi) === "on" ? "on" : "off";
189
- const sidebarCategory = byId("sidebar");
190
- const moshiCategory = byId("moshi");
191
- return [
192
- {
193
- ...sidebarCategory,
194
- active: sidebarActive,
195
- note: sidebarActive === null ? "state unknown; Enter re-runs the managed rows" : undefined,
196
- rows: [toggleRow(sidebarCategory, sidebarActive)],
197
- },
198
- { ...moshiCategory, active: moshiActive, rows: [toggleRow(moshiCategory, moshiActive)] },
199
- ];
198
+ const current = { sidebar: stored(sidebar), moshi: stored(moshi) === "on" ? "on" : "off" };
199
+ return CUSTOMIZE_CATEGORIES.map((category) => ({
200
+ id: category.id,
201
+ title: category.title,
202
+ rows: category.switches.map((switchId) => toggleRow(
203
+ CUSTOMIZE_SWITCHES.find((entry) => entry.id === switchId),
204
+ current[switchId],
205
+ )),
206
+ }));
200
207
  }
201
208
 
202
209
  // The key legend is ONE terminal row: the `key` spelling paints as the key
203
210
  // role and the rest as its description. `short` is the compact form, and
204
211
  // `priority` is the drop order, so the close key outlives every other hint.
212
+ // There is no `p profiles` entry: this plugin owns no profiles concept, and a
213
+ // dead key in the footer would be a lie.
205
214
  const CUSTOMIZE_FOOTER_KEYS = [
215
+ { text: "Click", short: "Click", priority: 10 },
206
216
  { key: "←/→", text: "←/→ or Tab panes", short: "←/→ panes", priority: 60 },
207
- { key: "↑/↓", text: "↑/↓ or j/k move", short: "↑/↓ move", priority: 70 },
208
- { key: "Enter", text: "Enter toggle", short: "Enter toggle", priority: 80 },
217
+ { key: "↑/↓", text: "↑/↓ move", short: "↑/↓ move", priority: 70 },
218
+ { key: "Enter", text: "Enter apply", short: "Enter apply", priority: 80 },
209
219
  { key: "Esc", text: "Esc close", short: "Esc close", priority: 100 },
210
220
  ];
211
221
 
@@ -345,14 +355,43 @@ function customizeIsKeyRelease(helpers, data) {
345
355
  return false;
346
356
  }
347
357
 
358
+ // One setting line: the name column, then the Shell's pill pair — `●` on the
359
+ // stored value and `○` on the other. A pair wider than the pane falls back to
360
+ // the stored pill alone, so the narrow width keeps showing the real state.
361
+ function customizeSettingLine(helpers, theme, row, nameWidth, size, focused) {
362
+ const name = String(row.setting);
363
+ const namePad = " ".repeat(Math.max(0, nameWidth - customizeMeasure(helpers, name)));
364
+ const prefix = focused ? "▸ " : " ";
365
+ const lead = `${prefix}${name}${namePad} `;
366
+ const stored = `${CUSTOMIZE_PILL_CURRENT} ${row.currentLabel}`;
367
+ const other = `${CUSTOMIZE_PILL_OTHER} ${row.otherLabel}`;
368
+ const pair = `${stored} ${other}`;
369
+ const showPair = customizeMeasure(helpers, `${lead}${pair}`) <= size;
370
+ const body = showPair ? pair : stored;
371
+ if (focused && theme && typeof theme.bg === "function") {
372
+ try {
373
+ const plain = customizeFit(helpers, `${lead}${body}`, Math.max(0, size));
374
+ const band = theme.bg("selectedBg", plain + " ".repeat(Math.max(0, size - customizeMeasure(helpers, plain))));
375
+ if (typeof band === "string") return band;
376
+ } catch {
377
+ // Fall through to the composed form below.
378
+ }
379
+ }
380
+ const segments = [
381
+ { kind: focused ? "key" : "label", text: prefix },
382
+ { kind: focused ? "value" : "description", text: `${name}${namePad} ` },
383
+ { kind: row.current === null ? "error" : "accent", text: stored },
384
+ ];
385
+ if (showPair) segments.push({ kind: "description", text: ` ${other}` });
386
+ return customizeCompose(helpers, theme, segments, size);
387
+ }
388
+
348
389
  function createCustomizePanel({ helpers, hostTui, theme, rowsAvailable, model, done }) {
349
390
  const state = {
350
391
  pane: "categories",
351
392
  cat: 0,
352
- row: model.map((category) => {
353
- const at = category.rows.findIndex((row) => row.id === category.active);
354
- return at >= 0 ? at : 0;
355
- }),
393
+ row: model.map(() => 0),
394
+ frame: null,
356
395
  };
357
396
  function availableRows() {
358
397
  try {
@@ -371,6 +410,7 @@ function createCustomizePanel({ helpers, hostTui, theme, rowsAvailable, model, d
371
410
  }
372
411
  function render(width) {
373
412
  const w = typeof width === "number" && Number.isFinite(width) ? Math.floor(width) : 0;
413
+ state.frame = null;
374
414
  if (w <= 0) return [];
375
415
  const height = availableRows();
376
416
  if (!height) return [];
@@ -394,25 +434,20 @@ function createCustomizePanel({ helpers, hostTui, theme, rowsAvailable, model, d
394
434
  const rightWidth = inner - leftWidth - (leftWidth ? 3 : 0);
395
435
  const category = model[state.cat];
396
436
  const rows = category.rows;
397
- const previewLines = height >= 11 ? 3 : height >= 8 ? 1 : 0;
398
437
  const showHeading = height >= 6;
399
- // Right pane: LABELS ONLY. Each choice's detail lives exactly once in the
400
- // preview block below, never under the rows.
401
- const rightLines = [];
402
- for (let index = 0; index < rows.length; index += 1) {
403
- const row = rows[index];
404
- const focusedValue = !navOnly && state.pane === "values" && index === state.row[state.cat];
405
- const mark = typeof row.mark === "string" ? row.mark : (row.id === category.active ? "→ " : " ");
406
- rightLines.push({ label: `${mark}${row.label}`, focused: focusedValue });
407
- }
408
- if (category.note) {
409
- rightLines.push({ label: category.note, mark: " ", focused: false, muted: true });
410
- }
411
- const contentHeight = Math.max(1, height - 2 - 1 - (showHeading ? 1 : 0) - previewLines - (showHeading ? 1 : 0));
438
+ // Right pane: one line per setting (name column plus the pill pair) and,
439
+ // when the stored state is unreadable, one muted note under it.
440
+ const rightLines = rows.map((row, index) => ({ kind: "row", index, row }));
441
+ for (const row of rows) if (row.note) rightLines.push({ kind: "note", text: row.note });
442
+ const contentHeight = Math.max(1, height - 2 - 1 - (showHeading ? 2 : 0));
412
443
  const position = navOnly ? state.cat : state.row[state.cat];
413
444
  const listLength = navOnly ? model.length : rightLines.length;
414
445
  const start = Math.min(Math.max(0, position - contentHeight + 1), Math.max(0, listLength - contentHeight));
415
446
  const navStart = Math.min(Math.max(0, state.cat - contentHeight + 1), Math.max(0, model.length - contentHeight));
447
+ const nameWidth = rows.reduce(
448
+ (need, row) => Math.max(need, customizeMeasure(helpers, row.setting)),
449
+ 0,
450
+ );
416
451
  const paint = (text, size, kind) => customizePaint(helpers, theme, kind, text, size);
417
452
  const compose = (segments, size) => customizeCompose(helpers, theme, segments, size);
418
453
  const divider = palette.paint(theme, "border", "│");
@@ -420,6 +455,7 @@ function createCustomizePanel({ helpers, hostTui, theme, rowsAvailable, model, d
420
455
  ? `${left}${" ".repeat(Math.max(0, leftWidth - customizeMeasure(helpers, left)))} ${divider} ${right}`
421
456
  : right;
422
457
  const lines = [];
458
+ const hits = [];
423
459
  // Title row doubles as the esc hint: same row, right-aligned.
424
460
  const escGap = Math.max(1, inner - customizeMeasure(helpers, title) - 3);
425
461
  lines.push(compose([
@@ -436,58 +472,52 @@ function createCustomizePanel({ helpers, hostTui, theme, rowsAvailable, model, d
436
472
  { kind: "count", text: rows.length ? `${state.row[state.cat] + 1}/${rows.length}` : "empty" },
437
473
  ];
438
474
  lines.push(join(
439
- leftWidth ? paint("CATEGORIES", leftWidth, "label") : "",
475
+ leftWidth ? paint("CATEGORIES", leftWidth, "key") : "",
440
476
  compose(heading, rightWidth),
441
477
  ));
442
478
  }
443
- const current = focused();
444
479
  for (let i = 0; i < contentHeight; i += 1) {
445
- const nav = model[navStart + i];
480
+ const navIndex = navStart + i;
481
+ const nav = model[navIndex];
482
+ const at = start + i;
483
+ const item = navOnly ? (model[at] || null) : (rightLines[at] || null);
484
+ // The card paints the top border above content line 0, so a content row's
485
+ // rendered row is its index + 1.
486
+ const y = lines.length + 1;
446
487
  const left = nav
447
- ? customizeSelect(helpers, theme, nav.title, leftWidth, navOnly || (navStart + i === state.cat && state.pane === "categories"))
488
+ ? customizeSelect(helpers, theme, nav.title, leftWidth, navOnly ? at === state.cat : navIndex === state.cat && state.pane === "categories")
448
489
  : "";
449
- const item = navOnly ? (model[start + i] || null) : (rightLines[start + i] || null);
450
490
  let right = "";
451
- if (item) {
452
- // Labels sit under a 4-column mark gutter (▸/→): the stored label
453
- // carries its → mark, focus adds ▸ in front and the rest pad two
454
- // spaces.
455
- if (navOnly) {
456
- right = customizeSelect(helpers, theme, item.title, rightWidth, start + i === position);
457
- } else if (item.muted) {
458
- right = paint(` ${item.label}`, rightWidth, "description");
459
- } else if (item.focused) {
460
- right = customizeSelect(helpers, theme, item.label, rightWidth, true);
461
- } else {
462
- right = paint(` ${item.label}`, rightWidth, "value");
463
- }
464
- } else if (!navOnly && rightLines.length === 0) {
491
+ if (navOnly) {
492
+ right = item ? customizeSelect(helpers, theme, item.title, rightWidth, at === state.cat) : "";
493
+ } else if (item && item.kind === "row") {
494
+ right = customizeSettingLine(
495
+ helpers,
496
+ theme,
497
+ item.row,
498
+ nameWidth,
499
+ rightWidth,
500
+ at === state.row[state.cat] && state.pane === "values",
501
+ );
502
+ } else if (item && item.kind === "note") {
503
+ right = paint(item.text, rightWidth, "description");
504
+ } else if (rightLines.length === 0) {
465
505
  right = paint("No settings available", rightWidth, "description");
466
506
  }
467
507
  lines.push(join(left, right));
468
- }
469
- // Bottom block: the FOCUSED choice's label in the preview title plus its
470
- // description on the next line — exactly once.
471
- const previewLabel = current.row
472
- ? (typeof current.row.preview === "string" ? current.row.preview : current.row.label)
473
- : current.category.title;
474
- const previewTitle = `Preview · ${previewLabel}`;
475
- const previewSample = current.row ? current.row.detail : "unavailable";
476
- if (previewLines === 3) {
477
- lines.push("");
478
- lines.push(compose([
479
- { kind: "label", text: "Preview" },
480
- { kind: "label", text: " · " },
481
- { kind: "value", text: previewLabel },
482
- ], inner));
483
- lines.push(paint(previewSample, inner, "description"));
484
- } else if (previewLines === 1) {
485
- lines.push(paint(previewTitle, inner, "description"));
508
+ // Pointer hits cover the pane text only: a click on a border, the title,
509
+ // the heading or the footer hits nothing and is ignored.
510
+ const rightStart = 2 + (leftWidth ? leftWidth + 3 : 0);
511
+ if (leftWidth && nav) hits.push({ kind: "category", index: navIndex, y, x: 2, end: 2 + leftWidth });
512
+ if (navOnly && item) hits.push({ kind: "category", index: at, y, x: rightStart + 2, end: rightStart + rightWidth });
513
+ else if (item && item.kind === "row") hits.push({ kind: "row", index: item.index, y, x: rightStart + 2, end: rightStart + rightWidth });
486
514
  }
487
515
  if (showHeading) {
488
516
  lines.push(customizePad(helpers, customizeFooter(helpers, theme, CUSTOMIZE_FOOTER_KEYS, inner), inner));
489
517
  }
490
- return customizeCard(helpers, theme, lines.slice(0, Math.max(0, height - 2)), w);
518
+ const shown = lines.slice(0, Math.max(0, height - 2));
519
+ state.frame = { width: w, height: shown.length + 2, hits: hits.filter((hit) => hit.y <= shown.length) };
520
+ return customizeCard(helpers, theme, shown, w);
491
521
  }
492
522
  function requestPaint() {
493
523
  try {
@@ -527,11 +557,45 @@ function createCustomizePanel({ helpers, hostTui, theme, rowsAvailable, model, d
527
557
  }
528
558
  if (customizeKeyMatches(helpers, data, ["enter", "return"])) {
529
559
  const current = focused();
530
- done({ categoryId: current.category.id, valueId: current.row ? current.row.id : null });
560
+ done({
561
+ categoryId: current.category.id,
562
+ switchId: current.row ? current.row.switchId : current.category.id,
563
+ valueId: current.row ? current.row.id : null,
564
+ });
565
+ }
566
+ }
567
+ // Pointer contract: x/y are local to this component's rendered frame, the
568
+ // card border included. A press only captures the gesture; the click that
569
+ // follows activates the hit, so a drag never applies a row by accident.
570
+ // Anything outside a pane's text is ignored, which is also the answer for a
571
+ // click on a border, the title, the heading or the footer.
572
+ function handleMouse(event) {
573
+ if (!event || event.button !== "left") return undefined;
574
+ if (event.type !== "press" && event.type !== "click") return undefined;
575
+ const frame = state.frame;
576
+ if (!frame) return undefined;
577
+ if (!Number.isFinite(event.x) || !Number.isFinite(event.y)) return undefined;
578
+ const sized = (!Number.isFinite(event.width) || event.width === frame.width)
579
+ && (!Number.isFinite(event.height) || event.height === frame.height);
580
+ if (!sized) return undefined;
581
+ const hit = frame.hits.find((entry) => entry.y === event.y && event.x >= entry.x && event.x < entry.end);
582
+ if (!hit) return undefined;
583
+ if (event.type === "press") return { handled: true, capture: true, render: false };
584
+ const target = model[state.cat];
585
+ if (hit.kind === "category") {
586
+ state.cat = hit.index;
587
+ state.pane = "categories";
588
+ return { handled: true, render: true };
531
589
  }
590
+ const row = target ? target.rows[hit.index] : null;
591
+ if (!row) return undefined;
592
+ state.pane = "values";
593
+ state.row[state.cat] = hit.index;
594
+ done({ categoryId: target.id, switchId: row.switchId, valueId: row.id });
595
+ return { handled: true, render: true };
532
596
  }
533
597
  function invalidate() {}
534
- return { render, handleInput, invalidate, state };
598
+ return { render, handleInput, handleMouse, invalidate, state };
535
599
  }
536
600
 
537
601
  module.exports = {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "herdr-gentle-shell",
3
- "version": "0.5.0",
3
+ "version": "1.1.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",
@@ -8,13 +8,13 @@
8
8
  "herdr",
9
9
  "moshi"
10
10
  ],
11
- "homepage": "https://github.com/jonasotoaguilar/herdr-gentle-agents#readme",
11
+ "homepage": "https://github.com/jonasotoaguilar/herdr-gentle-shell#readme",
12
12
  "bugs": {
13
- "url": "https://github.com/jonasotoaguilar/herdr-gentle-agents/issues"
13
+ "url": "https://github.com/jonasotoaguilar/herdr-gentle-shell/issues"
14
14
  },
15
15
  "repository": {
16
16
  "type": "git",
17
- "url": "git+https://github.com/jonasotoaguilar/herdr-gentle-agents.git"
17
+ "url": "git+https://github.com/jonasotoaguilar/herdr-gentle-shell.git"
18
18
  },
19
19
  "license": "MIT",
20
20
  "engines": {