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

fix(onboarding): expand `~` in the hive home so first-run setup can finish (#140)

Chaitanya Giri5b698c69e03b
diff --git a/src/main/config.ts b/src/main/config.ts
index f2d5292b..80ad5e8a 100644
--- a/src/main/config.ts
+++ b/src/main/config.ts
@@ -10,7 +10,7 @@ import {
type AgentProvider
} from '../shared/agentProvider';
import { defaultMcpDefaults } from '../shared/mcpCatalog';
-import { expandTilde } from './fs';
+import { expandTilde, normalizeHiveHome } from './fs';
import type { IntegrationRecord } from '../shared/integrations';
import {
DEFAULT_CONTEXT_TRIGGER,
@@ -600,12 +600,20 @@ export function writeConfig(patch: Partial<HarnessConfig>): HarnessConfig {
.map((r) => expandTilde(r))
.filter((r) => r && !seen.has(r) && (seen.add(r), true));
}
- // Track recently-opened hive homes so the launch picker can list them. Any write
- // that SETS harnessHome (onboarding finish, changeHome) promotes it to the front,
- // deduped and capped. Skips empty/null so a clear doesn't pollute the list.
+ // The HIVE HOME needs the exact same treatment as registeredRepos above, and for
+ // years it did not get it (#140). Onboarding SUGGESTS `~/HarnessAgents` and the
+ // field is free text, so the common path — accept the default, press Finish —
+ // persisted a literal `~`. The first thing the finish step does is create the
+ // directory, and Node's mkdir has no idea what `~` means: it tried to make a
+ // folder actually named "~", which fails as
+ // ENOENT: no such file or directory, mkdir '~/HarnessAgents'
+ // and left the wizard wedged on its last step with no way forward. Expand BEFORE
+ // the value is persisted or copied into recentHives, so every downstream reader
+ // (mkdir, the hive root, the launch picker) sees one absolute path.
if (typeof patch.harnessHome === 'string' && patch.harnessHome) {
- const prior = current.recentHives ?? [];
- next.recentHives = [patch.harnessHome, ...prior.filter((h) => h !== patch.harnessHome)].slice(0, 8);
+ const { home, recentHives } = normalizeHiveHome(patch.harnessHome, current.recentHives ?? []);
+ next.harnessHome = home;
+ next.recentHives = recentHives;
}
return persistConfig(next);
}
diff --git a/src/main/fs.ts b/src/main/fs.ts
index a868cd01..8dd53cf7 100644
--- a/src/main/fs.ts
+++ b/src/main/fs.ts
@@ -112,6 +112,39 @@ export function expandTilde(p: string): string {
return resolve(out);
}
+/**
+ * Normalize the hive home and its recent-list in one place (#140).
+ *
+ * Onboarding SUGGESTS `~/HarnessAgents` in a free-text field, so the single most
+ * common setup path — accept the default, press Finish — used to persist a literal
+ * `~`. Finish immediately creates that directory, and Node's mkdir has no concept
+ * of `~`: it tried to create a folder literally named "~" and died with
+ * `ENOENT: no such file or directory, mkdir '~/HarnessAgents'`, wedging the wizard
+ * on its last step. Expanding at the config-write boundary means every downstream
+ * reader — mkdir, the hive root, the launch picker — sees one absolute path.
+ *
+ * `prior` is normalized too: entries written before this existed would otherwise
+ * let the launch picker hand a stale `~/…` string straight back and reintroduce
+ * the same failure. Deduped against the new home, newest first, capped.
+ */
+export function normalizeHiveHome(
+ home: string,
+ prior: readonly string[] = [],
+ cap = 8
+): { home: string; recentHives: string[] } {
+ const abs = expandTilde(home);
+ const seen = new Set<string>([abs]);
+ const recentHives = [abs];
+ for (const h of prior) {
+ if (typeof h !== 'string' || !h.trim()) continue;
+ const e = expandTilde(h);
+ if (seen.has(e)) continue;
+ seen.add(e);
+ recentHives.push(e);
+ }
+ return { home: abs, recentHives: recentHives.slice(0, cap) };
+}
+
/** Existence/metadata check for an ABSOLUTE path (v0.3.4 — backs the terminal
* ⌘-click markdown flow). `~/` is expanded here (the renderer doesn't know
* the home dir). Read-only metadata: returns whether a regular file exists and
diff --git a/src/preload/index.ts b/src/preload/index.ts
index ca355ebf..9a70d036 100644
--- a/src/preload/index.ts
+++ b/src/preload/index.ts
@@ -621,7 +621,16 @@ const api = {
ipcRenderer.invoke('app:readClipboard'),
/** Clipboard text, read SYNCHRONOUSLY. Only for the terminal's paste shortcut,
* where an async read loses a race against dictation tools that restore the
- * previous clipboard right after sending the paste key. */
+ * previous clipboard right after sending the paste key.
+ *
+ * TRADEOFF, stated plainly because sendSync blocks the renderer until main
+ * answers: this app has a history of main-thread stalls (iCloud-evicted files
+ * wedging a spawnSync git call), and during such a stall this call freezes the
+ * paste keystroke rather than merely delaying it. Accepted because a clipboard
+ * read is a memory lookup with no I/O, and because the async alternative is
+ * measurably WRONG — it pastes the user's previous clipboard. Do not reach for
+ * sendSync elsewhere on this reasoning; it is justified by the race, not by
+ * convenience. */
readClipboardSync: (): string => {
try { return ipcRenderer.sendSync('app:readClipboardSync') ?? ''; } catch { return ''; }
},
diff --git a/src/renderer/src/hooks/useHive.ts b/src/renderer/src/hooks/useHive.ts
index 752a8142..bb036bb4 100644
--- a/src/renderer/src/hooks/useHive.ts
+++ b/src/renderer/src/hooks/useHive.ts
@@ -264,8 +264,15 @@ export function useHive(config: HarnessConfig | null): void {
// never drains, so the "newest" id was frozen on it: Michael was nudged once per
// app launch and then never again, however much real mail piled up behind it.
// Tracking the ids we have seen has no such ordering assumption, and it keeps
- // the property the high-water mark was there for — a set that only shrinks as
- // messages drain contains nothing new, so it does not re-nudge.
+ // the property the high-water mark was there for: draining removes ids from the
+ // INBOX without adding anything new, so a drain still produces no nudge.
+ //
+ // Note what this set does NOT do: it never shrinks. Ids accumulate for the life
+ // of the window (a restart clears it), because forgetting an id we have already
+ // nudged for would re-nudge the moment that message reappeared in a listing. The
+ // cost is a few tens of bytes per message, which for a 24/7 floor is real but
+ // negligible next to a stalled agent. Evicting ids that have left the inbox would
+ // bound it exactly; deliberately not done here to keep this fix minimal.
const nudged = useRef<Record<string, Set<string>>>({});
// Per-agent context size at the last auto-/compact queued. See the latch note
// in the context-trigger effect: an idle agent's token count is frozen, so
diff --git a/src/renderer/src/scene/office/OfficeFloor.tsx b/src/renderer/src/scene/office/OfficeFloor.tsx
index 1a883dca..075a02a7 100644
--- a/src/renderer/src/scene/office/OfficeFloor.tsx
+++ b/src/renderer/src/scene/office/OfficeFloor.tsx
@@ -178,9 +178,20 @@ export function OfficeFloor() {
//
// Stop the ticker instead of unmounting: the WebGL context, textures and the
// whole scene graph stay alive, so coming back out of fullscreen is instant
- // rather than a full theme reload. Nothing in the scene reads wall-clock time —
- // every update is driven by the ticker's own delta — so a paused floor simply
- // resumes where it left off.
+ // rather than a full theme reload.
+ //
+ // A paused floor resumes where it left off. Two things make that true, and it is
+ // worth being precise because the obvious claim — "nothing here reads wall-clock
+ // time" — is FALSE: Date.now() is read for the aura/coffee timers and for the
+ // busy/cheer thresholds. The first sits inside onTick, so a stopped ticker freezes
+ // it along with everything else. The second runs in applyState, a store
+ // subscription that keeps firing while paused — but it only mutates sprite state
+ // that is redrawn on resume, so the worst case is a cosmetic cheer reflecting
+ // genuinely-elapsed busy time, invisible while hidden anyway.
+ //
+ // The frame delta is safe by construction: Pixi clamps elapsedMS to minFPS on
+ // start(), so a floor paused for an hour advances a few frames on resume rather
+ // than teleporting every character across the map.
const fullscreenAgentId = useStore((s) => s.fullscreenAgentId);
const fullscreenFilePath = useStore((s) => s.fullscreenFilePath);
const [docHidden, setDocHidden] = useState(() => document.hidden);
diff --git a/test/expand-tilde.test.cjs b/test/expand-tilde.test.cjs
index 75194c74..3361a506 100644
--- a/test/expand-tilde.test.cjs
+++ b/test/expand-tilde.test.cjs
@@ -49,3 +49,46 @@ test('the expanded path is what fs can actually stat — the original bug', () =
assert.equal(path.isAbsolute(expanded), true);
assert.equal(fs.existsSync(expanded), true);
});
+
+/* ------------------------------------------------------------------ *
+ * #140 — the hive home was the one path that never got expanded.
+ * Onboarding suggests `~/HarnessAgents`; accepting that default persisted a
+ * literal `~`, and Finish then died on `mkdir '~/HarnessAgents'` (ENOENT),
+ * wedging the wizard on its last step with the UI pushed off-screen.
+ * ------------------------------------------------------------------ */
+
+const { normalizeHiveHome } = loadTs('src/main/fs.ts');
+
+test('#140: the suggested default is expanded, not persisted literally', () => {
+ const { home } = normalizeHiveHome('~/HarnessAgents');
+ assert.equal(home, path.join(HOME, 'HarnessAgents'));
+ assert.ok(!home.includes('~'), 'a literal ~ is what mkdir choked on');
+ assert.ok(path.isAbsolute(home), 'every downstream reader needs an absolute path');
+});
+
+test('#140: the new home leads the recent list exactly once', () => {
+ const { recentHives } = normalizeHiveHome('~/HarnessAgents', ['/other/hive']);
+ assert.deepEqual(recentHives, [path.join(HOME, 'HarnessAgents'), '/other/hive']);
+});
+
+test('#140: stale `~` entries already on disk are normalized too', () => {
+ // Without this the launch picker could hand a pre-fix `~/…` string straight
+ // back and reintroduce the identical mkdir failure.
+ const { recentHives } = normalizeHiveHome('/now/here', ['~/HarnessAgents']);
+ assert.deepEqual(recentHives, ['/now/here', path.join(HOME, 'HarnessAgents')]);
+});
+
+test('#140: the same home written twice does not duplicate', () => {
+ const { recentHives } = normalizeHiveHome('~/HarnessAgents', [
+ path.join(HOME, 'HarnessAgents'), // same place, already absolute
+ '~/HarnessAgents' // and again, unexpanded
+ ]);
+ assert.deepEqual(recentHives, [path.join(HOME, 'HarnessAgents')]);
+});
+
+test('#140: the recent list stays capped and skips blanks', () => {
+ const prior = Array.from({ length: 20 }, (_, i) => `/hive/${i}`);
+ const { recentHives } = normalizeHiveHome('/hive/new', ['', ' ', ...prior]);
+ assert.equal(recentHives.length, 8);
+ assert.equal(recentHives[0], '/hive/new');
+});