Skip to content

an open-source alternative to the dots, bots and muses of the world, run an office of claude code/codex like agents on your laptop, sandboxes or anywhere, uses your existing subscriptions

docs(config): trim the developer notes to house style

HundredBillionfee76db06f33
diff --git a/src/main/config.ts b/src/main/config.ts
index 6cd130f6..9c080b7f 100644
--- a/src/main/config.ts
+++ b/src/main/config.ts
@@ -621,19 +621,11 @@ function normalizeStoredHomes(cfg: HarnessConfig): HarnessConfig {
return cfg;
}
-/** Every persisted config write is announced here.
+/** Announces every saved setting, so a screen showing one can update.
*
- * The renderer holds the config as a snapshot loaded once at start-up, so
- * before this existed a write reached disk but nothing told the UI, and any
- * view seeded from that snapshot kept showing the pre-write value until the
- * app restarted. Settings was the visible casualty: a toggle wrote correctly,
- * then re-read the stale snapshot on reopen and displayed the old state (#263).
- *
- * This sits on `persistConfig` rather than on `writeConfig` deliberately —
- * `writeConfig` is one of 23 callers across the main process, and Slack,
- * freeflow and notifications each persist through their own path. The file
- * write is the only point every one of them has in common, so subscribing here
- * is the difference between "the fields we remembered" and "all of them". */
+ * Settings, Slack, voice and notifications each save by their own route, and
+ * all of them end up writing the file below — so one subscription here covers
+ * every setting rather than the ones anybody remembered to wire up. */
type ConfigWriteListener = (next: HarnessConfig) => void;
const configWriteListeners = new Set<ConfigWriteListener>();
@@ -646,19 +638,15 @@ function persistConfig(next: HarnessConfig): HarnessConfig {
const p = configPath();
mkdirSync(dirname(p), { recursive: true });
writeFileSync(p, JSON.stringify(next, null, 2), 'utf8');
- // Subscribers get the config in the same shape `readConfig` hands out, NOT the
- // object we just wrote. They are the second source feeding a renderer that also
- // calls config:get, and a patch touching one nested key persists a half-filled
- // sub-object — `withTriggerDefaults` is what deep-fills it on the way out, so
- // skipping it here would let a consumer read `undefined` from a trigger it had
- // read a number from a moment earlier. The migration is deliberately not run:
- // it persists, and it has already been applied to the config this patch built on.
+ // Saving one setting stores only that setting, so fill the rest back in first:
+ // subscribers must see the same complete config a read gives them, never a
+ // half-filled one. Skip the migration — it saves in its own right, and has
+ // already run against what this change was built on.
const view = normalizeStoredHomes(withTriggerDefaults({ ...DEFAULTS, ...next }));
- // A listener is a renderer send, which can fail while a window is closing.
- // The config is already on disk by this point, so a throwing subscriber must
- // neither fail the write for its caller nor starve the subscribers after it.
+ // The change is already saved, so one failed subscriber must not fail the save
+ // for its caller, nor stop the subscribers after it.
for (const listener of configWriteListeners) {
- try { listener(view); } catch { /* a broken listener is not a failed write */ }
+ try { listener(view); } catch { /* a broken listener is not a failed save */ }
}
return next;
}
@@ -728,8 +716,7 @@ export function setAgentTokenCap(agentId: unknown, tokenCap: unknown): HarnessCo
/** Wipe the persisted config back to first-run defaults so the app boots into
* onboarding again. Used by the "reset & start over" flow. */
export function resetConfig(): HarnessConfig {
- // Routed through persistConfig so the reset announces itself like any other
- // write; the bytes written are the same DEFAULTS as before.
+ // Saved like any other change, so a reset announces itself too.
persistConfig({ ...DEFAULTS });
// Drop the migration latch too: the file on disk is back to `triggersMigratedV1:
// false`, and a latch left set would keep the flag from ever being written again
diff --git a/src/main/index.ts b/src/main/index.ts
index 50e865a6..5f1bfde2 100644
--- a/src/main/index.ts
+++ b/src/main/index.ts
@@ -5161,11 +5161,8 @@ app.on('before-quit', (e) => {
}
});
-// Keep the renderer's copy of the config current. The renderer loads the config
-// once at start-up and hands it down as a prop, so without this a write reached
-// disk while every view seeded from that prop kept rendering the pre-write value
-// until the next launch (#263). Subscribing to the write itself covers Slack,
-// freeflow, notifications and the rest, each of which persists by its own route.
+// The window loads the config once at start-up, so tell it when a setting is
+// saved — otherwise it keeps showing the values it started with.
onConfigWritten((next) => {
if (!mainWindow || mainWindow.isDestroyed()) return;
mainWindow.webContents.send('config:changed', next);
diff --git a/src/preload/index.ts b/src/preload/index.ts
index 2f818185..c9ca777c 100644
--- a/src/preload/index.ts
+++ b/src/preload/index.ts
@@ -931,8 +931,7 @@ const api = {
ipcRenderer.invoke('hire:openFile'),
// ─── Config changes ──────────────────────────────────────────────────────
- /** Fired after every persisted config write, with the config as written, so a
- * renderer holding it as state never drifts from what is on disk. */
+ /** Fired whenever a setting is saved, with the full updated config. */
onConfigChanged: (cb: (config: HarnessConfig) => void): (() => void) => {
const listener = (_e: IpcRendererEvent, config: HarnessConfig) => cb(config);
ipcRenderer.on('config:changed', listener);
diff --git a/src/renderer/src/App.tsx b/src/renderer/src/App.tsx
index 92084435..ca6267d4 100644
--- a/src/renderer/src/App.tsx
+++ b/src/renderer/src/App.tsx
@@ -125,9 +125,8 @@ export function App() {
// (solo-hold threshold, aborts on any other key). See freeflow/holdOption.ts.
useHoldOptionToTalk();
- // The config is loaded once above and handed down as a prop, so anything that
- // writes it — Settings, Slack, freeflow, onboarding — has to be able to tell us,
- // or those views keep rendering the value from start-up (#263).
+ // Config subscription — the copy loaded above would otherwise go stale the
+ // moment anything saves a setting.
useEffect(() => window.cth.onConfigChanged(setConfig), []);
// Quit warning subscription
diff --git a/test/config-write-notify.test.cjs b/test/config-write-notify.test.cjs
index 6460eedc..cd7c73c1 100644
--- a/test/config-write-notify.test.cjs
+++ b/test/config-write-notify.test.cjs
@@ -23,10 +23,8 @@ const { writeConfig, readConfig, onConfigWritten, setAgentTokenCap, resetConfig
test.after(() => fs.rmSync(userData, { recursive: true, force: true }));
-// The app has a config on disk and reads it during start-up, which is what runs
-// the one-shot trigger migration. Reproduce both here before any test subscribes,
-// so these compare a write against a settled config rather than racing the
-// migration — on a bare directory readConfig short-circuits and never runs it.
+// A real app has a config on disk and reads it at start-up, which settles the
+// one-shot migration. Do the same first, so no test below races it.
writeConfig({});
readConfig();
@@ -37,19 +35,16 @@ test('a config write notifies subscribers with the persisted config', () => {
writeConfig({ orchestratorMaySpawn: true });
- // A single logical write can persist more than once — reading the config runs
- // any pending migration, which persists in its own right. The contract is what
- // subscribers end up holding, not that exactly one notification arrives.
+ // What subscribers end up holding is the contract; one save can legitimately
+ // write more than once, so the number of notifications is not.
assert.ok(seen.length >= 1);
assert.deepEqual(seen[seen.length - 1], readConfig());
assert.equal(seen[seen.length - 1].orchestratorMaySpawn, true);
off();
});
-// Not every field is written through writeConfig — agent token caps, and the
-// reset flow below, each persist by their own route. Subscribing at the file
-// write is what makes them all announce; these two tests are what stop a future
-// refactor from quietly moving the hook back up into writeConfig.
+// Token caps and the reset below each save by their own route. These two keep
+// the announcement where every route passes through it.
test('a token-cap write notifies too, not just writeConfig', () => {
const seen = [];
const off = onConfigWritten((next) => seen.push(next));
@@ -68,9 +63,8 @@ test('resetting the config notifies as well', () => {
resetConfig();
- // Listeners receive the config as PERSISTED. resetConfig hands its caller a
- // trigger-enriched view of the same defaults, so the two differ by design and
- // this asserts the reset reached subscribers rather than equality with it.
+ // A reset hands its caller a slightly fuller view than it stores, so check the
+ // reset reached subscribers rather than comparing the two.
assert.ok(seen.length >= 1);
assert.equal(seen[seen.length - 1].onboardingComplete, false);
off();
@@ -103,11 +97,9 @@ test('a listener that throws neither fails the write nor starves the next listen
offBad(); offGood();
});
-// The renderer keeps one `config` in state fed from two sources: config:get and
-// this notification. If they disagree in shape, a consumer reads a deep-filled
-// object one moment and a half-filled one the next. A patch that touches part of
-// a trigger is where that bites, because the merge on the way in is one level
-// deep (see withTriggerDefaults).
+// The window fills one copy of the config from both a read and this
+// announcement, so a screen must never get a fuller answer from one than the
+// other. Saving part of a setting is where that would show.
test('subscribers receive the same shape a config read returns', () => {
const seen = [];
const off = onConfigWritten((next) => seen.push(next));