herdr-gentle-shell 1.7.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.
@@ -275,7 +275,6 @@
275
275
  import net from "node:net";
276
276
  import { createHash, randomUUID } from "node:crypto";
277
277
  import { spawn, spawnSync } from "node:child_process";
278
- import { generateUnifiedPatch } from "@earendil-works/pi-coding-agent";
279
278
  import * as fs from "node:fs";
280
279
  import { homedir } from "node:os";
281
280
  import { delimiter as pathDelimiter, dirname, join, resolve as resolvePath, relative as pathRelative, basename as pathBasename, isAbsolute as pathIsAbsolute } from "node:path";
@@ -294,7 +293,15 @@ const nodeRequire = createRequire(import.meta.url);
294
293
  // are the only surface the harness extracts.
295
294
 
296
295
  export const PRESENCE_HEADER_LIMIT = 16 * 1024;
297
- export const PRESENCE_ACTIVITY_LIMIT = 16 * 1024 * 1024;
296
+ // The activity read is synchronous and runs on the agent's own event loop on
297
+ // every beat, so this ceiling is a cost the session pays rather than a hostile
298
+ // file's business alone. The envelope the writer emits is bounded by the same
299
+ // caps the reader honours (128 tracked tasks, ≤120-char labels): 16× the header
300
+ // limit covers that worst case with margin, and keeps the per-beat parse in
301
+ // single-digit milliseconds instead of the hundreds of milliseconds a 16 MiB
302
+ // ceiling allowed. An oversized file still resolves to no snapshot, never a
303
+ // partial one.
304
+ export const PRESENCE_ACTIVITY_LIMIT = 256 * 1024;
298
305
  export const PRESENCE_FRESH_MS = 15_000;
299
306
  export const PRESENCE_MAX_DIR_ENTRIES = 128;
300
307
  export const PRESENCE_MAX_WITNESSED = 256;
@@ -1303,138 +1310,6 @@ export function computeNativeState({
1303
1310
  return undefined;
1304
1311
  }
1305
1312
 
1306
- // ---------------------------------------------------------------------------
1307
- // Live session-changes metric (S62: authoritative publisher, never transcript)
1308
- //
1309
- // Gentle-shell shows the CURRENT working tree against HEAD for the session's
1310
- // subscribed roots. The transcript aggregate below (aggregateChanges over
1311
- // SESSION_CHANGE_ENTRY before/after patches) is retained as legacy evidence
1312
- // for other needs but is NOT the publisher authority: beats publish the
1313
- // live Git scan instead, so external/untracked edits and scope registration
1314
- // reflect immediately with numerical equality to the reference.
1315
- // ---------------------------------------------------------------------------
1316
-
1317
- function sameSnapshot(before, after) {
1318
- return (
1319
- before?.kind === after?.kind &&
1320
- (before?.kind === "absent" ||
1321
- (before?.kind === "text" &&
1322
- after?.kind === "text" &&
1323
- before?.text === after?.text))
1324
- );
1325
- }
1326
-
1327
- function snapshotPatchText(snapshot) {
1328
- return snapshot && snapshot.kind === "text" && typeof snapshot.text === "string" ? snapshot.text : "";
1329
- }
1330
-
1331
- function unavailableReason(snapshot) {
1332
- if (snapshot?.kind === "unavailable" && typeof snapshot?.reason === "string" && snapshot.reason.length > 0) {
1333
- return snapshot.reason;
1334
- }
1335
- return "Snapshot unavailable.";
1336
- }
1337
-
1338
- // Unified-patch accounting identical to Gentle Shell
1339
- // SessionChanges.changed(): generateUnifiedPatch(path, before, after),
1340
- // enter after the first @@ hunk, count lines beginning + and -. Fail-closed
1341
- // to 0/0 so token bounds hold when the patch cannot be built.
1342
- function safePatchPath(path) {
1343
- if (typeof path !== "string") return "change";
1344
- const clean = path.replace(/[\0\r\n]/g, "").slice(0, 256);
1345
- return clean.length > 0 ? clean : "change";
1346
- }
1347
-
1348
- function patchLineCounts(pathLabel, before, after) {
1349
- try {
1350
- const patch = generateUnifiedPatch(pathLabel, before, after);
1351
- const patchLines = patch.split("\n");
1352
- const firstHunk = patchLines.findIndex((line) => line.startsWith("@@"));
1353
- const lines = firstHunk < 0 ? [] : patchLines.slice(firstHunk + 1);
1354
- return {
1355
- added: lines.filter((line) => line.startsWith("+")).length,
1356
- deleted: lines.filter((line) => line.startsWith("-")).length,
1357
- };
1358
- } catch {
1359
- return { added: 0, deleted: 0 };
1360
- }
1361
- }
1362
-
1363
- function isPlausibleEvidence(evidence) {
1364
- return (
1365
- isRecord(evidence) &&
1366
- typeof evidence.id === "string" &&
1367
- evidence.id.length > 0 &&
1368
- typeof evidence.root === "string" &&
1369
- evidence.root.length > 0 &&
1370
- typeof evidence.path === "string" &&
1371
- evidence.path.length > 0 &&
1372
- isRecord(evidence.before) &&
1373
- isRecord(evidence.after)
1374
- );
1375
- }
1376
-
1377
- function aggregateChanges(entries, sessionId) {
1378
- const seen = new Set();
1379
- const perRoot = new Map();
1380
- let paths = 0;
1381
- for (const entry of entries ?? []) {
1382
- if (!isRecord(entry) || entry.type !== "custom" || entry.customType !== CHANGE_ENTRY) continue;
1383
- const data = entry.data;
1384
- if (!isRecord(data) || data.sessionId !== sessionId || !isPlausibleEvidence(data.evidence)) continue;
1385
- const evidence = data.evidence;
1386
- if (seen.has(evidence.id)) continue;
1387
- seen.add(evidence.id);
1388
- if (sameSnapshot(evidence.before, evidence.after)) continue;
1389
- let perPath = perRoot.get(evidence.root);
1390
- if (!perPath) {
1391
- perPath = new Map();
1392
- perRoot.set(evidence.root, perPath);
1393
- }
1394
- let slot = perPath.get(evidence.path);
1395
- if (!slot) {
1396
- if (paths >= MAX_CHANGE_PATHS) continue;
1397
- paths += 1;
1398
- slot = { before: evidence.before, after: evidence.after };
1399
- if (evidence.before?.kind === "unavailable") slot.unavailable = unavailableReason(evidence.before);
1400
- if (evidence.after?.kind === "unavailable" && !slot.unavailable) {
1401
- slot.unavailable = unavailableReason(evidence.after);
1402
- }
1403
- perPath.set(evidence.path, slot);
1404
- } else {
1405
- if (!slot.unavailable && !sameSnapshot(slot.after, evidence.before)) {
1406
- slot.unavailable =
1407
- "Snapshot continuity lost (external or unobserved edit); session diff unavailable.";
1408
- }
1409
- if (evidence.before?.kind === "unavailable" && !slot.unavailable) {
1410
- slot.unavailable = unavailableReason(evidence.before);
1411
- }
1412
- if (evidence.after?.kind === "unavailable" && !slot.unavailable) {
1413
- slot.unavailable = unavailableReason(evidence.after);
1414
- }
1415
- slot.after = evidence.after;
1416
- }
1417
- }
1418
- let files = 0;
1419
- let added = 0;
1420
- let deleted = 0;
1421
- for (const perPath of perRoot.values()) {
1422
- for (const [changePath, { before, after, unavailable }] of perPath) {
1423
- if (!unavailable && sameSnapshot(before, after)) continue;
1424
- files += 1;
1425
- if (unavailable) continue;
1426
- const { added: fileAdded, deleted: fileDeleted } = patchLineCounts(
1427
- safePatchPath(changePath),
1428
- snapshotPatchText(before),
1429
- snapshotPatchText(after),
1430
- );
1431
- added += fileAdded;
1432
- deleted += fileDeleted;
1433
- }
1434
- }
1435
- return { files, added, deleted };
1436
- }
1437
-
1438
1313
  // ---------------------------------------------------------------------------
1439
1314
  // Live Git scope + scan (S62, mirrored from gentle-shell shell-changes.ts +
1440
1315
  // session-changes.ts + bounded-writer-admission.ts). Self-contained like the
@@ -1922,6 +1797,10 @@ function sidebarPublishingEnabled() {
1922
1797
  // jiti; the tests load a copy as .mjs), so it carries no type annotations.
1923
1798
  const MOSHI_AGENT = "pi";
1924
1799
  const MOSHI_MAX_CHILD_HEADER = 16 * 1024;
1800
+ // Upper bound on one envelope's socket lifetime. Long enough for a local
1801
+ // daemon to answer a session.update, short enough that a hung peer cannot tie
1802
+ // up a descriptor for the rest of the session.
1803
+ const MOSHI_SEND_TIMEOUT_MS = 2000;
1925
1804
 
1926
1805
  function moshiSocketPath() {
1927
1806
  const override = process.env.MOSHI_SOCKET_PATH;
@@ -1945,6 +1824,20 @@ function moshiSendEnvelope(envelope) {
1945
1824
  const done = new Promise((resolve) => sock.once("close", () => resolve()));
1946
1825
  moshiInFlight.add(done);
1947
1826
  void done.then(() => moshiInFlight.delete(done));
1827
+ // A peer that accepts the envelope and never finishes the connection holds
1828
+ // this socket — and its fd — in FIN_WAIT_2 for the life of the session: the
1829
+ // half-close below is not an answer from it, only a request. One bounded,
1830
+ // unref'd destroy settles the envelope either way, so `moshiInFlight`
1831
+ // always drains and a broken daemon can never accumulate open handles.
1832
+ const giveUp = setTimeout(() => {
1833
+ try {
1834
+ sock.destroy();
1835
+ } catch {
1836
+ // Already gone; the close event below still settles the promise.
1837
+ }
1838
+ }, MOSHI_SEND_TIMEOUT_MS);
1839
+ giveUp.unref?.();
1840
+ sock.once("close", () => clearTimeout(giveUp));
1948
1841
  sock.setNoDelay(true);
1949
1842
  sock.on("error", () => {
1950
1843
  try {
@@ -2146,13 +2039,13 @@ function lastFinishedLabel(taskMap) {
2146
2039
  }
2147
2040
 
2148
2041
  // ---------------------------------------------------------------------------
2149
- // `/herdr-gentle:customize`: exactly two switches, offered in the floating panel
2042
+ // `/herdr-gentle:customize`: three categories, offered in the floating panel
2150
2043
  // shaped like Gentle Shell's own card (odd/tasks/restore-customize-panel.md T1;
2151
- // odd/tasks/customize-parity-done-idle.md T1/T3).
2044
+ // odd/tasks/customize-parity-done-idle.md T1/T3; odd/tasks/theme-sync.md T3).
2152
2045
  //
2153
2046
  // The command is registered BEFORE the `enabled()` gate in the factory below,
2154
2047
  // so it stays reachable from a plain Pi session outside a Herdr pane; the
2155
- // producer itself still needs a pane. The two switches are:
2048
+ // producer itself still needs a pane. The switches are:
2156
2049
  //
2157
2050
  // - Sidebar agent rows. The marked `[ui.sidebar.agents.rows_by_agent]` block
2158
2051
  // belongs to the Herdr plugin's own `bin/configure.js`, which is installed as
@@ -2168,6 +2061,12 @@ function lastFinishedLabel(taskMap) {
2168
2061
  // nothing at all. Disabling skips the gate and stays unconditional. A Pi
2169
2062
  // reload is requested only when the settings entry actually changed, because
2170
2063
  // that entry is the only part that waits for the next Pi extension load.
2064
+ // - Theme sync. `lib/theme-store.js` holds the one persisted document
2065
+ // (`gentle-theme.json`): whether Herdr follows the theme active in Pi (S1/S2)
2066
+ // and, with the sync off, the one theme the user pinned (S4). The toggle
2067
+ // writes that document and needs NO Pi reload — the palette lives in Herdr,
2068
+ // not in this extension — and the theme row lists `ctx.ui.getAllThemes()`
2069
+ // while refusing to change anything as long as the stored sync is on.
2171
2070
  //
2172
2071
  // No argument opens the recovered panel from lib/customize-panel.js through
2173
2072
  // `ctx.ui.custom` with the overlay options the former implementation pinned;
@@ -2181,9 +2080,35 @@ function lastFinishedLabel(taskMap) {
2181
2080
  const CUSTOMIZE_TITLE = "Customize · Herdr Gentle Shell";
2182
2081
  const CUSTOMIZE_SIDEBAR_LABEL = "Sidebar agent rows";
2183
2082
  const CUSTOMIZE_MOSHI_LABEL = "Moshi notifications";
2083
+ const CUSTOMIZE_THEME_SYNC_LABEL = "Theme sync";
2084
+ const CUSTOMIZE_THEME_LABEL = "Gentle Shell theme";
2184
2085
  const CUSTOMIZE_ON = "On";
2185
2086
  const CUSTOMIZE_OFF = "Off";
2186
2087
 
2088
+ // The theme picker's "no theme assigned" entry. It is deliberately NOT `Off`:
2089
+ // `Off` is the label the panel paints for a stored `null`
2090
+ // (THEME_OFF_LABEL in lib/theme-projection.js), and a Pi theme may legitimately
2091
+ // be named `Off`. Reusing that spelling as the sentinel would make such a theme
2092
+ // unpinnable, because selecting it would read as "clear the pin".
2093
+ const CUSTOMIZE_THEME_UNASSIGN = "Off (no theme assigned)";
2094
+
2095
+ // The theme setting's STRUCTURAL option ids from `lib/customize-panel.js`. They
2096
+ // are never labels: `none` is the "no theme assigned" choice and `theme:<name>`
2097
+ // a real theme, so an installed theme literally called `None` or `Off` keeps its
2098
+ // own option and stays pinnable.
2099
+ const CUSTOMIZE_THEME_SETTING_ID = "theme";
2100
+ const CUSTOMIZE_THEME_NONE_OPTION_ID = "none";
2101
+ const CUSTOMIZE_THEME_OPTION_PREFIX = "theme:";
2102
+ const THEME_SYNC_ON_TEXT = "Theme sync on; Herdr's palette follows the theme active in Pi.";
2103
+ const THEME_SYNC_OFF_TEXT = "Theme sync off; Herdr keeps the palette it was last given.";
2104
+ // The refusal keeps S4's promise: the pinned theme is only available while the
2105
+ // sync is off, so a stored sync turns the row into a no-op with a reason.
2106
+ const THEME_SYNC_REFUSED_TEXT = "Turn Theme sync off to pick a specific theme.";
2107
+ const THEME_LIST_UNAVAILABLE_TEXT =
2108
+ "Could not read Pi's theme list (this host exposes no getAllThemes()); nothing was changed.";
2109
+ const THEME_STORE_UNAVAILABLE_TEXT =
2110
+ "Could not reach the theme store (lib/theme-store.js is unavailable); nothing was changed.";
2111
+
2187
2112
  // The former panel's geometry and overlay options, unchanged. The helpers
2188
2113
  // module (@earendil-works/pi-tui) is resolved lazily through the injectable
2189
2114
  // seam below so registering the extension never depends on it and tests can
@@ -2203,29 +2128,101 @@ export function setCustomizeTuiLoader(loader) {
2203
2128
  customizeTuiLoader = loader;
2204
2129
  }
2205
2130
 
2206
- // The panel module lives in lib/, resolved relative to this file in the
2207
- // installed package. Tests load a copy from a temp directory and point the
2131
+ // The panel and the theme store live in lib/, resolved relative to this file in
2132
+ // the installed package. Tests load a copy from a temp directory and point the
2208
2133
  // documented override at the real lib dir. A single-file deployment (the
2209
- // installed copy or symlink without sibling helpers) has no panel module, so
2210
- // the callback returns null and the command keeps the plain menu below.
2134
+ // installed copy or symlink without sibling helpers) has neither module, so the
2135
+ // panel loader returns null (keeping the plain menu below) and the theme store
2136
+ // reports `ok: false`, which the panel paints as `Unknown` instead of guessing.
2137
+ function customizeLibDir() {
2138
+ const override = process.env.GENTLE_CUSTOMIZE_LIB_DIR;
2139
+ return typeof override === "string" && override.length > 0
2140
+ ? override
2141
+ : join(dirname(fileURLToPath(import.meta.url)), "..", "lib");
2142
+ }
2143
+
2211
2144
  function customizePanelModule() {
2212
2145
  try {
2213
- const override = process.env.GENTLE_CUSTOMIZE_LIB_DIR;
2214
- const dir = typeof override === "string" && override.length > 0
2215
- ? override
2216
- : join(dirname(fileURLToPath(import.meta.url)), "..", "lib");
2217
- return nodeRequire(join(dir, "customize-panel.js"));
2146
+ return nodeRequire(join(customizeLibDir(), "customize-panel.js"));
2147
+ } catch {
2148
+ return null;
2149
+ }
2150
+ }
2151
+
2152
+ function themeStoreModule() {
2153
+ try {
2154
+ return nodeRequire(join(customizeLibDir(), "theme-store.js"));
2155
+ } catch {
2156
+ return null;
2157
+ }
2158
+ }
2159
+
2160
+ // Never throws: an unreadable decision is `ok: false` with the inert defaults,
2161
+ // so the panel shows `Unknown` and the apply path refuses instead of writing a
2162
+ // value nobody chose (S7).
2163
+ function readCustomizeThemeState() {
2164
+ const inert = { ok: false, sync: false, theme: null, updatedAt: null };
2165
+ const store = themeStoreModule();
2166
+ if (!store || typeof store.readThemeState !== "function") return inert;
2167
+ try {
2168
+ const state = store.readThemeState(process.env);
2169
+ return isRecord(state) ? state : inert;
2170
+ } catch (error) {
2171
+ return { ...inert, error: `could not read the theme state: ${error?.message ?? error}` };
2172
+ }
2173
+ }
2174
+
2175
+ // S2: the panel lists Pi's own themes, so the extension reads them from the
2176
+ // host instead of shipping a copy. `null` means "this host exposes no list" and
2177
+ // the panel says so with one note instead of showing an empty picker.
2178
+ function readHostThemeNames(ctx) {
2179
+ const listThemes = ctx?.ui?.getAllThemes;
2180
+ if (typeof listThemes !== "function") return null;
2181
+ try {
2182
+ return themeNames(listThemes.call(ctx.ui));
2218
2183
  } catch {
2219
2184
  return null;
2220
2185
  }
2221
2186
  }
2222
2187
 
2223
- function customizePanelModel() {
2188
+ // S6: a theme's preview is a swatch in THAT theme's colours, taken from the
2189
+ // theme object the host hands back. The raw SGR is deliberate and lives only
2190
+ // here: the panel is a plain CommonJS module with no host colour API, and
2191
+ // falling back to the active theme would show a palette the user did not pick.
2192
+ // An unreadable theme throws, and the panel renders `Preview unavailable`.
2193
+ function themePreviewFactory(ctx) {
2194
+ const getTheme = ctx?.ui?.getTheme;
2195
+ if (typeof getTheme !== "function") return null;
2196
+ return (name) => {
2197
+ let theme;
2198
+ try {
2199
+ theme = getTheme.call(ctx.ui, name);
2200
+ } catch {
2201
+ theme = null;
2202
+ }
2203
+ if (!theme) throw new Error(`Theme ${name} is unavailable.`);
2204
+ if (typeof theme.name === "string" && theme.name !== name) {
2205
+ throw new Error(`Theme ${name} is unavailable.`);
2206
+ }
2207
+ const accent = typeof theme.getBgAnsi === "function" ? theme.getBgAnsi("accent") : undefined;
2208
+ const text = typeof theme.getFgAnsi === "function" ? theme.getFgAnsi("text") : undefined;
2209
+ if (typeof accent !== "string" || typeof text !== "string") {
2210
+ throw new Error(`Theme ${name} exposes no palette escapes.`);
2211
+ }
2212
+ // The upstream sample: a background block then the sample text.
2213
+ return { title: "source palette", sample: `${accent} \x1b[0m ${text}Aa sample text\x1b[0m` };
2214
+ };
2215
+ }
2216
+
2217
+ function customizePanelModel(ctx) {
2224
2218
  const panel = customizePanelModule();
2225
2219
  if (!panel) return null;
2226
2220
  return panel.customizePanelModel({
2227
2221
  sidebar: sidebarRowsState().state,
2228
2222
  moshi: moshiFlagEnabled(moshiFlagPath()) ? "on" : "off",
2223
+ theme: readCustomizeThemeState(),
2224
+ themeNames: readHostThemeNames(ctx),
2225
+ themePreview: themePreviewFactory(ctx),
2229
2226
  });
2230
2227
  }
2231
2228
 
@@ -2616,25 +2613,192 @@ function applyMoshiNotifications(want) {
2616
2613
  }
2617
2614
 
2618
2615
  // One apply path for both switches: notify once with the verdict and reload Pi
2619
- // only when the Moshi settings entry actually changed.
2620
- async function applyCustomizeSwitch(id, value, ctx) {
2616
+ // only when the Moshi settings entry actually changed. The theme switch never
2617
+ // reloads: the palette it writes belongs to Herdr, so a Pi reload would only
2618
+ // restart the extension for nothing.
2619
+ async function applyCustomizeSwitch(id, value, ctx, options = {}) {
2620
+ const want = value === "on";
2621
2621
  const result = id === "sidebar"
2622
- ? await applySidebarRows(value === "on")
2623
- : applyMoshiNotifications(value === "on");
2622
+ ? await applySidebarRows(want)
2623
+ : id === "theme-sync"
2624
+ ? applyThemeSync(want)
2625
+ : applyMoshiNotifications(want);
2624
2626
  const notify = ctx?.ui?.notify;
2625
2627
  if (typeof notify === "function") {
2626
2628
  notify(`${result.text}${result.needsReload ? " Reloading now to apply the change." : ""}`, result.level);
2627
2629
  }
2628
- if (result.needsReload && typeof ctx?.reload === "function") await ctx.reload();
2630
+ // The overlay defers the reload (`deferReload`): reloading while the card is
2631
+ // still mounted restarts Pi behind an open overlay, so the panel closes first
2632
+ // and the caller reloads after `ctx.ui.custom` resolved.
2633
+ if (result.needsReload && options.deferReload !== true && typeof ctx?.reload === "function") await ctx.reload();
2634
+ return result;
2635
+ }
2636
+
2637
+ // The one-line spelling of the theme state, shared by `status` and the menu
2638
+ // fallback so "unknown" can never drift from what the panel shows: an unreadable
2639
+ // store names no value at all, and an unassigned theme reads as `none`.
2640
+ function themeStateLabels(state) {
2641
+ if (!state || state.ok === false) return { sync: "unknown", theme: "unknown" };
2642
+ const theme = typeof state.theme === "string" && state.theme.length > 0 ? state.theme : "none";
2643
+ return { sync: state.sync === true ? "on" : "off", theme };
2644
+ }
2645
+
2646
+ function themeStoreWriteError(error) {
2647
+ return `Could not write the theme store: ${error?.message ?? error}; nothing was changed.`;
2648
+ }
2649
+
2650
+ // S1/S2: the sync flag is the whole toggle, and the theme the user pinned is
2651
+ // carried across it untouched, so turning the sync off restores that choice
2652
+ // instead of silently unassigning it. Nothing is reloaded.
2653
+ function applyThemeSync(want) {
2654
+ const store = themeStoreModule();
2655
+ if (!store || typeof store.writeThemeState !== "function") {
2656
+ return { changed: false, needsReload: false, level: "error", text: THEME_STORE_UNAVAILABLE_TEXT };
2657
+ }
2658
+ const state = readCustomizeThemeState();
2659
+ // An unreadable document is written over rather than blocked on (the same
2660
+ // repair the sidebar switch offers), but an already-correct flag still reports
2661
+ // "already" instead of rewriting the file.
2662
+ const current = state.sync === true;
2663
+ if (current === want) {
2664
+ return {
2665
+ changed: false,
2666
+ needsReload: false,
2667
+ level: "info",
2668
+ text: `Theme sync already ${want ? "on" : "off"}; nothing was changed.`,
2669
+ };
2670
+ }
2671
+ try {
2672
+ store.writeThemeState(process.env, { sync: want, theme: state.theme ?? null });
2673
+ } catch (error) {
2674
+ return { changed: false, needsReload: false, level: "error", text: themeStoreWriteError(error) };
2675
+ }
2676
+ return {
2677
+ changed: true,
2678
+ needsReload: false,
2679
+ level: "info",
2680
+ text: want ? THEME_SYNC_ON_TEXT : THEME_SYNC_OFF_TEXT,
2681
+ };
2682
+ }
2683
+
2684
+ // `ctx.ui.getAllThemes()` documents `{ name, path }` records; a plain string list
2685
+ // is accepted too. A malformed entry is skipped instead of failing the whole
2686
+ // list. S2 keeps Pi's OWN order (the list the user sees in /settings), drops the
2687
+ // names that are paths rather than themes (`/` in the name, as upstream does) and
2688
+ // deduplicates, so one theme is never offered twice.
2689
+ function themeNames(themes) {
2690
+ if (!Array.isArray(themes)) return null;
2691
+ const names = [];
2692
+ for (const entry of themes) {
2693
+ const name = typeof entry === "string" ? entry : isRecord(entry) ? entry.name : null;
2694
+ if (typeof name !== "string") continue;
2695
+ const clean = name.trim();
2696
+ if (clean.length === 0 || clean.includes("/")) continue;
2697
+ names.push(clean);
2698
+ }
2699
+ return [...new Set(names)];
2700
+ }
2701
+
2702
+ // The picker's entries plus the ONE entry that means "unassign". A theme really
2703
+ // named like the sentinel moves the sentinel instead of being shadowed, so every
2704
+ // theme name stays selectable and only the returned label writes `theme: null`.
2705
+ function themeSelectionOptions(names) {
2706
+ let unassign = CUSTOMIZE_THEME_UNASSIGN;
2707
+ let attempt = 2;
2708
+ while (names.includes(unassign)) {
2709
+ unassign = `${CUSTOMIZE_THEME_UNASSIGN} ${attempt}`;
2710
+ attempt += 1;
2711
+ }
2712
+ return { options: [...names, unassign], unassign };
2713
+ }
2714
+
2715
+ // One write for the pinned theme, shared by the inline panel setting and the
2716
+ // `ctx.ui.select` fallback: the refusal, the missing store and a failure all
2717
+ // write NOTHING, so the stored document only ever changes to a value the user
2718
+ // actually picked (S7).
2719
+ function writeThemeChoice(ctx, name) {
2720
+ const notify = ctx?.ui?.notify;
2721
+ const store = themeStoreModule();
2722
+ if (!store || typeof store.writeThemeState !== "function") {
2723
+ if (typeof notify === "function") notify(THEME_STORE_UNAVAILABLE_TEXT, "warning");
2724
+ return false;
2725
+ }
2726
+ if (readCustomizeThemeState().sync === true) {
2727
+ if (typeof notify === "function") notify(THEME_SYNC_REFUSED_TEXT, "warning");
2728
+ return false;
2729
+ }
2730
+ try {
2731
+ store.writeThemeState(process.env, { sync: false, theme: name });
2732
+ } catch (error) {
2733
+ if (typeof notify === "function") notify(themeStoreWriteError(error), "error");
2734
+ return false;
2735
+ }
2736
+ if (typeof notify === "function") {
2737
+ notify(
2738
+ name === null
2739
+ ? "Gentle Shell theme set to Off; Herdr keeps the palette it was last given."
2740
+ : `Gentle Shell theme set to ${name}.`,
2741
+ "info",
2742
+ );
2743
+ }
2744
+ return true;
2745
+ }
2746
+
2747
+ // S4: pin one of Pi's themes while the sync is off, through the host's own
2748
+ // picker. The refusal, the missing theme list and an empty answer all write
2749
+ // NOTHING, so the stored document only ever changes to a value the user picked.
2750
+ async function applyThemeSelection(ctx) {
2751
+ const notify = ctx?.ui?.notify;
2752
+ const store = themeStoreModule();
2753
+ if (!store || typeof store.writeThemeState !== "function") {
2754
+ if (typeof notify === "function") notify(THEME_STORE_UNAVAILABLE_TEXT, "warning");
2755
+ return;
2756
+ }
2757
+ if (readCustomizeThemeState().sync === true) {
2758
+ if (typeof notify === "function") notify(THEME_SYNC_REFUSED_TEXT, "warning");
2759
+ return;
2760
+ }
2761
+ const listThemes = ctx?.ui?.getAllThemes;
2762
+ if (typeof listThemes !== "function") {
2763
+ if (typeof notify === "function") notify(THEME_LIST_UNAVAILABLE_TEXT, "warning");
2764
+ return;
2765
+ }
2766
+ let themes;
2767
+ try {
2768
+ themes = listThemes.call(ctx.ui);
2769
+ } catch {
2770
+ themes = null;
2771
+ }
2772
+ const names = themeNames(themes);
2773
+ if (names === null) {
2774
+ if (typeof notify === "function") notify(THEME_LIST_UNAVAILABLE_TEXT, "warning");
2775
+ return;
2776
+ }
2777
+ const select = ctx?.ui?.select;
2778
+ if (typeof select !== "function") return;
2779
+ const picker = themeSelectionOptions(names);
2780
+ let picked;
2781
+ try {
2782
+ // The unassign entry is its own label, never the stored-value label `Off`, so
2783
+ // a theme named `Off` is pinned like any other and a way back to "no theme"
2784
+ // is always offered.
2785
+ picked = await select(CUSTOMIZE_THEME_LABEL, picker.options);
2786
+ } catch {
2787
+ picked = undefined;
2788
+ }
2789
+ // Esc/cancel and an empty answer write nothing at all.
2790
+ if (typeof picked !== "string" || picked.length === 0) return;
2791
+ writeThemeChoice(ctx, picked === picker.unassign ? null : picked);
2629
2792
  }
2630
2793
 
2631
- // The single apply path shared by the overlay and the menu fallback. The choice
2632
- // the panel resolves names the switch it drives (`switchId`) and the value to
2633
- // apply; that switch id is the only thing read here, so a row can never apply a
2634
- // switch its category does not own. An inconclusive sidebar verdict is never a
2635
- // refusal: choosing On still attempts the repair and reports the apply step's
2636
- // own error, exactly like the baseline menu did.
2637
- const CUSTOMIZE_SWITCH_IDS = ["sidebar", "moshi"];
2794
+ // The apply path of the menu fallback. The choice names the switch it drives
2795
+ // (`switchId`) and the value to apply; that switch id is the only thing read
2796
+ // here, so a row can never apply a switch its category does not own. An
2797
+ // inconclusive sidebar verdict is never a refusal: choosing On still attempts
2798
+ // the repair and reports the apply step's own error, exactly like the baseline
2799
+ // menu did. The fallback has no inline theme list, so its theme setting keeps
2800
+ // opening the host's picker through `applyThemeSelection`.
2801
+ const CUSTOMIZE_SWITCH_IDS = ["sidebar", "moshi", "theme-sync"];
2638
2802
 
2639
2803
  async function applyCustomizeChoice(choice, ctx) {
2640
2804
  if (!isRecord(choice)) return;
@@ -2645,25 +2809,68 @@ async function applyCustomizeChoice(choice, ctx) {
2645
2809
  await applyCustomizeSwitch(switchId, valueId, ctx);
2646
2810
  }
2647
2811
 
2812
+ // The overlay's apply path: it receives the structural ids of the setting and
2813
+ // the option the user confirmed, writes through the same functions the menu
2814
+ // uses, and answers with a freshly read model so the panel shows the real state
2815
+ // instead of guessing it. `close` is only true when Pi must reload: the caller
2816
+ // closes the overlay first and reloads after it resolved.
2817
+ async function applyCustomizePanel(choice, ctx) {
2818
+ const model = () => customizePanelModel(ctx);
2819
+ if (!isRecord(choice)) return { model: model(), close: false, reload: false };
2820
+ const { settingId, optionId } = choice;
2821
+ if (settingId === CUSTOMIZE_THEME_SETTING_ID) {
2822
+ if (optionId === CUSTOMIZE_THEME_NONE_OPTION_ID) writeThemeChoice(ctx, null);
2823
+ else if (typeof optionId === "string" && optionId.startsWith(CUSTOMIZE_THEME_OPTION_PREFIX)) {
2824
+ writeThemeChoice(ctx, optionId.slice(CUSTOMIZE_THEME_OPTION_PREFIX.length));
2825
+ }
2826
+ return { model: model(), close: false, reload: false };
2827
+ }
2828
+ if (!CUSTOMIZE_SWITCH_IDS.includes(settingId)) return { model: model(), close: false, reload: false };
2829
+ if (optionId !== "on" && optionId !== "off") return { model: model(), close: false, reload: false };
2830
+ const result = await applyCustomizeSwitch(settingId, optionId, ctx, { deferReload: true });
2831
+ const reload = Boolean(result && result.needsReload);
2832
+ return { model: model(), close: reload, reload };
2833
+ }
2834
+
2648
2835
  // The former plain menu, kept as the fallback when the TUI helpers or
2649
2836
  // `ctx.ui.custom` are unavailable. It reads the same model and applies
2650
- // through the same path as the overlay.
2837
+ // through the same path as the overlay, and it offers the theme rows too, so
2838
+ // theme sync is reachable in a plain terminal.
2651
2839
  async function runCustomizeFallback(ctx) {
2652
2840
  const select = ctx?.ui?.select;
2653
2841
  if (typeof select !== "function") return;
2654
2842
  let picked = null;
2655
2843
  try {
2656
- picked = await select(CUSTOMIZE_TITLE, [CUSTOMIZE_SIDEBAR_LABEL, CUSTOMIZE_MOSHI_LABEL]);
2844
+ picked = await select(CUSTOMIZE_TITLE, [
2845
+ CUSTOMIZE_SIDEBAR_LABEL,
2846
+ CUSTOMIZE_MOSHI_LABEL,
2847
+ CUSTOMIZE_THEME_SYNC_LABEL,
2848
+ CUSTOMIZE_THEME_LABEL,
2849
+ ]);
2657
2850
  } catch {
2658
2851
  picked = undefined;
2659
2852
  }
2660
2853
  // Esc/cancel (null or undefined) writes nothing and reloads nothing.
2661
2854
  if (picked === undefined || picked === null) return;
2662
- const id = picked === CUSTOMIZE_SIDEBAR_LABEL ? "sidebar" : picked === CUSTOMIZE_MOSHI_LABEL ? "moshi" : null;
2855
+ // The theme value is not an On/Off switch: it opens the (already sorted)
2856
+ // theme list itself, so the second prompt below never applies to it.
2857
+ if (picked === CUSTOMIZE_THEME_LABEL) {
2858
+ await applyThemeSelection(ctx);
2859
+ return;
2860
+ }
2861
+ const id = picked === CUSTOMIZE_SIDEBAR_LABEL
2862
+ ? "sidebar"
2863
+ : picked === CUSTOMIZE_MOSHI_LABEL
2864
+ ? "moshi"
2865
+ : picked === CUSTOMIZE_THEME_SYNC_LABEL
2866
+ ? "theme-sync"
2867
+ : null;
2663
2868
  if (!id) return;
2664
2869
  const current = id === "sidebar"
2665
2870
  ? sidebarRowsState().state
2666
- : (moshiFlagEnabled(moshiFlagPath()) ? "on" : "off");
2871
+ : id === "theme-sync"
2872
+ ? themeStateLabels(readCustomizeThemeState()).sync
2873
+ : (moshiFlagEnabled(moshiFlagPath()) ? "on" : "off");
2667
2874
  let choice = null;
2668
2875
  try {
2669
2876
  choice = await select(`${picked} (currently ${current})`, [CUSTOMIZE_ON, CUSTOMIZE_OFF]);
@@ -2682,8 +2889,12 @@ async function executeCustomize(rawArgs, ctx) {
2682
2889
  // One read-only line: nothing is written and nothing is reloaded.
2683
2890
  const sidebar = sidebarRowsState();
2684
2891
  const moshi = moshiFlagEnabled(moshiFlagPath()) ? "on" : "off";
2892
+ const theme = themeStateLabels(readCustomizeThemeState());
2685
2893
  if (typeof notify === "function") {
2686
- notify(`customize status: sidebar=${sidebar.state} moshi=${moshi}`, "info");
2894
+ notify(
2895
+ `customize status: sidebar=${sidebar.state} moshi=${moshi} theme-sync=${theme.sync} theme=${theme.theme}`,
2896
+ "info",
2897
+ );
2687
2898
  }
2688
2899
  return;
2689
2900
  }
@@ -2704,11 +2915,11 @@ async function executeCustomize(rawArgs, ctx) {
2704
2915
  }
2705
2916
  if (helpers && ctx?.ui && typeof ctx.ui.custom === "function") {
2706
2917
  const panel = customizePanelModule();
2707
- const model = customizePanelModel();
2708
- let choice = null;
2918
+ const model = customizePanelModel(ctx);
2919
+ let reloadPending = false;
2709
2920
  if (panel && model) {
2710
2921
  try {
2711
- choice = await ctx.ui.custom(
2922
+ await ctx.ui.custom(
2712
2923
  // Theme and terminal rows travel through the real factory arguments:
2713
2924
  // the card paints with the host theme and clips to the live height.
2714
2925
  (hostTui, theme, _keybindings, done) => panel.createCustomizePanel({
@@ -2726,6 +2937,15 @@ async function executeCustomize(rawArgs, ctx) {
2726
2937
  }
2727
2938
  },
2728
2939
  model,
2940
+ // Enter applies in place behind the panel's busy guard: the panel
2941
+ // swaps in the model this reads back and stays open, except when a
2942
+ // reload is needed — then it closes so `ctx.reload()` runs here,
2943
+ // never behind a mounted card.
2944
+ apply: async (request) => {
2945
+ const outcome = await applyCustomizePanel(request, ctx);
2946
+ if (outcome.reload) reloadPending = true;
2947
+ return { model: outcome.model, close: outcome.close };
2948
+ },
2729
2949
  done,
2730
2950
  }),
2731
2951
  CUSTOMIZE_OVERLAY_OPTIONS,
@@ -2735,14 +2955,10 @@ async function executeCustomize(rawArgs, ctx) {
2735
2955
  await runCustomizeFallback(ctx);
2736
2956
  return;
2737
2957
  }
2738
- } else {
2739
- await runCustomizeFallback(ctx);
2958
+ if (reloadPending && typeof ctx.reload === "function") await ctx.reload();
2740
2959
  return;
2741
2960
  }
2742
- // Esc (null) does nothing at all: no notification, no write, no reload.
2743
- // Anything else runs the single apply path once the overlay is disposed.
2744
- if (!choice || typeof choice !== "object") return;
2745
- await applyCustomizeChoice(choice, ctx);
2961
+ await runCustomizeFallback(ctx);
2746
2962
  return;
2747
2963
  }
2748
2964
  await runCustomizeFallback(ctx);
@@ -2753,7 +2969,7 @@ export default function (pi) {
2753
2969
  // must stay reachable from a plain Pi session outside a Herdr pane.
2754
2970
  if (typeof pi?.registerCommand === "function") {
2755
2971
  pi.registerCommand("herdr-gentle:customize", {
2756
- description: "Customize Herdr Gentle Shell: sidebar agent rows and Moshi notifications",
2972
+ description: "Customize Herdr Gentle Shell: sidebar agent rows, Moshi notifications and the Herdr theme",
2757
2973
  handler: async (args, ctx) => {
2758
2974
  await executeCustomize(args, ctx);
2759
2975
  },