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
HTML agent-harnessagent-orchestrationagentsai-agentsautonomous-agentsclaude-codecodexcoding-agentsdesktop-appdeveloper-toolselectrongemini-cliharnessharness-engineeringlocal-firstmemorymulti-agentopencodeorchestrationtypescript
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.mjsnew file mode 100644index 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.tsindex 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.tsindex 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();