herdr-gentle-shell 0.0.0-stage → 1.0.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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Jonathan Soto
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,461 @@
1
- # Temporary Holding Version
1
+ # Herdr Gentle Shell
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ ![Herdr Gentle Shell banner](docs/images/banner.png)
4
+
5
+ Local Herdr plugin so the sidebar recognises Pi + Gentle Shell agents.
6
+
7
+ ## What It Does
8
+
9
+ Reports per-pane agent state (`gentle` for generic activity — machine key
10
+ `working` — e.g. the orchestrator/main agent when settled with no fresh
11
+ root marker; `gentle` in pink while the principal
12
+ session actively works — even with zero
13
+ subagents — (machine display key
14
+ `orchestrating`, pink palette unchanged). The principal's own activity marker
15
+ (`gentle_principal_v1`, published while the principal session itself works and
16
+ cleared when it settles) decides the row — never the delegate count, and
17
+ never Herdr's aggregate native status (which reads `working` whenever any
18
+ delegate runs): while the principal is working it
19
+ reads `gentle` and no delegate role word wins; while the principal is idle
20
+ the oldest running delegate role shows — `explorer`, `worker`, `verify`,
21
+ `judge`, `rdd` — with the total running count in parentheses when two or
22
+ more subagents run, for example `explorer (3)`),
23
+ `ask` (three independent event legs — choice, native questionnaire, legacy rpiv — plus
24
+ executed `ask_user_question`/`ask_user_choice` tool calls (execution opens, end/result closes;
25
+ proposals never block), tool-gated `ui_prompt` dialog spans (a `custom` panel — agents view, ODD
26
+ viewer, changes view, design canvas — never counts: opening a panel is navigation, not a
27
+ question), and
28
+ permission waiting; `gentle_review` starts never speculate ask, amber/orange `?`), `blocked`, `done`, `idle`) plus compact
29
+ changes segments folded into the single row-1 heading cell (nonempty ` +N`/` -N`/` ↑N`
30
+ with leading spaces, symbols color-distinguished by `contains` rules: ` +` green for added,
31
+ ` -` red for deleted, ` ↑` blue for pull — added stays green, deleted stays red),
32
+ reduced from `gentle_*`
33
+ pane-metadata tokens. It coexists with `herdr-pi-tree` through a single-writer handoff: while
34
+ this plugin owns a pane, `herdr-pi-tree` stays disabled for that pane, so the
35
+ two never share token names or the 16-token budget. Details live in
36
+ [DESIGN.md](DESIGN.md).
37
+
38
+ ## What It Looks Like
39
+
40
+ <p align="center">
41
+ <img src="docs/images/sidebar-example.png" width="420" alt="Agents panel showing gentle states with change counts">
42
+ </p>
43
+
44
+ The Agents panel renders the active role (`worker`), the principal state (`gentle`),
45
+ and compact `+N` / `-N` change segments in one row per pane.
46
+
47
+ ## Quick Start
48
+
49
+ Prerequisites: Linux, Node >= 18, Herdr meeting `min_herdr_version` in
50
+ `herdr-plugin/herdr-plugin.toml`, and
51
+ `herdr-pi-tree` installed (it stays installed but disabled for gentle-owned
52
+ panes).
53
+
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
57
+ packages version independently and release from two tag series —
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.
61
+
62
+ Source repository: `github.com/jonasotoaguilar/herdr-gentle-shell`, the
63
+ origin that publishes both packages and creates the releases.
64
+
65
+ ### Install the Herdr plugin (always)
66
+
67
+ ```sh
68
+ herdr plugin install jonasotoaguilar/herdr-gentle-shell/herdr-plugin
69
+ ```
70
+
71
+ The Herdr side is always installed; the Pi package below is not optional
72
+ either, since the sidebar states come from it.
73
+
74
+ ### Install the Pi package
75
+
76
+ ```sh
77
+ pi install npm:herdr-gentle-shell
78
+ ```
79
+
80
+ Inside a Gentle Shell session, the same package is installed through the shell's launcher:
81
+
82
+ ```sh
83
+ gentle-shell install npm:herdr-gentle-shell
84
+ ```
85
+
86
+ Both hosts install the same npm package,
87
+ `herdr-gentle-shell` — the Pi extension that publishes the
88
+ session facts behind the sidebar states — and only the host command differs.
89
+
90
+ Running Pi sessions still need `/reload` (or a restart) to pick up the
91
+ updated extension.
92
+
93
+ ### Apply the sidebar override
94
+
95
+ ```sh
96
+ herdr plugin action invoke configure --plugin herdr-gentle-shell
97
+ ```
98
+
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.
103
+
104
+ ### Local development
105
+
106
+ Point Herdr at this checkout's plugin subdirectory (from this directory).
107
+ `herdr plugin link` only registers the directory; it runs no build.
108
+
109
+ ```sh
110
+ herdr plugin link --enabled ./herdr-plugin
111
+ herdr plugin action invoke configure --plugin herdr-gentle-shell
112
+ ```
113
+
114
+ The repository root is the Pi package (`herdr-gentle-shell`)
115
+ and `herdr-plugin/` is the Herdr plugin. Then run `/reload` in Pi to pick up
116
+ the local package.
117
+
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 .`.
120
+
121
+ ### Update
122
+
123
+ The two packages update independently. The Pi package updates with:
124
+
125
+ ```sh
126
+ pi update --extensions
127
+ ```
128
+
129
+ and the Herdr plugin updates with:
130
+
131
+ ```sh
132
+ herdr plugin update herdr-gentle-shell
133
+ ```
134
+
135
+ To move the Herdr side to an explicitly older `herdr-vX.Y.Z` release, install
136
+ that ref after removing the current one:
137
+
138
+ ```sh
139
+ herdr plugin install jonasotoaguilar/herdr-gentle-shell/herdr-plugin --ref herdr-vX.Y.Z
140
+ ```
141
+
142
+ If the installed plugin is locally linked, the remote install replaces it
143
+ automatically and warns naming the plugin id; to restore a checkout afterwards
144
+ re-link it:
145
+
146
+ ```sh
147
+ herdr plugin link --enabled ./herdr-plugin
148
+ ```
149
+
150
+ ### Removal
151
+
152
+ ```sh
153
+ herdr plugin action invoke unconfigure --plugin herdr-gentle-shell
154
+ pi remove npm:herdr-gentle-shell
155
+ herdr plugin uninstall herdr-gentle-shell
156
+ ```
157
+
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
162
+ pre-existing identical entry and unrelated settings are preserved. A foreign,
163
+ invalid, or misbound ownership record fails closed: removal warns, preserves
164
+ the entry, and still removes the plugin.
165
+
166
+ Path convention used below: `node bin/...` runs from the installed plugin
167
+ root, while `herdr-plugin/bin/...` is a repository location in this checkout.
168
+ `bin/configure.js` lives in the Herdr plugin and is no longer shipped by the
169
+ Pi package: `lib/gentle-sidebar.js` and the extension resolve the installed
170
+ Herdr plugin root through `herdr plugin list --json` (override
171
+ `GENTLE_HERDR_PLUGIN_ROOT` for isolated runs) and run that install's copy.
172
+
173
+ The `configure` action runs `node bin/configure.js --apply --reload`: it
174
+ appends one marked pi-only `[ui.sidebar.agents.rows_by_agent]` override for
175
+ canonical agent `pi` and reloads the server. Direct equivalents:
176
+
177
+ ```sh
178
+ node bin/configure.js --check
179
+ node bin/configure.js --apply
180
+ node bin/configure.js --apply --reload # apply + `herdr server reload-config`
181
+ node bin/configure.js --uninstall --reload
182
+ ```
183
+
184
+ ### Sidebar override (non-destructive, pi-only)
185
+
186
+ `bin/configure.js` manages only its marked block and never edits the
187
+ user-owned `[ui.sidebar.agents]` table it sits under. The managed override is
188
+ exactly two pi-only rows: row 1 is the native Herdr tokens `state_icon`,
189
+ `workspace`, `agent` in that order as plain native token strings (no custom
190
+ cells, no colors wired here — row-1 glyph and identity coloring, including
191
+ the native `state_icon`, is Herdr-native and not plugin-controlled); row 2
192
+ wires the eleven presence-encoded `gentle_title_*` state cells (state word
193
+ only, one current title per frame, each in its state's semantic color as
194
+ base fg with no rules; role words carry a running-count suffix above one)
195
+ followed by the three
196
+ change-segment tokens (added green `+N`, deleted red `-N`, pull blue `↑N`,
197
+ each its own color cell with no rules, never swapped). The review leg
198
+ renders the user-facing word `rdd` in blue `#89b4fa` (same as
199
+ explorer/pull; internal TaskStore role slug stays `rdd`, machine display key
200
+ and token names stay `review` — review execution is silent, never a
201
+ notification; only an actual waiting prompt renders `ask` (desktop attention
202
+ is Herdr's native `blocked` toast); the judge delegate role renders `judge` in
203
+ purple `#cba6f7` (distinct from explorer blue, verify teal, and
204
+ orchestrating pink); the error value renders `blocked`; the orchestrating
205
+ leg renders the user-facing word `gentle` (machine key stays
206
+ `orchestrating`, pink `#f5c2e7`). Remaining state colors:
207
+ working/worker amber `#f9e2af`, explorer blue `#89b4fa`, verify teal
208
+ `#94e2d5`, ask orange `#fab387`, error red `#f38ba8`, done green `#a6e3a1`,
209
+ idle grey `#7c7f93`. Added stays green and deleted stays red; the mapping
210
+ is never swapped. The custom `$gentle_heading_*` / `$gentle_project` /
211
+ `$gentle_agent` cells and `gentle_changes_summary` stay published and owned
212
+ for compatibility but are wired into no visible row.
213
+ Only one `gentle_title_*` token carries a value per frame (presence
214
+ encoding), so row 2 shows the current state word plus any nonempty change
215
+ segments while the rest render empty; native separators on row 2 are
216
+ acceptable. Row 1 holds 3 native cells and row 2 holds 14 cells (11 state
217
+ + 3 changes), each within Herdr's 16-token per-row ceiling (full block below).
218
+
219
+ ```toml
220
+ # BEGIN herdr-gentle-agents (managed; do not edit)
221
+ # Sidebar override owned by herdr-gentle-agents: two pi-only rows —
222
+ # row 1 native state_icon + workspace + agent, row 2 state word + changes.
223
+ # The parent [ui.sidebar.agents] table is user-owned and never touched here.
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_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
+ # END herdr-gentle-agents
227
+ ```
228
+
229
+ The
230
+ single row-1 heading cell mirrors the Gentle Shell SessionChanges model semantics
231
+ (write/edit tool outcomes, never `git status`, never an approximate
232
+ reaggregation): files keyed by `(root, path)` with snapshot-continuity and
233
+ unavailable counts (unavailable files stay in the file count with 0/0); `↑N` shows when the pane
234
+ branch is behind its upstream (branch-ab status only, no diff). `gentle_project`,
235
+ `gentle_changes_summary`, and the segment
236
+ tokens (`gentle_changes_added`/`_deleted`/`_pull`) stay published for
237
+ compatibility but render no visible row. `gentle`
238
+ renders for generic activity (machine key `working`): the main agent when settled with no fresh root marker or roles
239
+ (or active subs with an unsalvageable role shape and no fresh marker); pink
240
+ `gentle` (machine key `orchestrating`, pink palette unchanged) renders while the principal session actively works — even with zero subagents —
241
+ retaining running-subagent or pending-launch coverage. The principal's own
242
+ activity decides the row, never the delegate count and never Herdr's
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
246
+ `gentle_principal_v1` marker is published while the principal session itself
247
+ works and cleared when it settles. A **working principal** reads `gentle` —
248
+ pink
249
+ `orchestrating` while a fresh root marker is live — and no delegate role word
250
+ wins; an **idle principal** shows the oldest running TaskStore role
251
+ (`explorer`, `worker`, `verify`, `judge`, `rdd`), however many delegates run.
252
+ Both yield to `ask`/`rdd`/`blocked` and terminal `done` — where `done` needs
253
+ settled-plus-empty (principal settled with no running delegates and no
254
+ pending launches; a settled principal with running delegates keeps the role
255
+ word, never `done`). A role word is not a subagent label; it carries the
256
+ total running delegate count in parentheses when that count exceeds one. The
257
+ work total is a direct projection of the
258
+ Gentle Shell TaskStore `running` records (only `running` counts as
259
+ executing; queued/waiting never count), never a calculated
260
+ pending-call estimate: pending tool calls are role-only display hints (exact
261
+ in-flight subagent agent -> role slug, so task-mode launches show the active
262
+ role even at count 0) plus label correlation, and
263
+ true concurrent tasks all count. A live `running` record is never regressed
264
+ by a racy non-final status read (only the authoritative launch outcomes,
265
+ completions, and presence terminals move it), so principal activity with
266
+ live delegates keeps `gentle` while an idle principal keeps the role word; a
267
+ sanitized unknown slug exactly
268
+ equal to `working` degrades to `gentle` (the bare word `working` never
269
+ renders).
270
+ Background launches (`subagent_run` with `mode: background`) announce
271
+ lifecycle over `message_end` custom results: an ACTIVE status promotes the
272
+ start into the tasks map like a task-mode record, so an active background
273
+ worker keeps the pane on live activity and shows the worker role word rather
274
+ than settling to `idle`/`done`.
275
+ Errors render as user-facing `blocked`.
276
+ Other agents are unaffected. `--apply` refuses (exit 2, no write) when an
277
+ unmanaged `rows_by_agent` override already exists; remove or rename it, then
278
+ re-run. Writes are atomic (temp file plus rename) with a backup at
279
+ `<config>.herdr-gentle-agents.bak`. The config path resolves exactly like the installed plugin's
280
+ `bin/gentle-status.js` (`HERDR_CONFIG_PATH`, then `XDG_CONFIG_HOME`, then
281
+ the platform default).
282
+
283
+ ### Verification
284
+
285
+ ```sh
286
+ node --check herdr-plugin/bin/configure.js
287
+ node --check herdr-plugin/bin/gentle-status.js
288
+ HERDR_CONFIG_PATH=/tmp/herdr-fixture.toml node herdr-plugin/bin/configure.js --apply
289
+ HERDR_CONFIG_PATH=/tmp/herdr-fixture.toml node herdr-plugin/bin/configure.js --check
290
+ HERDR_CONFIG_PATH=/tmp/herdr-fixture.toml node herdr-plugin/bin/configure.js --uninstall
291
+ herdr plugin action invoke configure --plugin herdr-gentle-shell
292
+ herdr server reload-config
293
+ ```
294
+
295
+ Live check: with the daemon running and the override applied, open a Pi pane
296
+ and confirm row 2 shows pink `gentle` (machine key
297
+ `orchestrating`) while
298
+ the principal session actively works — even with zero subagents — and keeps
299
+ `gentle` while its delegates run (a role word such as `worker`, `explorer`,
300
+ `verify`, `judge` shows once the principal itself is idle), row 1 shows
301
+ the single heading cell (`● <project>` plus ` +N`/` -N`/` ↑N` inline, zero `·`) after edits / when behind upstream; then `ask` on an open
302
+ question (choice / native-questionnaire / legacy event legs, executed `ask_user_question`/`ask_user_choice`, tool-gated `ui_prompt` dialog spans (a `custom` panel — agents view, ODD viewer, changes view, design canvas — never counts, because opening a panel is navigation, not a question), or permission waiting; `gentle_review` starts never speculate ask) and `blocked` on error. `rdd` (machine key `review`) applies during acknowledged native capture/group execution only (`reviewerRunAcknowledged: true` at execution start — never proposal, never forecast-only, never `correctionLines` planning, never `gentle_review`/`gentle_review_scope` in any operation; no hook/sidebar signal observed; unknown legacy shapes stay dark; call-id tracked so thrown/cancelled calls still clear, read-only `assess` excluded). Bounded approximation: the acknowledged interval contains preparation and admission; no exact reviewer internal events exist today. The orchestrator-host `ask_user_choice` prompt emits no Pi tool/event observable by this extension and stays covered only by the event legs above. Never point the fixture commands at the live config: keep
303
+ `HERDR_CONFIG_PATH` on a temp file for apply/uninstall checks.
304
+
305
+ ## Core Workflow
306
+
307
+ A Pi sidecar extension publishes `gentle_*` tokens per pane; a plugin daemon
308
+ reduces the Herdr snapshot to sidebar state on a poll cadence. Same transport
309
+ and TTL discipline as `herdr-pi-tree`, new token names, no new socket or
310
+ webhook. `[[startup]] node bin/gentle-status.js` (no args) is the polling-daemon
311
+ bootstrap (ensures the adaptive poll daemon is running: 10 s baseline,
312
+ `GENTLE_STATUS_POLL_MS`-overridable, with a 2 s fast cycle while recent ask
313
+ activity or send/publish failures are observed); `[[events]] on =
314
+ "pane.agent_detected"`, `pane.agent_status_changed`, `pane.exited`, and
315
+ `pane.closed` each run `node bin/gentle-status.js --refresh`, which ensures the
316
+ adaptive poll daemon is running and requests one coalesced immediate frame
317
+ so a newly opened project name/state renders without waiting for the next
318
+ poll tick. Polling stays the fallback for every lifecycle signal, so a missed
319
+ or undelivered event never sticks. Read-only
320
+ supervision triage ships beside it: the `doctor` and `whois` plugin actions
321
+ (`node bin/gentle-doctor.js`, `node bin/gentle-whois.js`) plus the explicit-pane
322
+ `node bin/gentle-trace.js <pane-id>` CLI — all read-only, none mutating state.
323
+ See [DESIGN.md](DESIGN.md) §4 (producer) and §5 (consumer), and
324
+ [docs/diagnostics.md](docs/diagnostics.md) for the triage commands.
325
+
326
+ ## Key Features You Should Know About
327
+
328
+ - Full v1 state matrix including the root-session `orchestrating` marker
329
+ (pink `●` + user-facing word `gentle`, while the principal session actively
330
+ works — even with zero subagents — retaining subagent/pending coverage;
331
+ yielding only to `ask`/`rdd`/`blocked` and terminal `done` (done needs
332
+ settled-plus-empty)) and the authoritative TaskStore role signal
333
+ (`explorer` / `worker` / `verify` / `judge` / `rdd` from `TaskRecord.agent`,
334
+ oldest running first by immutable first-seen, shown while the principal
335
+ itself is idle — a working principal keeps `gentle`, asserted by the
336
+ principal-only `gentle_principal_v1` marker rather than by the delegate
337
+ count or Herdr's aggregate native status; `gentle` (machine
338
+ key `working`) for the principal's own working state; an unknown delegation
339
+ keeps its original sanitized name, 32-char bound — never a generic
340
+ collapse), with a running-count suffix on role labels when two or more
341
+ delegates run, `ask` on blocked user input,
342
+ `rdd` during native review execution (machine key stays `review`; execution
343
+ is silent — desktop attention fires only for a waiting `ask` intent, as
344
+ Herdr's native toast), and
345
+ user-facing `blocked` for errors.
346
+ - Single-cell row-1 heading (`<icon> <project>` plus ` +N`/` -N`/` ↑N`
347
+ inline, exactly one nonempty cell so zero `·` separators; white base with
348
+ `contains` rules keeping ` +` green (added), ` -` red (deleted,
349
+ leading-space match), ` ↑` blue (pull)) mirroring the Gentle Shell
350
+ SessionChanges model semantics over Gentle tool outcomes, never `git`
351
+ status and never an approximate reaggregation (root+path continuity and
352
+ unavailable counts); behind-upstream `↑N` from branch-ab status only.
353
+ Session-change tokens are refreshed/cleared from the current Gentle Shell
354
+ session model and never carried across sessions.
355
+ - Single-writer coexistence with `herdr-pi-tree`: no shared token names, no
356
+ dual-write, scoped sweep of own tokens on handover.
357
+ - Gentle mode is enabled by default: while selected, this extension is the single publisher of native `pane.report_agent` (`working`/`blocked`/`idle`) alongside its metadata beats, with session path-or-id binding, monotonic seq, and a serial latest-wins coalesced queue. Parity contract: `working` carries the specific working role in the message (oldest running role word — known short word, unknown sanitized name, or `gentle` with no delegation; never bare generic `working`; machine keys unchanged); terminal `idle` fires only on a truly empty settle (principal settled plus zero running/queued plus zero pending plus zero live background jobs plus no human-wait prompt; settle-with-delegates/pending/jobs stays `working`, emitted once). Live background jobs (`bash_background` / `monitor`) are read from Gentle Shell's session-scoped `gentle-ai:jobs-sidebar` bus event, so waiting on a CI run or a long command keeps the row on `gentle` and never reaches `done`; `blocked` fires only for a real 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 — while the sidebar row's working-vs-idle decision reads the principal-only `gentle_principal_v1` marker, so an idle principal with a running delegate shows the delegate role word instead of `gentle`. Our code never emits `done`/`finished` native states or a Herdr notification (the opt-in Moshi replacement below is a separate, off-by-default channel): the host owns finished text on `done`, `blocked`/unknown presentation, sound, and all desktop attention toasts (ask + finish) — there is no consumer toast path left to dedup. Single publisher by design: the managed native extension file stays on disk and is excluded through an ownership-bound Pi settings entry while Gentle mode is selected. `node bin/gentle-sidebar.js disable` removes only our owned exclusion and managed rows, gates our producer/daemon, and hands the sidebar back to the native publisher (running Pi sessions need `/reload`); never run both publishers on the same pane. Limits (unverified, host-owned): the host `idle`→`done`→`finished` mapping and unknown-state handling are owned by Herdr.
358
+ - Sidebar switch (`enable` / `disable` / `status` / `toggle`):
359
+ `node bin/gentle-sidebar.js <verb>` picks between this plugin's sidebar rows
360
+ and the native Herdr sidebar. `status` is read-only; `enable` converges the
361
+ managed Herdr rows and records the owned native-extension exclusion;
362
+ `disable` removes only our owned rows and exclusion, never a user table.
363
+ See [docs/sidebar-control.md](docs/sidebar-control.md).
364
+ - In-Pi switches (`/herdr-gentle:customize`): exactly two toggles, both local
365
+ state and both reachable from a plain Pi session outside a Herdr pane. With
366
+ no argument the command opens the restored floating two-pane panel
367
+ (`Herdr Sidebar` and `Moshi notifications`; `←/→` or `Tab` moves between the
368
+ category and value panes, `↑/↓` or `j/k` moves the cursor, `Enter` toggles the
369
+ focused switch and `Esc` closes). Each switch is one row that reads its stored
370
+ state, so `On` becomes `Off` and back in a single key press. The plain two-step menu stays as the fallback
371
+ when the TUI helpers or `ctx.ui.custom` are unavailable.
372
+ `Sidebar agent rows` drives the Herdr plugin's own `bin/configure.js`
373
+ (`--check` to read, `--apply --reload` / `--uninstall --reload` to change) and
374
+ never edits the Herdr config itself; `Moshi notifications` writes the flag
375
+ below and adds or removes the `-extensions/moshi-hooks.ts` exclusion in Pi's
376
+ `settings.json`, running the `moshi-hook` pairing gate before enabling (a
377
+ refusal writes nothing) and reloading Pi only when that settings entry
378
+ actually changed. `/herdr-gentle:customize status` prints one read-only line
379
+ (`customize status: sidebar=<on|off|unknown> moshi=<on|off>`); an unknown
380
+ argument, Esc, or a cancelled menu writes nothing. A sidebar verdict of
381
+ `unknown` is never a refusal: the panel says the state is unknown and
382
+ choosing `On` still runs the apply step, reporting that step's own error
383
+ when it refuses (the same behavior the menu always had). The run-by-hand
384
+ equivalents are the CLI and the flag file shown below.
385
+ - Optional Moshi replacement (off by default): one flag file,
386
+ `<state dir>/gentle-moshi.json` containing `{"enabled":true}` (the state dir
387
+ is `GENTLE_STATUS_STATE_DIR`, else the stored `herdr-gentle-agents` state dir
388
+ under `$XDG_STATE_HOME/herdr` or `~/.local/state/herdr`):
389
+
390
+ ```sh
391
+ dir="${GENTLE_STATUS_STATE_DIR:-${XDG_STATE_HOME:-$HOME/.local/state}/herdr/plugins/herdr-gentle-agents}"
392
+ mkdir -p "$dir" && echo '{"enabled":true}' > "$dir/gentle-moshi.json"
393
+ ```
394
+
395
+ `/herdr-gentle:customize` → `Moshi notifications` writes this flag for you,
396
+ and enabling there first requires the `moshi-hook` CLI on `PATH` with
397
+ `moshi-hook status --json` reporting `paired: true` (an unpaired host is
398
+ refused and nothing is written).
399
+
400
+ With the flag on, this plugin **replaces the
401
+ Moshi-managed Pi hook**: the same Moshi integration (Chat View, Live Activity,
402
+ session row, terminal context, phone-side approvals) keeps working, but
403
+ notifications follow this plugin's policy — one when Pi really needs your
404
+ input (`ask`) and one when Pi really finishes. Nothing per prompt, nothing per
405
+ turn. If `extensions/moshi-hooks.ts` is installed, add
406
+ `-extensions/moshi-hooks.ts` to the `extensions` list in your Pi
407
+ `settings.json` so the Moshi-managed hook cannot notify in parallel; that edit
408
+ leaves every other settings key and entry untouched. Removal of the flag (or
409
+ `{"enabled":false}`) silences this channel immediately — the flag is re-read
410
+ per event — and restoring the hook entry brings the original notifier back.
411
+ Moshi owns pairing and credentials; this plugin never
412
+ reads or stores a token, an absent daemon or unpaired host is a silent
413
+ no-op, and Pi is never interrupted by a Moshi failure.
414
+ - Delegation completion reconciled from Gentle Shell presence files, not chat
415
+ delivery: a delegate resolves only from an explicit terminal status or a
416
+ witnessed absence in a strictly newer verified activity generation of the
417
+ same session, bound to an immutable per-task execution epoch (new launch,
418
+ resume, or inactive-to-active transition — never a progress read or
419
+ heartbeat tick). Ambiguous, stale, or oversize snapshots never clear
420
+ tasks. Known limits: delegates that launch and finish between presence
421
+ publications never appear and still depend on chat delivery, and
422
+ absence-driven completion records `completed` without latching an error.
423
+ - TTL-bounded tokens: stale panes fall back to native `idle`.
424
+ - Herdr session opener (`herdr_session_open`): opens a Herdr panel running a
425
+ Pi session at a path. A linked Git worktree opens as a **worktree panel**
426
+ (reusing the workspace Herdr already has for that checkout); a repository's
427
+ primary checkout, a subdirectory or any generic directory opens as a
428
+ **normal panel**. Panel kind is decided from git, the pane Herdr names is
429
+ verified to belong to its workspace and to sit in the requested path before
430
+ Pi starts, and (unless `notify: false`) the caller is woken when that session
431
+ really finishes. The other worktree tools and the ODD and issues panels live
432
+ in `odd-worktree` now; the sidebar and Moshi switches stayed here and are
433
+ reached through `/herdr-gentle:customize`. See
434
+ [docs/herdr-session-open.md](docs/herdr-session-open.md).
435
+
436
+ ## Documentation
437
+
438
+ | Your task | Start here |
439
+ | --- | --- |
440
+ | Protocol, token grammar, reducer, and coexistence rules | [DESIGN.md](DESIGN.md) |
441
+ | Compatibility, migration, and rollback | [DESIGN.md](DESIGN.md) §9 |
442
+ | Open decisions blocking implementation | [DESIGN.md](DESIGN.md) §10 |
443
+ | Supervision triage (read-only doctor/trace/whois) | [docs/diagnostics.md](docs/diagnostics.md) |
444
+ | Lifecycle recovery and interruption (polling fallback) | [docs/supervision.md](docs/supervision.md) |
445
+ | Sidebar switch (`bin/gentle-sidebar.js`) | [docs/sidebar-control.md](docs/sidebar-control.md) |
446
+ | Herdr session opener (`herdr_session_open`) | [docs/herdr-session-open.md](docs/herdr-session-open.md) |
447
+ | Performance trace and its report | [docs/performance-trace.md](docs/performance-trace.md) |
448
+
449
+ ## Next Steps
450
+
451
+ - Ship the Pi producer extension (`extensions/`) and the Herdr consumer daemon
452
+ (`herdr-plugin/bin/` plus `herdr-plugin/lib/`); the daemon ships, the sidebar
453
+ override installs via the `configure` plugin action above.
454
+ - Resolve the open decisions in [DESIGN.md](DESIGN.md) §10 before implementing
455
+ against them.
456
+ - Live sidebar eyeball with subagents/`ask` remains the final acceptance check
457
+ (see Verification above).
458
+
459
+ ## License
460
+
461
+ MIT — see [LICENSE](LICENSE).
package/bin/.gitkeep ADDED
File without changes
@@ -0,0 +1,53 @@
1
+ #!/usr/bin/env node
2
+ 'use strict';
3
+
4
+ // Package-side CLI for the Gentle/native sidebar switch (S7):
5
+ // node bin/gentle-sidebar.js (enable|disable|status|toggle) [--json]
6
+ //
7
+ // The only supported sidebar switch in this package; see lib/gentle-sidebar.js
8
+ // and docs/sidebar-control.md. Isolated use:
9
+ // GENTLE_STATUS_STATE_DIR=/tmp/s PI_CODING_AGENT_DIR=/tmp/a
10
+ // HERDR_CONFIG_PATH=/tmp/c.toml node bin/gentle-sidebar.js status
11
+ //
12
+ // Exit codes: 0 success; 1 operational failure; 2 usage failure.
13
+
14
+ const sidebar = require('../lib/gentle-sidebar.js');
15
+
16
+ function usage() {
17
+ console.error('usage: node bin/gentle-sidebar.js (enable|disable|status|toggle) [--json]');
18
+ }
19
+
20
+ function main() {
21
+ const args = process.argv.slice(2);
22
+ const verb = args[0];
23
+ const json = args.includes('--json');
24
+ for (const flag of args.slice(1)) {
25
+ if (flag !== '--json') {
26
+ console.error(`gentle-sidebar: unknown flag ${flag}`);
27
+ usage();
28
+ process.exit(2);
29
+ }
30
+ }
31
+ let result;
32
+ if (verb === 'enable') result = sidebar.enable();
33
+ else if (verb === 'disable') result = sidebar.disable();
34
+ else if (verb === 'status') result = sidebar.status();
35
+ else if (verb === 'toggle') {
36
+ const mode = sidebar.readMode();
37
+ if (mode.state === 'malformed') {
38
+ console.error(`gentle-sidebar: mode file is malformed (expected {"version":1,"enabled":boolean}); fix or remove it first.`);
39
+ process.exit(1);
40
+ }
41
+ result = mode.publish ? sidebar.disable() : sidebar.enable();
42
+ } else {
43
+ console.error(`gentle-sidebar: unknown verb ${verb === undefined ? '(none)' : JSON.stringify(verb)}`);
44
+ usage();
45
+ process.exit(2);
46
+ }
47
+ if (json) console.log(JSON.stringify({ code: result.code, message: result.message }));
48
+ else if (result.code === 0) console.log(result.message);
49
+ else console.error(result.message);
50
+ process.exit(result.code);
51
+ }
52
+
53
+ if (require.main === module) main();
@@ -0,0 +1,64 @@
1
+ # Diagnostics (read-only)
2
+
3
+ Three standalone Node CLIs for supervision triage. All are read-only:
4
+ they never create the state directory, write tokens/config/ledger, start
5
+ or stop the daemon, read transcripts, or dump private raw tokens, task
6
+ labels, or review verdicts. Herdr is reached only through fixed-argv
7
+ `HERDR_BIN_PATH` list commands; no socket calls are made or claimed.
8
+
9
+ ## Commands
10
+
11
+ - `node herdr-plugin/bin/gentle-doctor.js [--help]` — daemon pidfile liveness
12
+ (signal 0; presence alone is not liveness), producer/token freshness
13
+ from one `herdr agent list` snapshot, managed sidebar override marker
14
+ scan. Prints `pass:`/`warn:`/`fail:` lines plus actionable `remedy:`
15
+ lines. When native mode is selected
16
+ (`gentle-sidebar-mode.json` holding `{"version":1,"enabled":false}`), skips
17
+ inactive Gentle daemon/producer/override checks and still checks snapshot
18
+ availability. An invalid mode file fails closed without exposing its contents.
19
+ Exit 0 pass/warn only, 1 any fail or failed snapshot, 2 bad args.
20
+ - `node herdr-plugin/bin/gentle-trace.js <pane-id>` — one JSON document for a pane
21
+ (e.g. `wBG:p1`): safe ids, agent, display, roles, count, freshness
22
+ booleans, identity session hash, and the safe interruption record.
23
+ A disappeared agent whose pane is still present traces as
24
+ `display: interrupted` / `label: Interrumpido` with the safe record;
25
+ confirmed pane absence stays `pane_not_found`. A failed snapshot or
26
+ unknown pane is a JSON `ok:false` failure, never an empty success.
27
+ Exit 0 traced, 1 unavailable/not-found, 2 bad args.
28
+ - `node herdr-plugin/bin/gentle-whois.js [--all]` — concise `PANE AGENT STATE ROLES
29
+ WORKSPACE` table in stable pane order, fitted to narrow widths with
30
+ control characters stripped. Default lists only plugin-owned panes;
31
+ `--all` also lists native/foreign panes without task names.
32
+ `Interrumpido` is diagnostic-only (valid ledger record while the pane
33
+ shows no fresh activity); the sidebar vocabulary is unchanged. Ledger
34
+ rows for panes missing from the agent list are confirmed with one
35
+ extra `pane list` call: confirmed presence renders the row, confirmed
36
+ absence shows no ghost, and a failed pane list fails explicitly.
37
+ Exit 0 rendered, 1 snapshot unavailable, 2 bad args.
38
+
39
+ Invalid arguments are rejected with exit 2 before any state read or
40
+ Herdr call. A failed `agent list` snapshot is always a failure (exit 1),
41
+ distinct from an empty-but-successful view.
42
+
43
+ ## Environment
44
+
45
+ - `HERDR_BIN_PATH` — Herdr binary (default `herdr`).
46
+ - `GENTLE_STATUS_STATE_DIR` (else `HERDR_PLUGIN_STATE_DIR`, else the
47
+ default plugins state dir) — read for `gentle-status.pid` and the
48
+ `gentle-sidebar-mode.json` (`{version:1,enabled:boolean}`; missing defaults
49
+ to Gentle mode), and the `gentle-interruptions.json` ledger
50
+ (`{version:1,panes:{...}}` with only
51
+ identity hash, whitelisted unfinished displays, finite timestamps, and
52
+ reason `agent_disappeared`). A missing ledger is tolerated; a malformed
53
+ one is ignored with a warning and its arbitrary fields never exposed.
54
+ - `HERDR_CONFIG_PATH` — read for the managed sidebar marker scan.
55
+ - `COLUMNS` — whois table width (default 80, clamped 20–512).
56
+
57
+ ## Shared library
58
+
59
+ `herdr-plugin/lib/gentle-diagnostics.js` holds the read-only helpers (path
60
+ resolution without mkdir, bounded reads, sanitization/width fitting,
61
+ strict ledger validation, pidfile signal-0 check, per-pane whitelist
62
+ summary via `herdr-plugin/lib/gentle-tokens.js`). It exposes only safe pane/workspace
63
+ ids, validated agent names, the agent_status enum, role slugs, running
64
+ counts, freshness booleans, and the identity hash.