herdr-gentle-shell 0.0.0-stage → 0.5.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,539 @@
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
+ 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
59
+ 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.
63
+
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.
68
+
69
+ Installer usage:
70
+ `install.sh [--ref REF] [--pi-source auto|npm|git] [--allow-downgrade] [--uninstall] [--help]`
71
+
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.
76
+
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.
80
+
81
+ ### Install in Pi
82
+
83
+ ```sh
84
+ pi install npm:herdr-gentle-shell
85
+ ```
86
+
87
+ ### Install in Gentle Shell
88
+
89
+ ```sh
90
+ gentle-shell install npm:herdr-gentle-shell
91
+ ```
92
+
93
+ Both hosts install the same npm package,
94
+ `herdr-gentle-shell` — the Pi extension that publishes the
95
+ 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
+
102
+ ```sh
103
+ curl -fsSL https://github.com/jonasotoaguilar/herdr-gentle-agents/releases/latest/download/install.sh | sh
104
+ ```
105
+
106
+ With no `--ref` the installer resolves the newest `herdr-vX.Y.Z` release tag automatically.
107
+
108
+ ### Pinned install (explicit tag)
109
+
110
+ ```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
112
+ ```
113
+
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.
173
+
174
+ ### Local development
175
+
176
+ Point Herdr at this checkout's plugin subdirectory (from this directory).
177
+ `herdr plugin link` only registers the directory; it runs no build.
178
+
179
+ ```sh
180
+ herdr plugin link --enabled ./herdr-plugin
181
+ herdr plugin action invoke configure --plugin herdr-gentle-shell
182
+ ```
183
+
184
+ The repository root is the Pi package (`herdr-gentle-shell`)
185
+ and `herdr-plugin/` is the Herdr plugin. Then run `/reload` in Pi to pick up
186
+ the local package.
187
+
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`.
191
+
192
+ ### Update
193
+
194
+ The two packages update independently. The Pi package updates with:
195
+
196
+ ```sh
197
+ pi update --extensions
198
+ ```
199
+
200
+ and the Herdr plugin updates with:
201
+
202
+ ```sh
203
+ herdr plugin update herdr-gentle-shell
204
+ ```
205
+
206
+ To move the Herdr side to an explicitly older `herdr-vX.Y.Z` release, pass
207
+ `--ref` with `--allow-downgrade`:
208
+
209
+ ```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
211
+ ```
212
+
213
+ Without `--allow-downgrade`, installing an older Herdr version than the
214
+ installed one aborts naming both versions.
215
+
216
+ If the installed plugin is locally linked, the remote install replaces it
217
+ automatically and warns naming the plugin id; to restore a checkout afterwards
218
+ re-link it:
219
+
220
+ ```sh
221
+ herdr plugin link --enabled ./herdr-plugin
222
+ ```
223
+
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
+ ### Removal
228
+
229
+ ```sh
230
+ curl -fsSL https://github.com/jonasotoaguilar/herdr-gentle-agents/releases/latest/download/install.sh | sh -s -- --uninstall
231
+ ```
232
+
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
240
+ pre-existing identical entry and unrelated settings are preserved. A foreign,
241
+ invalid, or misbound ownership record fails closed: uninstall warns, preserves
242
+ the entry, and still removes the plugin.
243
+
244
+ Path convention used below: `node bin/...` runs from the installed plugin
245
+ root, while `herdr-plugin/bin/...` is a repository location in this checkout.
246
+ `bin/configure.js` lives in the Herdr plugin and is no longer shipped by the
247
+ Pi package: `lib/gentle-sidebar.js` and the extension resolve the installed
248
+ Herdr plugin root through `herdr plugin list --json` (override
249
+ `GENTLE_HERDR_PLUGIN_ROOT` for isolated runs) and run that install's copy.
250
+
251
+ The `configure` action runs `node bin/configure.js --apply --reload`: it
252
+ appends one marked pi-only `[ui.sidebar.agents.rows_by_agent]` override for
253
+ canonical agent `pi` and reloads the server. Direct equivalents:
254
+
255
+ ```sh
256
+ node bin/configure.js --check
257
+ node bin/configure.js --apply
258
+ node bin/configure.js --apply --reload # apply + `herdr server reload-config`
259
+ node bin/configure.js --uninstall --reload
260
+ ```
261
+
262
+ ### Sidebar override (non-destructive, pi-only)
263
+
264
+ `bin/configure.js` manages only its marked block and never edits the
265
+ user-owned `[ui.sidebar.agents]` table it sits under. The managed override is
266
+ exactly two pi-only rows: row 1 is the native Herdr tokens `state_icon`,
267
+ `workspace`, `agent` in that order as plain native token strings (no custom
268
+ cells, no colors wired here — row-1 glyph and identity coloring, including
269
+ the native `state_icon`, is Herdr-native and not plugin-controlled); row 2
270
+ wires the eleven presence-encoded `gentle_title_*` state cells (state word
271
+ only, one current title per frame, each in its state's semantic color as
272
+ base fg with no rules; role words carry a running-count suffix above one)
273
+ followed by the three
274
+ change-segment tokens (added green `+N`, deleted red `-N`, pull blue `↑N`,
275
+ each its own color cell with no rules, never swapped). The review leg
276
+ renders the user-facing word `rdd` in blue `#89b4fa` (same as
277
+ explorer/pull; internal TaskStore role slug stays `rdd`, machine display key
278
+ and token names stay `review` — review execution is silent, never a
279
+ notification; only an actual waiting prompt renders `ask` (desktop attention
280
+ is Herdr's native `blocked` toast); the judge delegate role renders `judge` in
281
+ purple `#cba6f7` (distinct from explorer blue, verify teal, and
282
+ orchestrating pink); the error value renders `blocked`; the orchestrating
283
+ leg renders the user-facing word `gentle` (machine key stays
284
+ `orchestrating`, pink `#f5c2e7`). Remaining state colors:
285
+ working/worker amber `#f9e2af`, explorer blue `#89b4fa`, verify teal
286
+ `#94e2d5`, ask orange `#fab387`, error red `#f38ba8`, done green `#a6e3a1`,
287
+ idle grey `#7c7f93`. Added stays green and deleted stays red; the mapping
288
+ is never swapped. The custom `$gentle_heading_*` / `$gentle_project` /
289
+ `$gentle_agent` cells and `gentle_changes_summary` stay published and owned
290
+ for compatibility but are wired into no visible row.
291
+ Only one `gentle_title_*` token carries a value per frame (presence
292
+ encoding), so row 2 shows the current state word plus any nonempty change
293
+ segments while the rest render empty; native separators on row 2 are
294
+ acceptable. Row 1 holds 3 native cells and row 2 holds 14 cells (11 state
295
+ + 3 changes), each within Herdr's 16-token per-row ceiling (full block below).
296
+
297
+ ```toml
298
+ # BEGIN herdr-gentle-agents (managed; do not edit)
299
+ # Sidebar override owned by herdr-gentle-agents: two pi-only rows —
300
+ # row 1 native state_icon + workspace + agent, row 2 state word + changes.
301
+ # The parent [ui.sidebar.agents] table is user-owned and never touched here.
302
+ [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" }]]
304
+ # END herdr-gentle-agents
305
+ ```
306
+
307
+ The
308
+ single row-1 heading cell mirrors the Gentle Shell SessionChanges model semantics
309
+ (write/edit tool outcomes, never `git status`, never an approximate
310
+ reaggregation): files keyed by `(root, path)` with snapshot-continuity and
311
+ unavailable counts (unavailable files stay in the file count with 0/0); `↑N` shows when the pane
312
+ branch is behind its upstream (branch-ab status only, no diff). `gentle_project`,
313
+ `gentle_changes_summary`, and the segment
314
+ tokens (`gentle_changes_added`/`_deleted`/`_pull`) stay published for
315
+ compatibility but render no visible row. `gentle`
316
+ renders for generic activity (machine key `working`): the main agent when settled with no fresh root marker or roles
317
+ (or active subs with an unsalvageable role shape and no fresh marker); pink
318
+ `gentle` (machine key `orchestrating`, pink palette unchanged) renders while the principal session actively works — even with zero subagents —
319
+ retaining running-subagent or pending-launch coverage. The principal's own
320
+ activity decides the row, never the delegate count and never Herdr's
321
+ aggregate native status (the work token counts running delegates, and the
322
+ native status reads `working` for any running delegate, pending launch, or
323
+ live job — so neither can say the principal works): the dedicated
324
+ `gentle_principal_v1` marker is published while the principal session itself
325
+ works and cleared when it settles. A **working principal** reads `gentle` —
326
+ pink
327
+ `orchestrating` while a fresh root marker is live — and no delegate role word
328
+ wins; an **idle principal** shows the oldest running TaskStore role
329
+ (`explorer`, `worker`, `verify`, `judge`, `rdd`), however many delegates run.
330
+ Both yield to `ask`/`rdd`/`blocked` and terminal `done` — where `done` needs
331
+ settled-plus-empty (principal settled with no running delegates and no
332
+ pending launches; a settled principal with running delegates keeps the role
333
+ word, never `done`). A role word is not a subagent label; it carries the
334
+ total running delegate count in parentheses when that count exceeds one. The
335
+ work total is a direct projection of the
336
+ Gentle Shell TaskStore `running` records (only `running` counts as
337
+ executing; queued/waiting never count), never a calculated
338
+ pending-call estimate: pending tool calls are role-only display hints (exact
339
+ in-flight subagent agent -> role slug, so task-mode launches show the active
340
+ role even at count 0) plus label correlation, and
341
+ true concurrent tasks all count. A live `running` record is never regressed
342
+ by a racy non-final status read (only the authoritative launch outcomes,
343
+ completions, and presence terminals move it), so principal activity with
344
+ live delegates keeps `gentle` while an idle principal keeps the role word; a
345
+ sanitized unknown slug exactly
346
+ equal to `working` degrades to `gentle` (the bare word `working` never
347
+ renders).
348
+ Background launches (`subagent_run` with `mode: background`) announce
349
+ lifecycle over `message_end` custom results: an ACTIVE status promotes the
350
+ start into the tasks map like a task-mode record, so an active background
351
+ worker keeps the pane on live activity and shows the worker role word rather
352
+ than settling to `idle`/`done`.
353
+ Errors render as user-facing `blocked`.
354
+ Other agents are unaffected. `--apply` refuses (exit 2, no write) when an
355
+ unmanaged `rows_by_agent` override already exists; remove or rename it, then
356
+ re-run. Writes are atomic (temp file plus rename) with a backup at
357
+ `<config>.herdr-gentle-agents.bak`. The config path resolves exactly like the installed plugin's
358
+ `bin/gentle-status.js` (`HERDR_CONFIG_PATH`, then `XDG_CONFIG_HOME`, then
359
+ the platform default).
360
+
361
+ ### Verification
362
+
363
+ ```sh
364
+ node --check herdr-plugin/bin/configure.js
365
+ node --check herdr-plugin/bin/gentle-status.js
366
+ HERDR_CONFIG_PATH=/tmp/herdr-fixture.toml node herdr-plugin/bin/configure.js --apply
367
+ HERDR_CONFIG_PATH=/tmp/herdr-fixture.toml node herdr-plugin/bin/configure.js --check
368
+ HERDR_CONFIG_PATH=/tmp/herdr-fixture.toml node herdr-plugin/bin/configure.js --uninstall
369
+ herdr plugin action invoke configure --plugin herdr-gentle-shell
370
+ herdr server reload-config
371
+ ```
372
+
373
+ Live check: with the daemon running and the override applied, open a Pi pane
374
+ and confirm row 2 shows pink `gentle` (machine key
375
+ `orchestrating`) while
376
+ the principal session actively works — even with zero subagents — and keeps
377
+ `gentle` while its delegates run (a role word such as `worker`, `explorer`,
378
+ `verify`, `judge` shows once the principal itself is idle), row 1 shows
379
+ the single heading cell (`● <project>` plus ` +N`/` -N`/` ↑N` inline, zero `·`) after edits / when behind upstream; then `ask` on an open
380
+ 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
381
+ `HERDR_CONFIG_PATH` on a temp file for apply/uninstall checks.
382
+
383
+ ## Core Workflow
384
+
385
+ A Pi sidecar extension publishes `gentle_*` tokens per pane; a plugin daemon
386
+ reduces the Herdr snapshot to sidebar state on a poll cadence. Same transport
387
+ and TTL discipline as `herdr-pi-tree`, new token names, no new socket or
388
+ webhook. `[[startup]] node bin/gentle-status.js` (no args) is the polling-daemon
389
+ bootstrap (ensures the adaptive poll daemon is running: 10 s baseline,
390
+ `GENTLE_STATUS_POLL_MS`-overridable, with a 2 s fast cycle while recent ask
391
+ activity or send/publish failures are observed); `[[events]] on =
392
+ "pane.agent_detected"`, `pane.agent_status_changed`, `pane.exited`, and
393
+ `pane.closed` each run `node bin/gentle-status.js --refresh`, which ensures the
394
+ adaptive poll daemon is running and requests one coalesced immediate frame
395
+ so a newly opened project name/state renders without waiting for the next
396
+ poll tick. Polling stays the fallback for every lifecycle signal, so a missed
397
+ or undelivered event never sticks. Read-only
398
+ supervision triage ships beside it: the `doctor` and `whois` plugin actions
399
+ (`node bin/gentle-doctor.js`, `node bin/gentle-whois.js`) plus the explicit-pane
400
+ `node bin/gentle-trace.js <pane-id>` CLI — all read-only, none mutating state.
401
+ See [DESIGN.md](DESIGN.md) §4 (producer) and §5 (consumer), and
402
+ [docs/diagnostics.md](docs/diagnostics.md) for the triage commands.
403
+
404
+ ## Key Features You Should Know About
405
+
406
+ - Full v1 state matrix including the root-session `orchestrating` marker
407
+ (pink `●` + user-facing word `gentle`, while the principal session actively
408
+ works — even with zero subagents — retaining subagent/pending coverage;
409
+ yielding only to `ask`/`rdd`/`blocked` and terminal `done` (done needs
410
+ settled-plus-empty)) and the authoritative TaskStore role signal
411
+ (`explorer` / `worker` / `verify` / `judge` / `rdd` from `TaskRecord.agent`,
412
+ oldest running first by immutable first-seen, shown while the principal
413
+ itself is idle — a working principal keeps `gentle`, asserted by the
414
+ principal-only `gentle_principal_v1` marker rather than by the delegate
415
+ count or Herdr's aggregate native status; `gentle` (machine
416
+ key `working`) for the principal's own working state; an unknown delegation
417
+ keeps its original sanitized name, 32-char bound — never a generic
418
+ collapse), with a running-count suffix on role labels when two or more
419
+ delegates run, `ask` on blocked user input,
420
+ `rdd` during native review execution (machine key stays `review`; execution
421
+ is silent — desktop attention fires only for a waiting `ask` intent, as
422
+ Herdr's native toast), and
423
+ user-facing `blocked` for errors.
424
+ - Single-cell row-1 heading (`<icon> <project>` plus ` +N`/` -N`/` ↑N`
425
+ inline, exactly one nonempty cell so zero `·` separators; white base with
426
+ `contains` rules keeping ` +` green (added), ` -` red (deleted,
427
+ leading-space match), ` ↑` blue (pull)) mirroring the Gentle Shell
428
+ SessionChanges model semantics over Gentle tool outcomes, never `git`
429
+ status and never an approximate reaggregation (root+path continuity and
430
+ unavailable counts); behind-upstream `↑N` from branch-ab status only.
431
+ Session-change tokens are refreshed/cleared from the current Gentle Shell
432
+ session model and never carried across sessions.
433
+ - Single-writer coexistence with `herdr-pi-tree`: no shared token names, no
434
+ dual-write, scoped sweep of own tokens on handover.
435
+ - 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.
436
+ - Sidebar switch (`enable` / `disable` / `status` / `toggle`):
437
+ `node bin/gentle-sidebar.js <verb>` picks between this plugin's sidebar rows
438
+ and the native Herdr sidebar. `status` is read-only; `enable` converges the
439
+ managed Herdr rows and records the owned native-extension exclusion;
440
+ `disable` removes only our owned rows and exclusion, never a user table.
441
+ See [docs/sidebar-control.md](docs/sidebar-control.md).
442
+ - In-Pi switches (`/herdr-gentle:customize`): exactly two toggles, both local
443
+ 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
449
+ when the TUI helpers or `ctx.ui.custom` are unavailable.
450
+ `Sidebar agent rows` drives the Herdr plugin's own `bin/configure.js`
451
+ (`--check` to read, `--apply --reload` / `--uninstall --reload` to change) and
452
+ never edits the Herdr config itself; `Moshi notifications` writes the flag
453
+ below and adds or removes the `-extensions/moshi-hooks.ts` exclusion in Pi's
454
+ `settings.json`, running the `moshi-hook` pairing gate before enabling (a
455
+ refusal writes nothing) and reloading Pi only when that settings entry
456
+ actually changed. `/herdr-gentle:customize status` prints one read-only line
457
+ (`customize status: sidebar=<on|off|unknown> moshi=<on|off>`); an unknown
458
+ argument, Esc, or a cancelled menu writes nothing. A sidebar verdict of
459
+ `unknown` is never a refusal: the panel says the state is unknown and
460
+ choosing `On` still runs the apply step, reporting that step's own error
461
+ when it refuses (the same behavior the menu always had). The run-by-hand
462
+ equivalents are the CLI and the flag file shown below.
463
+ - Optional Moshi replacement (off by default): one flag file,
464
+ `<state dir>/gentle-moshi.json` containing `{"enabled":true}` (the state dir
465
+ is `GENTLE_STATUS_STATE_DIR`, else the stored `herdr-gentle-agents` state dir
466
+ under `$XDG_STATE_HOME/herdr` or `~/.local/state/herdr`):
467
+
468
+ ```sh
469
+ dir="${GENTLE_STATUS_STATE_DIR:-${XDG_STATE_HOME:-$HOME/.local/state}/herdr/plugins/herdr-gentle-agents}"
470
+ mkdir -p "$dir" && echo '{"enabled":true}' > "$dir/gentle-moshi.json"
471
+ ```
472
+
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).
477
+
478
+ With the flag on, this plugin **replaces the
479
+ Moshi-managed Pi hook**: the same Moshi integration (Chat View, Live Activity,
480
+ session row, terminal context, phone-side approvals) keeps working, but
481
+ notifications follow this plugin's policy — one when Pi really needs your
482
+ input (`ask`) and one when Pi really finishes. Nothing per prompt, nothing per
483
+ turn. If `extensions/moshi-hooks.ts` is installed, add
484
+ `-extensions/moshi-hooks.ts` to the `extensions` list in your Pi
485
+ `settings.json` so the Moshi-managed hook cannot notify in parallel; that edit
486
+ leaves every other settings key and entry untouched. Removal of the flag (or
487
+ `{"enabled":false}`) silences this channel immediately — the flag is re-read
488
+ per event — and restoring the hook entry brings the original notifier back.
489
+ Moshi owns pairing and credentials; this plugin never
490
+ reads or stores a token, an absent daemon or unpaired host is a silent
491
+ no-op, and Pi is never interrupted by a Moshi failure.
492
+ - Delegation completion reconciled from Gentle Shell presence files, not chat
493
+ delivery: a delegate resolves only from an explicit terminal status or a
494
+ witnessed absence in a strictly newer verified activity generation of the
495
+ same session, bound to an immutable per-task execution epoch (new launch,
496
+ resume, or inactive-to-active transition — never a progress read or
497
+ heartbeat tick). Ambiguous, stale, or oversize snapshots never clear
498
+ tasks. Known limits: delegates that launch and finish between presence
499
+ publications never appear and still depend on chat delivery, and
500
+ absence-driven completion records `completed` without latching an error.
501
+ - TTL-bounded tokens: stale panes fall back to native `idle`.
502
+ - Herdr session opener (`herdr_session_open`): opens a Herdr panel running a
503
+ Pi session at a path. A linked Git worktree opens as a **worktree panel**
504
+ (reusing the workspace Herdr already has for that checkout); a repository's
505
+ primary checkout, a subdirectory or any generic directory opens as a
506
+ **normal panel**. Panel kind is decided from git, the pane Herdr names is
507
+ verified to belong to its workspace and to sit in the requested path before
508
+ Pi starts, and (unless `notify: false`) the caller is woken when that session
509
+ really finishes. The other worktree tools and the ODD and issues panels live
510
+ in `odd-worktree` now; the sidebar and Moshi switches stayed here and are
511
+ reached through `/herdr-gentle:customize`. See
512
+ [docs/herdr-session-open.md](docs/herdr-session-open.md).
513
+
514
+ ## Documentation
515
+
516
+ | Your task | Start here |
517
+ | --- | --- |
518
+ | Protocol, token grammar, reducer, and coexistence rules | [DESIGN.md](DESIGN.md) |
519
+ | Compatibility, migration, and rollback | [DESIGN.md](DESIGN.md) §9 |
520
+ | Open decisions blocking implementation | [DESIGN.md](DESIGN.md) §10 |
521
+ | Supervision triage (read-only doctor/trace/whois) | [docs/diagnostics.md](docs/diagnostics.md) |
522
+ | Lifecycle recovery and interruption (polling fallback) | [docs/supervision.md](docs/supervision.md) |
523
+ | Sidebar switch (`bin/gentle-sidebar.js`) | [docs/sidebar-control.md](docs/sidebar-control.md) |
524
+ | Herdr session opener (`herdr_session_open`) | [docs/herdr-session-open.md](docs/herdr-session-open.md) |
525
+ | Performance trace and its report | [docs/performance-trace.md](docs/performance-trace.md) |
526
+
527
+ ## Next Steps
528
+
529
+ - Ship the Pi producer extension (`extensions/`) and the Herdr consumer daemon
530
+ (`herdr-plugin/bin/` plus `herdr-plugin/lib/`); the daemon ships, the sidebar
531
+ override installs via the `configure` plugin action above.
532
+ - Resolve the open decisions in [DESIGN.md](DESIGN.md) §10 before implementing
533
+ against them.
534
+ - Live sidebar eyeball with subagents/`ask` remains the final acceptance check
535
+ (see Verification above).
536
+
537
+ ## License
538
+
539
+ 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();