herdr-gentle-shell 1.8.0 → 1.9.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
@@ -1008,35 +1008,76 @@ nothing:
1008
1008
  settings entry actually changed, because that entry is the only part that
1009
1009
  waits for the next Pi extension load.
1010
1010
 
1011
+ The command always exists and the page is additive.
1012
+ `/herdr-gentle:customize` is registered in the extension factory, unconditionally
1013
+ and before the pane gate, exactly as it always was; when gentle-shell-bridge
1014
+ answers its handshake — the `gentle-shell-bridge/api/v1` object published on
1015
+ `globalThis`, gated exactly like the bridge's own `isBridgeApi` — the extension
1016
+ ALSO registers one row provider (`registerRows`, a row `category`, never
1017
+ `registerSection`) on the `Herdr` page of Gentle Shell's own `/gentle:customize`
1018
+ menu, holding exactly the four options S1 names: `Herd agents`, `Moshi`,
1019
+ `Theme sync`, `Select theme`. Two surfaces coexisting is by design: Pi gives an
1020
+ extension no way to withdraw a registered command, and a bridge with no host
1021
+ menu must never leave the user with none. The page is asked for at
1022
+ `session_start` and again on the bridge's `gentle-shell-bridge:ready` announce,
1023
+ so a bridge that publishes after this extension or after the session start still
1024
+ produces it; the live provider is its own guard, so a second `session_start` or a
1025
+ repeated announce never stacks a second page, and only the provider is disposed
1026
+ at `session_shutdown` while the command stays as registered.
1027
+
1028
+ Each row is that switch and nothing else: its action calls the same
1029
+ `applyCustomizePanel` the panel calls, so the writes, the `moshi-hook`
1030
+ prerequisite gate and the "a refusal writes nothing" promise are identical by
1031
+ construction, and the model is re-read on every menu build so `current()` is the
1032
+ stored value rather than a copy taken at registration. The page's four lines are
1033
+ the same four switches under their row names — `Herd agents` for
1034
+ `Sidebar agent rows`, `Moshi` for `Moshi notifications`, `Theme sync` and
1035
+ `Select theme` for the two `Herdr Theme` settings — one row per value, applied
1036
+ with `Enter` (the bridge stages `applyOnMove: false` on every row it
1037
+ contributes), with the theme rows hidden while the sync is on instead of
1038
+ refused in place. One accepted limitation: a row action receives only the
1039
+ inline helpers (`input`, `confirm`, `capture`), so it has no reload handle —
1040
+ the Moshi toggle still writes the settings exclusion and then asks for a
1041
+ restart (`Restart Pi so the new Moshi hook exclusion takes effect.`) where the
1042
+ command and the panel reload immediately (`Reloading now to apply the change.`).
1043
+ Every string that sends the user back to these switches names
1044
+ `/herdr-gentle:customize`, byte-identical to the pre-page build: the command
1045
+ always exists, so no message needs a surface-dependent wording — the Moshi gate
1046
+ refusals end `… re-apply On from /herdr-gentle:customize.` and the follower's
1047
+ missing-theme notice says `… pick an installed theme in
1048
+ /herdr-gentle:customize.`
1049
+
1011
1050
  `/herdr-gentle:customize status` prints one read-only line; an unknown
1012
1051
  argument, Esc, or a cancelled menu writes nothing. With no argument the
1013
1052
  command opens the floating panel (`lib/customize-panel.js`, painted through its
1014
1053
  own palette) over `ctx.ui.custom` in Gentle Shell's own layout: one left
1015
- `CATEGORIES` list, one right pane headed `<Category> · n/m` with its setting
1016
- rows, each row painting the stored value with `●` and the other with `○`; one
1017
- line above the footer describes the focused setting
1018
- (`<setting> — <what it changes>`), and the footer
1019
- `←/→ or Tab panes · ↑/↓ move · Enter apply · Esc close`. There is no
1020
- `Click` token and no
1021
- `Preview · …` band and no `p profiles` key: this plugin owns no profiles
1022
- concept, so the footer advertises nothing it cannot do — every token in it is a
1023
- key the panel answers to, and a narrow card compacts the legend instead of
1024
- wrapping it. `←/→` or `Tab` moves
1025
- between the category and value panes, `↑/↓` or `j/k` moves the cursor, `Enter`
1026
- applies the focused row and `Esc` closes without a write; a click on a category
1027
- selects it, a click on a row applies it, and a click outside the panes is
1028
- ignored (a press only captures the gesture, so a drag never applies a row).
1029
- Each switch is one row that paints the stored state and carries the opposite
1030
- value. Each category owns exactly one switch: `Herdr Sidebar` shows the single
1031
- `Sidebar agent rows` row and its description names the managed agent rows only,
1032
- while the only Moshi switch is the `Notifications` row under
1033
- `Moshi notifications`, which applies the `gentle-moshi.json` flag through
1034
- `applyMoshiNotifications`. The two channels are never mixed: the sidebar-rows
1054
+ `CATEGORIES` list, one right pane headed `<Category> · n/m`, and one line per
1055
+ setting with its options inline — `●` the stored option, `›` the cursor while it
1056
+ sits elsewhere, `○` the rest. The arrows move the option cursor and only `Enter`
1057
+ applies; `Enter` keeps the card open (only a Moshi settings change that needs a
1058
+ Pi reload closes it), `Esc` closes without a write, `Tab`
1059
+ switches panes and `↑/↓` (or `j/k`) moves between settings. A line whose options
1060
+ do not fit scrolls sideways behind muted `‹`/`›` markers with an `n/m` counter,
1061
+ falling back to a compact `‹ value ›`; the Preview block below the panes reads
1062
+ `Preview · <option> · <title>` plus a sample, and a theme option is painted in
1063
+ that theme's own palette; the footer carries one of three legends (categories,
1064
+ option row, panes) after the `Click · ` prefix, chosen by what the keys do right
1065
+ now and compacted instead of wrapped on a narrow card, with no `p profiles` key
1066
+ because this plugin owns no profiles concept. A click on an option applies
1067
+ exactly that option, a click on a setting's name only moves the focus, a click
1068
+ on a category selects it, and a click outside the panes is ignored (a press only
1069
+ captures the gesture, so a drag never applies anything).
1070
+ Each category owns its own settings: `Herdr Sidebar` shows the single
1071
+ `Sidebar agent rows` setting, the only Moshi switch is the `Notifications`
1072
+ setting under `Moshi notifications`, which applies the `gentle-moshi.json` flag
1073
+ through `applyMoshiNotifications`, and `Herdr Theme` owns the `Theme sync`
1074
+ toggle plus the inline `Gentle Shell theme` list (§12). The two channels are
1075
+ never mixed: the sidebar-rows
1035
1076
  switch neither reads nor writes that flag, so disabling the agent rows leaves
1036
1077
  the notification channel exactly as it was.
1037
- An inconclusive sidebar verdict (`unknown`) renders as `● Unknown` with a note
1038
- instead of hiding the row: toggling still attempts the repair and reports the
1039
- apply step's own error, exactly like the menu. The plain
1078
+ An inconclusive sidebar verdict (`unknown`) renders with no option marked `●`
1079
+ and a note instead of hiding the setting: toggling still attempts the repair and
1080
+ reports the apply step's own error, exactly like the menu. The plain
1040
1081
  two-step `ctx.ui.select` menu remains the
1041
1082
  fallback when the TUI helpers or `ctx.ui.custom` are unavailable. The removed
1042
1083
  `Plugin tools` and `Reset` sections and the in-process provider slot
@@ -1160,10 +1201,12 @@ exactly one mechanism writes each piece of state.
1160
1201
  `worktree_close` / `worktree_session_open` / `worktree_warp`), the warp
1161
1202
  panel, the ODD and Issues readers, and the `Plugin tools` toggles no longer
1162
1203
  ship. This package publishes the Herdr producer sidecar and the Moshi channel
1163
- only; `bin/gentle-sidebar.js` is its one CLI and `/herdr-gentle:customize`
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.
1204
+ only; `bin/gentle-sidebar.js` is its one CLI and the customize switches are
1205
+ reached two ways, additively: `/herdr-gentle:customize`, always, and — when
1206
+ gentle-shell-bridge answers its handshake — the `Herdr` page of Gentle Shell's
1207
+ own `/gentle:customize` menu as well (§7). The former
1208
+ in-process provider slot `globalThis[Symbol.for("herdr-gentle.customize.v1")]`
1209
+ stays removed.
1167
1210
  - Rollback: disable this plugin → producer stops writing; consumer sweeps
1168
1211
  only `gentle_*` tokens + labels it set (O5); pi-tree re-enable restores
1169
1212
  `↳N` behavior with zero data migration.
@@ -1255,91 +1298,331 @@ list, not silent.
1255
1298
  ## 12. Theme sync (Pi palette → Herdr theme)
1256
1299
 
1257
1300
  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.
1301
+ pinned while the sync is off (S1–S7). The switch lives with the other two on
1302
+ `/herdr-gentle:customize` and, beside it, on the `Herdr` page of Gentle Shell's
1303
+ own customize menu whenever the bridge answers the handshake (§7), where it is
1304
+ the `Theme sync` and `Select theme` rows; the user-facing reference is
1305
+ [docs/theme-sync.md](docs/theme-sync.md). Six modules with one owner — this Pi
1306
+ package — and one direction of data:
1307
+
1308
+ | Module | Owns |
1309
+ | --- | --- |
1310
+ | `lib/theme-store.js` | 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. |
1311
+ | `lib/theme-projection.js` | The pure translation: assignable Herdr theme names, Herdr token order, `HERDR_ROLE_SOURCES`, the `DOTS_FIXED` surface tables, `projectPalette`, `paletteFingerprint`, and the `Off` label the projection exposes. No filesystem, no host import. |
1312
+ | `lib/herdr-theme-config.js` | The pure planner — a **line splicer, not a TOML validator**: table-boundary scanning (headers only at real line starts), opaque bytes outside the two theme tables, a strict theme-table grammar, the whole-line `was` marker with byte-exact restoration (the user's latest trailing comment wins), the single regenerated block (`begin` / `begin created` … `end` / `end after a missing line ending`) and the created table it removes again, the ambiguity refusal for a marker-shaped comment above a block being removed or moved, the 1.8.0 marker-pair migration, the BOM, and the enforced splice invariant. |
1313
+ | `lib/herdr-theme-apply.js` | The writer: the availability guard matrix, the bounded snapshot, the two compare-and-swap checks, the atomic non-overwriting backup (a regular existing file is accepted as it is), retried temp cleanup that names a survivor and only ever removes a path it created itself, the growth limit, `forceReload`, the exclusive temp + `fchmod` (all mode bits) + `fsync` + `rename`, and the reload. |
1314
+ | `extensions/herdr-theme-sync.ts` | The follower: session-start evaluation, 500 ms tick, the two identities, one in-process apply per change, the notices. |
1315
+ | `lib/customize-panel.js` + the theme wiring in `extensions/gentle-herdr-state.ts` | The switch and the card: `applyThemeSync`, `writeThemeChoice`, `applyCustomizePanel`, `customize status`, and the setting lines, Preview block, legends and pointer hits. |
1316
+
1317
+ **In process, and why that is the fix.** The 1.8.0 follower spawned
1318
+ `bin/configure-theme.js` from the *separately installed* Herdr plugin, found
1319
+ through `herdr plugin list`, and that writer refused any `[theme]` table outside
1320
+ its own marker block. A Pi-only update therefore kept running the old plugin's
1321
+ writer — or, on an install that never shipped it, ran no writer at all — while
1322
+ the user's real config, which already owns `[theme]`, was never touched. The
1323
+ reference implementation
1324
+ ([gentle-herdr](https://github.com/MarsSall/gentle-herdr), MIT License,
1325
+ Copyright (c) MarsSall) applies from Pi itself, so this package does the same:
1326
+ `applyHerdrTheme` edits the config inside the running Pi process, and the
1327
+ plugin-side `configure-theme.js`, its planner and the
1328
+ `# BEGIN herdr-gentle-theme` managed block are gone. The plugin is not involved
1329
+ in theme sync and needs no update for it. A config written by 1.8.0 keeps
1330
+ working: the planner drops those two marker lines only when they are the nearest
1331
+ pair and the pair actually encloses a `[theme]`/`[theme.custom]` table (a stale
1332
+ pair around unrelated keys is the user's text and stays, and a pair closing on an
1333
+ unterminated last line migrates without changing the file's final-newline state),
1334
+ then edits the table between them like any other. Pi colours become hex
1335
+ strings in the follower through `colorToHex` from `@earendil-works/pi-tui`,
1336
+ which is why the follower is its own extension rather than a section of the
1337
+ state sidecar: the sidecar is loaded by every suite as a renamed copy with one
1338
+ stubbed host import, and the projection needs no host at all.
1339
+
1340
+ **Ownership rule, and the two classes it implies.** Sync is a switch the user
1341
+ turns on deliberately, so with the sync on — or a theme pinned — this package
1342
+ OWNS the `name` line and every token it projects, and it must be able to give
1343
+ them back. Two classes, which is what makes switching Pi themes safe:
1344
+
1345
+ - **a value the user already had** is replaced in place and remembered by one
1346
+ comment recording **the whole original line** (minus its indentation, so
1347
+ trailing spaces and an inline comment are part of the record) above it: the
1348
+ first original wins, a later palette change reuses it, and a projection that
1349
+ stops carrying that token — or comes back to the recorded value — **restores
1350
+ the line byte for byte** and drops the comment. The one exception is the
1351
+ **latest edit wins**: if the user changed the line's trailing comment after the
1352
+ planner wrote its value, the restore keeps the recorded key/value and the
1353
+ user's *current* comment. A comment is only a marker when
1354
+ its payload parses as the strict `key = <string> [comment]` line for the key
1355
+ under it, and two markers for one key are refused;
1356
+ - **a token the user did not have** is written inside ONE marked block
1357
+ (`# herdr-gentle-shell: begin` … `# herdr-gentle-shell: end`, or
1358
+ `# herdr-gentle-shell: begin created` when the planner also creates the table,
1359
+ and closed with `# herdr-gentle-shell: end after a missing line ending` when
1360
+ placing the block also added the file's missing final line ending, so a later
1361
+ clear takes back only what the planner added)
1362
+ at the end of `[theme.custom]`, regenerated on every plan, and removed entirely
1363
+ when nothing is left to own — so leaving a projection never leaves a stale
1364
+ colour behind. A table the planner created is removed again once its block
1365
+ empties and nothing else lives in it, which is what makes a cycle of
1366
+ projections ending in an empty custom projection return the original
1367
+ `[theme.custom]` byte for byte; only `<token> = "#rrggbb"` lines may sit
1368
+ inside the block, and anything else there is refused rather than deleted.
1369
+ Removing or moving a block is refused
1370
+ (`line <n>: ambiguous herdr-gentle-shell marker above the managed block`) when a
1371
+ marker-shaped comment directly above `begin` would become adjacent to the token
1372
+ key under the block, because the next plan would promote the user's ordinary
1373
+ comment to ownership.
1374
+
1375
+ A token the user owns with no marker (`panel_bg`, `blue`, `yellow`, …) is never
1376
+ written, merged or repaired, even when the projection stops carrying it: it was
1377
+ never ours. A `[theme.custom]` header the **user** wrote stays even when it ends
1378
+ up empty, because the planner cannot prove it created that line. Two
1379
+ consequences are stated rather than papered over: a tool that rewrites the same
1380
+ keys (a desktop-theme sync such as DMS/Niri, for example) overwrites the
1381
+ projected values on its next run, and the next palette change here overwrites
1382
+ them back; and the revert is per token, not per file — a user-written empty header
1383
+ and the `name` marker stay. This is also where
1384
+ the port deliberately differs from the reference: it accepts
1385
+ `auto_switch = false` untouched — the reference refuses that line outright,
1386
+ which is exactly why the user's real config was never written — and it edits
1387
+ tables the reference treats as foreign.
1278
1388
 
1279
1389
  **The state file is the only persisted truth.** `gentle-theme.json` holds
1280
1390
  `{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`,
1391
+ panel and the follower read the same document, so the setting, the switch and
1392
+ the applied palette can never disagree. Missing is inert (`sync:false`,
1283
1393
  `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
1394
+ no option marked, a `state unknown` note, follower silent — never a guess, and
1395
+ it is written over only
1285
1396
  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.
1397
+ nothing at all (S7), and a stored pin is carried across a sync toggle so turning
1398
+ the sync off restores that choice instead of unassigning it.
1399
+
1400
+ **Tick, fingerprint and the follower repairs.** The host publishes no
1401
+ theme-change event, so the palette is a pull-read of `ctx.ui.theme` (or
1402
+ `ctx.ui.getTheme(name)` for a pin): one immediate evaluation on `session_start`
1403
+ and then one every 500 ms, on an unreferenced timer so an idle follower never
1404
+ keeps Pi alive, cleared on `session_shutdown` (a shutdown that lands during the
1405
+ first evaluation wins: no tick is armed afterwards). Each evaluation computes two
1406
+ identities — the requested `[sync, chosen]` and the palette fingerprint
1407
+ (`[theme name, sorted token/hex pairs]`) — and acts only when one differs from
1408
+ the last one it recorded, so a theme recoloured in place (same name, new
1409
+ colours) is noticed without a restart, and the same palette is never applied
1410
+ twice. The observation is recorded **before** the apply, so a failed or refused
1411
+ write is never retried on the next tick and never blocks the next real change
1412
+ either; one apply is in flight at a time. With the sync off and no theme pinned
1413
+ the follower asks for nothing at all (no write, no removal) **and forgets what it
1414
+ applied**, which is what makes re-enabling the sync always re-apply: without that
1415
+ reset the next `On` would look unchanged and a config the user repaired in
1416
+ between would never be written (an already-matching config then answers
1417
+ `unchanged`). A projection with no concrete token is refused before the writer is
1418
+ called — `Herdr theme not applied: <name> has no concrete colours to project.`,
1419
+ once per session — because it would otherwise rewrite the theme name and paint
1420
+ nothing. Availability is decided once, by `applyHerdrTheme`, so the follower can
1421
+ never disagree with the writer about who may write; a subagent child
1422
+ (`GENTLE_PI_AGENTS_CHILD=1`) never registers the follower at all, and every
1423
+ user-visible outcome is one of the fixed notices in
1424
+ [docs/theme-sync.md](docs/theme-sync.md). A `partial/reload` sets an **owed
1425
+ reload**: the next apply attempt of the same session is sent with
1426
+ `forceReload`, and a success pays the debt off. It is session memory on purpose
1427
+ (a tick never reloads while the debt stands), which is why the notice ends with
1428
+ `Run 'herdr server reload-config' to apply it.`
1429
+
1430
+ **A splicer, and a strict core.** The writer edits the user's own `[theme]` and
1431
+ `[theme.custom]` tables and preserves every byte it does not own: other tables
1432
+ and keys, comments, blank lines, ordering, indentation, spacing around `=`, a
1433
+ trailing comment on a rewritten line, CRLF or mixed endings, a leading UTF-8 BOM
1434
+ and a missing final newline. **Outside those two tables nothing is validated**:
1435
+ the planner only tracks the three contexts that can hide a line
1436
+ break (multi-line strings, multi-line arrays, inline tables) plus comments, so it
1437
+ can find table boundaries — a header-shaped line must parse and a multi-line
1438
+ construct must be terminated, or the plan refuses — and it treats the rest of the
1439
+ document as opaque bytes: an input that is already invalid TOML there is the
1440
+ user's pre-existing breakage (Herdr refuses to load it) and is left exactly as it
1441
+ is. Escapes there are never validated (a backslash only consumes the next
1442
+ character, in single-line and multi-line strings alike) and a run of three or
1443
+ more quotes closes a multi-line string; the scan validates escapes only where it
1444
+ must read a value back (a quoted key and a strict theme-table line).
1445
+ **Inside the two tables it is strict**: comments, blank lines and
1446
+ `key = value [comment]` with a single-line string, boolean, integer or float; a
1447
+ key the plan must touch in any other form is refused with its line number, while
1448
+ a key it does not touch is kept byte for byte whenever the scanner can find where
1449
+ that line ends. It refuses: `auto_switch` with a value other than `false`,
1450
+ `dark_name`/`light_name`, a top-level `theme` key, a dotted key extending
1451
+ `[theme]` or a Herdr token in `[theme.custom]`, a second `[theme]`/`[theme.custom]`
1452
+ table, a third `[theme.*]` table, `[[theme]]` array-of-tables, `name`/
1453
+ `auto_switch` repeated in `[theme]`, a token repeated in `[theme.custom]` or in
1454
+ both the block and the user's keys, two markers for one key, a touched value that
1455
+ is not a strict single-line string (or a multi-line form, refused as "cannot
1456
+ record the original value … safely"), a control character, a bare carriage
1457
+ return, a malformed block (outside `[theme.custom]`, unterminated, a second
1458
+ begin, an end without a begin, any line in it that is not
1459
+ `<token> = "#rrggbb"`), the ambiguous marker above a block that is about to be
1460
+ removed or moved (`ambiguous herdr-gentle-shell marker above the managed
1461
+ block`), and a table header or unterminated multi-line string/array/inline table
1462
+ the boundary scan cannot resolve. A malformed
1463
+ projection is refused the same way without a line number, because that one is a
1464
+ package bug. **The splice invariant is enforced in code**: before `ok: true` the
1465
+ planner re-derives the non-theme lines of its own output and compares them with
1466
+ the input's (only the 1.8.0 marker lines it wrote may be missing, and only the
1467
+ single terminator needed to append a table after an unterminated last line may be
1468
+ added); a mismatch returns `internal splice invariant violated; no changes
1469
+ proposed.` rather than a document that moved a byte it promised not to touch. The
1470
+ file-level refusals belong to the snapshot and the write: a non-absolute or
1471
+ non-canonical path, a symlinked parent directory, not a regular single-link
1472
+ file, over 256 KiB, invalid UTF-8, a backup path that is not a regular file, a
1473
+ planned document past the 256 KiB limit, bytes that changed between the snapshot
1474
+ and the replacement (`Herdr config changed before replacement`), a backup temp
1475
+ that cannot be removed, a missing config (never bootstrapped), and a failed
1476
+ rename. Every refusal writes nothing, backs up nothing and reloads nothing.
1477
+
1478
+ **Safe write, and exactly one reload.** The snapshot is one bounded strictly
1479
+ decoded read with stat identity checks; a leading BOM is decoded as part of the
1480
+ text (`ignoreBOM`) so a changed write keeps it and the backup and the file agree
1481
+ on those bytes. The plan is refused **before anything is written** if the
1482
+ document would grow past the same 256 KiB limit. The original bytes are re-read
1483
+ and compared immediately before the backup and again immediately before the
1484
+ swap, so a projection computed from stale bytes is never renamed into place. The new text
1485
+ is staged at a path chosen **before the file exists**, so every failure — open,
1486
+ write, `fsync`, `fchmod` — leaves the writer able to remove it: exclusive `0600`,
1487
+ `fchmod`-ed to the original mode (`0o7777`, so setuid/setgid/sticky survive),
1488
+ compared once more, then `rename`d. Temp cleanup is best-effort **and never
1489
+ silent**: the unlink is retried once and then force-removed, and a survivor is
1490
+ reported instead of hiding — if the **backup's** temp survives, the apply fails
1491
+ with `Herdr backup temporary could not be removed: <path>` (so it can never
1492
+ answer `requested` with a stray file), and a surviving **staged** temp appends
1493
+ `; temporary file left behind: <path>` to the `partial`/`config` error. Cleanup
1494
+ only ever removes a path the call created itself: a foreign file at that exact
1495
+ temp name makes the exclusive open fail with `EEXIST`, the apply answers
1496
+ `partial`/`config` with that text, and the file is left alone (config and backup
1497
+ untouched). The
1498
+ backup itself is **published atomically and never overwritten**: written to a
1499
+ temp name and hard-linked into place, so a crash or a full disk leaves no
1500
+ truncated `.bak` that a later run would mistake for "already backed up". A
1501
+ regular file already at the backup path — pre-existing or raced — **is** the
1502
+ existing backup: accepted as it is, never compared and never overwritten (it may
1503
+ be an older original from before the user's last edit), while a non-regular
1504
+ entry (directory, symlink, socket) is refused. `unchanged` writes
1505
+ nothing and reloads nothing — Herdr already holds that palette, and a reload on
1506
+ every tick would make the sidebar flicker for nothing. `forceReload` is the one
1507
+ exception, and it exists for the owed-reload repair above: it reloads an
1508
+ unchanged plan and answers `requested`. A real write is followed by exactly one
1509
+ `herdr server reload-config` through `execFile` with `HERDR_BIN_PATH` (default
1510
+ `herdr`), no shell, a 5 s timeout and a 4096-byte output cap; a reload failure is
1511
+ reported as partial state because the config is already committed. **CAS limit:**
1512
+ an edit that lands between the final compare and the `rename` cannot be detected
1513
+ without holding a lock on the config, which this writer deliberately does not
1514
+ do — everything earlier (snapshot, plan, backup, staging) is still caught. A
1515
+ **pre-existing truncated backup** is a second documented limit: because a regular
1516
+ file at that path is accepted as it is and never repaired or compared, a `.bak`
1517
+ damaged by an earlier failure or another tool stays damaged.
1518
+
1519
+ **The guard matrix.** `applyHerdrTheme` answers `unavailable` with one reason
1520
+ before it opens any file: `not-herdr` (no `HERDR_ENV=1` plus a pane id and an
1521
+ absolute socket path), `child` (a subagent's Pi must never write the user's
1522
+ config), `remote` (an SSH session, where Herdr reads another machine's config),
1523
+ and `unsupported` (a `herdr-dev` binary, a non-Linux host, or a non-absolute
1524
+ socket/config path). The follower reports `not-herdr`, `remote` and
1525
+ `unsupported` as one `info` notice per session and asks again only when the
1526
+ palette itself changes.
1527
+
1528
+ **The panel.** `/herdr-gentle:customize` — the surface that always exists (§7) —
1529
+ reuses Gentle Shell's own card shape:
1530
+ one left `CATEGORIES` list, one right pane headed `<Category> · n/m`, one line
1531
+ per setting with its options inline (`●` stored, `›` cursor elsewhere, `○` the
1532
+ rest). The arrows move the option cursor and only Enter applies; Enter keeps the
1533
+ card open (only the Moshi reload closes it), Esc closes without a write, Tab
1534
+ switches panes. A line whose options do not fit scrolls sideways behind muted
1535
+ `‹`/`›` with an `n/m` counter, falling back to a compact `‹ value ›`. The
1536
+ Preview block below the panes is `Preview · <option> · <title>` plus a sample
1537
+ painted with the host theme, where a theme option shows that theme's own palette
1538
+ through the raw SGR the host hands back. Three footer legends (categories,
1539
+ option row, panes) are chosen by what the keys do right now and compact instead
1540
+ of wrapping. The theme list comes from `ctx.ui.getAllThemes()` in the host's own
1541
+ order with `None` first, the `Gentle Shell theme` setting is painted dim and
1542
+ refused with `Turn Theme sync off to pick a specific theme.` while the sync is
1543
+ on, and a host that exposes no list shows one note instead of an empty picker.
1544
+ The panel writes nothing itself: it calls the extension's apply path, swaps in
1545
+ the model that path re-read, and keeps the cursor by structural option ids.
1546
+
1547
+ **The page.** The `Herdr` page of Gentle Shell's own customize menu (§7) is not
1548
+ this card: Gentle Shell paints its own rows and enters their actions. The
1549
+ switch side is the same — two rows, `Theme sync` and `Select theme`, built from
1550
+ the same model by `lib/customize-rows.js`, applied through the same
1551
+ `applyCustomizePanel` — so the notices above are the same strings, a theme row
1552
+ keeps its swatch, and the theme rows are hidden while the sync is on rather
1553
+ than refused in place. The sync never needs a Pi reload on either surface; the
1554
+ one surface-specific difference in this feature is Moshi's, which asks for a
1555
+ restart on the page because a row action has no reload handle (§7).
1556
+
1557
+ The page's row set is FIXED for the life of the menu, and the cache in
1558
+ `lib/customize-rows.js` is what makes that affordable: one model read per paint
1559
+ burst (one synchronous `configure.js --check`, not one per callback), dropped
1560
+ after an `apply` settles and after a one-second TTL. Two properties follow and
1561
+ are accepted rather than promised away. First, an external write while the menu
1562
+ is idle becomes visible on the first read after the cache expires, or on a
1563
+ rebuild: the cache never asks the host to repaint, so a repaint that lands
1564
+ before expiry redraws the previous model and the displayed state has no upper
1565
+ freshness bound. Second, when an external write hides the row the user had
1566
+ focused (the theme
1567
+ picker, with the sync turned on elsewhere), the host clamps the focus to the
1568
+ neighbouring row, so Enter can act on that one; the clamp itself writes nothing.
1569
+ The fixed row set is also why a theme applied from a row is checked against a
1570
+ fresh `ctx.ui.getAllThemes()` read at apply time: a theme removed after the
1571
+ build refuses and writes nothing instead of pinning a name this install no
1572
+ longer has. That check lives on the page's own apply path, so the command's
1573
+ picker and the mounted panel keep the `865d360` write (S2).
1326
1574
 
1327
1575
  **Limits** (the §10 style, none of them a promise this design makes):
1328
1576
 
1329
1577
  - The 500 ms tick is the whole observation granularity — there is no event to
1330
1578
  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.
1579
+ - The page's displayed state has **no upper freshness bound**: its row cache
1580
+ never requests a repaint, so a write from another process while the menu is
1581
+ idle appears on the first read after the cache expires, or on a rebuild, not
1582
+ when it lands; a repaint that lands before expiry redraws the previous model,
1583
+ and on a menu nobody touches the write is not shown at all.
1584
+ - The page cannot keep the cursor on a row an external write hid: the host clamps
1585
+ the focus to the neighbouring row, so the next Enter can act on that neighbour.
1586
+ The clamp writes nothing; it only moves the cursor.
1587
+ - The automated evidence is a stubbed Pi host plus a real binary stand-in on
1588
+ disk; **no live Pi TUI run is recorded**. `ctx.ui.theme`, `getTheme`,
1589
+ `getAllThemes`, `notify` and the host component contract are used as
1590
+ documented, and a host missing one degrades to "nothing changed" rather than
1591
+ to a guess.
1592
+ - Remote sessions are inactive: in SSH the Herdr client reads the config of the
1593
+ machine it runs on, so writing the server-side file would change nothing on
1594
+ screen and the guard refuses.
1595
+ - Two writers of the same keys fight. The sync owns what it projects, so a
1596
+ desktop-theme sync and this feature overwrite each other on their next run;
1597
+ there is no merge, lock or arbitration, only the `was` comments, the marked
1598
+ block and the one-time backup.
1599
+ - The compare-and-swap has one unavoidable window: an edit between the final
1600
+ compare and the rename is undetectable without a config lock, which this
1601
+ writer does not take.
1602
+ - The planner is a **splicer, not a validator**: it guarantees table boundaries
1603
+ for terminated multi-line constructs and byte-identical non-theme lines (checked
1604
+ by the splice invariant), and it deliberately checks nothing outside the theme
1605
+ tables — invalid TOML there is left as it is, because Herdr already refuses
1606
+ that file. A theme-table line the plan must touch has to be the strict
1607
+ single-line form; the revert is per token, so a user-written empty
1608
+ `[theme.custom]` header and the `name` marker stay behind (a table the planner
1609
+ created is removed, so a full cycle is byte-identical).
1610
+ - A pre-existing truncated backup is kept, not repaired (see above), which is why
1611
+ the `was` comments are the per-value revert path.
1612
+ - There is no "full clear" distinct from an empty custom projection: a projection
1613
+ always carries the theme name, so a `name` line the planner inserted stays (an
1614
+ existing name is restored) and a `[theme]` table it created is not removed —
1615
+ only the `[theme.custom]` table it created is, once its block empties.
1335
1616
  - Herdr's surface tokens (`sidebar_bg`, `panel_bg`, `active_row_bg`,
1336
- `selection_bg`, `surface*`) and `peach` are never written: Pi names
1617
+ `selection_bg`, `surface*`) and `peach` are not projected: Pi names
1337
1618
  foregrounds and accents, not panel backgrounds, so backgrounds and status
1338
- colours stay with the Herdr base theme.
1619
+ colours stay with the Herdr base theme — except the `DOTS_FIXED` tables for
1620
+ `Gentleman-Cute`, `Gentleman-Sexy` and `Gentle`, which are the surfaces the
1621
+ user's own Herdr profiles already use.
1339
1622
  - One machine: another Herdr client reads its own `config.toml`, so this is a
1340
1623
  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.
1624
+ - No automatic repair: a `[theme]` table the user or another tool keeps editing
1625
+ is re-projected on the next palette change and never reconciled, and a document
1626
+ whose table boundaries cannot be found (an unterminated multi-line string,
1627
+ array or inline table) stops the writer until it is fixed. A missing
1628
+ `config.toml` is refused, never created.