herdr-gentle-shell 1.8.0 → 1.8.1

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
@@ -1012,31 +1012,33 @@ nothing:
1012
1012
  argument, Esc, or a cancelled menu writes nothing. With no argument the
1013
1013
  command opens the floating panel (`lib/customize-panel.js`, painted through its
1014
1014
  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
1015
+ `CATEGORIES` list, one right pane headed `<Category> · n/m`, and one line per
1016
+ setting with its options inline — `●` the stored option, `›` the cursor while it
1017
+ sits elsewhere, `○` the rest. The arrows move the option cursor and only `Enter`
1018
+ applies; `Enter` keeps the card open (only a Moshi settings change that needs a
1019
+ Pi reload closes it), `Esc` closes without a write, `Tab`
1020
+ switches panes and `↑/↓` (or `j/k`) moves between settings. A line whose options
1021
+ do not fit scrolls sideways behind muted `‹`/`›` markers with an `n/m` counter,
1022
+ falling back to a compact `‹ value ›`; the Preview block below the panes reads
1023
+ `Preview · <option> · <title>` plus a sample, and a theme option is painted in
1024
+ that theme's own palette; the footer carries one of three legends (categories,
1025
+ option row, panes) after the `Click · ` prefix, chosen by what the keys do right
1026
+ now and compacted instead of wrapped on a narrow card, with no `p profiles` key
1027
+ because this plugin owns no profiles concept. A click on an option applies
1028
+ exactly that option, a click on a setting's name only moves the focus, a click
1029
+ on a category selects it, and a click outside the panes is ignored (a press only
1030
+ captures the gesture, so a drag never applies anything).
1031
+ Each category owns its own settings: `Herdr Sidebar` shows the single
1032
+ `Sidebar agent rows` setting, the only Moshi switch is the `Notifications`
1033
+ setting under `Moshi notifications`, which applies the `gentle-moshi.json` flag
1034
+ through `applyMoshiNotifications`, and `Herdr Theme` owns the `Theme sync`
1035
+ toggle plus the inline `Gentle Shell theme` list (§12). The two channels are
1036
+ never mixed: the sidebar-rows
1035
1037
  switch neither reads nor writes that flag, so disabling the agent rows leaves
1036
1038
  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
1039
+ An inconclusive sidebar verdict (`unknown`) renders with no option marked `●`
1040
+ and a note instead of hiding the setting: toggling still attempts the repair and
1041
+ reports the apply step's own error, exactly like the menu. The plain
1040
1042
  two-step `ctx.ui.select` menu remains the
1041
1043
  fallback when the TUI helpers or `ctx.ui.custom` are unavailable. The removed
1042
1044
  `Plugin tools` and `Reset` sections and the in-process provider slot
@@ -1255,91 +1257,292 @@ list, not silent.
1255
1257
  ## 12. Theme sync (Pi palette → Herdr theme)
1256
1258
 
1257
1259
  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
1260
+ pinned while the sync is off (S1–S7). The switch lives with the other two in
1259
1261
  `/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.
1262
+ [docs/theme-sync.md](docs/theme-sync.md). Six modules with one owner — this Pi
1263
+ package — and one direction of data:
1264
+
1265
+ | Module | Owns |
1266
+ | --- | --- |
1267
+ | `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. |
1268
+ | `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. |
1269
+ | `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. |
1270
+ | `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. |
1271
+ | `extensions/herdr-theme-sync.ts` | The follower: session-start evaluation, 500 ms tick, the two identities, one in-process apply per change, the notices. |
1272
+ | `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. |
1273
+
1274
+ **In process, and why that is the fix.** The 1.8.0 follower spawned
1275
+ `bin/configure-theme.js` from the *separately installed* Herdr plugin, found
1276
+ through `herdr plugin list`, and that writer refused any `[theme]` table outside
1277
+ its own marker block. A Pi-only update therefore kept running the old plugin's
1278
+ writer — or, on an install that never shipped it, ran no writer at all — while
1279
+ the user's real config, which already owns `[theme]`, was never touched. The
1280
+ reference implementation
1281
+ ([gentle-herdr](https://github.com/MarsSall/gentle-herdr), MIT License,
1282
+ Copyright (c) MarsSall) applies from Pi itself, so this package does the same:
1283
+ `applyHerdrTheme` edits the config inside the running Pi process, and the
1284
+ plugin-side `configure-theme.js`, its planner and the
1285
+ `# BEGIN herdr-gentle-theme` managed block are gone. The plugin is not involved
1286
+ in theme sync and needs no update for it. A config written by 1.8.0 keeps
1287
+ working: the planner drops those two marker lines only when they are the nearest
1288
+ pair and the pair actually encloses a `[theme]`/`[theme.custom]` table (a stale
1289
+ pair around unrelated keys is the user's text and stays, and a pair closing on an
1290
+ unterminated last line migrates without changing the file's final-newline state),
1291
+ then edits the table between them like any other. Pi colours become hex
1292
+ strings in the follower through `colorToHex` from `@earendil-works/pi-tui`,
1293
+ which is why the follower is its own extension rather than a section of the
1294
+ state sidecar: the sidecar is loaded by every suite as a renamed copy with one
1295
+ stubbed host import, and the projection needs no host at all.
1296
+
1297
+ **Ownership rule, and the two classes it implies.** Sync is a switch the user
1298
+ turns on deliberately, so with the sync on — or a theme pinned — this package
1299
+ OWNS the `name` line and every token it projects, and it must be able to give
1300
+ them back. Two classes, which is what makes switching Pi themes safe:
1301
+
1302
+ - **a value the user already had** is replaced in place and remembered by one
1303
+ comment recording **the whole original line** (minus its indentation, so
1304
+ trailing spaces and an inline comment are part of the record) above it: the
1305
+ first original wins, a later palette change reuses it, and a projection that
1306
+ stops carrying that token — or comes back to the recorded value — **restores
1307
+ the line byte for byte** and drops the comment. The one exception is the
1308
+ **latest edit wins**: if the user changed the line's trailing comment after the
1309
+ planner wrote its value, the restore keeps the recorded key/value and the
1310
+ user's *current* comment. A comment is only a marker when
1311
+ its payload parses as the strict `key = <string> [comment]` line for the key
1312
+ under it, and two markers for one key are refused;
1313
+ - **a token the user did not have** is written inside ONE marked block
1314
+ (`# herdr-gentle-shell: begin` … `# herdr-gentle-shell: end`, or
1315
+ `# herdr-gentle-shell: begin created` when the planner also creates the table,
1316
+ and closed with `# herdr-gentle-shell: end after a missing line ending` when
1317
+ placing the block also added the file's missing final line ending, so a later
1318
+ clear takes back only what the planner added)
1319
+ at the end of `[theme.custom]`, regenerated on every plan, and removed entirely
1320
+ when nothing is left to own — so leaving a projection never leaves a stale
1321
+ colour behind. A table the planner created is removed again once its block
1322
+ empties and nothing else lives in it, which is what makes a cycle of
1323
+ projections ending in an empty custom projection return the original
1324
+ `[theme.custom]` byte for byte; only `<token> = "#rrggbb"` lines may sit
1325
+ inside the block, and anything else there is refused rather than deleted.
1326
+ Removing or moving a block is refused
1327
+ (`line <n>: ambiguous herdr-gentle-shell marker above the managed block`) when a
1328
+ marker-shaped comment directly above `begin` would become adjacent to the token
1329
+ key under the block, because the next plan would promote the user's ordinary
1330
+ comment to ownership.
1331
+
1332
+ A token the user owns with no marker (`panel_bg`, `blue`, `yellow`, …) is never
1333
+ written, merged or repaired, even when the projection stops carrying it: it was
1334
+ never ours. A `[theme.custom]` header the **user** wrote stays even when it ends
1335
+ up empty, because the planner cannot prove it created that line. Two
1336
+ consequences are stated rather than papered over: a tool that rewrites the same
1337
+ keys (a desktop-theme sync such as DMS/Niri, for example) overwrites the
1338
+ projected values on its next run, and the next palette change here overwrites
1339
+ them back; and the revert is per token, not per file — a user-written empty header
1340
+ and the `name` marker stay. This is also where
1341
+ the port deliberately differs from the reference: it accepts
1342
+ `auto_switch = false` untouched — the reference refuses that line outright,
1343
+ which is exactly why the user's real config was never written — and it edits
1344
+ tables the reference treats as foreign.
1278
1345
 
1279
1346
  **The state file is the only persisted truth.** `gentle-theme.json` holds
1280
1347
  `{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`,
1348
+ panel and the follower read the same document, so the setting, the switch and
1349
+ the applied palette can never disagree. Missing is inert (`sync:false`,
1283
1350
  `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
1351
+ no option marked, a `state unknown` note, follower silent — never a guess, and
1352
+ it is written over only
1285
1353
  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.
1354
+ nothing at all (S7), and a stored pin is carried across a sync toggle so turning
1355
+ the sync off restores that choice instead of unassigning it.
1356
+
1357
+ **Tick, fingerprint and the follower repairs.** The host publishes no
1358
+ theme-change event, so the palette is a pull-read of `ctx.ui.theme` (or
1359
+ `ctx.ui.getTheme(name)` for a pin): one immediate evaluation on `session_start`
1360
+ and then one every 500 ms, on an unreferenced timer so an idle follower never
1361
+ keeps Pi alive, cleared on `session_shutdown` (a shutdown that lands during the
1362
+ first evaluation wins: no tick is armed afterwards). Each evaluation computes two
1363
+ identities — the requested `[sync, chosen]` and the palette fingerprint
1364
+ (`[theme name, sorted token/hex pairs]`) — and acts only when one differs from
1365
+ the last one it recorded, so a theme recoloured in place (same name, new
1366
+ colours) is noticed without a restart, and the same palette is never applied
1367
+ twice. The observation is recorded **before** the apply, so a failed or refused
1368
+ write is never retried on the next tick and never blocks the next real change
1369
+ either; one apply is in flight at a time. With the sync off and no theme pinned
1370
+ the follower asks for nothing at all (no write, no removal) **and forgets what it
1371
+ applied**, which is what makes re-enabling the sync always re-apply: without that
1372
+ reset the next `On` would look unchanged and a config the user repaired in
1373
+ between would never be written (an already-matching config then answers
1374
+ `unchanged`). A projection with no concrete token is refused before the writer is
1375
+ called — `Herdr theme not applied: <name> has no concrete colours to project.`,
1376
+ once per session — because it would otherwise rewrite the theme name and paint
1377
+ nothing. Availability is decided once, by `applyHerdrTheme`, so the follower can
1378
+ never disagree with the writer about who may write; a subagent child
1379
+ (`GENTLE_PI_AGENTS_CHILD=1`) never registers the follower at all, and every
1380
+ user-visible outcome is one of the fixed notices in
1381
+ [docs/theme-sync.md](docs/theme-sync.md). A `partial/reload` sets an **owed
1382
+ reload**: the next apply attempt of the same session is sent with
1383
+ `forceReload`, and a success pays the debt off. It is session memory on purpose
1384
+ (a tick never reloads while the debt stands), which is why the notice ends with
1385
+ `Run 'herdr server reload-config' to apply it.`
1386
+
1387
+ **A splicer, and a strict core.** The writer edits the user's own `[theme]` and
1388
+ `[theme.custom]` tables and preserves every byte it does not own: other tables
1389
+ and keys, comments, blank lines, ordering, indentation, spacing around `=`, a
1390
+ trailing comment on a rewritten line, CRLF or mixed endings, a leading UTF-8 BOM
1391
+ and a missing final newline. **Outside those two tables nothing is validated**:
1392
+ the planner only tracks the three contexts that can hide a line
1393
+ break (multi-line strings, multi-line arrays, inline tables) plus comments, so it
1394
+ can find table boundaries — a header-shaped line must parse and a multi-line
1395
+ construct must be terminated, or the plan refuses — and it treats the rest of the
1396
+ document as opaque bytes: an input that is already invalid TOML there is the
1397
+ user's pre-existing breakage (Herdr refuses to load it) and is left exactly as it
1398
+ is. Escapes there are never validated (a backslash only consumes the next
1399
+ character, in single-line and multi-line strings alike) and a run of three or
1400
+ more quotes closes a multi-line string; the scan validates escapes only where it
1401
+ must read a value back (a quoted key and a strict theme-table line).
1402
+ **Inside the two tables it is strict**: comments, blank lines and
1403
+ `key = value [comment]` with a single-line string, boolean, integer or float; a
1404
+ key the plan must touch in any other form is refused with its line number, while
1405
+ a key it does not touch is kept byte for byte whenever the scanner can find where
1406
+ that line ends. It refuses: `auto_switch` with a value other than `false`,
1407
+ `dark_name`/`light_name`, a top-level `theme` key, a dotted key extending
1408
+ `[theme]` or a Herdr token in `[theme.custom]`, a second `[theme]`/`[theme.custom]`
1409
+ table, a third `[theme.*]` table, `[[theme]]` array-of-tables, `name`/
1410
+ `auto_switch` repeated in `[theme]`, a token repeated in `[theme.custom]` or in
1411
+ both the block and the user's keys, two markers for one key, a touched value that
1412
+ is not a strict single-line string (or a multi-line form, refused as "cannot
1413
+ record the original value … safely"), a control character, a bare carriage
1414
+ return, a malformed block (outside `[theme.custom]`, unterminated, a second
1415
+ begin, an end without a begin, any line in it that is not
1416
+ `<token> = "#rrggbb"`), the ambiguous marker above a block that is about to be
1417
+ removed or moved (`ambiguous herdr-gentle-shell marker above the managed
1418
+ block`), and a table header or unterminated multi-line string/array/inline table
1419
+ the boundary scan cannot resolve. A malformed
1420
+ projection is refused the same way without a line number, because that one is a
1421
+ package bug. **The splice invariant is enforced in code**: before `ok: true` the
1422
+ planner re-derives the non-theme lines of its own output and compares them with
1423
+ the input's (only the 1.8.0 marker lines it wrote may be missing, and only the
1424
+ single terminator needed to append a table after an unterminated last line may be
1425
+ added); a mismatch returns `internal splice invariant violated; no changes
1426
+ proposed.` rather than a document that moved a byte it promised not to touch. The
1427
+ file-level refusals belong to the snapshot and the write: a non-absolute or
1428
+ non-canonical path, a symlinked parent directory, not a regular single-link
1429
+ file, over 256 KiB, invalid UTF-8, a backup path that is not a regular file, a
1430
+ planned document past the 256 KiB limit, bytes that changed between the snapshot
1431
+ and the replacement (`Herdr config changed before replacement`), a backup temp
1432
+ that cannot be removed, a missing config (never bootstrapped), and a failed
1433
+ rename. Every refusal writes nothing, backs up nothing and reloads nothing.
1434
+
1435
+ **Safe write, and exactly one reload.** The snapshot is one bounded strictly
1436
+ decoded read with stat identity checks; a leading BOM is decoded as part of the
1437
+ text (`ignoreBOM`) so a changed write keeps it and the backup and the file agree
1438
+ on those bytes. The plan is refused **before anything is written** if the
1439
+ document would grow past the same 256 KiB limit. The original bytes are re-read
1440
+ and compared immediately before the backup and again immediately before the
1441
+ swap, so a projection computed from stale bytes is never renamed into place. The new text
1442
+ is staged at a path chosen **before the file exists**, so every failure — open,
1443
+ write, `fsync`, `fchmod` — leaves the writer able to remove it: exclusive `0600`,
1444
+ `fchmod`-ed to the original mode (`0o7777`, so setuid/setgid/sticky survive),
1445
+ compared once more, then `rename`d. Temp cleanup is best-effort **and never
1446
+ silent**: the unlink is retried once and then force-removed, and a survivor is
1447
+ reported instead of hiding — if the **backup's** temp survives, the apply fails
1448
+ with `Herdr backup temporary could not be removed: <path>` (so it can never
1449
+ answer `requested` with a stray file), and a surviving **staged** temp appends
1450
+ `; temporary file left behind: <path>` to the `partial`/`config` error. Cleanup
1451
+ only ever removes a path the call created itself: a foreign file at that exact
1452
+ temp name makes the exclusive open fail with `EEXIST`, the apply answers
1453
+ `partial`/`config` with that text, and the file is left alone (config and backup
1454
+ untouched). The
1455
+ backup itself is **published atomically and never overwritten**: written to a
1456
+ temp name and hard-linked into place, so a crash or a full disk leaves no
1457
+ truncated `.bak` that a later run would mistake for "already backed up". A
1458
+ regular file already at the backup path — pre-existing or raced — **is** the
1459
+ existing backup: accepted as it is, never compared and never overwritten (it may
1460
+ be an older original from before the user's last edit), while a non-regular
1461
+ entry (directory, symlink, socket) is refused. `unchanged` writes
1462
+ nothing and reloads nothing — Herdr already holds that palette, and a reload on
1463
+ every tick would make the sidebar flicker for nothing. `forceReload` is the one
1464
+ exception, and it exists for the owed-reload repair above: it reloads an
1465
+ unchanged plan and answers `requested`. A real write is followed by exactly one
1466
+ `herdr server reload-config` through `execFile` with `HERDR_BIN_PATH` (default
1467
+ `herdr`), no shell, a 5 s timeout and a 4096-byte output cap; a reload failure is
1468
+ reported as partial state because the config is already committed. **CAS limit:**
1469
+ an edit that lands between the final compare and the `rename` cannot be detected
1470
+ without holding a lock on the config, which this writer deliberately does not
1471
+ do — everything earlier (snapshot, plan, backup, staging) is still caught. A
1472
+ **pre-existing truncated backup** is a second documented limit: because a regular
1473
+ file at that path is accepted as it is and never repaired or compared, a `.bak`
1474
+ damaged by an earlier failure or another tool stays damaged.
1475
+
1476
+ **The guard matrix.** `applyHerdrTheme` answers `unavailable` with one reason
1477
+ before it opens any file: `not-herdr` (no `HERDR_ENV=1` plus a pane id and an
1478
+ absolute socket path), `child` (a subagent's Pi must never write the user's
1479
+ config), `remote` (an SSH session, where Herdr reads another machine's config),
1480
+ and `unsupported` (a `herdr-dev` binary, a non-Linux host, or a non-absolute
1481
+ socket/config path). The follower reports `not-herdr`, `remote` and
1482
+ `unsupported` as one `info` notice per session and asks again only when the
1483
+ palette itself changes.
1484
+
1485
+ **The panel.** `/herdr-gentle:customize` reuses Gentle Shell's own card shape:
1486
+ one left `CATEGORIES` list, one right pane headed `<Category> · n/m`, one line
1487
+ per setting with its options inline (`●` stored, `›` cursor elsewhere, `○` the
1488
+ rest). The arrows move the option cursor and only Enter applies; Enter keeps the
1489
+ card open (only the Moshi reload closes it), Esc closes without a write, Tab
1490
+ switches panes. A line whose options do not fit scrolls sideways behind muted
1491
+ `‹`/`›` with an `n/m` counter, falling back to a compact `‹ value ›`. The
1492
+ Preview block below the panes is `Preview · <option> · <title>` plus a sample
1493
+ painted with the host theme, where a theme option shows that theme's own palette
1494
+ through the raw SGR the host hands back. Three footer legends (categories,
1495
+ option row, panes) are chosen by what the keys do right now and compact instead
1496
+ of wrapping. The theme list comes from `ctx.ui.getAllThemes()` in the host's own
1497
+ order with `None` first, the `Gentle Shell theme` setting is painted dim and
1498
+ refused with `Turn Theme sync off to pick a specific theme.` while the sync is
1499
+ on, and a host that exposes no list shows one note instead of an empty picker.
1500
+ The panel writes nothing itself: it calls the extension's apply path, swaps in
1501
+ the model that path re-read, and keeps the cursor by structural option ids.
1326
1502
 
1327
1503
  **Limits** (the §10 style, none of them a promise this design makes):
1328
1504
 
1329
1505
  - The 500 ms tick is the whole observation granularity — there is no event to
1330
1506
  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.
1507
+ - The automated evidence is a stubbed Pi host plus a real binary stand-in on
1508
+ disk; **no live Pi TUI run is recorded**. `ctx.ui.theme`, `getTheme`,
1509
+ `getAllThemes`, `notify` and the host component contract are used as
1510
+ documented, and a host missing one degrades to "nothing changed" rather than
1511
+ to a guess.
1512
+ - Remote sessions are inactive: in SSH the Herdr client reads the config of the
1513
+ machine it runs on, so writing the server-side file would change nothing on
1514
+ screen and the guard refuses.
1515
+ - Two writers of the same keys fight. The sync owns what it projects, so a
1516
+ desktop-theme sync and this feature overwrite each other on their next run;
1517
+ there is no merge, lock or arbitration, only the `was` comments, the marked
1518
+ block and the one-time backup.
1519
+ - The compare-and-swap has one unavoidable window: an edit between the final
1520
+ compare and the rename is undetectable without a config lock, which this
1521
+ writer does not take.
1522
+ - The planner is a **splicer, not a validator**: it guarantees table boundaries
1523
+ for terminated multi-line constructs and byte-identical non-theme lines (checked
1524
+ by the splice invariant), and it deliberately checks nothing outside the theme
1525
+ tables — invalid TOML there is left as it is, because Herdr already refuses
1526
+ that file. A theme-table line the plan must touch has to be the strict
1527
+ single-line form; the revert is per token, so a user-written empty
1528
+ `[theme.custom]` header and the `name` marker stay behind (a table the planner
1529
+ created is removed, so a full cycle is byte-identical).
1530
+ - A pre-existing truncated backup is kept, not repaired (see above), which is why
1531
+ the `was` comments are the per-value revert path.
1532
+ - There is no "full clear" distinct from an empty custom projection: a projection
1533
+ always carries the theme name, so a `name` line the planner inserted stays (an
1534
+ existing name is restored) and a `[theme]` table it created is not removed —
1535
+ only the `[theme.custom]` table it created is, once its block empties.
1335
1536
  - Herdr's surface tokens (`sidebar_bg`, `panel_bg`, `active_row_bg`,
1336
- `selection_bg`, `surface*`) and `peach` are never written: Pi names
1537
+ `selection_bg`, `surface*`) and `peach` are not projected: Pi names
1337
1538
  foregrounds and accents, not panel backgrounds, so backgrounds and status
1338
- colours stay with the Herdr base theme.
1539
+ colours stay with the Herdr base theme — except the `DOTS_FIXED` tables for
1540
+ `Gentleman-Cute`, `Gentleman-Sexy` and `Gentle`, which are the surfaces the
1541
+ user's own Herdr profiles already use.
1339
1542
  - One machine: another Herdr client reads its own `config.toml`, so this is a
1340
1543
  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.
1544
+ - No automatic repair: a `[theme]` table the user or another tool keeps editing
1545
+ is re-projected on the next palette change and never reconciled, and a document
1546
+ whose table boundaries cannot be found (an unterminated multi-line string,
1547
+ array or inline table) stops the writer until it is fixed. A missing
1548
+ `config.toml` is refused, never created.
package/README.md CHANGED
@@ -489,22 +489,29 @@ See [DESIGN.md](DESIGN.md) §4 (producer) and §5 (consumer), and
489
489
  no argument the command opens the floating panel in Gentle Shell's own
490
490
  layout: one left `CATEGORIES` list (`Herdr Sidebar`, `Moshi notifications`,
491
491
  `Herdr Theme`)
492
- and one right pane headed `<Category> · n/m` with its setting rows, each row
493
- painting the stored value with `●` and the other with `○`; one line above the
494
- footer describes the focused setting (`<setting> — <what it changes>`), and
495
- the footer reads
496
- `←/→ or Tab panes · ↑/↓ move · Enter apply · Esc close`, while `←/→` or
497
- `Tab` moves between the category and value panes, `↑/↓` or `j/k` moves the
498
- cursor, `Enter` applies the focused row and `Esc` closes without a write. The
499
- legend names only keys: it never advertises `Click`, because every token in
500
- it is a key the panel answers to, and a narrow card compacts it instead of
501
- wrapping. Pointer input still works without being advertised — a click on a
502
- category selects it, a click on a row applies it, and a click outside the
503
- panes is ignored. Each category owns its own rows: `Herdr Sidebar`
492
+ and one right pane headed `<Category> · n/m`, where each setting is ONE line
493
+ with its options inline — `●` the stored option, `›` the cursor while it sits
494
+ elsewhere, `○` the rest. The arrows move the option cursor and only `Enter`
495
+ applies; `Enter` keeps the card open (a Moshi change that needs a Pi reload
496
+ closes it first), `Esc` closes without a write, `Tab`
497
+ switches panes and `↑/↓` (or `j/k`) moves between settings. A line whose
498
+ options do not fit scrolls sideways behind muted `‹` / `›` markers with an
499
+ `n/m` counter (falling back to a compact `‹ value ›` when not even one option
500
+ fits), and the Preview block below the panes reads
501
+ `Preview · <option> · <title>` plus a sample painted with the host theme (a
502
+ theme option shows that theme's own palette). The footer carries one of three
503
+ legends after a `Click · ` prefix —
504
+ `↑/↓ categories · → open · Esc close`,
505
+ `←/→ choose · Enter apply · ↑/↓ settings · Tab panes · Esc close`, or
506
+ `←/→ or Tab panes · ↑/↓ move · Enter apply · Esc close` — and compacts
507
+ instead of wrapping on a narrow card. A click on an option applies exactly
508
+ that option, a click on a setting's name only moves the focus, a click on a
509
+ category selects it, and a click outside the panes is ignored. Each category
510
+ owns its own rows: `Herdr Sidebar`
504
511
  shows the single `Sidebar agent rows` row, and the only Moshi switch is the
505
512
  `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
513
+ both theme settings (the `Theme sync` toggle and the inline
514
+ `Gentle Shell theme` list described in the subsection below). The
508
515
  sidebar and Moshi switches are never mixed — `Sidebar agent rows` neither
509
516
  reads nor writes `gentle-moshi.json`, so turning the agent rows off never
510
517
  turns the notification channel off. Herdr's own
@@ -595,19 +602,72 @@ See [DESIGN.md](DESIGN.md) §4 (producer) and §5 (consumer), and
595
602
 
596
603
  ### Theme sync (Herdr palette follows Pi)
597
604
 
598
- `/herdr-gentle:customize` → `Herdr Theme` is one switch and one pinned value.
605
+ `/herdr-gentle:customize` → `Herdr Theme` is one switch and one pinned theme.
599
606
  `Theme sync` is **OFF by default**: while it is on, Herdr's palette is the
600
607
  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
608
+ running. While it is off, `Gentle Shell theme` pins one Gentle Shell / Pi theme
609
+ from Pi's own inline list (`None` first, then the host's order) and `None`
610
+ clears the pin; the setting is painted dim and refused while the sync is on
603
611
  (`Turn Theme sync off to pick a specific theme.`). Turning the sync off writes
604
612
  nothing to Herdr, so **Herdr keeps the last applied palette** — a fresh install
605
613
  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.
614
+ one file, `gentle-theme.json`, beside `gentle-moshi.json`.
615
+
616
+ The writer runs **in process in this Pi package**
617
+ (`lib/herdr-theme-config.js` plans it, `lib/herdr-theme-apply.js` writes it,
618
+ `extensions/herdr-theme-sync.ts` follows the theme), so the Herdr plugin is not
619
+ involved and needs no update for this feature. It is a **line splicer, not a TOML
620
+ validator**: it finds the boundaries of your `[theme]` and `[theme.custom]`
621
+ tables (a header only counts at a real line start, never inside a multi-line
622
+ string, array or comment) and treats every line outside them as opaque bytes —
623
+ nothing there is validated or rewritten (escapes included), and an invalid line
624
+ outside those tables is left exactly as it is, because Herdr already refuses such
625
+ a file (the scanner only looks at those lines far enough to find where a table
626
+ starts and ends). A
627
+ splice invariant is enforced before a plan is returned: the non-theme lines of
628
+ the output must be byte-identical to the input's.
629
+
630
+ Inside the two theme tables it edits in place and keeps two kinds of value
631
+ apart: a value you already had is replaced where it stands and remembered by one
632
+ comment recording **the whole original line** (one per key; the first original
633
+ wins, and restoring gives back your quoting, spacing and inline comment — or
634
+ **your current comment** when you edited it after the planner wrote the value,
635
+ because the latest edit wins), while
636
+ a token you did not have is written inside ONE marked block — a `begin`/`end`
637
+ comment pair naming this package, spelled `begin created` when the planner also
638
+ created the table and closed with `end after a missing line ending` when placing
639
+ the block also added the file's missing final newline, so clearing gives that
640
+ byte back — at the
641
+ end of `[theme.custom]`, regenerated on every apply. Leaving a theme therefore
642
+ never leaves a stale colour: a token that leaves the projection is restored from
643
+ its comment byte for byte (or when the projection returns to the recorded value),
644
+ or dropped with the block when the package created it, and a token you own
645
+ without such a comment is never touched. Removing or moving that block is refused
646
+ (`ambiguous herdr-gentle-shell marker above the managed block`) when a
647
+ marker-shaped comment directly above `begin` would end up attached to the key
648
+ under it. Everything else — other tables,
649
+ comments, ordering, a BOM, CRLF or mixed endings, a missing final newline — is
650
+ preserved, a one-time `<config>.herdr-gentle-shell.bak` is published atomically
651
+ before the first modification and never overwritten, and a temp file that
652
+ survives a failed replace is named in the error instead of being hidden, while a
653
+ temp path the writer did not create itself is never deleted (the apply reports
654
+ the `EEXIST` and leaves it alone). What
655
+ fails closed, with the line number and no write, is what a theme-table edit
656
+ cannot be done safely over: `auto_switch` with a value other than `false`,
657
+ `dark_name`, `light_name`, a top-level `theme` key, a dotted key extending the
658
+ theme tables, a duplicated `[theme]`/`[theme.custom]` table or duplicated key
659
+ inside them, a line inside the marked block that is not a token assignment, and a
660
+ value the plan must touch that is not a strict single-line string/boolean/number
661
+ (an unterminated multi-line string or array anywhere also blocks the plan,
662
+ because table boundaries depend on it). While the sync is on (or a theme is
663
+ pinned) the package owns the tokens it projects, so another tool that rewrites
664
+ the same keys (a desktop-theme sync, for example) overwrites them on its next run
665
+ and the next palette change here overwrites them back. There is no "full clear":
666
+ a projection always carries a theme name, so a `name` line the planner inserted
667
+ stays, and only the `[theme.custom]` table it created is removed again. See
668
+ [docs/theme-sync.md](docs/theme-sync.md) for the golden example, the exact
669
+ comment and block lines, what is and is not guaranteed, the refusals, the
670
+ notices and the limits.
611
671
 
612
672
  ## Documentation
613
673
 
@@ -619,7 +679,7 @@ the limits.
619
679
  | Supervision triage (read-only doctor/trace/whois) | [docs/diagnostics.md](docs/diagnostics.md) |
620
680
  | Lifecycle recovery and interruption (polling fallback) | [docs/supervision.md](docs/supervision.md) |
621
681
  | 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) |
682
+ | Theme sync (Pi palette → Herdr theme, written in process) | [docs/theme-sync.md](docs/theme-sync.md) |
623
683
  | Herdr session opener (`herdr_session_open`) | [docs/herdr-session-open.md](docs/herdr-session-open.md) |
624
684
  | Performance trace and its report | [docs/performance-trace.md](docs/performance-trace.md) |
625
685