@pi-archimedes/core 2.6.3 → 2.7.1

package/README.md

@@ -30,7 +30,7 @@ After installing Pi, choose one installation command above, then `cd` into your
 
 - **Splash screen** — an animated greeting when the session launches, in one of nine reveal styles (`diagonal`, `top-right`, `bottom-left`, `bottom-right`, `center-out`, `wave`, `horizontal`, `vertical`, `vertical-up`).
 - **Framed editor** — your input in a clean bordered frame, with a double-press guard on the quit key (`Ctrl+C` by default) so a stray keystroke doesn't end the session.
-- **Working spinner on the border** — one of ten animating styles (`pendulum`, `typing`, `pulse`, `marquee`, `wave-rows`, `columns`, `cascade`, `diagonal-swipe`, `rain`, `sparkle`) traces the editor frame while the agent works, replacing Pi's native "Working" line.
+- **Working spinner on the border** — one of ten animating styles (`pendulum`, `typing`, `pulse`, `marquee`, `wave-rows`, `columns`, `cascade`, `diagonal-swipe`, `rain`, `sparkle`) traces the editor frame while the agent works, replacing Pi's native "Working" line. When `editorSpinLabel` is at its default, the label switches to a random quip per busy episode — re-picked on a subtle random 15–45 s timer while long episodes continue; set a custom value to pin a label (an empty value still hides it).
 - **Thinking blocks** — chain-of-thought output gets a consistent label, colour, and layout; `codeUnindent` strips the common indentation so code in reasoning reads flush.
 - **The bus** (`@pi-archimedes/core/bus`) — a global pub/sub event system: `COST_UPDATE`, `ASK_REQUEST`, `TODOS_UPDATE`, `TODOS_CLEAR`… subagent costs flow to the footer through it, subagent todos to the task board, subagent questions to the ask UI.
 - **Shared utilities** — text truncation and width measurement, colour formatting, settings I/O, and startup profiling.
@@ -44,7 +44,7 @@ Settings live in `~/.pi/agent/settings.json` under `archimedes.core`. The file i
 | `editorSpinBorder` | bool | `true` | Show the animated border spinner while the agent works |
 | `editorSpinStyle` | string | `pendulum` | One of the ten spinner styles |
 | `editorSpinSpeed` | string | `normal` | `slow`, `normal`, or `fast` |
-| `editorSpinLabel` | string | `Working` | Label shown alongside the border spinner |
+| `editorSpinLabel` | string | `Working` | Label shown alongside the border spinner; the default is replaced by a random quip per busy episode (re-picked on a subtle random 15–45 s timer while long episodes continue) — set a custom value to pin it (empty still hides it) |
 | `animationStyle` | string | `vertical-up` | Splash-screen reveal style (the nine styles above) |
 | `labelText` | string | `Thinking...` | Prefix before thinking blocks |
 | `labelColor` | string | `255,215,0` | RGB string for the thinking label |

package/package.json

@@ -1,6 +1,10 @@
 {
   "name": "@pi-archimedes/core",
-  "version": "2.6.3",
+  "version": "2.7.1",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/danielcherubini/pi-archimedes.git"
+  },
   "type": "module",
   "keywords": [
     "pi-package"

package/src/editor/index.test.ts

@@ -62,15 +62,30 @@ vi.mock("@earendil-works/pi-coding-agent", () => {
   return { CustomEditor, getAgentDir: () => "/nonexistent-pi-agent-dir" };
 });
 
+// Deterministic quip picker: `exclude === "Quip A" → "Quip B"` (the 2nd
+// episode never back-to-back repeats), anything else → "Quip A". The
+// baseline is the `vi.fn` constructor argument (NOT `.mockImplementation(...)`):
+// `afterEach`'s `vi.restoreAllMocks()` runs `mockReset()`, which clears the
+// implementation; dispatch then falls back to `state.getOriginal()`, which is
+// the constructor baseline for a `vi.fn(baselineFn)` (the `.mockImplementation`
+// form's original is the noop — `pickQuip → undefined` — and would silently
+// drop every default-label test after the first `afterEach`).
+vi.mock("./spin-quips.js", () => {
+  const baseline = (exclude?: string): string =>
+    exclude === "Quip A" ? "Quip B" : "Quip A";
+  return { pickQuip: vi.fn(baseline), QUIP_ROTATION_MIN_SECS: 15, QUIP_ROTATION_MAX_SECS: 45 };
+});
+
 import {
   HephaestusEditor,
   SPIN_TYPE_START,
   SPIN_TYPE_CELLS,
 } from "./index.js";
 import { SPIN_VARIANTS } from "./spin.js";
+import { pickQuip } from "./spin-quips.js";
 
-/** The default label (no `spinLabel` in the ctor options), including the leading AND trailing spaces the renderer contributes (`" " + label + " "`). */
-const LABEL = " Working ";
+/** The label the default-path tests assert on: ` Loading ` — 7 chars (9 with the leading AND trailing spaces the renderer contributes via `" " + label + " "`), the same visible width as the default "Working" (`labelFit` 16, `LABEL.length` 9). The default-path tests pass this explicitly so they stay verbatim-mode (with no `spinLabel` they would be quip-mode, where the row carries the mocked quip after the first busy tick). */
+const LABEL = " Loading ";
 
 // ── Helpers ──────────────────────────────────────────────────────────────────
 
@@ -162,7 +177,7 @@ const rowFirmsToDashes = (run: string, len: number): void => {
 
 // Compensated width for a 60-wide box (inner = 56): the block sits at start 0
 // right at the corner (leading space at column 0, the 4-cell window at 1–4,
-// ` Working ` with its leading AND trailing space at 5–13): the row minus the
+// ` Loading ` with its leading AND trailing space at 5–13): the row minus the
 // block's 14 columns is all hard `─` — those columns replaced trailing dashes,
 // so the row width stays constant.
 const compensatedAt60 = (run: string): void => {
@@ -255,7 +270,7 @@ describe("static prefix, plain idle edge", () => {
 describe("busy/idle repaint at the render level", () => {
   it("busy→idle: the plain border repaints exactly once, then idle ticks are no-ops", () => {
     // isIdle() returns false, false, true, true across the four ticks
-    const { editor, tui } = makeEditor({ spin: true, idleSeq: [false, false, true, true] });
+    const { editor, tui } = makeEditor({ spin: true, spinLabel: "Loading", idleSeq: [false, false, true, true] });
 
     tick(editor); // busy #1
     expect(tui.requestRender).toHaveBeenCalledTimes(1);
@@ -270,12 +285,12 @@ describe("busy/idle repaint at the render level", () => {
     expect(tui.requestRender).toHaveBeenCalledTimes(3);
   });
 
-  it("busy streak wraps at the 38-step cycle: clear beat is 4 spaces + ` Working ` (label stays up), then the block grows again", () => {
+  it("busy streak wraps at the 38-step cycle: clear beat is 4 spaces + ` Loading ` (label stays up), then the block grows again", () => {
     // 40 busy values: 37 to reach step 37, then the wrap tick (→ 0, clear beat)
     // and the regrowth tick (→ step 1); the render decision uses the
     // overridden isIdle below, the tick machine uses the constructor sequence.
     // The intent is the typing cycle (38 steps, braille frames) — explicit, since the default style is now pendulum.
-    const { editor } = makeEditor({ spin: true, spinStyle: "typing", idleSeq: Array.from({ length: 40 }, () => false) });
+    const { editor } = makeEditor({ spin: true, spinStyle: "typing", spinLabel: "Loading", idleSeq: Array.from({ length: 40 }, () => false) });
     for (let i = 0; i < 37; i++) tick(editor); // s=1..37
     (editor as any).isIdle = () => false;
     tick(editor); // wraps to 0 — the clear beat
@@ -285,7 +300,7 @@ describe("busy/idle repaint at the render level", () => {
         SPIN_TYPE_START,
         SPIN_TYPE_START + 1 + SPIN_TYPE_CELLS + LABEL.length,
       ),
-    ).toBe( // `     Working` — the leading space + 4 clear spaces + the label
+    ).toBe( // `     Loading` — the leading space + 4 clear spaces + the label
       " " + "    " + LABEL,
     );
     tick(editor); // back to step 1 — cell 1 enters at ⠁
@@ -295,7 +310,7 @@ describe("busy/idle repaint at the render level", () => {
         SPIN_TYPE_START,
         SPIN_TYPE_START + 1 + SPIN_TYPE_CELLS + LABEL.length,
       ),
-    ).toBe(" ⠁   " + LABEL); // `⠁    Working`
+    ).toBe(" ⠁   " + LABEL); // `⠁    Loading`
     
   });
 });
@@ -307,41 +322,45 @@ describe("busy/idle repaint at the render level", () => {
 
 describe("typing strip on the top border row", () => {
   // 60-wide box (inner = 56): the full beat = leading space at 0 + 4-cell
-  // window + ` Working ` label (leading AND trailing space) when labelFit
-  // (16 for the default label) is met.
+  // window + ` Loading ` label (leading AND trailing space) when labelFit
+  // (16 for the 7-char label) is met.
   const beat = (ed: HephaestusEditor): string =>
     borderRun(ed.render(60), 60).slice(
       SPIN_TYPE_START,
       SPIN_TYPE_START + 1 + SPIN_TYPE_CELLS + LABEL.length,
     );
 
-  it("step 1: leading space at 0, then only cell 1 is `⠁` (dot block starts to grow), ` Working ` label follows", () => {
-    expect(beat(busyAt(1, { spinStyle: "typing" }))).toBe(" ⠁   " + LABEL);
-    rowFirmsToDashes(borderRun(busyAt(1, { spinStyle: "typing" }).render(60), 60), 56);
-    compensatedAt60(borderRun(busyAt(1, { spinStyle: "typing" }).render(60), 60));
+  it("step 1: leading space at 0, then only cell 1 is `⠁` (dot block starts to grow), ` Loading ` label follows", () => {
+    expect(beat(busyAt(1, { spinStyle: "typing", spinLabel: "Loading" }))).toBe(" ⠁   " + LABEL);
+    rowFirmsToDashes(borderRun(busyAt(1, { spinStyle: "typing", spinLabel: "Loading" }).render(60), 60), 56);
+    compensatedAt60(borderRun(busyAt(1, { spinStyle: "typing", spinLabel: "Loading" }).render(60), 60));
   });
 
   it("step 8 (line 1 complete): leading space at 0, all 4 cells are `⠉`, label follows", () => {
-    const ed = busyAt(8, { spinStyle: "typing" });
+    const ed = busyAt(8, { spinStyle: "typing", spinLabel: "Loading" });
     expect(beat(ed)).toBe(" ⠉⠉⠉⠉" + LABEL);
     rowFirmsToDashes(borderRun(ed.render(60), 60), 56);
     compensatedAt60(borderRun(ed.render(60), 60));
   });
 
   it("step 32 (fully grown): leading space at 0, all 4 cells are `⣿`, label follows", () => {
-    const ed = busyAt(32, { spinStyle: "typing" });
+    const ed = busyAt(32, { spinStyle: "typing", spinLabel: "Loading" });
     expect(beat(ed)).toBe(" ⣿⣿⣿⣿" + LABEL);
     rowFirmsToDashes(borderRun(ed.render(60), 60), 56);
     compensatedAt60(borderRun(ed.render(60), 60));
   });
 
   it("hold region (step 37): leading space at 0, full block holds — `⣿`×4 on, label still up (the hold clamp 33–38 is covered in spin.test.ts)", () => {
-    expect(beat(busyAt(37, { spinStyle: "typing" }))).toBe(" ⣿⣿⣿⣿" + LABEL);
+    const ed = busyAt(37, { spinStyle: "typing", spinLabel: "Loading" });
+    expect(beat(ed)).toBe(" ⣿⣿⣿⣿" + LABEL);
   });
 
   it("narrow width (14, inner 10): block at the corner (leading space at 0), window at 1, no label, row dash-compensated", () => {
-    // inner = 10 → 7 ≤ 10 < 16: window-only tier at start 0; trailing = 10 − 1 − 4 = 5
-    const run = borderRun(busyAt(4, { spinStyle: "typing" }).render(14), 14);
+    // inner = 10 → 7 ≤ 10 < 16: window-only tier at start 0; trailing = 10 − 1 − 4 = 5.
+    // Explicit verbatim label — the default (quip) mode would hand the seq-driven
+    // isIdle() a second per-tick consumer (the quip block, before the border
+    // spinner's own read) and reset the tick machine one tick early.
+    const run = borderRun(busyAt(4, { spinStyle: "typing", spinLabel: "Loading" }).render(14), 14);
     expect(run.slice(0, 1)).toBe(" ");
     expect(run.slice(1, 5)).toBe("⠉⠉  ");
     expect(run.slice(5)).toBe("─".repeat(5));
@@ -349,17 +368,17 @@ describe("typing strip on the top border row", () => {
     rowFirmsToDashes(run, 10);
   });
 
-  it("label-fit tiers: window-only at inner 15 (19, 10 trailing dashes); label on at inner 16 (20 = L + 9) — verbatim beat ` ⠛⠛⠛⠛ Working ` with 2 trailing dashes", () => {
-    const run15 = borderRun(busyAt(16, { spinStyle: "typing" }).render(19), 19);
+  it("label-fit tiers: window-only at inner 15 (19, 10 trailing dashes); label on at inner 16 (20 = L + 9) — verbatim beat ` ⠛⠛⠛⠛ Loading ` with 2 trailing dashes", () => {
+    const run15 = borderRun(busyAt(16, { spinStyle: "typing", spinLabel: "Loading" }).render(19), 19);
     expect(run15).not.toContain("Working"); // inner 15 < 16 → window-only tier
     expect(run15.slice(0, 1)).toBe(" ");
     expect(run15.slice(1, 5)).toBe("⠛⠛⠛⠛");
     expect(run15.slice(5)).toBe("─".repeat(10)); // trailing = 15 − 1 − 4 = 10
     rowFirmsToDashes(run15, 15);
-    const run = borderRun(busyAt(16, { spinStyle: "typing" }).render(20), 20); // inner = 16 = 0 + 1 + 4 + (1 + 7 + 1) + 2 (labelFit for L = 7)
+    const run = borderRun(busyAt(16, { spinStyle: "typing", spinLabel: "Loading" }).render(20), 20); // inner = 16 = 0 + 1 + 4 + (1 + 7 + 1) + 2 (labelFit for L = 7)
     expect(run.slice(0, 1)).toBe(" ");
     expect(run.slice(1, 5)).toBe("⠛⠛⠛⠛");
-    expect(run.slice(5, 14)).toBe(LABEL); // ` Working ` — leading AND trailing space
+    expect(run.slice(5, 14)).toBe(LABEL); // ` Loading ` — leading AND trailing space
     expect(run.slice(14)).toBe("─".repeat(2)); // trailing = 16 − 0 − 1 − 4 − (1 + 7 + 1) = 2
     rowFirmsToDashes(run, 16);
   });
@@ -457,10 +476,189 @@ describe("typing strip on the top border row", () => {
     rowFirmsToDashes(run, 56);
   });
 
-  it("non-string label (corrupt config): the ctor falls back to \"Working\" (never throws in visibleWidth)", () => {
+  it("non-string label (corrupt config): the ctor falls back to \"Working\" → quip mode — no crash, and the first episode's quip (mock ` Quip A `) is what renders", () => {
     const ed = busyAt(4, { spinStyle: "typing", spinLabel: null as unknown as string });
     const run = borderRun(ed.render(60), 60);
-    expect(run).toContain(LABEL);
+    expect(run).toContain(" Quip A ");
+    expect(run).not.toContain("Working");
+  });
+});
+
+// ── 3b. Spin quips (default / corrupt label → per-episode quip) ─────────────
+// The quip block runs in `tickSpin` BEFORE the border-spinner tick (the
+// selection lands before the first repaint). The default "Working" (and a
+// non-string corrupt config, which falls back to it) → quip mode: one quip
+// per busy episode, `exclude` = the previous episode's. An explicit
+// non-empty, non-"Working" label → verbatim; `""` → hidden; `spin: false`
+// → the timer never exists, so the quip block is unreachable (inert).
+
+describe("spin quips (per-episode selection)", () => {
+  it("default label (no spinLabel): the first busy pick shows (mock ` Quip A `) in a 60-col busy row — the literal ` Working ` label is NOT in the row", () => {
+    const run = borderRun(busyAt(1, { spinStyle: "typing" }).render(60), 60);
+    expect(run).toContain(" Quip A ");
+    expect(run).not.toContain(" Working ");
+  });
+
+  it("busy → idle → busy: the quip survives the idle (no re-pick on idle ticks); the 2nd episode re-picks with it excluded (mock ` Quip B `)", () => {
+    // the seq feeds isIdle() in [quip block, border spinner] order per tick:
+    // t1 busy (false, false), t2 idle (true, true), t3 busy (false, false).
+    const { editor } = makeEditor({
+      spin: true,
+      spinStyle: "typing",
+      idleSeq: [false, false, true, true, false, false],
+    });
+    tick(editor); // busy episode 1 → picks `Quip A`
+    tick(editor); // idle — the quip survives (no re-pick)
+    expect((editor as any).spinQuip).toBe("Quip A");
+    tick(editor); // busy episode 2 → re-picks with exclude `Quip A` → `Quip B`
+    expect((editor as any).spinQuip).toBe("Quip B");
+    (editor as any).isIdle = () => false;
+    const run = borderRun(editor.render(60), 60);
+    expect(run).toContain(" Quip B ");
+    expect(run).not.toContain(" Quip A ");
+  });
+
+  it("empty label (empty string): no label text in any tier — hidden mode, the quip block never runs (window-only even wide)", () => {
+    const wide = borderRun(busyAt(4, { spinStyle: "typing", spinLabel: "" }).render(60), 60);
+    expect(wide).not.toContain("Quip");
+    expect(wide).not.toContain("Working");
+    expect(wide.slice(0, 1)).toBe(" ");
+    expect(wide.slice(1, 5)).toBe("⠉⠉  ");
+    expect(wide.slice(5)).toBe("─".repeat(51)); // trailing = 56 − 1 − 4 = 51 (no label cost)
+    rowFirmsToDashes(wide, 56);
+    const narrow = borderRun(busyAt(4, { spinStyle: "typing", spinLabel: "" }).render(14), 14);
+    expect(narrow).not.toContain("Quip");
+    expect(narrow.slice(0, 1)).toBe(" ");
+    expect(narrow.slice(5)).toBe("─".repeat(5)); // window-only tier (inner 10)
+    rowFirmsToDashes(narrow, 10);
+  });
+
+  it("spin=false: fully inert — even when ticked, `spinEnabled` is false so the quip block never picks; the border row stays plain (no window, no label)", () => {
+    const { editor } = makeEditor({ spin: false, idleSeq: Array(4).fill(false) });
+    for (let i = 0; i < 4; i++) tick(editor);
+    (editor as any).isIdle = () => false;
+    const run = borderRun(editor.render(60), 60);
+    expect(run).toBe("─".repeat(56));
+    expect(run).not.toContain("Quip");
+  });
+
+  it("20-char quip (mock one-time override): hidden at width 32 (inner 28 < 29 = 20 + 9), shown at 33 (inner 29 = 1 + 4 + (1 + 20 + 1) + 2) with the floor-held trailing", () => {
+    // Single busy episode: ONE tick, and the seq hands BOTH per-tick isIdle()
+    // readers (the quip block, then the border spinner) a false — the
+    // one-time override is consumed exactly once by the quip block, and the
+    // stored quip is what both renders see.
+    vi.mocked(pickQuip).mockImplementationOnce(() => "TwentyCharsQuipQuiz!");
+    const { editor } = makeEditor({
+      spin: true,
+      spinStyle: "typing",
+      idleSeq: [false, false],
+    });
+    tick(editor);
+    (editor as any).isIdle = () => false;
+    const hidden = borderRun(editor.render(32), 32); // inner 28 < 29 → window-only tier
+    expect(hidden).not.toContain("TwentyCharsQuipQuiz!");
+    expect(hidden.slice(0, 1)).toBe(" ");
+    expect(hidden.slice(1, 5)).toBe("⠁   ");
+    expect(hidden.slice(5)).toBe("─".repeat(23)); // trailing = 28 − 1 − 4
+    rowFirmsToDashes(hidden, 28);
+    const shown = borderRun(editor.render(33), 33); // inner 29 = 0 + 1 + 4 + (1 + 20 + 1) + 2
+    expect(shown.slice(0, 1)).toBe(" ");
+    expect(shown.slice(1, 5)).toBe("⠁   ");
+    expect(shown.slice(5, 27)).toBe(" TwentyCharsQuipQuiz! "); // own leading AND trailing space
+    expect(shown.slice(27)).toBe("─".repeat(2)); // trailing = 29 − 1 − 4 − (1 + 20 + 1)
+    rowFirmsToDashes(shown, 29);
+  });
+});
+
+// ── 3c. Quip timer rotation (in-episode re-rotation, random 15–45s) ──
+// The in-episode rotation rides the existing spin tick (no new interval):
+// a counter accumulates while busy; at the per-episode random threshold
+// (inclusive 15–45s from the injected `quipRand`, `ceil` ticks, never
+// shorter than requested) the quip is re-picked (`exclude` = current, the
+// same one-re-roll contract). A new episode always re-picks + resets.
+// Idle freezes the counter (no rotation across gaps; the label persists).
+// Forced periods go through `as any` field overrides (no setting reaches
+// them: `SPIN_INTERVALS` max 80 ms × 1.5 (slow) = 120 ms); they must be
+// applied before the first busy tick (the window is drawn lazily there).
+
+describe("spin quips (in-episode timer rotation)", () => {
+  it("window threshold: 300 ms (divides 15000/30000/45000) → exact 15 / 30 / 45 s for the forced rand 0 / 0.5 / 1, within the ceil-form bounds", () => {
+    const draws: Array<[number, number]> = [[0, 50], [0.5, 100], [0.999, 150]];
+    for (const [r, ticksExact] of draws) {
+      const { editor } = makeEditor({ spin: true, spinStyle: "typing", idleSeq: [false] });
+      (editor as any).spinTickMs = 300;
+      (editor as any).quipRand = () => r;
+      tick(editor); // episode start → window drawn
+      const ticks = (editor as any).spinQuipEveryTicks as number;
+      expect(ticks, `rand ${r}`).toBe(ticksExact);
+    }
+  });
+
+  it("window threshold: 2000 ms + rand 1 → ceil(22.5) = 23 ticks = 46 s — the ceil-form bounds hold (never shorter than the request; at most one tick past the max)", () => {
+    const { editor } = makeEditor({ spin: true, spinStyle: "typing", idleSeq: [false] });
+    (editor as any).spinTickMs = 2000;
+    (editor as any).quipRand = () => 1;
+    tick(editor);
+    const ticks = (editor as any).spinQuipEveryTicks as number;
+    expect(ticks).toBe(23);
+    const seconds = (ticks * 2000) / 1000;
+    expect(seconds).toBeGreaterThanOrEqual(15);
+    expect(seconds).toBeLessThan(45 + 2000 / 1000);
+  });
+
+  it("one long busy episode (T = 50, N = 60 ticks @ 300 ms, T < N < 2T): exactly one re-pick (at tick 50, `exclude` = the previous), counter reset, next window re-drawn, border shows the rotation's quip", () => {
+    const { editor } = makeEditor({
+      spin: true,
+      spinStyle: "typing",
+      // The seq feeds isIdle() in [quip block, border spinner] order — two readers per tick.
+      idleSeq: Array(120).fill(false),
+    });
+    (editor as any).spinTickMs = 300;
+    (editor as any).quipRand = () => 0;
+    for (let i = 0; i < 60; i++) tick(editor);
+    expect(pickQuip).toHaveBeenCalledTimes(2); // episode pick + the one rotation
+    expect(pickQuip).toHaveBeenNthCalledWith(2, "Quip A", expect.any(Function));
+    expect((editor as any).spinQuip).toBe("Quip B");
+    expect((editor as any).spinQuipTicks).toBe(9); // 60 − 50, reset after the re-pick
+    expect((editor as any).spinQuipEveryTicks).toBe(50); // re-drawn (rand 0)
+    (editor as any).isIdle = () => false; // render reads isIdle() itself (the seq is exhausted)
+    const run = borderRun(editor.render(60), 60);
+    expect(run).toContain(" Quip B ");
+  });
+
+  it("while idle: the counter is frozen (no cumulative rotation across the gap, 44 + 30 idle < never reached), the pick count doesn't move, and the label survives; the next episode re-picks + resets", () => {
+    const { editor } = makeEditor({
+      spin: true,
+      spinStyle: "typing",
+      // Two readers per tick: 45 busy ticks = 90 falses, 30 idle ticks = 60 trues, 2 busy ticks = 4 falses.
+      idleSeq: [...Array(90).fill(false), ...Array(60).fill(true), false, false, false, false],
+    });
+    (editor as any).spinTickMs = 300;
+    (editor as any).quipRand = () => 0;
+    for (let i = 0; i < 45; i++) tick(editor); // busy → ticks 44 (< T = 50)
+    expect((editor as any).spinQuipTicks).toBe(44);
+    for (let i = 0; i < 30; i++) tick(editor); // idle → frozen
+    expect((editor as any).spinQuipTicks).toBe(44);
+    expect(pickQuip).toHaveBeenCalledTimes(1);
+    expect((editor as any).spinQuip).toBe("Quip A");
+    for (let i = 0; i < 2; i++) tick(editor); // busy again → new episode: pick #2 + reset
+    expect(pickQuip).toHaveBeenCalledTimes(2);
+    expect(pickQuip).toHaveBeenNthCalledWith(2, "Quip A", expect.any(Function));
+    expect((editor as any).spinQuip).toBe("Quip B");
+    expect((editor as any).spinQuipTicks).toBe(1);
+  });
+
+  it("real (unmocked) rand: 10 consecutive episode windows all within [15 s, 45 s + 1 tick period)", () => {
+    for (let i = 0; i < 10; i++) {
+      const { editor } = makeEditor({ spin: true, spinStyle: "typing", idleSeq: [false, true] });
+      tick(editor); // episode start — the default `Math.random` quipRand draws the window
+      const ticks = (editor as any).spinQuipEveryTicks as number;
+      const ms = (editor as any).spinTickMs as number;
+      const seconds = (ticks * ms) / 1000;
+      expect(seconds, `window ${i + 1}`).toBeGreaterThanOrEqual(15);
+      expect(seconds, `window ${i + 1}`).toBeLessThan(45 + ms / 1000);
+      tick(editor); // idle — end of episode
+    }
   });
 });
 
@@ -494,7 +692,10 @@ describe("timer lifecycle & gating", () => {
 
   it("spinStyle \"wave-rows\" (ported — batch 2): a never-ticked busy box shows the wave-rows step-0 window (⢦⣠⠞⠙), NOT the typing fallback (⠁)", () => {
     // hold-0 port styles run the full source loop: step 0 is the real first frame (no blank beat).
-    const { editor } = makeEditor({ spin: true, spinStyle: "wave-rows" });
+    // Explicit verbatim label — this box is never ticked, so its row carries the
+    // label as-is (a quip-mode box would flash the default "Working" for one
+    // un-ticked render before the first pick).
+    const { editor } = makeEditor({ spin: true, spinStyle: "wave-rows", spinLabel: "Loading" });
     (editor as any).isIdle = () => false;
     const wave0 = SPIN_VARIANTS["wave-rows"]!.compute(0);
     const cellStr = wave0
@@ -582,12 +783,12 @@ describe("timer lifecycle & gating", () => {
 // ── 5. EAW fallback (⣿ reports width 2 → stage set flips to shading) ──────
 
 describe("EAW terminal fallback", () => {
-  it("⣿ reports width 2: the window uses the shade set (░→█) in the same cell-wise order, no braille in the row, the ` Working ` label stays (ASCII-safe)", () => {
+  it("⣿ reports width 2: the window uses the shade set (░→█) in the same cell-wise order, no braille in the row, the ` Loading ` label stays (ASCII-safe)", () => {
     const braille = ["⠁", "⠉", "⠋", "⠛", "⠟", "⠿", "⡿", "⣿"];
     widthProbe.probe = (s: string) => (s === "⣿" ? 2 : s.length);
     try {
       const expectWindow = (s: number, window: string) => {
-        const run = borderRun(busyAt(s, { spinStyle: "typing" }).render(60), 60);
+        const run = borderRun(busyAt(s, { spinStyle: "typing", spinLabel: "Loading" }).render(60), 60);
         expect(run.slice(SPIN_TYPE_START, SPIN_TYPE_START + 1)).toBe(" ");
         expect(
           run.slice(

package/src/editor/index.ts

@@ -23,6 +23,7 @@ import {
 } from "../chrome.js";
 import { isParentBorder, formatKey } from "../text.js";
 import { SPIN_INTERVALS, BorderTypeSpinner } from "./spin.js";
+import { pickQuip, QUIP_ROTATION_MAX_SECS, QUIP_ROTATION_MIN_SECS } from "./spin-quips.js";
 import { SPIN_SPEED_MULT, type CoreConfig, type SpinnerStyle } from "../config.js";
 
 const DOUBLE_PRESS_WINDOW_MS = 500;
@@ -44,8 +45,22 @@ export class HephaestusEditor extends CustomEditor {
   private readonly spinEnabled: boolean;
   /** Label typed after the 4-cell window while busy (the `editorSpinLabel` setting): an empty string hides it. */
   private readonly spinLabel: string;
+  /** Immutable label mode, derived in the ctor from the RAW `spinLabel`: `""` (a string) → `"hidden"` (no quip; legacy precedence); non-string (corrupt config — `safeSpinLabel` fell back to `"Working"`) → `"quip"`; `safeSpinLabel === "Working"` (default or hand-typed, indistinguishable) → `"quip"`; any other non-empty string → `"verbatim"` (the config label wins). */
+  private readonly labelMode: "hidden" | "quip" | "verbatim";
+  /** The current busy episode's quip: `undefined` until the first idle→busy tick (the default `"Working"` then shows for at most one tick — approved), survives idle ticks, and is re-picked on the next busy transition with the previous quip excluded. */
+  private spinQuip: string | undefined;
+  /** Quip-mode busy-episode tracker — deliberately starts `false`, never reads `isIdle()` at construction, so an already-busy agent gets a quip on its first tick (transition detection needs `false` beforehand). */
+  private wasBusy = false;
   /** The border-row spin spinner (mechanism in `BorderTypeSpinner`): the `spinStyle` (raw setting strings normalize — unknown names fall back to typing frames) — created only when `spin` is on, so the off path stays fully inert. The tick period is the style's native tempo × the `spinSpeed` multiplier, 32 ms floor. */
   private readonly borderSpinner: BorderTypeSpinner | undefined;
+  /** The quip rotation tick period in ms — set to the style tempo when `spin` is on; the 32 ms default is inert (`rotationThresholdTicks()` is only reached on busy ticks, which imply spin is on). */
+  private readonly spinTickMs: number = 32;
+  /** In-episode quip rotation — the counter accumulates busy ticks; at the per-episode random threshold it re-picks the quip. Frozen while idle (no re-rotation across gaps); a new episode re-picks + resets. */
+  private spinQuipTicks = 0;
+  /** The current rotation window's threshold in ticks — a per-episode draw (see `rotationThresholdTicks()`); the `0` default is never read before the idle→busy branch assigns it (the counter only increments after that branch has run). */
+  private spinQuipEveryTicks = 0;
+  /** The injected random source for the in-episode quip rotation window (inclusive 15–45 s); tests override via `as any`, the same seam as `isIdle` — the constructor gains no signature change. */
+  private quipRand: () => number = Math.random;
   private readonly onSpinInterval:
     | ((interval: ReturnType<typeof setInterval> | undefined) => void)
     | undefined;
@@ -74,7 +89,7 @@ export class HephaestusEditor extends CustomEditor {
       spinSpeed?: CoreConfig["editorSpinSpeed"];
       /** The `editorSpinStyle` setting — the default style, from the config default (pendulum); raw setting strings are tolerated, but unknown names still normalize to typing frames (the normalizer's fallback, kept distinct from the default). */
       spinStyle?: SpinnerStyle | string;
-      /** Label typed after the window while busy (the `editorSpinLabel` setting); an empty string hides it. Non-string values (corrupt config) fall back to "Working". */
+      /** Label typed after the window while busy (the `editorSpinLabel` setting): an empty string hides it. The default `"Working"` (and a hand-typed `"Working"`, indistinguishable from it) is replaced by a random quip picked once per busy episode, re-picked on a subtle random 15–45 s timer while a long episode continues; any other non-empty string is shown verbatim. Non-string values (corrupt config) fall back to `"Working"` — i.e. quip mode. */
       spinLabel?: string;
       /** Lets an out-of-editor scope (core index.ts session hooks) clear the timer. */
       onSpinInterval?: (
@@ -93,15 +108,22 @@ export class HephaestusEditor extends CustomEditor {
     const safeSpinLabel =
       typeof spinLabel === "string" ? spinLabel : "Working";
     this.spinLabel = safeSpinLabel;
+    // Immutable label mode from the RAW option (the `typeof` check reads the raw value, so it also distinguishes a corrupt non-string from a hand-typed "Working").
+    this.labelMode =
+      typeof spinLabel === "string" && spinLabel === ""
+        ? "hidden"
+        : safeSpinLabel === "Working"
+          ? "quip"
+          : "verbatim";
     this.borderSpinner = spin ? new BorderTypeSpinner(this.isIdle, spinStyle) : undefined;
     if (spin) {
       // The style's native per-tick tempo × the `editorSpinSpeed` multiplier, 32 ms tick floor (the floor also caps a 30 ms native style under `fast` at 32); unknown raw strings fall back to the typing native (the normalize fallback).
       const nativeMs = SPIN_INTERVALS[spinStyle as SpinnerStyle];
-      const spinTickMs = Math.max(
+      this.spinTickMs = Math.max(
         32,
         (nativeMs ?? SPIN_INTERVALS["typing"]) * (SPIN_SPEED_MULT[spinSpeed] ?? 1),
       );
-      this.spinTimer = setInterval(() => this.tickSpin(), spinTickMs);
+      this.spinTimer = setInterval(() => this.tickSpin(), this.spinTickMs);
       this.onSpinInterval?.(this.spinTimer);
     }
   }
@@ -117,12 +139,37 @@ export class HephaestusEditor extends CustomEditor {
 
   // ── Prompt spin ───────────────────────────────────────
 
+  /** Advances the spin; in quip mode the selection (per-episode pick, and the in-episode re-pick at the computed window's threshold) lands BEFORE the border-spinner repaint. While idle, the rotation counter is frozen (the label remains; no re-rotation across the gap). */
   private tickSpin(): void {
+    if (this.labelMode === "quip") {
+      const busy = this.spinEnabled && !this.isIdle();
+      if (busy && !this.wasBusy) {
+        // Episode start: fresh quip + reset the rotation window.
+        this.spinQuip = pickQuip(this.spinQuip, this.quipRand);
+        this.spinQuipTicks = 0;
+        this.spinQuipEveryTicks = this.rotationThresholdTicks();
+      } else if (busy) {
+        this.spinQuipTicks += 1;
+        if (this.spinQuipTicks >= this.spinQuipEveryTicks) {
+          // In-episode re-rotation: re-pick (excludes the current), reset the counter, draw the next window.
+          this.spinQuip = pickQuip(this.spinQuip, this.quipRand);
+          this.spinQuipTicks = 0;
+          this.spinQuipEveryTicks = this.rotationThresholdTicks();
+        }
+      }
+      this.wasBusy = busy;
+    }
     if (this.borderSpinner && this.borderSpinner.tick()) {
       this.tui.requestRender();
     }
   }
 
+  /** The random 15–45 s window (inclusive, from the injected `quipRand`) in whole ticks — `ceil`'d so the window is never shorter than requested (at most one tick over the max). */
+  private rotationThresholdTicks(): number {
+    const seconds = QUIP_ROTATION_MIN_SECS + Math.floor(this.quipRand() * (QUIP_ROTATION_MAX_SECS - QUIP_ROTATION_MIN_SECS + 1));
+    return Math.ceil((seconds * 1000) / this.spinTickMs);
+  }
+
   /** The 4-cell window that replaces a segment of the border (mechanism in `BorderTypeSpinner`): cells fill cell-by-cell left→right, the current step's stage chars rendered in the spin (accent) palette (⠁⠉ / ⠋⠛ / ⠟⠿ / ⡿⣿; EAW: the width-1 shading ░ → █) — the 2×4 dot block grows across the window — the not-yet-reached cells are plain spaces (the border line breaks) — plain " " (U+0020). The empty clear step (step 0) is all spaces; hold steps clamp to the last (fully grown) frame. The window sits one leading space after `┌` at start 0 (right at the corner), and the label follows it typed as `" " + spinLabel + " "` — its own leading and trailing spaces, with the trailing one providing the margin to the trailing dashes. */
   private typeStrip(): string {
     const p = resolvePalette(this.getTheme());
@@ -250,7 +297,8 @@ export class HephaestusEditor extends CustomEditor {
       // otherwise).
       const borderRun = (() => {
         const busy = this.spinEnabled && !this.isIdle();
-        const label = this.spinLabel;
+        // Quip mode: the current episode's quip replaces the default label (`spinQuip` is `undefined` before the first busy tick, so at most one tick shows the default `"Working"` — approved); `hidden` / `verbatim` render the config label as-is.
+        const label = this.labelMode === "quip" ? (this.spinQuip ?? this.spinLabel) : this.spinLabel;
         // Visible width (not `.length`): a 4-char CJK label is 8 cells wide — `label.length` would short the row.
         const labelW = visibleWidth(label);
         const labelShown =

package/src/editor/spin-quips.test.ts

@@ -0,0 +1,106 @@
+import { describe, expect, it, vi } from "vitest";
+import { SPIN_QUIPS, pickQuip, QUIP_ROTATION_MIN_SECS, QUIP_ROTATION_MAX_SECS } from "./spin-quips.js";
+
+// ── SPIN_QUIPS pool invariants ───────────────────────────────────────────────
+
+describe("SPIN_QUIPS", () => {
+  /** A mutable copy — the frozen `SPIN_QUIPS` is asserted read-only below. */
+  const pool = [...SPIN_QUIPS];
+
+  it("has 20–60 entries", () => {
+    expect(SPIN_QUIPS.length).toBeGreaterThanOrEqual(20);
+    expect(SPIN_QUIPS.length).toBeLessThanOrEqual(60);
+  });
+
+  it("entries are 1–64 chars", () => {
+    for (const q of pool) {
+      expect(q.length, JSON.stringify(q)).toBeGreaterThanOrEqual(1);
+      expect(q.length, JSON.stringify(q)).toBeLessThanOrEqual(64);
+    }
+  });
+
+  it("entries are printable ASCII only (U+0020–U+007E)", () => {
+    for (const q of pool) {
+      const ok = [...q].every((c) => {
+        const code = c.charCodeAt(0);
+        return code >= 0x20 && code <= 0x7e;
+      });
+      expect(ok, JSON.stringify(q)).toBe(true);
+    }
+  });
+
+  it("entries have no leading or trailing space", () => {
+    for (const q of pool) {
+      expect(q.startsWith(" "), JSON.stringify(q)).toBe(false);
+      expect(q.endsWith(" "), JSON.stringify(q)).toBe(false);
+    }
+  });
+
+  it("entries have no double (consecutive) spaces", () => {
+    for (const q of pool) {
+      expect(q.includes("  "), JSON.stringify(q)).toBe(false);
+    }
+  });
+
+  it("entries are all unique", () => {
+    expect(new Set(pool).size).toBe(pool.length);
+  });
+
+  it("is frozen", () => {
+    expect(Object.isFrozen(SPIN_QUIPS)).toBe(true);
+  });
+});
+
+// ── Quip rotation constants ──────────────────────────────────────────────────
+
+describe("QUIP_ROTATION_* constants", () => {
+  it("are the inclusive 15 s / 45 s bounds, min < max, integers", () => {
+    expect(QUIP_ROTATION_MIN_SECS).toBe(15);
+    expect(QUIP_ROTATION_MAX_SECS).toBe(45);
+    expect(QUIP_ROTATION_MIN_SECS).toBeLessThan(QUIP_ROTATION_MAX_SECS);
+    expect(Number.isInteger(QUIP_ROTATION_MIN_SECS)).toBe(true);
+    expect(Number.isInteger(QUIP_ROTATION_MAX_SECS)).toBe(true);
+  });
+});
+
+// ── pickQuip ─────────────────────────────────────────────────────────────────
+
+describe("pickQuip", () => {
+  it("rand = () => 0 (no exclude) → the first pool entry", () => {
+    expect(pickQuip(undefined, () => 0)).toBe(SPIN_QUIPS[0]!);
+  });
+
+  it("exclude = first pick → exactly one restricted re-roll: the first non-excluded entry, and rand is consumed twice", () => {
+    const rand = vi.fn().mockReturnValue(0);
+    const first = SPIN_QUIPS[0]!;
+    const quip = pickQuip(first, rand);
+    // a second draw really happened (not a duplicate of the first)…
+    expect(rand).toHaveBeenCalledTimes(2);
+    expect(quip).not.toBe(first);
+    // …and it is the first pool entry ≠ exclude (filtered pick, rand 0).
+    expect(quip).toBe(SPIN_QUIPS[1]!);
+    expect(poolHas(quip)).toBe(true);
+  });
+
+  it("exclude given but the first pick misses it → no re-roll (rand consumed once)", () => {
+    const rand = vi.fn().mockReturnValue(0);
+    const quip = pickQuip(SPIN_QUIPS[1]!, rand);
+    expect(rand).toHaveBeenCalledTimes(1);
+    expect(quip).toBe(SPIN_QUIPS[0]!);
+  });
+
+  it("exclude not in the pool → single draw, never a re-roll", () => {
+    const rand = vi.fn().mockReturnValue(0);
+    expect(pickQuip("not in the pool", rand)).toBe(SPIN_QUIPS[0]!);
+    expect(rand).toHaveBeenCalledTimes(1);
+  });
+
+  it("default rand returns an actual pool member (smoke)", () => {
+    expect(poolHas(pickQuip())).toBe(true);
+  });
+});
+
+/** Whether `q` is a pool member. */
+function poolHas(q: string): boolean {
+  return SPIN_QUIPS.includes(q);
+}

package/src/editor/spin-quips.ts

@@ -0,0 +1,44 @@
+/** The spinner quip pool — fun (≤ 64 visible chars, printable-ASCII-only) status labels shown instead of the default "Working" per busy episode (see plan-037). Mixed nerdy: compute/OS, CS/programmer folklore, math/physics. Invariants (20–60 entries, 1–64 chars, printable ASCII, no edge/double spaces, unique, frozen) are enforced by `spin-quips.test.ts`. */
+export const SPIN_QUIPS: readonly string[] = Object.freeze([
+  "Working...",
+  "Compiling a list of excuses for the next stand-up...",
+  "Containerizing the 'it works on my machine' anomaly...",
+  "Consulting a 10-year-old Stack Overflow thread...",
+  "Explaining the entire architecture to a rubber duck...",
+  "Force-pushing a rebase onto objective reality...",
+  "Pretending the linter warnings are just polite suggestions...",
+  "Wrangling a regex that no mortal can actually comprehend...",
+  "Slipping a $20 bill to the CPU's branch predictor...",
+  "Waiting for a cosmic ray to flip exactly the right bit...",
+  "Convincing floating-point math that 0.1 + 0.2 equals 0.3...",
+  "Quantizing the vibes from FP32 all the way down to INT4...",
+  "Performing evasive maneuvers to dodge a thread deadlock...",
+  "Politely asking the borrow checker for permission to live...",
+  "Deep-sea mining in the codebase for a missing semicolon...",
+  "Blaming a mysterious DNS issue like we always do...",
+  "Downloading more RAM from a highly suspicious website...",
+  "Collapsing quantum wavefunctions just by looking at them...",
+  "Hunting for rogue gravitons inside the server rack...",
+  "Paging memory to disk because we refused to optimize...",
+  "Optimizing the optimizer so it can optimize faster...",
+  "Searching the entire keyboard for the legendary 'Any' key...",
+  "Reticulating multi-dimensional splines...",
+  "Running gradient ascent until we reach enlightenment...",
+  "Pruning decision trees before autumn sets in...",
+  "Desugaring the syntax until it's completely flavorless...",
+  "Checking for starvation in the dining philosophers...",
+  "Negotiating a peace treaty between competing threads..."
+]);
+
+/** Uniformly pick a quip; `exclude` (the previous episode's quip) is never returned — if the first draw lands on it, exactly one re-roll restricted to entries ≠ `exclude` (no loops). `rand` is injectable for deterministic tests. */
+/** In-episode quip rotation bounds — the quip is re-picked on a random window drawn inclusive between these seconds (from the editor's injected random source), only while a busy episode continues; a new episode always re-picks and resets the window. */
+export const QUIP_ROTATION_MIN_SECS = 15;
+export const QUIP_ROTATION_MAX_SECS = 45;
+
+export function pickQuip(exclude?: string, rand: () => number = Math.random): string {
+  const pick = (customPool: readonly string[]): string =>
+    customPool[Math.floor(rand() * customPool.length)]!;
+  const first = pick(SPIN_QUIPS);
+  if (exclude === undefined || first !== exclude) return first;
+  return pick(SPIN_QUIPS.filter((q) => q !== exclude));
+}

package/src/settings-io.test.ts

@@ -17,7 +17,7 @@ vi.mock("@earendil-works/pi-coding-agent", () => ({
 }));
 
 // Import after mocks are set up
-const { loadConfig, saveConfig, removeConfig, isConfigEnabled, setConfigEnabled } = await import("./settings-io.js");
+const { loadConfig, saveConfig, removeConfig, isConfigEnabled, setConfigEnabled, updateConfig } = await import("./settings-io.js");
 
 describe("removeConfig", () => {
   beforeEach(() => {
@@ -242,3 +242,114 @@ describe("saveConfig", () => {
     expect(fs.existsSync(settingsPath + ".tmp")).toBe(false);
   });
 });
+
+describe("updateConfig", () => {
+  const settingsPath = () => join(tempDir, "settings.json");
+
+  beforeEach(() => {
+    const p = settingsPath();
+    if (fs.existsSync(p)) fs.unlinkSync(p);
+  });
+
+  afterEach(() => {
+    const p = settingsPath();
+    const tmpP = p + ".tmp";
+    try { fs.unlinkSync(p); } catch { /* ignore */ }
+    try { fs.unlinkSync(tmpP); } catch { /* ignore */ }
+  });
+
+  it("applies mutation onto defaults when settings.json does not exist", () => {
+    const result = updateConfig(
+      "test.ns",
+      { done: false, count: 0 },
+      (cfg) => ({ ...cfg, done: true }),
+    );
+    expect(result).toEqual({ done: true, count: 0 });
+    const data = JSON.parse(fs.readFileSync(settingsPath(), "utf-8"));
+    expect(data["test.ns"]).toEqual({ done: true, count: 0 });
+  });
+
+  it("preserves sibling namespaces AND other keys of the target namespace", () => {
+    fs.writeFileSync(
+      settingsPath(),
+      JSON.stringify({
+        "test.ns": { done: false, extra: 99 },
+        "other.ns": { sibling: "value" },
+      }),
+      "utf-8",
+    );
+    const result = updateConfig(
+      "test.ns",
+      { done: false, extra: 0 },
+      (cfg) => ({ ...cfg, done: true }),
+    );
+    expect(result).toEqual({ done: true, extra: 99 });
+    const data = JSON.parse(fs.readFileSync(settingsPath(), "utf-8"));
+    expect(data["test.ns"]).toEqual({ done: true, extra: 99 });
+    expect(data["other.ns"]).toEqual({ sibling: "value" });
+  });
+
+  it("concurrent-change detection: detects a mid-mutation external write and retries; final file contains both the external key and the mutated value", () => {
+    fs.writeFileSync(
+      settingsPath(),
+      JSON.stringify({ "test.ns": { done: false } }),
+      "utf-8",
+    );
+
+    let mutateCallCount = 0;
+    const result = updateConfig(
+      "test.ns",
+      { done: false },
+      (cfg) => {
+        mutateCallCount += 1;
+        // On the first call, simulate a concurrent process writing an external key
+        // between the `before` read and the `after` read. This change must be
+        // detected by the optimistic re-read check, triggering a retry.
+        if (mutateCallCount === 1) {
+          const raw = JSON.parse(fs.readFileSync(settingsPath(), "utf-8"));
+          raw["concurrent.ns"] = { injected: true };
+          fs.writeFileSync(settingsPath(), JSON.stringify(raw), "utf-8");
+        }
+        return { ...cfg, done: true };
+      },
+    );
+
+    expect(mutateCallCount).toBeGreaterThan(1);
+    expect(result).toEqual({ done: true });
+    const data = JSON.parse(fs.readFileSync(settingsPath(), "utf-8"));
+    // Retry recomputed from fresh state — both the external key AND the mutated value survive
+    expect(data["test.ns"]).toEqual({ done: true });
+    expect(data["concurrent.ns"]).toEqual({ injected: true });
+  });
+
+  it("persistent concurrent writer: after maxAttempts the update still completes (last-writer-wins, no crash)", () => {
+    fs.writeFileSync(
+      settingsPath(),
+      JSON.stringify({ "test.ns": { done: false } }),
+      "utf-8",
+    );
+
+    let mutateCallCount = 0;
+    // mutate always writes the external key — simulates a persistent concurrent writer
+    const result = updateConfig(
+      "test.ns",
+      { done: false },
+      (cfg) => {
+        mutateCallCount += 1;
+        // Always write a concurrent change to force re-read on every attempt
+        const raw = JSON.parse(fs.readFileSync(settingsPath(), "utf-8"));
+        raw["concurrent.ns"] = { injected: mutateCallCount };
+        fs.writeFileSync(settingsPath(), JSON.stringify(raw), "utf-8");
+        return { ...cfg, done: true };
+      },
+      3, // maxAttempts
+    );
+
+    // Must complete (not loop forever or throw)
+    expect(mutateCallCount).toBe(3); // saturated at maxAttempts
+    expect(result).toEqual({ done: true }); // flag value persisted
+    const data = JSON.parse(fs.readFileSync(settingsPath(), "utf-8"));
+    expect(data["test.ns"]).toEqual({ done: true }); // flag survived
+    expect(data["concurrent.ns"]).toBeDefined(); // siblings survived
+  });
+});

package/src/settings-io.ts

@@ -4,16 +4,35 @@ import { getAgentDir } from "@earendil-works/pi-coding-agent";
 
 const SETTINGS_PATH = join(getAgentDir(), "settings.json");
 
-/** Read the full settings.json, returning empty object if missing/corrupt. */
-function readSettings(): Record<string, unknown> {
-  if (!existsSync(SETTINGS_PATH)) return {};
+/**
+ * Read settings.json as a raw string. Returns null when the file is absent or
+ * unreadable (EISDIR, EACCES, etc.) — callers treat null the same as an empty
+ * file (i.e. no prior settings).
+ */
+function readRawSettings(): string | null {
+  if (!existsSync(SETTINGS_PATH)) return null;
   try {
-    return JSON.parse(readFileSync(SETTINGS_PATH, "utf-8"));
+    return readFileSync(SETTINGS_PATH, "utf-8");
+  } catch {
+    return null;
+  }
+}
+
+/** Parse a raw settings string, returning empty object on null/corrupt input. */
+function parseSettings(raw: string | null): Record<string, unknown> {
+  if (raw === null) return {};
+  try {
+    return JSON.parse(raw) as Record<string, unknown>;
   } catch {
     return {};
   }
 }
 
+/** Read the full settings.json, returning empty object if missing/corrupt. */
+function readSettings(): Record<string, unknown> {
+  return parseSettings(readRawSettings());
+}
+
 /**
  * Load a config section from settings.json, merged with defaults.
  */
@@ -97,3 +116,47 @@ export function setConfigEnabled(namespace: string, enabled: boolean): void {
     saveConfig(namespace, cfg);
   }
 }
+
+/**
+ * Concurrency-safe read-modify-write for one settings namespace.
+ *
+ * Uses an optimistic re-read check: the settings file is read before and after
+ * the `mutate` callback runs. If the file changed during that window (indicating
+ * a concurrent writer, e.g. another TUI session running /plugins toggle), the
+ * attempt is discarded and the loop restarts from a fresh read — up to
+ * `maxAttempts` times.
+ *
+ * Sibling namespaces always benefit from `saveConfig`’s own fresh read inside
+ * the atomic write, so they are never clobbered regardless of retries.
+ *
+ * The residual window between the final `after` check and `saveConfig`’s
+ * internal read is last-writer-wins; the optimistic check handles all
+ * detectable races (changes that happen during the `mutate` call itself).
+ *
+ * When the maximum attempt count is reached without a clean window (persistent
+ * concurrent writer), the last computed value is still written — no crash, no
+ * unbounded loop.
+ */
+export function updateConfig<T extends object>(
+  namespace: string,
+  defaults: T,
+  mutate: (cfg: T) => T,
+  maxAttempts = 3,
+): T {
+  let last = { ...defaults } as T;
+  for (let attempt = 1; ; attempt++) {
+    const before = readRawSettings();
+    const parsed = parseSettings(before);
+    const current = { ...defaults, ...(parsed[namespace] ?? {}) } as T;
+    const next = mutate(current);
+    const after = readRawSettings();
+    if (before !== after && attempt < maxAttempts) {
+      // Settings file changed during our update window (concurrent writer) —
+      // recompute from the fresh state on the next iteration.
+      continue;
+    }
+    last = next;
+    saveConfig(namespace, next);
+    return last;
+  }
+}