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

feat(main): power keep-alive hardening — catch up missed schedules on wake

Chaitanya Giridd9ea5fc51ae
diff --git a/scripts/verify-keepalive-catchup.mjs b/scripts/verify-keepalive-catchup.mjs
new file mode 100644
index 00000000..b126129f
--- /dev/null
+++ b/scripts/verify-keepalive-catchup.mjs
@@ -0,0 +1,94 @@
+// Deterministic acceptance verify for the keep-alive power-hardening fix
+// (card impl-keepalive-hardening). Run: `node scripts/verify-keepalive-catchup.mjs`
+//
+// This repo ships no test runner, and src/main/index.ts cannot be imported outside
+// Electron (top-level `electron` + native deps). So this script mirrors the EXACT
+// production catch-up logic — the `remaining = Math.max(0, intervalMs - (now -
+// lastFiredAt))` arming line plus the setTimeout -> setInterval settle from
+// syncMissions(), and the "re-arm on wake" of onSystemResume() — under a
+// controllable fake clock, and asserts the guarantees the fix rests on:
+// 1. A mission overdue across sleep fires EXACTLY ONCE on resume (coalesced
+// catch-up — never N replays of every tick missed while asleep).
+// 2. After the catch-up it settles back to its steady interval cadence.
+// 3. A mission NOT yet due does not fire early on resume.
+// 4. Overlapping resume + unlock-screen events collapse to ONE catch-up fire
+// (onSystemResume is idempotent: clear-then-arm).
+
+// ---- fake clock + timer queue (libuv-style monotonic; we control advancement) --
+let nowMs = 1_000_000; // arbitrary "boot" instant
+let nextId = 1;
+const timers = new Map(); // id -> { fireAt, fn, kind, intervalMs }
+const setT = (fn, delay) => { const id = nextId++; timers.set(id, { fireAt: nowMs + delay, fn, kind: 'timeout' }); return id; };
+const setI = (fn, delay) => { const id = nextId++; timers.set(id, { fireAt: nowMs + delay, fn, kind: 'interval', intervalMs: delay }); return id; };
+const clr = (id) => { timers.delete(id); };
+function advance(ms) {
+ const target = nowMs + ms;
+ while (true) {
+ let next = null;
+ for (const [id, t] of timers) if (t.fireAt <= target && (next === null || t.fireAt < timers.get(next).fireAt)) next = id;
+ if (next === null) { nowMs = target; return; }
+ const t = timers.get(next);
+ nowMs = t.fireAt;
+ if (t.kind === 'interval') t.fireAt += t.intervalMs; else timers.delete(next);
+ t.fn();
+ }
+}
+
+// ---- production logic mirror (verbatim shape from src/main/index.ts) -----------
+let fireCount = 0;
+let missionsUpdatedEmits = 0;
+const missionTimers = new Map();
+function clearMissionTimers() {
+ for (const e of missionTimers.values()) { if (e.timeout) clr(e.timeout); if (e.interval) clr(e.interval); }
+ missionTimers.clear();
+}
+function syncMissions(m) {
+ clearMissionTimers();
+ const fire = () => { fireCount++; m.lastFiredAt = nowMs; missionsUpdatedEmits++; /* mirrors liveWebContents().send('missions:updated') */ };
+ const remaining = Math.max(0, m.intervalMs - (nowMs - (m.lastFiredAt ?? 0))); // <- the exact line from index.ts
+ const entry = {};
+ entry.timeout = setT(() => { fire(); entry.interval = setI(fire, m.intervalMs); }, remaining);
+ missionTimers.set(m.id, entry);
+}
+const onSystemResume = (m) => { syncMissions(m); }; // resume's scheduler re-arm (beats/keep-awake are not timer-fire-counted here)
+
+// ---- assertions ----------------------------------------------------------------
+let failures = 0;
+const ok = (cond, msg) => { console.log(`${cond ? 'PASS' : 'FAIL'} ${msg}`); if (!cond) failures++; };
+const reset = () => { fireCount = 0; missionsUpdatedEmits = 0; clearMissionTimers(); };
+
+const HOUR = 60 * 60 * 1000;
+
+// (1)+(2) Overdue across a long sleep -> ONE catch-up fire, then steady cadence.
+reset();
+let m = { id: 'standup', intervalMs: HOUR, lastFiredAt: nowMs - 5 * HOUR }; // slept ~5h past a 1h interval
+onSystemResume(m); // wake: re-arm scheduler
+advance(0); // flush the remaining=0 catch-up timeout
+ok(fireCount === 1, `overdue-by-5h fires exactly ONCE on resume (not 5x) -> fireCount=${fireCount}`);
+ok(missionsUpdatedEmits === 1, `missions:updated emitted on the catch-up fire -> emits=${missionsUpdatedEmits}`);
+advance(HOUR);
+ok(fireCount === 2, `settles to interval: +1 fire after one more hour -> fireCount=${fireCount}`);
+advance(HOUR);
+ok(fireCount === 3, `still steady: +1 fire after the next hour -> fireCount=${fireCount}`);
+
+// (3) Not yet due -> no early fire on resume.
+reset();
+m = { id: 'soon', intervalMs: HOUR, lastFiredAt: nowMs - 10 * 60 * 1000 }; // fired 10m ago
+onSystemResume(m);
+advance(0);
+ok(fireCount === 0, `mission fired 10m ago does NOT fire early on resume -> fireCount=${fireCount}`);
+advance(49 * 60 * 1000);
+ok(fireCount === 0, `still not due at +49m -> fireCount=${fireCount}`);
+advance(2 * 60 * 1000);
+ok(fireCount === 1, `fires once it reaches its due time (~+51m) -> fireCount=${fireCount}`);
+
+// (4) Idempotent: resume + unlock-screen back-to-back -> ONE catch-up fire.
+reset();
+m = { id: 'standup', intervalMs: HOUR, lastFiredAt: nowMs - 3 * HOUR };
+onSystemResume(m); // 'resume'
+onSystemResume(m); // 'unlock-screen' immediately after — must cancel the pending 0-timer, re-arm
+advance(0);
+ok(fireCount === 1, `resume+unlock collapse to ONE catch-up fire (idempotent) -> fireCount=${fireCount}`);
+
+console.log(failures === 0 ? '\nALL CHECKS PASS' : `\n${failures} CHECK(S) FAILED`);
+process.exit(failures === 0 ? 0 : 1);
diff --git a/src/main/config.ts b/src/main/config.ts
index 4d08712a..e3ce7ab2 100644
--- a/src/main/config.ts
+++ b/src/main/config.ts
@@ -169,6 +169,13 @@ export interface HarnessConfig {
knowledgeGraph?: KnowledgeGraphConfig;
/** Fire native desktop notifications on agent lifecycle events (idle finish / waiting for input). */
notifications?: boolean;
+ /** Opt-in "strong keep-alive": while ≥1 agent PTY is live, escalate the power
+ * blocker from 'prevent-app-suspension' to 'prevent-display-sleep', which on
+ * macOS also blocks TRUE system sleep (lid-close/idle) so scheduled missions
+ * and terminals keep firing ON TIME while away — at a battery cost (best on
+ * AC). Default OFF: the honest default is "survive sleep + catch up once on
+ * resume" (see the powerMonitor 'resume' handler), not "stay awake". */
+ strongKeepalive?: boolean;
/** Multi-window "floors": expose a New Floor action that opens additional
* windows, each an independent office with isolated renderer state (its own
* session partition) and per-window PTY routing. OFF by default (opt-in) —
@@ -253,6 +260,7 @@ const DEFAULTS: HarnessConfig = {
embeddingModel: 'minilm',
missions: [OPS_STANDUP_MISSION],
notifications: false,
+ strongKeepalive: false,
multiWindow: true,
tvShowOffices: false,
officeTheme: 'office',
diff --git a/src/main/index.ts b/src/main/index.ts
index cc01997b..104ff121 100644
--- a/src/main/index.ts
+++ b/src/main/index.ts
@@ -1,4 +1,4 @@
-import { app, BrowserWindow, clipboard, dialog, ipcMain, Menu, powerSaveBlocker, screen, shell, Notification } from 'electron';
+import { app, BrowserWindow, clipboard, dialog, ipcMain, Menu, powerMonitor, powerSaveBlocker, screen, shell, Notification } from 'electron';
import { spawn } from 'node:child_process';
import { rmSync, existsSync, readFileSync, readdirSync, statSync, cpSync, writeFileSync, unlinkSync, mkdirSync, createWriteStream } from 'node:fs';
import { randomBytes, createHash, timingSafeEqual } from 'node:crypto';
@@ -203,16 +203,33 @@ ptyManager.setExitHandler(teardownPty);
* processes!) shortly after the display sleeps/locks — the whole hive froze
* mid-turn until unlock. `prevent-app-suspension` blocks exactly that while
* still letting the display turn off and the session lock. Held only while at
- * least one PTY is alive, so an idle harness doesn't pin a laptop awake. */
+ * least one PTY is alive, so an idle harness doesn't pin a laptop awake.
+ *
+ * Opt-in `config.strongKeepalive` escalates to `prevent-display-sleep`, which on
+ * macOS ALSO blocks true system sleep (lid-close/idle) so timers & PTYs keep
+ * firing on time while away — at a battery cost. The default ('prevent-app-
+ * suspension') still lets the Mac truly sleep; we survive that and catch up once
+ * on resume (see onSystemResume). Re-evaluated on every call so toggling the
+ * flag while agents run swaps the blocker mode live. */
+type KeepAwakeMode = 'prevent-app-suspension' | 'prevent-display-sleep';
let keepAwakeId: number | null = null;
+let keepAwakeMode: KeepAwakeMode | null = null;
function syncKeepAwake(): void {
const live = ptyManager.list().length > 0;
- if (live && keepAwakeId === null) {
- keepAwakeId = powerSaveBlocker.start('prevent-app-suspension');
- console.log('[power] keep-awake ON — agents running');
- } else if (!live && keepAwakeId !== null) {
+ const desired: KeepAwakeMode | null = live
+ ? (readConfig().strongKeepalive ? 'prevent-display-sleep' : 'prevent-app-suspension')
+ : null;
+ if (desired === keepAwakeMode) return; // no change — avoid stop/start churn + log spam
+ // Tear down the current blocker (mode change, or going idle with no agents).
+ if (keepAwakeId !== null) {
try { if (powerSaveBlocker.isStarted(keepAwakeId)) powerSaveBlocker.stop(keepAwakeId); } catch { /* noop */ }
keepAwakeId = null;
+ }
+ keepAwakeMode = desired;
+ if (desired) {
+ keepAwakeId = powerSaveBlocker.start(desired);
+ console.log(`[power] keep-awake ON (${desired}) — agents running`);
+ } else {
console.log('[power] keep-awake off — no agents');
}
}
@@ -2289,9 +2306,15 @@ function bootstrapHiveServices(): void {
memory.start(); // init shared palace + mine loop (no-op without mempalace)
reflector.start(); // bound oversized memory.md files on a timer (no-op until threshold)
- // Always-on beats (decoupled from the optional heartbeat): the live fleet
- // snapshot Michael reads (~8s) + the breaker/cost-ledger beat (~30s). Guarded so
- // a re-bootstrap (changeHome recovery) can't stack duplicate timers.
+ armAlwaysOnBeats();
+}
+
+/** (Re)arm the always-on beats (decoupled from the optional heartbeat): the live
+ * fleet snapshot Michael reads (~8s) + the breaker/cost-ledger beat (~30s).
+ * Guarded (clear-then-set) so a re-bootstrap (changeHome recovery) OR a
+ * powerMonitor resume can't stack duplicate timers — these are setInterval
+ * handles that freeze during true system sleep and must be re-armed on wake. */
+function armAlwaysOnBeats(): void {
if (fleetTimer) clearInterval(fleetTimer);
writeFleetSnapshot();
fleetTimer = setInterval(writeFleetSnapshot, 8_000);
@@ -2299,6 +2322,68 @@ function bootstrapHiveServices(): void {
breakerBeatTimer = setInterval(() => { try { runBreakerBeat(300_000); } catch (e) { console.error('[breaker beat]', e); } }, 30_000);
}
+/** Wall-clock instant we last observed the machine suspend or lock, so a resume
+ * can report how long we were out. Best-effort context for the renderer follow-on
+ * (auto-revive); null until the first suspend/lock of the session. */
+let lastSuspendAt: number | null = null;
+/** Single pending post-resume PTY health check, so overlapping resume+unlock
+ * events collapse to ONE check (the latest) instead of stacking. */
+let resumeHealthTimer: NodeJS.Timeout | null = null;
+
+/** After the machine wakes, probe each live PTY for liveness and surface any that
+ * didn't survive. macOS can wedge a child `claude` process/socket across a long
+ * sleep while node-pty still holds the fd (its exit event never fired) — so a
+ * dead PTY can linger in our list. `process.kill(pid, 0)` is a pure existence
+ * probe (signal 0 never touches the process); ESRCH means the process is gone.
+ * We only LOG + NOTIFY here (no auto-kill/respawn — true revive is renderer-owned
+ * via pty:spawn) and emit `power:resume` as the integration point for the
+ * follow-on renderer auto-revive card. */
+function healthCheckPtys(reason: string, awayMs: number | null): void {
+ const ptys = ptyManager.list();
+ const dead: string[] = [];
+ for (const p of ptys) {
+ if (typeof p.pid === 'number' && p.pid > 0) {
+ try { process.kill(p.pid, 0); } // liveness probe only — never kills
+ catch { dead.push(p.id); } // ESRCH: process gone but PTY still registered
+ }
+ }
+ const away = awayMs != null ? ` (away ~${Math.round(awayMs / 1000)}s)` : '';
+ if (dead.length) {
+ console.warn(`[power] ${reason}${away}: ${dead.length}/${ptys.length} PTY(s) look wedged (process gone):`, dead.join(', '));
+ breakerToast('Agents need a restart', `${dead.length} agent terminal(s) didn't survive sleep — re-open them to resume.`);
+ } else {
+ console.log(`[power] ${reason}${away}: ${ptys.length} PTY(s) healthy`);
+ }
+ // Single integration point for the (separate) renderer auto-revive card: it can
+ // listen for 'power:resume' and respawn the `dead` PTYs with --resume.
+ try { liveWebContents()?.send('power:resume', { reason, awayMs, dead, total: ptys.length }); } catch { /* window gone */ }
+}
+
+/** Re-arm everything that runs on a frozen libuv timer after the machine slept,
+ * and surface any PTY that didn't survive. macOS pauses setTimeout/setInterval
+ * during true system sleep (the monotonic clock halts) — on wake they resume
+ * where they paused, shifted by the whole sleep, so missions due during sleep
+ * never fired and never replay. We rebuild the scheduler (syncMissions reuses its
+ * remaining=max(0,…) semantics → each overdue mission fires exactly ONCE then
+ * re-settles, never N replays), re-arm the always-on beats, re-evaluate the
+ * power blocker, then — after a short grace for PTYs to wake their pipes —
+ * health-check the terminals. Idempotent: overlapping resume+unlock events
+ * collapse safely (clear-then-arm everywhere; at most one catch-up fire). */
+function onSystemResume(reason: string): void {
+ console.log(`[power] ${reason} — re-arming scheduler, beats, keep-awake`);
+ try { syncMissions(); } catch (e) { console.error('[power] syncMissions on resume', e); }
+ try { armAlwaysOnBeats(); } catch (e) { console.error('[power] armAlwaysOnBeats on resume', e); }
+ try { syncKeepAwake(); } catch (e) { console.error('[power] syncKeepAwake on resume', e); }
+ const awayMs = lastSuspendAt != null ? Date.now() - lastSuspendAt : null;
+ // Give PTYs a beat to resume their pipes before judging them wedged; reset any
+ // pending check so a resume quickly followed by unlock runs the probe just once.
+ if (resumeHealthTimer) clearTimeout(resumeHealthTimer);
+ resumeHealthTimer = setTimeout(() => {
+ resumeHealthTimer = null;
+ healthCheckPtys(reason, awayMs);
+ }, 15_000);
+}
+
app.whenReady().then(() => {
// A cold-start deep link (Windows/Linux) rides in on OUR argv.
const startupHireLink = process.argv.find((a) => a.startsWith('munderdifflin://'));
@@ -2315,6 +2400,15 @@ app.whenReady().then(() => {
try { persist.open(); } catch (e) { console.error('[db] open failed:', e); }
// Bootstrap the hive (if harnessHome is configured) and start the message router.
bootstrapHiveServices();
+ // Survive sleep/lock. macOS freezes libuv timers during true system sleep, so a
+ // locked/idle/slept Mac stops firing schedules and can wedge PTYs. On wake we
+ // re-arm the scheduler (catching up missed missions ONCE) + beats + keep-awake,
+ // then health-check terminals. App-lifetime listeners — powerMonitor outlives
+ // every window, so there is nothing to tear down on quit.
+ powerMonitor.on('resume', () => onSystemResume('resume'));
+ powerMonitor.on('unlock-screen', () => onSystemResume('unlock-screen'));
+ powerMonitor.on('suspend', () => { lastSuspendAt = Date.now(); console.log('[power] suspend — system sleeping'); });
+ powerMonitor.on('lock-screen', () => { lastSuspendAt = Date.now(); console.log('[power] lock-screen'); });
// Multi-window floors (opt-in): install the menu carrying "New Floor". When
// off, the app keeps Electron's default menu — zero behavior change.
if (readConfig().multiWindow) installAppMenu();