herdr-gentle-shell 1.6.2 → 1.8.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
@@ -154,13 +154,13 @@ an explicit writer-ownership decision. Rationale follows each choice.
154
154
  absent under single-writer handoff (O1). Gentle renders exactly two rows
155
155
  for the `pi` agent: row 1 is the heading context as exactly one active
156
156
  cell — the active `gentle_heading_*` value holds `<icon> <project>` plus
157
- compact nonempty changes segments (` +N`, ` -N`, ` ↑N`) in that same
158
- cell (e.g. `● myproj +110 -22 ↑3`). Exactly one row-1 cell is nonempty,
157
+ compact nonempty changes segments (` +N`, ` -N`) in that same
158
+ cell (e.g. `● myproj +110 -22`). Exactly one row-1 cell is nonempty,
159
159
  so Herdr inserts zero inter-cell `·` separators. The cell sits on white
160
160
  `#ffffff` (SIDEBAR_PROJECT) so the project text stays white; symbol
161
161
  `contains` rules recolor the icon (unchanged state mapping) plus ` +`
162
- green (added), ` -` red (deleted, leading-space match so hyphens inside
163
- project names never turn red), and ` ↑` blue (pull). `gentle_project`,
162
+ green (added), and ` -` red (deleted, leading-space match so hyphens inside
163
+ project names never turn red). `gentle_project`,
164
164
  `gentle_changes_summary`, and the change-segment tokens stay published
165
165
  and owned for compatibility but are wired into no visible row; row 2 is
166
166
  the agent context (the
@@ -483,7 +483,7 @@ explorers with count 3 → `explorer (3)`; 5 files
483
483
  `● myproj +110 -22` (` +` green for added, ` -` red for deleted with a
484
484
  leading-space match, zero `·` separators because exactly one heading cell
485
485
  is nonempty).
486
- A review label renders `rdd` with a blue `●` (`#89b4fa`, same as explorer/pull). A
486
+ A review label renders `rdd` with a blue `●` (`#89b4fa`, same as explorer). A
487
487
  `gentle_orchestrating_v1` marker renders the pink `gentle` (machine display
488
488
  key `orchestrating`, pink palette unchanged): it covers the principal's
489
489
  queued/running subs and pending launches, and it yields to a delegate role
@@ -579,8 +579,7 @@ display — repairs a missed `error:` label edge, §4.3),
579
579
  `gentle_roles_v1` (authoritative activity roles,
580
580
  oldest-first by immutable firstSeen), `gentle_names_v1` (compat transport only — never
581
581
  rendered), `gentle_changes_v2` (normative; a
582
- v1-only pane renders no change segments, §4.3). Pane cwd
583
- (`foreground_cwd` ?? `cwd`) feeds the daemon-side pull marker (§5.3).
582
+ v1-only pane renders no change segments, §4.3).
584
583
  Foreign `pi_subagents_work_v1` / `state_*` / `title_*` are observed only to
585
584
  ignore them under O1 (never parsed for state, never deleted).
586
585
 
@@ -706,7 +705,7 @@ cap has lapsed, does it recede to `idle` (§4.3).
706
705
  `#cba6f7` (distinct from explorer blue, verify teal, orchestrating pink),
707
706
  ask orange `#fab387`, blocked red `#f38ba8`, done green `#a6e3a1`,
708
707
  idle grey `#7c7f93` (recedes), review blue `#89b4fa` (same as
709
- explorer/pull; internal TaskStore role slug stays `rdd`, machine display
708
+ explorer; internal TaskStore role slug stays `rdd`, machine display
710
709
  key stays `review`). Native separators on row 2 are acceptable. The
711
710
  `gentle_state_*` / `gentle_agent_*` / `gentle_icon_*` /
712
711
  `gentle_row_*` combined names stay published for compatibility but are
@@ -735,20 +734,17 @@ cap has lapsed, does it recede to `idle` (§4.3).
735
734
  running delegates and no pending launches; a settled principal with
736
735
  running delegates keeps the role word) | `idle`. Role labels append the
737
736
  total count when at least two delegates run.
738
- - Row-2 changes: the nonempty `+N`/`-N`/`↑N` segments ride as their own
737
+ - Row-2 changes: the nonempty `+N`/`-N` segments ride as their own
739
738
  structural row-2 cells after the eleven title cells (each its own color
740
- cell with no rules — added green, deleted red, pull blue, never
739
+ cell with no rules — added green, deleted red, never
741
740
  swapped; empty segments collapse so nothing renders). `+N`/`-N` come
742
741
  from fresh `gentle_changes_v2`
743
- (exact SessionChanges evidence totals, never git status); `↑N` (blue)
744
- marks the pane branch behind its upstream. The pull marker is derived by the daemon from fixed-argv,
745
- bounded `git status --porcelain=2 --branch` (the `# branch.ab` line
746
- only — no shell, no diff, no fetch), cached/deduped per cwd over a short
747
- TTL so panes sharing a worktree cost ~1 call per window. Any pull failure
748
- resolves to absent (fail-closed).
749
- - Each `+N`/`-N`/`↑N` segment renders only when its total is > 0; each
750
- rides its own structural row-2 cell (added green, deleted red, pull
751
- blue, no rules, never swapped; empty segments collapse). `gentle_project`,
742
+ (exact SessionChanges evidence totals, never git status). The row carries
743
+ no ahead/behind marker relative to the branch: only the exact added and
744
+ deleted line counts.
745
+ - Each `+N`/`-N` segment renders only when its total is > 0; each
746
+ rides its own structural row-2 cell (added green, deleted red,
747
+ no rules, never swapped; empty segments collapse). `gentle_project`,
752
748
  `gentle_heading_*`, `gentle_agent` (both the single and per-display
753
749
  forms), and `gentle_changes_summary` stay published for compatibility
754
750
  but render no visible row. The retired
@@ -756,11 +752,11 @@ cap has lapsed, does it recede to `idle` (§4.3).
756
752
  badge is never emitted (see the §4.3 versioning rule).
757
753
  - Placement: exactly two pi-only rows — row 1 the native `state_icon` +
758
754
  `workspace` + `agent` strings (3 cells, no custom wiring, no plugin
759
- colors), row 2 the eleven `gentle_title_*` state cells plus the three
760
- change-segment cells (14 cells: 11 state + 3 changes), each row within
755
+ colors), row 2 the eleven `gentle_title_*` state cells plus the two
756
+ change-segment cells (13 cells: 11 state + 2 changes), each row within
761
757
  Herdr's 16-token per-row ceiling — with the
762
758
  herdr-pi-tree palette (added green `#a6e3a1`,
763
- removed red `#f38ba8`, pull blue `#89b4fa`, working golden `#f9e2af`, ask
759
+ removed red `#f38ba8`, working golden `#f9e2af`, ask
764
760
  orange `#fab387`, orchestrating pink fuchsia `#f5c2e7`, explorer/rdd blue `#89b4fa` (same color; internal role slug stays `rdd`,
765
761
  visible word is `rdd`, machine key stays `review`), judge purple `#cba6f7` (distinct),
766
762
  blocked/error red `#f38ba8`,
@@ -993,10 +989,10 @@ report with a higher seq lands. Parity contract: `working` carries the specific
993
989
 
994
990
  The package ships one CLI switch command,
995
991
  `node bin/gentle-sidebar.js (enable|disable|status|toggle)` (§7), and one in-Pi
996
- command, `/herdr-gentle:customize`, with exactly two switches: the managed
997
- sidebar agent rows and the Moshi notification channel. The command registers
998
- before the `enabled()` pane gate, so both switches stay reachable from a plain
999
- Pi session outside a Herdr pane. It owns no state of its own and reimplements
992
+ command, `/herdr-gentle:customize`, with exactly three switches: the managed
993
+ sidebar agent rows, the Moshi notification channel and the Herdr theme sync
994
+ (§12). The command registers before the `enabled()` pane gate, so every switch
995
+ stays reachable from a plain Pi session outside a Herdr pane. It owns no state of its own and reimplements
1000
996
  nothing:
1001
997
 
1002
998
  - `Sidebar agent rows` drives the Herdr plugin's own `bin/configure.js` —
@@ -1057,11 +1053,11 @@ exactly one mechanism writes each piece of state.
1057
1053
  `gentle_orchestrating_v1`, `gentle_principal_v1`, `gentle_done_v1`,
1058
1054
  `gentle_ask_v1`, `gentle_review_v1`, `gentle_error_v1`,
1059
1055
  `gentle_changes_v2`,
1060
- `gentle_changes_v1`) and the daemon publishes its 72-token owned family
1056
+ `gentle_changes_v1`) and the daemon publishes its 71-token owned family
1061
1057
  chunked ≤ 16 per report (row 1 is the 3 native tokens
1062
1058
  `state_icon`/`workspace`/`agent`; the legacy 11 `gentle_heading_*` compat
1063
1059
  family stays published but wired into no visible row. Row 2 wires 11
1064
- title + 3 change cells = 14 — each within the per-row ceiling). Names are
1060
+ title + 2 change cells = 13 — each within the per-row ceiling). Names are
1065
1061
  advisory; roles are authoritative for display and role labels carry the
1066
1062
  running total as a suffix when at least two delegates run.
1067
1063
  - TTL: `expiry <= now + 60000` at write; readers use `now` at read.
@@ -1078,8 +1074,8 @@ exactly one mechanism writes each piece of state.
1078
1074
  (`GENTLE_STATUS_FAST_QUIET_FRAMES`) or a TTL-bounded window
1079
1075
  (`GENTLE_STATUS_FAST_WINDOW_MS`), 250 ms floor, single dynamic
1080
1076
  `setTimeout` chain. The active-display trigger exists because the row data
1081
- the daemon derives by itself — the `+N/-N` changes summary and the `↑N`
1082
- pull marker, read from local git plus `agent.list` — cannot be driven by a
1077
+ the daemon refreshes by a frame rather than from a producer report —
1078
+ `agent.list` plus the presence prefix — cannot be driven by a
1083
1079
  producer report; only `idle` counts as settled, so an idle pane keeps the
1084
1080
  baseline exactly.
1085
1081
  Drawing is event-synchronized; polling is only the fallback. Every landed
@@ -1112,10 +1108,9 @@ exactly one mechanism writes each piece of state.
1112
1108
  Shutdown closes the socket and its retry timer, and neither keeps the process
1113
1109
  alive. Idle cost with no events is exactly today's: an idle subscription is
1114
1110
  silent and the loop sleeps as before.
1115
- What the subscription can never drive stays poll-only: the row data the
1116
- daemon derives by itself — the `+N/-N` changes summary and the `↑N` pull
1117
- marker, read from local git plus `agent.list` — plus the presence prefix,
1118
- because Herdr emits no event for either. That is why the fast cycle is armed
1111
+ What the subscription can never drive stays poll-only: the daemon's own
1112
+ `agent.list` snapshot and the presence prefix, because Herdr emits no event
1113
+ for either. That is why the fast cycle is armed
1119
1114
  by a rendered non-idle display, and why polling is never removed.
1120
1115
  The sleep is also capped at the nearest live `gentle_done_v1` expiry AND the
1121
1116
  nearest pending view-dwell deadline (`DONE_VIEW_DWELL_MS`) among
@@ -1145,7 +1140,7 @@ exactly one mechanism writes each piece of state.
1145
1140
  `gentle_heading_*`, `gentle_project`, `gentle_row_*` (each family now
1146
1141
  includes the `judge` display alongside the original ten), plus display-only
1147
1142
  `gentle_changes_added`, `gentle_changes_deleted`,
1148
- `gentle_changes_pull`, `gentle_changes_summary`); no change to `pi_subagents_work_v1`, `state_*`,
1143
+ `gentle_changes_summary`); no change to `pi_subagents_work_v1`, `state_*`,
1149
1144
  `title_*`, or native `working`/`blocked`/`idle` semantics.
1150
1145
  `gentle_title_error` keeps its machine-key-derived token name; only its
1151
1146
  user-facing value is `blocked` (§5.3). `gentle_title_review` likewise
@@ -1155,7 +1150,9 @@ exactly one mechanism writes each piece of state.
1155
1150
  likewise keeps its machine-key-derived token name; its user-facing value is
1156
1151
  a non-contemplated subagent's own sanitized name, never the word `working`.
1157
1152
  The retired `*_working_subs` token family (the old `working (n)`
1158
- count display) is swept, never written.
1153
+ count display) is swept, never written. The retired
1154
+ `gentle_changes_pull` name (the removed behind-upstream `↑N` marker) is
1155
+ swept the same way, never written.
1159
1156
  - Coexistence: `herdr-pi-tree` stays installed but disabled for gentle-owned
1160
1157
  panes (O1). No uninstall, no token migration, no dual-run merge — ownership
1161
1158
  handoff is by enable/disable switch, reversible at any time.
@@ -1164,9 +1161,9 @@ exactly one mechanism writes each piece of state.
1164
1161
  panel, the ODD and Issues readers, and the `Plugin tools` toggles no longer
1165
1162
  ship. This package publishes the Herdr producer sidecar and the Moshi channel
1166
1163
  only; `bin/gentle-sidebar.js` is its one CLI and `/herdr-gentle:customize`
1167
- its one in-Pi command, carrying just the sidebar-rows and Moshi switches.
1168
- Its provider slot `globalThis[Symbol.for("herdr-gentle.customize.v1")]` stays
1169
- removed, so no other extension renders those two switches.
1164
+ its one in-Pi command, carrying just the sidebar-rows, Moshi and theme-sync
1165
+ switches. Its provider slot `globalThis[Symbol.for("herdr-gentle.customize.v1")]`
1166
+ stays removed, so no other extension renders those switches.
1170
1167
  - Rollback: disable this plugin → producer stops writing; consumer sweeps
1171
1168
  only `gentle_*` tokens + labels it set (O5); pi-tree re-enable restores
1172
1169
  `↳N` behavior with zero data migration.
@@ -1223,7 +1220,7 @@ exactly one mechanism writes each piece of state.
1223
1220
  - **U5. Changes badge — RESOLVED (two-row contract):** the `±N` vs `~N`
1224
1221
  selection no longer exists — the combined badge is retired in favor of
1225
1222
  independent `+N`/`-N` segments from exact `gentle_changes_v2` added/deleted
1226
- totals, plus the daemon-side `↑N` pull marker (§5.3). The producer mirrors
1223
+ totals, plus the daemon-side change cells (§5.3). The producer mirrors
1227
1224
  the Gentle Shell `SessionChanges` model semantics over the same transcript
1228
1225
  `SESSION_CHANGE_ENTRY` evidence (never git and never an approximate
1229
1226
  reaggregation): files keyed by `(root, path)`, evidence-ID dedup,
@@ -1247,10 +1244,102 @@ confirming each criterion has a normative section:
1247
1244
  | V1 | Sidebar shows the active TaskStore role with live subagents | §4.2 (role source G3 + `gentle_roles_v1`), §5.2–§5.3 |
1248
1245
  | V2 | Sidebar shows `ask` on open question | §4.2 (G4 → `ask:`), §5.2 priority, §7 notify-once |
1249
1246
  | V3 | Sidebar shows `review` during native review | §4.2 (review tool lifecycle → `review:`, incl. capture-group parent call), §5.2 priority |
1250
- | V4 | Change segments render from Gentle session-changes | §4.2/§4.4 (`gentle_changes_v2`), §5.3 `+N`/`-N`/`↑N` |
1247
+ | V4 | Change segments render from Gentle session-changes | §4.2/§4.4 (`gentle_changes_v2`), §5.3 `+N`/`-N` |
1251
1248
  | V5 | No collision with pi-tree `↳N` / `state_*` names | §3 O1/O2/O4, §9 rollback |
1252
1249
  | V6 | Stale panes fall back to `idle`, orphans swept on handover | §3 O5, §5.4, §6 |
1253
1250
 
1254
1251
  Task closes when V1–V6 are all traceable above and the file re-read reports
1255
1252
  path + line count. Any untraceable cell → `status: partial` with the gap
1256
1253
  list, not silent.
1254
+
1255
+ ## 12. Theme sync (Pi palette → Herdr theme)
1256
+
1257
+ Herdr's palette follows the theme active in Gentle Shell / Pi, or one theme
1258
+ pinned while the sync is off (S1–S5). The switch lives with the other two in
1259
+ `/herdr-gentle:customize`; the user-facing reference is
1260
+ [docs/theme-sync.md](docs/theme-sync.md). Three modules with three owners, and
1261
+ one direction of data:
1262
+
1263
+ | Module | Package | Owns |
1264
+ |---|---|---|
1265
+ | `lib/theme-store.js` | Pi (`herdr-gentle-shell`) | The one persisted document (`gentle-theme.json`): the state-dir resolution copied verbatim from the sidecar's Moshi flag, a normalised read, and the atomic replace. |
1266
+ | `lib/theme-projection.js` | Pi | The pure translation: assignable Herdr theme names, Herdr token order, `HERDR_ROLE_SOURCES`, `projectPalette`, `paletteFingerprint`, and the `null`/`Off` spelling the panel paints. No filesystem, no host import. |
1267
+ | `herdr-plugin/lib/gentle-theme-config.js` + `bin/configure-theme.js` | Herdr plugin | Everything that touches `config.toml`: payload validation, the managed block, the refusals, the atomic write with its own `.bak`, and the optional reload. |
1268
+
1269
+ Two thin glue layers sit above them and own no state: the follower
1270
+ `extensions/herdr-theme-sync.ts` (tick, fingerprint, one spawn per change,
1271
+ notices) and the switch in `extensions/gentle-herdr-state.ts` plus
1272
+ `lib/customize-panel.js` (`applyThemeSync`, `applyThemeSelection`,
1273
+ `customize status`). Pi colours become hex strings in the follower through
1274
+ `colorToHex` from `@earendil-works/pi-tui`, which is why the follower is its own
1275
+ extension rather than a section of the state sidecar: the sidecar is loaded by
1276
+ every suite as a renamed copy with one stubbed host import, and the projection
1277
+ needs no host at all.
1278
+
1279
+ **The state file is the only persisted truth.** `gentle-theme.json` holds
1280
+ `{sync, theme, updatedAt}` and nothing else is cached, mirrored or inferred: the
1281
+ panel and the follower read the same document, so the row, the switch and the
1282
+ applied palette can never disagree. Missing is inert (`sync:false`,
1283
+ `theme:null`); a document that cannot be read or parsed is a refusal — `ok:false`,
1284
+ painted `Unknown`, follower silent — never a guess, and it is written over only
1285
+ when the user acts. The default install (sync off, no theme) therefore writes
1286
+ nothing at all (S7), while a stored pin is carried across a sync toggle so
1287
+ turning the sync off restores that choice instead of unassigning it.
1288
+
1289
+ **Tick and fingerprint.** The host publishes no theme-change event, so the
1290
+ palette is a pull-read of `ctx.ui.theme` (or `ctx.ui.getTheme(name)` for a pin):
1291
+ one immediate evaluation on `session_start` and then one every 500 ms, on an
1292
+ unreferenced timer so an idle follower never keeps Pi alive. Each evaluation
1293
+ computes two identities — the requested `[sync, chosen]` and the palette
1294
+ fingerprint (`[theme name, sorted token/hex pairs]`) — and acts only when one
1295
+ differs from the last one it recorded, so a theme recoloured in place (same
1296
+ name, new colours) is noticed without a restart, and the same palette is never
1297
+ applied twice. The observation is recorded **before** the spawn, so a failed or
1298
+ refused apply is never retried on the next tick and never blocks the next real
1299
+ change either. One apply is in flight at a time, each spawn is capped at 60 s,
1300
+ and the apply is exactly
1301
+ `<plugin>/bin/configure-theme.js --apply --json --reload` with the projection on
1302
+ stdin. Nothing on shutdown writes, removes or reloads: Herdr keeps the last
1303
+ applied palette (S5). There is deliberately no Herdr pane gate — the config is
1304
+ the user's own and outlives any pane — and no automatic repair of a config the
1305
+ user also edits.
1306
+
1307
+ **Managed block and refusal policy.** The writer owns a second marker-delimited
1308
+ block (`# BEGIN herdr-gentle-theme (managed; do not edit)` …
1309
+ `# END herdr-gentle-theme`) holding `[theme] name = "one-dark"` and a
1310
+ `[theme.custom]` table, in a fixed token order with lower-cased hex, so the same
1311
+ palette is always the same bytes, `current` is a no-op answer, and a refusal can
1312
+ never be mistaken for a change. It reuses `bin/configure.js`'s
1313
+ `herdrConfigPath`/`readConfig`/`writeAtomic`/`removeBlock`/`appendBlock`/
1314
+ `reloadConfig` primitives rather than copying them, so both blocks fail, back up
1315
+ and reload identically — but shares no marker bytes and no backup file, because
1316
+ two writers that share markers each treat the other's block as their own and the
1317
+ last one erases the first. Validation happens before disk: an unknown theme
1318
+ name, an unknown token or a non-`#rrggbb` value is a refusal, not a file Herdr
1319
+ would reject or silently ignore. A `[theme]` or `[theme.custom]` table outside
1320
+ the markers is user config: refuse, never adopt, merge or overwrite. Malformed
1321
+ markers (lone begin, lone end, end before begin, a second pair) refuse instead
1322
+ of guessing where the block ends. `--remove` on an absent block is `absent` and
1323
+ exits 0 even when a foreign table exists, because uninstall must not touch user
1324
+ config. Every refusal guarantees no write, no reload and unchanged config bytes;
1325
+ exit 1 means a stale `--check` or a reload that failed after a successful write.
1326
+
1327
+ **Limits** (the §10 style, none of them a promise this design makes):
1328
+
1329
+ - The 500 ms tick is the whole observation granularity — there is no event to
1330
+ subscribe to, so a theme change is noticed within one tick and not sooner.
1331
+ - The automated evidence is a stubbed Pi host plus a real CLI stand-in on disk;
1332
+ **no live Pi TUI run is recorded**. `ctx.ui.theme`, `getTheme`,
1333
+ `getAllThemes`, `select` and `notify` are used as documented, and a host
1334
+ missing one degrades to "nothing changed" rather than to a guess.
1335
+ - Herdr's surface tokens (`sidebar_bg`, `panel_bg`, `active_row_bg`,
1336
+ `selection_bg`, `surface*`) and `peach` are never written: Pi names
1337
+ foregrounds and accents, not panel backgrounds, so backgrounds and status
1338
+ colours stay with the Herdr base theme.
1339
+ - One machine: another Herdr client reads its own `config.toml`, so this is a
1340
+ local sync and not a fleet setting.
1341
+ - Plugin-root resolution goes through `herdr plugin list --json` and fails
1342
+ closed on zero or ambiguous matches; that refusal is reported once per session
1343
+ and retried silently afterwards.
1344
+ - The CLI requires Node 18 or newer; an older runtime exits 1 before reading
1345
+ anything.
package/README.md CHANGED
@@ -40,9 +40,9 @@ nested `codemode` call, which starts while a sibling dialog is still awaited) or
40
40
  assistant message arriving while it is open — never counts either, so a Gentle Shell command
41
41
  menu opened mid-work leaves the row on the agent's real activity), and
42
42
  permission waiting; `gentle_review` starts never speculate ask, amber/orange `?`), `blocked`, `done`, `idle`) plus compact
43
- changes segments folded into the single row-1 heading cell (nonempty ` +N`/` -N`/` ↑N`
43
+ changes segments (nonempty ` +N`/` -N`
44
44
  with leading spaces, symbols color-distinguished by `contains` rules: ` +` green for added,
45
- ` -` red for deleted, ` ↑` blue for pull — added stays green, deleted stays red),
45
+ ` -` red for deleted — added stays green, deleted stays red),
46
46
  reduced from `gentle_*`
47
47
  pane-metadata tokens. It coexists with `herdr-pi-tree` through a single-writer handoff: while
48
48
  this plugin owns a pane, `herdr-pi-tree` stays disabled for that pane, so the
@@ -206,11 +206,11 @@ the native `state_icon`, is Herdr-native and not plugin-controlled); row 2
206
206
  wires the eleven presence-encoded `gentle_title_*` state cells (state word
207
207
  only, one current title per frame, each in its state's semantic color as
208
208
  base fg with no rules; role words carry a running-count suffix above one)
209
- followed by the three
210
- change-segment tokens (added green `+N`, deleted red `-N`, pull blue `↑N`,
209
+ followed by the two
210
+ change-segment tokens (added green `+N`, deleted red `-N`,
211
211
  each its own color cell with no rules, never swapped). The review leg
212
212
  renders the user-facing word `rdd` in blue `#89b4fa` (same as
213
- explorer/pull; internal TaskStore role slug stays `rdd`, machine display key
213
+ explorer; internal TaskStore role slug stays `rdd`, machine display key
214
214
  and token names stay `review` — review execution is silent, never a
215
215
  notification; only an actual waiting prompt renders `ask` (desktop attention
216
216
  is Herdr's native `blocked` toast); the judge delegate role renders `judge` in
@@ -234,8 +234,8 @@ for compatibility but are wired into no visible row.
234
234
  Only one `gentle_title_*` token carries a value per frame (presence
235
235
  encoding), so row 2 shows the current state word plus any nonempty change
236
236
  segments while the rest render empty; native separators on row 2 are
237
- acceptable. Row 1 holds 3 native cells and row 2 holds 14 cells (11 state
238
- + 3 changes), each within Herdr's 16-token per-row ceiling (full block below).
237
+ acceptable. Row 1 holds 3 native cells and row 2 holds 13 cells (11 state
238
+ + 2 changes), each within Herdr's 16-token per-row ceiling (full block below).
239
239
  The `gs` label of an isolated Gentle Shell pane needs no key here: `gs` is not
240
240
  one of Herdr's canonical agents, so `rows_by_agent.gs` is a configuration error
241
241
  rather than an inert key. Only the daemon's label ladder (DESIGN.md §5.5)
@@ -247,7 +247,7 @@ makes that row appear, and `rows_by_agent` stays keyed by the canonical `pi`.
247
247
  # row 1 native state_icon + workspace + agent, row 2 state word + changes.
248
248
  # The parent [ui.sidebar.agents] table is user-owned and never touched here.
249
249
  [ui.sidebar.agents.rows_by_agent]
250
- 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" }]]
250
+ 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" }]]
251
251
  # END herdr-gentle-agents
252
252
  ```
253
253
 
@@ -255,11 +255,11 @@ The
255
255
  single row-1 heading cell mirrors the Gentle Shell SessionChanges model semantics
256
256
  (write/edit tool outcomes, never `git status`, never an approximate
257
257
  reaggregation): files keyed by `(root, path)` with snapshot-continuity and
258
- unavailable counts (unavailable files stay in the file count with 0/0); `↑N` shows when the pane
259
- branch is behind its upstream (branch-ab status only, no diff). `gentle_project`,
258
+ unavailable counts (unavailable files stay in the file count with 0/0). `gentle_project`,
260
259
  `gentle_changes_summary`, and the segment
261
- tokens (`gentle_changes_added`/`_deleted`/`_pull`) stay published for
262
- compatibility but render no visible row. Pink `gentle` (machine key
260
+ tokens (`gentle_changes_added`/`_deleted`) stay published for
261
+ compatibility but render no visible row. The changes row carries no
262
+ ahead/behind marker relative to the branch. Pink `gentle` (machine key
263
263
  `orchestrating`, pink palette unchanged) is the
264
264
  only user-facing `gentle`: it renders while the principal session actively
265
265
  works — even with zero subagents, with or without a fresh root marker — and
@@ -357,7 +357,7 @@ role word such as `worker`, `explorer`,
357
357
  once the principal itself is idle — and also while a
358
358
  task-mode subagent call blocks the principal's turn, until it returns), that
359
359
  a row never reads `gentle` on an idle pane; row 1
360
- shows the single heading cell (`● <project>` plus ` +N`/` -N`/` ↑N` inline, zero `·`) after edits / when behind upstream; then `ask` on an open
360
+ shows the single heading cell (`● <project>` plus ` +N`/` -N` inline, zero `·`) after edits; then `ask` on an open
361
361
  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; neither does a span the agent proves it is not waiting on, since a run blocked on its own dialog cannot start a new top-level tool execution (a nested `codemode` call proves nothing: it starts while a sibling dialog is still awaited) or finish an assistant message, so a Gentle Shell command menu opened mid-work keeps the row on the agent's real activity), or permission waiting; `gentle_review` starts never speculate ask, and no failed tool ever does either: a tool error changes nothing, see the error rule below). `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
362
362
  `HERDR_CONFIG_PATH` on a temp file for apply/uninstall checks.
363
363
 
@@ -400,7 +400,7 @@ producer's own beat is 15 s by default and
400
400
  TTL. Reports in one window collapse into one frame, and refresh-driven frames
401
401
  are floored at 250 ms, so a burst can never spin the daemon. Polling stays the
402
402
  fallback for every lifecycle signal and the only source for what no Herdr event
403
- carries (the git-derived `+N/-N` and `↑N` row data and the presence prefix), so a
403
+ carries (the presence prefix), so a
404
404
  missed, undelivered, or rejected event never sticks. Read-only
405
405
  supervision triage ships beside it: the `doctor` and `whois` plugin actions
406
406
  (`node bin/gentle-doctor.js`, `node bin/gentle-whois.js`) plus the explicit-pane
@@ -440,13 +440,14 @@ See [DESIGN.md](DESIGN.md) §4 (producer) and §5 (consumer), and
440
440
  NeedsAttention toast and sound, so the sidebar carries the error on the
441
441
  durable `gentle_error_v1` token while the pane stays quiet on `working`,
442
442
  and no phone envelope is sent).
443
- - Single-cell row-1 heading (`<icon> <project>` plus ` +N`/` -N`/` ↑N`
443
+ - Single-cell row-1 heading (`<icon> <project>` plus ` +N`/` -N`
444
444
  inline, exactly one nonempty cell so zero `·` separators; white base with
445
445
  `contains` rules keeping ` +` green (added), ` -` red (deleted,
446
- leading-space match), ` ↑` blue (pull)) mirroring the Gentle Shell
446
+ leading-space match)) mirroring the Gentle Shell
447
447
  SessionChanges model semantics over Gentle tool outcomes, never `git`
448
448
  status and never an approximate reaggregation (root+path continuity and
449
- unavailable counts); behind-upstream `↑N` from branch-ab status only.
449
+ unavailable counts). The changes row carries no ahead/behind marker
450
+ relative to the branch.
450
451
  Session-change tokens are refreshed/cleared from the current Gentle Shell
451
452
  session model and never carried across sessions.
452
453
  - Single-writer coexistence with `herdr-pi-tree`: no shared token names, no
@@ -483,10 +484,11 @@ See [DESIGN.md](DESIGN.md) §4 (producer) and §5 (consumer), and
483
484
  managed Herdr rows and records the owned native-extension exclusion;
484
485
  `disable` removes only our owned rows and exclusion, never a user table.
485
486
  See [docs/sidebar-control.md](docs/sidebar-control.md).
486
- - In-Pi switches (`/herdr-gentle:customize`): two switches, both local
487
- state and both reachable from a plain Pi session outside a Herdr pane. With
487
+ - In-Pi switches (`/herdr-gentle:customize`): three switches, all local
488
+ state and all reachable from a plain Pi session outside a Herdr pane. With
488
489
  no argument the command opens the floating panel in Gentle Shell's own
489
- layout: one left `CATEGORIES` list (`Herdr Sidebar`, `Moshi notifications`)
490
+ layout: one left `CATEGORIES` list (`Herdr Sidebar`, `Moshi notifications`,
491
+ `Herdr Theme`)
490
492
  and one right pane headed `<Category> · n/m` with its setting rows, each row
491
493
  painting the stored value with `●` and the other with `○`; one line above the
492
494
  footer describes the focused setting (`<setting> — <what it changes>`), and
@@ -498,11 +500,14 @@ See [DESIGN.md](DESIGN.md) §4 (producer) and §5 (consumer), and
498
500
  it is a key the panel answers to, and a narrow card compacts it instead of
499
501
  wrapping. Pointer input still works without being advertised — a click on a
500
502
  category selects it, a click on a row applies it, and a click outside the
501
- panes is ignored. Each category owns exactly one switch: `Herdr Sidebar`
503
+ panes is ignored. Each category owns its own rows: `Herdr Sidebar`
502
504
  shows the single `Sidebar agent rows` row, and the only Moshi switch is the
503
- `Notifications` row under `Moshi notifications`. The two are never mixed —
504
- `Sidebar agent rows` neither reads nor writes `gentle-moshi.json`, so turning
505
- the agent rows off never turns the notification channel off. Herdr's own
505
+ `Notifications` row under `Moshi notifications`, while `Herdr Theme` owns
506
+ both theme rows (the `Theme sync` toggle and the non-toggle
507
+ `Gentle Shell theme` value row described in the subsection below). The
508
+ sidebar and Moshi switches are never mixed — `Sidebar agent rows` neither
509
+ reads nor writes `gentle-moshi.json`, so turning the agent rows off never
510
+ turns the notification channel off. Herdr's own
506
511
  done/ask attention (the finished and needs-attention pop-ups and their
507
512
  sound) is Herdr's native behavior, configured in Herdr itself — its config
508
513
  and its settings — and this package deliberately offers no switch for it:
@@ -517,7 +522,8 @@ See [DESIGN.md](DESIGN.md) §4 (producer) and §5 (consumer), and
517
522
  `settings.json`, running the `moshi-hook` pairing gate before enabling (a
518
523
  refusal writes nothing) and reloading Pi only when that settings entry
519
524
  actually changed. `/herdr-gentle:customize status` prints one read-only line
520
- (`customize status: sidebar=<on|off|unknown> moshi=<on|off>`); an unknown
525
+ (`customize status: sidebar=<on|off|unknown> moshi=<on|off>
526
+ theme-sync=<on|off|unknown> theme=<name|none|unknown>`); an unknown
521
527
  argument, Esc, or a cancelled menu writes nothing. A sidebar verdict of
522
528
  `unknown` is never a refusal: the panel says the state is unknown and
523
529
  choosing `On` still runs the apply step, reporting that step's own error
@@ -587,6 +593,22 @@ See [DESIGN.md](DESIGN.md) §4 (producer) and §5 (consumer), and
587
593
  reached through `/herdr-gentle:customize`. See
588
594
  [docs/herdr-session-open.md](docs/herdr-session-open.md).
589
595
 
596
+ ### Theme sync (Herdr palette follows Pi)
597
+
598
+ `/herdr-gentle:customize` → `Herdr Theme` is one switch and one pinned value.
599
+ `Theme sync` is **OFF by default**: while it is on, Herdr's palette is the
600
+ palette of the theme Pi is showing, and it follows a theme change while Pi keeps
601
+ running. While it is off, `Gentle Shell theme` assigns one Gentle Shell / Pi
602
+ theme by name and the picker's `Off (no theme assigned)` entry clears the pin; the row is refused while the sync is on
603
+ (`Turn Theme sync off to pick a specific theme.`). Turning the sync off writes
604
+ nothing to Herdr, so **Herdr keeps the last applied palette** — a fresh install
605
+ whose sync is off and whose theme is unassigned writes nothing at all. State is
606
+ one file, `gentle-theme.json`, beside `gentle-moshi.json`; the palette reaches
607
+ Herdr through the plugin's own `bin/configure-theme.js`, which owns a marked
608
+ `[theme]` block and refuses to touch a `[theme]` table you maintain yourself.
609
+ See [docs/theme-sync.md](docs/theme-sync.md) for the projection, the CLI and
610
+ the limits.
611
+
590
612
  ## Documentation
591
613
 
592
614
  | Your task | Start here |
@@ -597,6 +619,7 @@ See [DESIGN.md](DESIGN.md) §4 (producer) and §5 (consumer), and
597
619
  | Supervision triage (read-only doctor/trace/whois) | [docs/diagnostics.md](docs/diagnostics.md) |
598
620
  | Lifecycle recovery and interruption (polling fallback) | [docs/supervision.md](docs/supervision.md) |
599
621
  | Sidebar switch (`bin/gentle-sidebar.js`) | [docs/sidebar-control.md](docs/sidebar-control.md) |
622
+ | Theme sync (Pi palette → Herdr theme) | [docs/theme-sync.md](docs/theme-sync.md) |
600
623
  | Herdr session opener (`herdr_session_open`) | [docs/herdr-session-open.md](docs/herdr-session-open.md) |
601
624
  | Performance trace and its report | [docs/performance-trace.md](docs/performance-trace.md) |
602
625