claude-code-session-manager 0.3.2 → 0.5.0

package/src/main/scheduler.cjs

@@ -0,0 +1,717 @@
+/**
+ * scheduler.cjs — runs queued PRDs as headless `claude -p` jobs around
+ * the next 5h token-window reset.
+ *
+ * Layout (under ~/.claude/session-manager/scheduled-plans/):
+ *   prds/NN-slug.md      → user/Claude-authored PRD files (source of truth)
+ *   queue.json           → scheduler state: schedule, runs, status per PRD
+ *   runs/<ISO>/<slug>.log → captured stdout/stderr for one execution
+ *   runs/<ISO>/<slug>.meta.json → per-job metadata (exit, duration, cwd)
+ *
+ * Time:
+ *   - "Next reset" comes from /api/oauth/usage five_hour.resets_at
+ *     (already exposed via billing.fetchUsage()).
+ *   - Trigger fires at resets_at + offsetMinutes (default 15).
+ *   - We schedule a single setTimeout for the next fire-time. On schedule
+ *     change (queue updated, reset_at moves) we cancel + reschedule.
+ *
+ * Parallelism:
+ *   - PRD filename `NN-slug.md` — `NN` is the parallel group. All PRDs in
+ *     the same group launch simultaneously; the next group only starts
+ *     after the previous group's jobs all settle.
+ *   - User-set concurrency cap (default 5) is the within-group ceiling. If
+ *     a group has more PRDs than the cap, the excess waits until a slot
+ *     frees in that group.
+ *
+ * Execution:
+ *   - `claude -p "<PRD body>" --dangerously-skip-permissions` per PRD.
+ *   - Stdout/stderr → runs/<ts>/<slug>.log; meta json gets exit + duration.
+ *   - PRD frontmatter `cwd` → child cwd. Default: PROJECT_CWD const below.
+ *
+ * Persistence:
+ *   - queue.json is the system of record for scheduling. Edited atomically
+ *     via fs.writeFileSync(tmp) + rename.
+ *   - On startup, walk prds/, ensure every .md has a queue.json entry.
+ *     Orphaned entries (.md gone) are pruned.
+ *
+ * Renderer events:
+ *   - 'schedule:state' broadcasts the full state on any change. Keeps the
+ *     panel UI dead simple — no diff machinery.
+ */
+
+const fs = require('node:fs');
+const fsp = require('node:fs/promises');
+const path = require('node:path');
+const os = require('node:os');
+const { spawn } = require('node:child_process');
+const { ipcMain } = require('electron');
+const billing = require('./usage.cjs');
+
+const ROOT = path.join(os.homedir(), '.claude', 'session-manager', 'scheduled-plans');
+const PRDS_DIR = path.join(ROOT, 'prds');
+const RUNS_DIR = path.join(ROOT, 'runs');
+const QUEUE_PATH = path.join(ROOT, 'queue.json');
+const DEFAULT_PROJECT_CWD = path.join(os.homedir(), 'Projects', 'session-manager');
+
+const DEFAULT_CONFIG = {
+  // Legacy on/off retained for backwards compat; v0.5+ uses firePolicy.
+  enabled: false,
+  offsetMinutes: 15,
+  concurrencyCap: 5,
+  defaultCwd: DEFAULT_PROJECT_CWD,
+  // 'when-available' = poll usage and fire whenever utilization < threshold.
+  // 'on-reset'        = fire offsetMinutes after the next 5h reset (legacy).
+  // 'manual'          = only fire on explicit Run-now click.
+  firePolicy: 'when-available',
+  // For 'when-available'. Fire only when five_hour utilization < this percent.
+  utilizationThreshold: 90,
+  schemaVersion: 1,
+};
+
+// ---------- fs helpers ----------
+
+function ensureDirs() {
+  fs.mkdirSync(PRDS_DIR, { recursive: true });
+  fs.mkdirSync(RUNS_DIR, { recursive: true });
+}
+
+function atomicWriteJson(p, data) {
+  const tmp = `${p}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(data, null, 2));
+  fs.renameSync(tmp, p);
+}
+
+function readQueue() {
+  try {
+    const raw = fs.readFileSync(QUEUE_PATH, 'utf8');
+    const data = JSON.parse(raw);
+    return {
+      config: { ...DEFAULT_CONFIG, ...(data.config || {}) },
+      jobs: Array.isArray(data.jobs) ? data.jobs : [],
+      scheduledFor: data.scheduledFor ?? null,
+      lastRunAt: data.lastRunAt ?? null,
+      paused: data.paused ?? null,
+    };
+  } catch {
+    return { config: { ...DEFAULT_CONFIG }, jobs: [], scheduledFor: null, lastRunAt: null, paused: null };
+  }
+}
+
+function writeQueue(state) {
+  ensureDirs();
+  atomicWriteJson(QUEUE_PATH, state);
+}
+
+// ---------- PRD parsing ----------
+
+/**
+ * Parse YAML-ish frontmatter — only the keys we use. We don't take a
+ * yaml dep; the schema is small (title, cwd, estimateMinutes, parallelGroup)
+ * and the format is documented in the user-facing README.
+ */
+function parsePrd(filePath) {
+  const text = fs.readFileSync(filePath, 'utf8');
+  const meta = { title: null, cwd: null, estimateMinutes: null, parallelGroup: null };
+  let body = text;
+
+  if (text.startsWith('---\n')) {
+    const end = text.indexOf('\n---', 4);
+    if (end !== -1) {
+      const fm = text.slice(4, end);
+      body = text.slice(end + 4).replace(/^\n/, '');
+      for (const line of fm.split('\n')) {
+        const m = line.match(/^([a-zA-Z]+):\s*(.+?)\s*$/);
+        if (!m) continue;
+        const k = m[1];
+        let v = m[2];
+        if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) {
+          v = v.slice(1, -1);
+        }
+        if (k === 'title') meta.title = v;
+        else if (k === 'cwd') meta.cwd = v;
+        else if (k === 'estimateMinutes') meta.estimateMinutes = Number(v) || null;
+        else if (k === 'parallelGroup') meta.parallelGroup = Number(v) || null;
+      }
+    }
+  }
+
+  const base = path.basename(filePath, '.md');
+  const groupFromName = (() => {
+    const m = base.match(/^(\d+)-/);
+    return m ? Number(m[1]) : null;
+  })();
+
+  return {
+    slug: base,
+    path: filePath,
+    title: meta.title || base,
+    cwd: meta.cwd || null,
+    estimateMinutes: meta.estimateMinutes,
+    parallelGroup: meta.parallelGroup ?? groupFromName ?? 99,
+    body: body.trim(),
+  };
+}
+
+function listPrdFiles() {
+  ensureDirs();
+  return fs.readdirSync(PRDS_DIR)
+    .filter((f) => f.endsWith('.md') && !f.startsWith('.'))
+    .map((f) => path.join(PRDS_DIR, f))
+    .sort();
+}
+
+// ---------- queue reconciliation ----------
+
+/**
+ * Walk prds/, ensure every .md has a queue entry. Drop entries whose .md
+ * is gone. Refresh title/cwd/parallelGroup from disk every reconcile so
+ * editing the .md after queueing is honored.
+ *
+ * Status is preserved: pending stays pending, completed stays completed.
+ * Newly-discovered PRDs land as `pending`.
+ */
+function reconcile(state) {
+  const files = listPrdFiles();
+  const onDisk = new Map();
+  for (const f of files) {
+    try {
+      const p = parsePrd(f);
+      onDisk.set(p.slug, p);
+    } catch (e) {
+      console.warn('[scheduler] failed to parse', f, e?.message);
+    }
+  }
+
+  const next = [];
+  const seen = new Set();
+  for (const job of state.jobs) {
+    const p = onDisk.get(job.slug);
+    if (!p) continue;
+    seen.add(job.slug);
+    next.push({
+      ...job,
+      title: p.title,
+      cwd: p.cwd,
+      parallelGroup: p.parallelGroup,
+      estimateMinutes: p.estimateMinutes,
+      bodyPreview: p.body.split('\n').slice(0, 6).join('\n'),
+    });
+  }
+  for (const [slug, p] of onDisk) {
+    if (seen.has(slug)) continue;
+    next.push({
+      slug,
+      title: p.title,
+      cwd: p.cwd,
+      parallelGroup: p.parallelGroup,
+      estimateMinutes: p.estimateMinutes,
+      bodyPreview: p.body.split('\n').slice(0, 6).join('\n'),
+      status: 'pending',
+      runId: null,
+      startedAt: null,
+      finishedAt: null,
+      exitCode: null,
+      error: null,
+    });
+  }
+  state.jobs = next.sort((a, b) => a.slug.localeCompare(b.slug));
+  return state;
+}
+
+// ---------- next-reset detection ----------
+
+let cachedNextReset = { at: null, fetchedAt: 0 };
+let cachedUtilization = null; // five_hour utilization %, 0–100, or null if unknown
+
+async function refreshNextReset() {
+  try {
+    const r = await billing.fetchUsage();
+    const at = r?.usage?.five_hour?.resets_at ?? null;
+    cachedNextReset = { at, fetchedAt: Date.now() };
+    cachedUtilization = r?.usage?.five_hour?.utilization ?? cachedUtilization;
+    return at;
+  } catch {
+    return cachedNextReset.at;
+  }
+}
+
+function getNextResetCached() {
+  return cachedNextReset.at;
+}
+
+// ---------- timer ----------
+
+let mainWindow = null;
+let fireTimer = null;
+let resumeTimer = null;
+let pollTimer = null;
+let isExecuting = false;
+let cancelToken = { cancelled: false };
+let claudeBinPathCached = null;
+
+function attachWindow(w) { mainWindow = w; }
+
+function broadcast() {
+  if (!mainWindow || mainWindow.isDestroyed()) return;
+  const state = readQueue();
+  reconcile(state);
+  writeQueue(state);
+  mainWindow.webContents.send('schedule:state', {
+    config: state.config,
+    jobs: state.jobs,
+    scheduledFor: state.scheduledFor,
+    lastRunAt: state.lastRunAt,
+    nextReset: getNextResetCached(),
+    paused: state.paused,
+    utilization: cachedUtilization,
+  });
+}
+
+function clearFireTimer() {
+  if (fireTimer) {
+    clearTimeout(fireTimer);
+    fireTimer = null;
+  }
+}
+
+function computeFireAt(state, nextResetIso) {
+  // Only the legacy 'on-reset' policy uses scheduled fire times. Other
+  // policies fire either immediately on demand ('manual') or via the
+  // when-available poll loop.
+  if (state.config.firePolicy !== 'on-reset') return null;
+  if (!nextResetIso) return null;
+  const reset = new Date(nextResetIso).getTime();
+  if (Number.isNaN(reset)) return null;
+  return reset + (state.config.offsetMinutes * 60_000);
+}
+
+async function rescheduleTimer() {
+  clearFireTimer();
+  const state = readQueue();
+  reconcile(state);
+  const nextResetIso = await refreshNextReset();
+  const fireAt = computeFireAt(state, nextResetIso);
+  if (!fireAt) {
+    state.scheduledFor = null;
+    writeQueue(state);
+    broadcast();
+    return;
+  }
+
+  state.scheduledFor = new Date(fireAt).toISOString();
+  writeQueue(state);
+  broadcast();
+
+  const delay = Math.max(1000, fireAt - Date.now());
+  // setTimeout caps at int32 ms (~24.8 days) — well above our 5h horizon, so
+  // a single timer is fine. If reset_at is wildly in the future we'd still
+  // re-anchor on the next billing refresh.
+  fireTimer = setTimeout(() => { runDueJobs().catch(() => {}); }, delay);
+  console.log(`[scheduler] next fire in ${Math.round(delay / 1000)}s @ ${state.scheduledFor}`);
+}
+
+// ---------- pause / resume ----------
+
+function setPaused(reason, resumeAtIso) {
+  const s = readQueue();
+  if (s.paused && s.paused.reason === reason) {
+    // already paused for this reason; just refresh resumeAt if newer
+    if (resumeAtIso) s.paused.resumeAt = resumeAtIso;
+  } else {
+    s.paused = { reason, since: new Date().toISOString(), resumeAt: resumeAtIso || null };
+  }
+  writeQueue(s);
+  broadcast();
+  cancelToken.cancelled = true;
+  if (resumeTimer) { clearTimeout(resumeTimer); resumeTimer = null; }
+  if (resumeAtIso) {
+    // Resume 30s after the reset to give the auth/billing endpoint time to flip.
+    const delay = Math.max(30_000, new Date(resumeAtIso).getTime() - Date.now() + 30_000);
+    if (delay <= 0x7fffffff) {
+      resumeTimer = setTimeout(() => {
+        clearPause('resume-timer');
+        runDueJobs().catch(() => {});
+      }, delay);
+      console.log(`[scheduler] paused (${reason}); auto-resume in ${Math.round(delay/1000)}s`);
+    } else {
+      console.warn(`[scheduler] paused (${reason}); resumeAt too far in future for setTimeout (${delay}ms)`);
+    }
+  }
+}
+
+function clearPause(source) {
+  if (resumeTimer) { clearTimeout(resumeTimer); resumeTimer = null; }
+  const s = readQueue();
+  if (s.paused) {
+    console.log(`[scheduler] clearPause (${source || 'manual'})`);
+    s.paused = null;
+    writeQueue(s);
+    broadcast();
+  }
+}
+
+/** Scan the tail of a job's log for the canonical rate-limit signal. We look
+ *  at the last 16 KB — final result event always lands at the end. */
+function detectRateLimitInLog(logPath) {
+  try {
+    const stat = fs.statSync(logPath);
+    const start = Math.max(0, stat.size - 16384);
+    const len = stat.size - start;
+    if (len <= 0) return false;
+    const fd = fs.openSync(logPath, 'r');
+    const buf = Buffer.alloc(len);
+    fs.readSync(fd, buf, 0, len, start);
+    fs.closeSync(fd);
+    const text = buf.toString('utf8');
+    return /"rateLimitType":"five_hour"/.test(text)
+      || /"api_error_status":429/.test(text)
+      || /You'?ve hit your limit/.test(text);
+  } catch {
+    return false;
+  }
+}
+
+// ---------- claude binary ----------
+
+function resolveClaudeBin() {
+  if (claudeBinPathCached) return claudeBinPathCached;
+  const candidates = [
+    path.join(os.homedir(), '.claude', 'local', 'claude'),
+    '/usr/local/bin/claude',
+    '/opt/homebrew/bin/claude',
+    '/usr/bin/claude',
+  ];
+  for (const c of candidates) {
+    try { fs.accessSync(c, fs.constants.X_OK); claudeBinPathCached = c; return c; } catch { /* */ }
+  }
+  // Last resort: rely on PATH lookup at spawn time.
+  claudeBinPathCached = 'claude';
+  return claudeBinPathCached;
+}
+
+// ---------- execution ----------
+
+function pickRunDir() {
+  const ts = new Date().toISOString().replace(/[:.]/g, '-');
+  const dir = path.join(RUNS_DIR, ts);
+  fs.mkdirSync(dir, { recursive: true });
+  return { runId: ts, dir };
+}
+
+async function executeJob(job, runDir, defaultCwd) {
+  const logPath = path.join(runDir, `${job.slug}.log`);
+  const metaPath = path.join(runDir, `${job.slug}.meta.json`);
+  const cwd = job.cwd || defaultCwd;
+  const startedAt = Date.now();
+
+  const fd = fs.openSync(logPath, 'a');
+  fs.writeSync(fd, `[scheduler] starting ${job.slug} at ${new Date().toISOString()}\n[scheduler] cwd=${cwd}\n\n`);
+
+  // Read full PRD body fresh from disk (queue stored only the preview).
+  let prompt;
+  try {
+    const parsed = parsePrd(path.join(PRDS_DIR, `${job.slug}.md`));
+    prompt = parsed.body;
+  } catch (e) {
+    fs.writeSync(fd, `[scheduler] failed to read PRD: ${e?.message}\n`);
+    fs.closeSync(fd);
+    return { exitCode: -1, durationMs: 0, error: e?.message };
+  }
+
+  return await new Promise((resolve) => {
+    const claudeBin = resolveClaudeBin();
+    const child = spawn(claudeBin, [
+      '-p', prompt,
+      '--dangerously-skip-permissions',
+      '--output-format', 'stream-json',
+      '--verbose',
+    ], {
+      cwd,
+      env: process.env,
+      stdio: ['ignore', fd, fd],
+    });
+
+    fs.writeSync(fd, `[scheduler] spawned pid=${child.pid}\n\n`);
+
+    child.on('error', (err) => {
+      const durationMs = Date.now() - startedAt;
+      fs.writeSync(fd, `\n[scheduler] spawn error: ${err.message}\n`);
+      fs.closeSync(fd);
+      atomicWriteJson(metaPath, { slug: job.slug, cwd, exitCode: -1, error: err.message, startedAt, finishedAt: Date.now(), durationMs });
+      resolve({ exitCode: -1, durationMs, error: err.message });
+    });
+
+    child.on('exit', (code) => {
+      const durationMs = Date.now() - startedAt;
+      fs.writeSync(fd, `\n[scheduler] exit code=${code} duration=${Math.round(durationMs / 1000)}s\n`);
+      fs.closeSync(fd);
+      const rateLimited = code !== 0 && detectRateLimitInLog(logPath);
+      atomicWriteJson(metaPath, { slug: job.slug, cwd, exitCode: code, rateLimited, startedAt, finishedAt: Date.now(), durationMs });
+      resolve({ exitCode: code, durationMs, rateLimited });
+    });
+  });
+}
+
+async function runDueJobs() {
+  if (isExecuting) return;
+  isExecuting = true;
+  cancelToken = { cancelled: false };
+  try {
+    const state = readQueue();
+    if (state.paused) {
+      console.log('[scheduler] runDueJobs skipped: paused');
+      return;
+    }
+    reconcile(state);
+    const pending = state.jobs.filter((j) => j.status === 'pending');
+    if (pending.length === 0) {
+      return;
+    }
+    const { runId, dir: runDir } = pickRunDir();
+    state.lastRunAt = new Date().toISOString();
+
+    // Group by parallelGroup, ascending. Each group runs serially after the
+    // previous group completes.
+    const groups = new Map();
+    for (const j of pending) {
+      const g = j.parallelGroup ?? 99;
+      if (!groups.has(g)) groups.set(g, []);
+      groups.get(g).push(j);
+    }
+    const groupKeys = Array.from(groups.keys()).sort((a, b) => a - b);
+
+    writeQueue(state);
+    broadcast();
+
+    for (const gk of groupKeys) {
+      if (cancelToken.cancelled) break;
+      const groupJobs = groups.get(gk);
+      // Within a group: cap concurrency and run waves until all done.
+      const cap = Math.max(1, Math.min(state.config.concurrencyCap, groupJobs.length));
+      const queue = [...groupJobs];
+      const inFlight = new Set();
+
+      const launch = (job) => {
+        const s = readQueue();
+        const idx = s.jobs.findIndex((x) => x.slug === job.slug);
+        if (idx >= 0) {
+          s.jobs[idx].status = 'running';
+          s.jobs[idx].runId = runId;
+          s.jobs[idx].startedAt = new Date().toISOString();
+          writeQueue(s);
+          broadcast();
+        }
+        const promise = executeJob(job, runDir, state.config.defaultCwd).then(async (res) => {
+          // Rate-limit OR pause-already-set means we treat this job as
+          // unfinished — bounce it back to 'pending' so the next run
+          // (after token reset) picks it up.
+          if (res.rateLimited) {
+            const resetIso = await refreshNextReset();
+            setPaused('rate_limit', resetIso);
+          }
+          const sn = readQueue();
+          const i2 = sn.jobs.findIndex((x) => x.slug === job.slug);
+          if (i2 >= 0) {
+            const treatAsPending = res.rateLimited || (sn.paused && sn.paused.reason === 'rate_limit');
+            if (treatAsPending) {
+              sn.jobs[i2].status = 'pending';
+              sn.jobs[i2].runId = null;
+              sn.jobs[i2].startedAt = null;
+              sn.jobs[i2].finishedAt = null;
+              sn.jobs[i2].exitCode = null;
+              sn.jobs[i2].error = res.rateLimited ? 'paused: rate limit' : 'paused: queue halted';
+            } else {
+              sn.jobs[i2].status = res.exitCode === 0 ? 'completed' : 'failed';
+              sn.jobs[i2].finishedAt = new Date().toISOString();
+              sn.jobs[i2].exitCode = res.exitCode;
+              sn.jobs[i2].error = res.error || null;
+            }
+            writeQueue(sn);
+            broadcast();
+          }
+          inFlight.delete(promise);
+        });
+        inFlight.add(promise);
+      };
+
+      // Prime up to cap
+      while (queue.length && inFlight.size < cap && !cancelToken.cancelled) launch(queue.shift());
+      // Drain. If cancelled mid-group, stop launching new jobs but let
+      // already-launched ones settle (they're rate-limited too — short).
+      while (inFlight.size > 0) {
+        await Promise.race(inFlight);
+        if (cancelToken.cancelled) {
+          await Promise.allSettled([...inFlight]);
+          break;
+        }
+        while (queue.length && inFlight.size < cap) launch(queue.shift());
+      }
+    }
+  } finally {
+    isExecuting = false;
+    // No longer auto-disable after a run. The firePolicy now governs whether
+    // the next batch fires automatically. Just clear the one-shot scheduledFor.
+    const s = readQueue();
+    s.scheduledFor = null;
+    writeQueue(s);
+    broadcast();
+  }
+}
+
+// ---------- when-available poll loop ----------
+
+async function pollWhenAvailable() {
+  try {
+    const state = readQueue();
+    if (state.config.firePolicy !== 'when-available') return;
+    if (state.paused) return;
+    if (isExecuting) return;
+    const pending = state.jobs.filter((j) => j.status === 'pending');
+    if (pending.length === 0) return;
+
+    // Refresh utilization. If the call fails, don't fire blindly — wait
+    // for the next tick.
+    let util;
+    try {
+      const r = await billing.fetchUsage();
+      util = r?.usage?.five_hour?.utilization ?? null;
+      cachedUtilization = util;
+      cachedNextReset = { at: r?.usage?.five_hour?.resets_at ?? cachedNextReset.at, fetchedAt: Date.now() };
+    } catch {
+      return;
+    }
+    if (util === null || util === undefined) return;
+    if (util >= state.config.utilizationThreshold) {
+      // Tokens too high — broadcast so the UI shows current util but don't fire.
+      broadcast();
+      return;
+    }
+    console.log(`[scheduler] when-available: util=${util}%, ${pending.length} pending — firing`);
+    runDueJobs().catch((e) => console.error('[scheduler] runDueJobs error', e));
+  } catch (e) {
+    console.error('[scheduler] poll error', e);
+  }
+}
+
+// ---------- IPC ----------
+
+function registerScheduleHandlers() {
+  ensureDirs();
+
+  ipcMain.handle('schedule:state', async () => {
+    const state = readQueue();
+    reconcile(state);
+    writeQueue(state);
+    return {
+      config: state.config,
+      jobs: state.jobs,
+      scheduledFor: state.scheduledFor,
+      lastRunAt: state.lastRunAt,
+      nextReset: getNextResetCached(),
+      paused: state.paused,
+      utilization: cachedUtilization,
+      paths: { root: ROOT, prds: PRDS_DIR, runs: RUNS_DIR, queue: QUEUE_PATH },
+    };
+  });
+
+  ipcMain.handle('schedule:set-config', async (_e, partial) => {
+    const state = readQueue();
+    state.config = { ...state.config, ...(partial || {}) };
+    if (typeof state.config.concurrencyCap === 'number') {
+      state.config.concurrencyCap = Math.max(1, Math.min(20, Math.floor(state.config.concurrencyCap)));
+    }
+    if (typeof state.config.offsetMinutes === 'number') {
+      state.config.offsetMinutes = Math.max(0, Math.min(180, Math.floor(state.config.offsetMinutes)));
+    }
+    writeQueue(state);
+    await rescheduleTimer();
+    return { ok: true, config: state.config };
+  });
+
+  ipcMain.handle('schedule:reset-job', async (_e, { slug }) => {
+    const state = readQueue();
+    const idx = state.jobs.findIndex((j) => j.slug === slug);
+    if (idx < 0) return { ok: false, error: 'not found' };
+    state.jobs[idx].status = 'pending';
+    state.jobs[idx].runId = null;
+    state.jobs[idx].startedAt = null;
+    state.jobs[idx].finishedAt = null;
+    state.jobs[idx].exitCode = null;
+    state.jobs[idx].error = null;
+    writeQueue(state);
+    broadcast();
+    return { ok: true };
+  });
+
+  ipcMain.handle('schedule:run-now', async () => {
+    // Manual run-now overrides any auto-pause. Clear it first.
+    clearPause('run-now');
+    runDueJobs().catch((e) => console.error('[scheduler] runDueJobs error', e));
+    return { ok: true };
+  });
+
+  ipcMain.handle('schedule:resume', async () => {
+    clearPause('manual');
+    return { ok: true };
+  });
+
+  ipcMain.handle('schedule:refresh-reset', async () => {
+    const at = await refreshNextReset();
+    await rescheduleTimer();
+    return { ok: true, nextReset: at };
+  });
+
+  ipcMain.handle('schedule:open-folder', async () => {
+    const { shell } = require('electron');
+    await shell.openPath(ROOT);
+    return { ok: true };
+  });
+
+  ipcMain.handle('schedule:read-prd', async (_e, { slug }) => {
+    try {
+      const text = await fsp.readFile(path.join(PRDS_DIR, `${slug}.md`), 'utf8');
+      return { ok: true, text };
+    } catch (e) {
+      return { ok: false, error: e?.message };
+    }
+  });
+
+  ipcMain.handle('schedule:read-log', async (_e, { runId, slug }) => {
+    try {
+      const p = path.join(RUNS_DIR, runId, `${slug}.log`);
+      const text = await fsp.readFile(p, 'utf8');
+      return { ok: true, text };
+    } catch (e) {
+      return { ok: false, error: e?.message };
+    }
+  });
+}
+
+async function init() {
+  ensureDirs();
+  // Ensure queue.json exists with defaults so the renderer can read it.
+  if (!fs.existsSync(QUEUE_PATH)) writeQueue({ config: { ...DEFAULT_CONFIG }, jobs: [], scheduledFor: null, lastRunAt: null, paused: null });
+
+  // If we boot up while paused with a resumeAt in the past, clear it. This
+  // happens when the app was closed across the reset window.
+  const boot = readQueue();
+  if (boot.paused && boot.paused.resumeAt && new Date(boot.paused.resumeAt).getTime() <= Date.now()) {
+    clearPause('boot-elapsed');
+  } else if (boot.paused && boot.paused.resumeAt) {
+    // Re-arm the resume timer (lost across restart).
+    setPaused(boot.paused.reason, boot.paused.resumeAt);
+  }
+
+  await rescheduleTimer();
+  // Refresh next-reset every 10 minutes — billing window can shift if usage
+  // resets early or the auth token rotates.
+  setInterval(() => { rescheduleTimer().catch(() => {}); }, 10 * 60_000);
+  // when-available poll loop. Tick every 2 minutes; the function itself is
+  // a no-op when policy != 'when-available' or queue is empty/paused.
+  if (pollTimer) clearInterval(pollTimer);
+  pollTimer = setInterval(() => { pollWhenAvailable().catch(() => {}); }, 2 * 60_000);
+  // First tick fires after a short delay so billing is warmed up.
+  setTimeout(() => { pollWhenAvailable().catch(() => {}); }, 15_000);
+}
+
+module.exports = { registerScheduleHandlers, attachWindow, init, ROOT, PRDS_DIR };