claude-code-session-manager 0.108.0 → 0.110.0

package/scripts/README.md

@@ -10,6 +10,8 @@ scripts/lib was moved into src/main/lib (2026-09); nothing under src/ may requir
 | --- | --- | --- |
 | audit-ops-hygiene.cjs | manual; named in `ops-sweep` SKILL.md | yes |
 | bench/main-bench.cjs | `npm run bench` (main-process micro-benches, plain Node); renderer half is `npm run bench:renderer` (`tests/bench/`, `vitest.bench.config.ts`, not in `test:unit`) | no |
+| page-surface.cjs | manual and by the page steward personas `.claude/agents/page-*.md`; derives a page's owned/shared files, window.api methods, main handlers and tests | no |
+| check-page-stewards.cjs | `npm run lint:page-stewards` (in `lint`) — every nav page has a valid `.claude/agents/page-<key>.md` steward persona; ratchets PENDING | no |
 | check-conditional-hooks.cjs | `npm run lint:hooks` (in `lint`) | no |
 | check-epic-transcripts.cjs | manual read-only diagnostic (`--json`); also surfaced as a non-fatal warning in `npm run health` | no |
 | check-doc-hierarchy.cjs | `npm run lint:docs` (in `lint`) | no |
@@ -32,6 +34,11 @@ scripts/lib was moved into src/main/lib (2026-09); nothing under src/ may requir
 | sm-ps.cjs | manual process-tree inspector | no |
 | sync-settings-schema.cjs | `npm run sync:settings-schema` | no |
 | write-build-info.cjs | npm `prepack` and `prepublishOnly` | no |
+| test-quality/smells.cjs | `npm run lint:test-smells` (in `lint`) — static test-smell scan; ratchets source-text/no-assert against `tests/quality/smell-allowlist.json` | no |
+| test-quality/coverage-map.cjs | manual, dev-only — per-test-file v8 coverage and unique-coverage attribution | no |
+| test-quality/mutants.cjs | manual, dev-only — seeded mutation sampler; which test files kill which mutants | no |
+| test-quality/coverage-guard.cjs | manual, dev-only — `--base <ref>`; fails if a test-only diff drops covered statements/branches | no |
+| test-quality/report.cjs | manual, dev-only — keep/review/merge/bloat verdict per test file from the coverage map | no |
 | hooks/guard-destructive-git.cjs | `.claude/settings.json` PreToolUse + shim | yes |
 | hooks/guard-inline-implementation.cjs | `.claude/settings.json` PreToolUse + shim | yes |
 | hooks/guard-prd-writes.cjs | `.claude/settings.json` PreToolUse + shim | yes |

package/scripts/scheduler-mcp-server.cjs

@@ -365,9 +365,36 @@ const TOOLS = [
           description: 'Absolute cwd of YOUR project (the sender). Must differ from toCwd.',
         },
         title: { type: 'string', description: 'One line naming the finding — becomes the receiving queue row' },
+        motivation: {
+          type: 'string',
+          description: 'WHY this is needed, in the originating human\'s terms (max 2000 chars). Lead with this — the approving human reads it first. When a request is split into a series, summarise the overall plan here.',
+        },
+        plan: {
+          type: 'array', items: { type: 'string' },
+          description: "Ordered proposed steps (max 20). REQUIRED when tag is 'feature'.",
+        },
+        acceptanceCriteria: {
+          type: 'array', items: { type: 'string' },
+          description: 'How the receiving human will know this is done (1-20 items).',
+        },
+        outOfScope: {
+          type: 'array', items: { type: 'string' },
+          description: 'Optional: what this proposal deliberately does not cover (max 20).',
+        },
+        series: {
+          type: 'object',
+          description: 'Optional: set on EVERY proposal when one request is split into several. Share the same key/title/total across them; index is this proposal\'s position.',
+          properties: {
+            key: { type: 'string', description: 'Shared kebab-case series id (max 60 chars)' },
+            title: { type: 'string', description: 'Shared series title (max 120 chars)' },
+            index: { type: 'integer', description: 'This proposal\'s 1-based position in the series' },
+            total: { type: 'integer', description: 'Number of proposals in the series (2-50)' },
+          },
+          required: ['key', 'title', 'index', 'total'],
+        },
         body: {
           type: 'string',
-          description: 'The report itself: symptom, where observed, expected behavior, suspected cause. Self-contained — the reader cannot see your project.',
+          description: 'Supporting detail: evidence, symptom, where observed, references. Self-contained — the reader cannot see your project — but no longer the whole report; motivation/plan/acceptanceCriteria carry the proposal.',
         },
         tag: {
           type: 'string',
@@ -384,7 +411,7 @@ const TOOLS = [
           description: 'Optional absolute paths worth reading, appended as Reference lines',
         },
       },
-      required: ['toCwd', 'fromCwd', 'title', 'body'],
+      required: ['toCwd', 'fromCwd', 'title', 'motivation', 'acceptanceCriteria', 'body'],
     },
   },
   {

package/src/main/agentLibrary.cjs

@@ -163,19 +163,30 @@ async function savePersona({
     return saveOverlay({ name, projectName, model, effort, loadSessions, validatePath, writeTextAtomic });
   }
   const target = validatePath(path.join(globalDir, `${name}.md`));
-  // The Agent Library editor's form has no `seedVersion` field, so a save
-  // through it never passes one explicitly — carry over whatever stamp the
-  // existing file already has rather than silently erasing it. An explicit
-  // `seedVersion` argument (e.g. the seeder's own future callers) still wins.
+  // A caller that omits seedVersion/title/projects/action/actionLabel (the
+  // Agent Library form has no seedVersion field) must not erase what the
+  // existing file holds — carry each undefined one over. An explicit value,
+  // including `projects: []`, still wins. `effort` is deliberately not
+  // carried: omitted means "write no effort line".
   let resolvedSeedVersion = seedVersion;
-  if (resolvedSeedVersion === undefined) {
+  let resolvedTitle = title;
+  let resolvedProjects = projects;
+  let resolvedAction = action;
+  let resolvedActionLabel = actionLabel;
+  if ([seedVersion, title, projects, action, actionLabel].some((v) => v === undefined)) {
     try {
-      const existing = splitFrontmatter(fsSync.readFileSync(target, 'utf8'));
-      const existingVersion = Number(existing.fm.seedVersion);
-      if (Number.isFinite(existingVersion)) resolvedSeedVersion = existingVersion;
+      const { fm } = splitFrontmatter(fsSync.readFileSync(target, 'utf8'));
+      if (resolvedSeedVersion === undefined) {
+        const existingVersion = Number(fm.seedVersion);
+        if (Number.isFinite(existingVersion)) resolvedSeedVersion = existingVersion;
+      }
+      if (resolvedTitle === undefined && fm.title) resolvedTitle = fm.title;
+      if (resolvedProjects === undefined && fm.projects) resolvedProjects = parseTools(fm.projects);
+      if (resolvedAction === undefined && fm.action) resolvedAction = decodeLine(fm.action);
+      if (resolvedActionLabel === undefined && fm.actionLabel) resolvedActionLabel = decodeLine(fm.actionLabel);
     } catch { /* no existing file (or unreadable) — nothing to carry over */ }
   }
-  const text = serializePersona({ name, description, tools, model, effort, color, tags, projects, action, actionLabel, title, seedVersion: resolvedSeedVersion, body });
+  const text = serializePersona({ name, description, tools, model, effort, color, tags, projects: resolvedProjects, action: resolvedAction, actionLabel: resolvedActionLabel, title: resolvedTitle, seedVersion: resolvedSeedVersion, body });
   await writeTextAtomic(target, text);
   if (originalName && originalName !== name) {
     const oldReal = validatePath(path.join(globalDir, `${originalName}.md`));

package/src/main/build-info.json

@@ -1,8 +1,8 @@
 {
-  "version": "0.108.0",
-  "gitSha": "6abcc4e355e214ed60fe76291081712aa98d44c2",
-  "gitShortSha": "6abcc4e3",
+  "version": "0.110.0",
+  "gitSha": "1c3befa7cbc4d8fe34535a0ea583bffd47af11a0",
+  "gitShortSha": "1c3befa7",
   "gitBranch": "HEAD",
-  "builtAt": "2026-10-09T19:19:08.109Z",
+  "builtAt": "2026-10-11T00:20:48.379Z",
   "dirty": false
 }

package/src/main/chatRunner.cjs

@@ -970,6 +970,12 @@ function enqueueExternalPrompt(tabId, prompt) {
   broadcast('chat:external-send', { tabId, prompt });
 }
 
+// Asks the renderer to start a new Session (same launchSession a macro press
+// uses) on behalf of the paired phone. Payload is pre-validated by the caller.
+function requestExternalNewSession(payload) {
+  broadcast('chat:external-new-session', payload);
+}
+
 /**
  * Registers the admin-HTTP entry point for enqueueExternalPrompt, mirroring
  * prdCreate.cjs's registerAdminRoute pattern (auth is the injected transport's
@@ -1050,5 +1056,6 @@ module.exports = {
   WARN_CEILING_MS,
   __setExecutor,
   enqueueExternalPrompt,
+  requestExternalNewSession,
   registerAdminRoute,
 };

package/src/main/config.cjs

@@ -27,9 +27,9 @@ const { expandHome } = require('./lib/expandHome.cjs');
 const { listReferencedFiles } = require('./lib/importReferences.cjs');
 const atomicFs = require('./lib/atomicFs.cjs');
 
-/** Map<absPath, {watcher, refCount}> — one chokidar watcher per path. */
+/** Map<watchKey, {watcher, refCount}> — one chokidar watcher per path (+ depth, see watchKeyOf). */
 const watchers = new Map();
-/** Map<senderId, Map<absPath, count>> — per-sender watch contributions for reload teardown. */
+/** Map<senderId, Map<watchKey, count>> — per-sender watch contributions for reload teardown. */
 const senderWatches = new Map();
 let window = null;
 
@@ -380,26 +380,34 @@ function normalizePathKey(p) {
   return path.resolve(expandHome(p));
 }
 
+/** Watcher-map key: the resolved path, plus a depth suffix for non-default (bounded) watches. */
+function watchKeyOf(key, depth) {
+  return depth === undefined ? key : `${key}\u0000d${depth}`;
+}
+
 /**
  * Watch one or more absolute paths. Each call increments a refcount per path.
  * Unwatch decrements; when refcount hits zero the underlying watcher is closed.
  * Fires IPC event `config:changed` with {path, mtimeMs, kind} on any change.
  */
-function watch(paths, senderId) {
+function watch(paths, senderId, opts) {
+  const depth = opts?.depth;
   for (const rawPath of paths) {
     validatePath(expandHome(rawPath)); // security check — throws if out of bounds
     const key = normalizePathKey(rawPath);
+    const mapKey = watchKeyOf(key, depth);
     if (senderId != null) {
       if (!senderWatches.has(senderId)) senderWatches.set(senderId, new Map());
       const sm = senderWatches.get(senderId);
-      sm.set(key, (sm.get(key) || 0) + 1);
+      sm.set(mapKey, (sm.get(mapKey) || 0) + 1);
     }
-    const existing = watchers.get(key);
+    const existing = watchers.get(mapKey);
     if (existing) {
       existing.refCount++;
       continue;
     }
     const w = chokidar.watch(key, {
+      ...(depth === undefined ? {} : { depth }),
       ignoreInitial: true,
       persistent: true,
       awaitWriteFinish: { stabilityThreshold: 50, pollInterval: 25 },
@@ -420,13 +428,13 @@ function watch(paths, senderId) {
     w.on('error', (err) => {
       console.warn('[config] watcher error for', key, err.message);
     });
-    watchers.set(key, { watcher: w, refCount: 1 });
+    watchers.set(mapKey, { watcher: w, refCount: 1 });
   }
 }
 
-function unwatch(paths, senderId) {
+function unwatch(paths, senderId, opts) {
   for (const rawPath of paths) {
-    const key = normalizePathKey(rawPath);
+    const key = watchKeyOf(normalizePathKey(rawPath), opts?.depth);
     if (senderId != null) {
       const sm = senderWatches.get(senderId);
       if (sm) {
@@ -489,8 +497,8 @@ function registerConfigHandlers() {
       return { ok: false, error: e.message };
     }
   }));
-  ipcMain.on('config:watch', (e, { paths }) => { try { s.configWatch.parse(paths); watch(paths, e.sender.id); } catch (err) { logs.writeLine({ level: 'warn', scope: 'config', message: 'config:watch schema reject', meta: { error: err?.message } }); } });
-  ipcMain.on('config:unwatch', (e, { paths }) => { try { s.configWatch.parse(paths); unwatch(paths, e.sender.id); } catch (err) { logs.writeLine({ level: 'warn', scope: 'config', message: 'config:unwatch schema reject', meta: { error: err?.message } }); } });
+  ipcMain.on('config:watch', (e, { paths, opts }) => { try { s.configWatch.parse(paths); s.configWatchOpts.parse(opts); watch(paths, e.sender.id, opts); } catch (err) { logs.writeLine({ level: 'warn', scope: 'config', message: 'config:watch schema reject', meta: { error: err?.message } }); } });
+  ipcMain.on('config:unwatch', (e, { paths, opts }) => { try { s.configWatch.parse(paths); s.configWatchOpts.parse(opts); unwatch(paths, e.sender.id, opts); } catch (err) { logs.writeLine({ level: 'warn', scope: 'config', message: 'config:unwatch schema reject', meta: { error: err?.message } }); } });
 }
 
 module.exports = {
@@ -498,6 +506,8 @@ module.exports = {
   registerConfigHandlers,
   closeAllWatchers,
   releaseWatchesForSender,
+  watch,
+  unwatch,
   // exported for tests / direct use
   readJson,
   readText,

package/src/main/historyAggregator.cjs

@@ -6,6 +6,7 @@ const path = require('node:path');
 const os = require('node:os');
 const { schemas } = require('./ipcSchemas.cjs');
 const historyRollup = require('./lib/historyRollup.cjs');
+const { sendIfAlive } = require('./lib/sendToRenderer.cjs');
 
 const PROJECTS_DIR = path.join(os.homedir(), '.claude', 'projects');
 const PARSE_BUDGET_MS = 2_000;
@@ -52,6 +53,47 @@ function resolvePricingKey(modelId) {
 // Shared implementation: lib/lruCache.cjs (re-exported below for existing callers).
 const { LRUCache } = require('./lib/lruCache.cjs');
 
+// ── history:updated broadcast ─────────────────────────────────────────────────
+// Open History pages re-fetch on this event. Throttled leading+trailing so a
+// backfill burst announces its first and last write only.
+const HISTORY_UPDATED_THROTTLE_MS = 5000;
+let historyNotifyTimer = null;
+let historyNotifyPending = false;
+
+function broadcastHistoryUpdated() {
+  try {
+    const { BrowserWindow } = require('electron');
+    for (const win of BrowserWindow.getAllWindows()) sendIfAlive(win, 'history:updated', {});
+  } catch {
+    // Never let a failed broadcast break aggregation.
+  }
+}
+
+function notifyHistoryUpdated() {
+  if (historyNotifyTimer) {
+    historyNotifyPending = true;
+    return;
+  }
+  broadcastHistoryUpdated();
+  const arm = () => {
+    historyNotifyTimer = setTimeout(() => {
+      historyNotifyTimer = null;
+      if (historyNotifyPending) {
+        historyNotifyPending = false;
+        broadcastHistoryUpdated();
+        arm();
+      }
+    }, HISTORY_UPDATED_THROTTLE_MS);
+    if (historyNotifyTimer.unref) historyNotifyTimer.unref();
+  };
+  arm();
+}
+
+async function appendRollupAndNotify(entries) {
+  await historyRollup.appendRollupDays(entries);
+  if (entries.length) notifyHistoryUpdated();
+}
+
 /**
  * Cache for parseJSONL results.
  * Entry shape: { mtimeMs: number, size: number, readOffset: number, inode: number, result: AggrResult }
@@ -574,7 +616,7 @@ async function finalizeClosedDays({ budgetMs, dryRun = false } = {}) {
   }
 
   if (!dryRun) {
-    await historyRollup.appendRollupDays(entries);
+    await appendRollupAndNotify(entries);
   }
   return { finalizedDates: partial ? [] : Array.from(dates), partial };
 }
@@ -741,7 +783,7 @@ async function refreshIntradayToday() {
 
   const entries = [];
   for (const b of buckets.values()) entries.push(...bucketToRollupLines(b));
-  if (entries.length) await historyRollup.appendRollupDays(entries);
+  if (entries.length) await appendRollupAndNotify(entries);
 
   return { date: today, projectsUpdated: buckets.size, strategy: INTRADAY_STRATEGY };
 }
@@ -859,7 +901,7 @@ async function aggregate(req) {
     if (b.date < today) backfillEntries.push(...bucketToRollupLines(b));
   }
   if (backfillEntries.length) {
-    await historyRollup.appendRollupDays(backfillEntries);
+    await appendRollupAndNotify(backfillEntries);
   }
 
   const rollupRows = rollupMapToRows(rollupMap, finalizedDates);
@@ -951,6 +993,7 @@ module.exports = {
   finalizeClosedDays,
   decodeCwd,
   refreshIntradayToday,
+  appendRollupAndNotify,
   computeIntradayBuckets,
   // exported for tests
   scanAggrLines,

package/src/main/index.cjs

@@ -129,6 +129,8 @@ const heapSnapshot = require('./heapSnapshot.cjs');
 const filesIpc = require('./files.cjs');
 const { registerDocEditHandlers, attachWindow: attachDocEditWindow } = require('./docEdit.cjs');
 const webRemote = require('./webRemote.cjs');
+const { registerRemoteClientHandlers } = require('./remoteClientIpc.cjs');
+const { registerUpdaterIpc } = require('./updaterIpc.cjs');
 const { listExchanges } = require('./exchanges.cjs');
 const { resolveClaudeBin } = require('./lib/claudeBin.cjs');
 const { checkInsideHome, assertInsideHome } = require('./lib/insideHome.cjs');
@@ -1098,6 +1100,12 @@ git.register(ipcMain);
 filesIpc.registerFilesHandlers();
 registerDocEditHandlers();
 webRemote.registerRemoteHandlers();
+registerRemoteClientHandlers(() => mainWindow);
+try {
+  registerUpdaterIpc({ ipcMain, getWindow: () => mainWindow, ptyManager });
+} catch (e) {
+  logs.writeLine({ scope: 'main', level: 'error', message: 'updater IPC registration failed', meta: { error: e?.message } });
+}
 chatRunner.registerChatHandlers();
 
 // Direct in-process PRD authoring for a queued PromptTicket classified

package/src/main/ipcSchemas.cjs

@@ -139,6 +139,7 @@ const configListDir = z.object({
 });
 
 const configWatch = z.array(z.string().min(1).max(4096));
+const configWatchOpts = z.object({ depth: z.number().int().min(0).max(2) }).strict().optional();
 
 const configParseImports = z.object({ path: z.string().min(1).max(4096) });
 
@@ -943,6 +944,19 @@ const chatExternalSend = z.object({
   ),
 });
 
+// Phone-initiated new Session. cwd/agentName are re-checked against the open
+// tabs / persona list in webRemote.cjs before anything touches the filesystem.
+const remoteSessionCreate = z.object({
+  cwd: z.string().min(1).max(4096),
+  agentName: z.string().regex(/^[A-Za-z0-9._-]{1,64}$/),
+  tag: EpicTagSchema,
+  title: z.string().min(1).max(120),
+  prompt: z.string().min(1).refine(
+    (s) => Buffer.byteLength(s, 'utf8') <= CHAT_PROMPT_MAX_BYTES,
+    `prompt must be ≤ ${CHAT_PROMPT_MAX_BYTES} bytes`,
+  ),
+});
+
 // ──────────────────────────────────────────── Web Remote
 // OTP is 8 uppercase alphanumeric chars (case-insensitive entry, normalised to upper in handler).
 const WEB_REMOTE_OTP_RE = /^[A-Z0-9]{8}$/i;
@@ -956,6 +970,11 @@ const webRemoteRevokeDevice = z.object({
   deviceId: z.string().regex(DEVICE_ID_RE),
 }).strict();
 
+// Optional payload: omit (undefined) to confirm the single pending client.
+const webRemoteConfirmSas = z.object({
+  clientKey: z.string().max(64).optional(),
+}).strict().optional();
+
 const webRemoteAuditTail = z.object({
   lines: z.number().int().min(1).max(500).optional(),
 }).strict();
@@ -1136,9 +1155,11 @@ function validated(schema, handler) {
 //
 // Ungated READ_COMMANDS (justify each):
 //   cmd:app:version      — exposes only the app semver string; no user data.
+//   cmd:app:info         — exposes only app semver + OS platform string; no user data.
 //   cmd:session:unsubscribe — teardown lifecycle; returns nothing sensitive.
 const READ_COMMANDS = new Set([
   'cmd:app:version',
+  'cmd:app:info',
   // v2 mobile: unsubscribe is a teardown lifecycle call with no data payload.
   'cmd:session:unsubscribe',
 ]);
@@ -1146,9 +1167,13 @@ const READ_COMMANDS = new Set([
 // Sensitive reads — return user data; require SAS confirmation same as MUTATE.
 const SAS_GATED_READS = new Set([
   'cmd:sessions:load',
+  // Same data as the event:session:list push (projects + their active Epics).
+  'cmd:sessions:list',
   'cmd:history:aggregate',
   // subscribe initiates a live stream of session state/summary — sensitive.
   'cmd:session:subscribe',
+  // Picker data (projects, personas, tags, macros) for the phone's New Session.
+  'cmd:session:options',
   // NOTE: cmd:exchanges:list is intentionally NOT allowlisted — webRemote.cjs has
   // no dispatch handler for it, so an allowlist entry would only fail closed with
   // an opaque reject. Re-add here together with the handler when remote exchanges
@@ -1174,6 +1199,8 @@ const MUTATE_COMMANDS = new Set([
   // Pushes a prompt into an open tab's chat queue — a real mutation of that
   // tab's session, same tier as pty:write.
   'cmd:chat:send',
+  // Starts a new Session on the desktop via the renderer's launchSession.
+  'cmd:session:create',
 ]);
 
 const ALLOWED_COMMANDS = new Set([...READ_COMMANDS, ...SAS_GATED_READS, ...MUTATE_COMMANDS]);
@@ -1192,6 +1219,7 @@ module.exports = {
     webRemotePair,
     webRemoteRevokeDevice,
     webRemoteAuditTail,
+    webRemoteConfirmSas,
     sessionSubscribe,
     ptySpawn,
     ptyTabId,
@@ -1211,6 +1239,7 @@ module.exports = {
     configWriteText,
     configListDir,
     configWatch,
+    configWatchOpts,
     configParseImports,
     sessionsPayload,
     layoutEnvelope,
@@ -1282,6 +1311,7 @@ module.exports = {
     chatCancel,
     chatClassifyTicket,
     chatExternalSend,
+    remoteSessionCreate,
     exchangesList,
     agentsSavePersona,
     macrosSave,

package/src/main/lib/autoUpdater.cjs

@@ -0,0 +1,190 @@
+'use strict';
+
+/**
+ * autoUpdater.cjs — pure, dependency-injected state machine around electron-updater's autoUpdater.
+ *
+ * Requires neither electron nor electron-updater: the caller injects the updater instance. The feed is
+ * whatever app-update.yml electron-builder baked into the installer; this module never supplies a feed URL.
+ * Checks on start() and every 4h, downloads in the background, and installs ONLY after requestInstall() —
+ * deferring (polling isBusy every 60s) while scheduler jobs or terminals are busy.
+ */
+
+const CHECK_INTERVAL_MS = 4 * 60 * 60 * 1000;
+const BUSY_POLL_MS = 60 * 1000;
+
+/** Unsigned mac builds cannot use Squirrel.Mac, so darwin is always unsupported. */
+function isAutoUpdateSupported({ packaged, platform, env }) {
+  const e = env || {};
+  if (packaged !== true) return false;
+  if (e.SM_AUTO_UPDATE === '0' || e.SM_E2E === '1') return false;
+  if (platform === 'win32') return true;
+  return platform === 'linux' && typeof e.APPIMAGE === 'string' && e.APPIMAGE.length > 0;
+}
+
+function createAutoUpdater({
+  updater, supported, currentVersion, isBusy, getEnabled,
+  setInterval: setIntervalFn = setInterval, clearInterval: clearIntervalFn = clearInterval,
+  now = Date.now, log = () => {},
+}) {
+  let enabledOverride = null;
+  let started = false;
+  let listening = false;
+  let checkTimer = null;
+  let pollTimer = null;
+  const subscribers = new Set();
+
+  const isEnabled = () => {
+    if (enabledOverride !== null) return enabledOverride;
+    return typeof getEnabled === 'function' ? getEnabled() !== false : true;
+  };
+
+  let snapshot = {
+    state: supported ? 'idle' : 'unsupported',
+    current: currentVersion,
+    latest: null,
+    progress: null,
+    error: null,
+    busyReason: null,
+    lastCheckedAt: null,
+  };
+
+  function setState(patch) {
+    const next = { ...snapshot, ...patch };
+    if (Object.keys(next).every((k) => next[k] === snapshot[k])) return;
+    snapshot = next;
+    for (const fn of [...subscribers]) {
+      try { fn(snapshot); } catch (e) { log('autoUpdater subscriber threw', e); }
+    }
+  }
+
+  const holding = () => snapshot.state === 'ready' || snapshot.state === 'deferred';
+
+  function fail(e) {
+    const message = e && e.message ? e.message : String(e);
+    log('autoUpdater error', message);
+    setState({ state: 'error', error: message, progress: null });
+  }
+
+  function clearPoll() {
+    if (pollTimer !== null) { clearIntervalFn(pollTimer); pollTimer = null; }
+  }
+
+  function clearChecks() {
+    if (checkTimer !== null) { clearIntervalFn(checkTimer); checkTimer = null; }
+  }
+
+  function attach() {
+    if (listening) return;
+    listening = true;
+    updater.autoDownload = true;
+    updater.autoInstallOnAppQuit = true;
+    updater.allowPrerelease = false;
+    updater.allowDowngrade = false;
+    updater.on('checking-for-update', () => {
+      if (!holding()) setState({ state: 'checking', error: null });
+    });
+    updater.on('update-available', (info) => {
+      if (!holding()) setState({ state: 'downloading', latest: info && info.version ? info.version : null, progress: null, error: null });
+    });
+    updater.on('download-progress', (p) => {
+      if (!holding()) setState({ state: 'downloading', progress: p && typeof p.percent === 'number' ? p.percent : null });
+    });
+    updater.on('update-downloaded', (info) => {
+      setState({ state: 'ready', latest: info && info.version ? info.version : snapshot.latest, progress: 100, error: null, busyReason: null });
+    });
+    updater.on('update-not-available', () => {
+      if (!holding()) setState({ state: 'idle', latest: null, progress: null, error: null });
+    });
+    updater.on('error', (e) => {
+      if (!holding()) fail(e);
+    });
+  }
+
+  async function checkNow() {
+    if (!supported || !isEnabled()) return;
+    if (holding() || snapshot.state === 'checking' || snapshot.state === 'downloading') return;
+    attach();
+    setState({ state: 'checking', error: null, lastCheckedAt: now() });
+    try {
+      await updater.checkForUpdates();
+    } catch (e) {
+      fail(e);
+    }
+  }
+
+  function startChecks() {
+    clearChecks();
+    checkTimer = setIntervalFn(() => { checkNow(); }, CHECK_INTERVAL_MS);
+    if (checkTimer && typeof checkTimer.unref === 'function') checkTimer.unref();
+    checkNow();
+  }
+
+  function applyEnabled() {
+    if (!supported) return;
+    if (!isEnabled()) {
+      clearChecks();
+      clearPoll();
+      setState({ state: 'disabled', busyReason: null, progress: null, error: null });
+      return;
+    }
+    if (snapshot.state === 'disabled') setState({ state: 'idle' });
+    if (started) startChecks();
+  }
+
+  function start() {
+    if (!supported || started) return;
+    started = true;
+    applyEnabled();
+  }
+
+  function stop() {
+    started = false;
+    clearChecks();
+    clearPoll();
+  }
+
+  function setEnabled(value) {
+    enabledOverride = !!value;
+    applyEnabled();
+  }
+
+  function install() {
+    clearPoll();
+    try {
+      updater.quitAndInstall(false, true);
+    } catch (e) {
+      fail(e);
+    }
+  }
+
+  function requestInstall({ force } = {}) {
+    if (!supported || !holding()) return;
+    if (snapshot.state === 'deferred' && !force) return;
+    if (force) { install(); return; }
+    const b = isBusy ? isBusy() : { busy: false };
+    if (!b || !b.busy) { install(); return; }
+    setState({ state: 'deferred', busyReason: b.reason || null });
+    clearPoll();
+    pollTimer = setIntervalFn(() => {
+      const cur = isBusy ? isBusy() : { busy: false };
+      if (cur && cur.busy) { setState({ busyReason: cur.reason || null }); return; }
+      install();
+    }, BUSY_POLL_MS);
+    if (pollTimer && typeof pollTimer.unref === 'function') pollTimer.unref();
+  }
+
+  function cancelDeferred() {
+    if (snapshot.state !== 'deferred') return;
+    clearPoll();
+    setState({ state: 'ready', busyReason: null });
+  }
+
+  function subscribe(fn) {
+    subscribers.add(fn);
+    return () => { subscribers.delete(fn); };
+  }
+
+  return { start, stop, checkNow, requestInstall, cancelDeferred, setEnabled, status: () => snapshot, subscribe };
+}
+
+module.exports = { isAutoUpdateSupported, createAutoUpdater, CHECK_INTERVAL_MS, BUSY_POLL_MS };