onbuzz 5.4.0 → 5.4.3

package/src/interfaces/webServer.js

@@ -13,7 +13,12 @@ import { createServer } from 'http';
 import { WebSocketServer } from 'ws';
 import path from 'path';
 import { promises as fs, createReadStream } from 'fs';
-import { execSync, spawn } from 'child_process';
+import { exec, spawn } from 'child_process';
+import { promisify } from 'util';
+
+// Async exec so a self-update never blocks the event loop (and thus every other
+// route + the WebSocket + the agent scheduler) for the full npm install.
+const execAsync = promisify(exec);
 import { resolveModuleFilename } from '../utilities/esmCjsPath.js';
 
 import {
@@ -29,6 +34,7 @@ import { getVisualEditorServer, getVisualEditorPort, getVisualEditorBaseUrl, set
 
 // Import credential vault for secure credential management
 import { getGalleryService } from '../services/galleryService.js';
+import { getEventLoopMonitor } from '../services/eventLoopMonitor.js';
 import composioService from '../services/composioService.js';
 import { getUserDataPaths } from '../utilities/userDataDir.js';
 import { projectActiveRuns } from '../utilities/flowRunFilters.js';
@@ -1104,6 +1110,16 @@ h2{color:#16a34a;margin-bottom:.5rem;} p{color:#666;}</style></head>
     // package.json so OnBuzz reports `npm i -g onbuzz` and Autopilot
     // reports `npm i -g @loxia-labs/loxia-autopilot-one`. canSelfUpdate
     // is false for electron (self-updates via electron-updater) and pkg
+    // Event-loop delay — how blocked the single event loop is under real load.
+    // High p99 here is the honest signal that routes are competing for CPU.
+    this.app.get('/api/system/event-loop', (req, res) => {
+      try {
+        res.json({ success: true, eventLoop: getEventLoopMonitor().snapshot() });
+      } catch (error) {
+        res.status(HTTP_STATUS.INTERNAL_SERVER_ERROR).json({ success: false, error: error.message });
+      }
+    });
+
     // (standalone binary) so the UI can hide the in-app "Auto-update".
     this.app.get('/api/system/update-status', async (req, res) => {
       try {
@@ -1193,11 +1209,12 @@ h2{color:#16a34a;margin-bottom:.5rem;} p{color:#666;}</style></head>
       try {
         this.logger.info('Starting system update...', { packageName, distribution });
 
-        // Run npm install
-        const updateOutput = execSync(updateCommand, {
+        // Run npm install asynchronously — the child runs while the event loop
+        // keeps serving other routes; we still await the result so the response
+        // contract (returns when done) is unchanged.
+        const { stdout: updateOutput } = await execAsync(updateCommand, {
           encoding: 'utf8',
           timeout: 120000, // 2 minute timeout
-          stdio: ['pipe', 'pipe', 'pipe']
         });
 
         this.logger.info('Update completed successfully', { output: updateOutput });
@@ -2265,11 +2282,15 @@ h2{color:#16a34a;margin-bottom:.5rem;} p{color:#666;}</style></head>
 
         const credentials = this.credentialVault.listCredentials();
         const knownSites = this.credentialVault.listKnownSites();
+        const status = typeof this.credentialVault.getStatus === 'function'
+          ? this.credentialVault.getStatus()
+          : null;
 
         res.json({
           success: true,
           credentials,
-          knownSites
+          knownSites,
+          status
         });
 
       } catch (error) {

package/src/services/__tests__/credentialVault.crypto.test.js

@@ -0,0 +1,214 @@
+/**
+ * Real-crypto, real-fs integration tests for the credential vault's durability
+ * guarantees — the "always working" properties:
+ *   - encrypt→persist→reload round-trip across instances
+ *   - siteId canonicalization so a save via URL is found by slug/domain
+ *   - transparent migration from the legacy machine-derived key to the stable
+ *     master key (existing users keep their credentials)
+ *   - undecryptable data is backed up + surfaced (not silently emptied)
+ *   - a transient/corrupt key-file read never regenerates the key (no silent
+ *     data loss); it degrades to memory-only + a surfaced error
+ *
+ * Only userDataDir is mocked (to point the vault at a temp dir); fs, crypto,
+ * os and stealthConstants are REAL so this exercises the actual AES-GCM paths.
+ */
+import { jest, describe, test, expect, beforeEach, afterEach } from '@jest/globals';
+import { promises as fs } from 'fs';
+import path from 'path';
+import os from 'os';
+import crypto from 'crypto';
+import { CREDENTIAL_CONFIG } from '../../utilities/stealthConstants.js';
+import { createMockLogger } from '../../__test-utils__/mockFactories.js';
+
+let tmpDir;
+jest.unstable_mockModule('../../utilities/userDataDir.js', () => ({
+  getUserDataPaths: () => ({ settings: tmpDir, agents: tmpDir, state: tmpDir }),
+  ensureUserDataDirs: async () => {},
+}));
+
+const { default: CredentialVault } = await import('../credentialVault.js');
+
+const credFile = () => path.join(tmpDir, CREDENTIAL_CONFIG.STORAGE.CREDENTIALS_FILE);
+const keyFile = () => path.join(tmpDir, '.credential-key');
+const saltFile = () => path.join(tmpDir, '.credential-salt');
+
+const machineId = () =>
+  [os.hostname(), os.homedir(), os.userInfo().username, process.platform, 'loxia-credential-vault-v1'].join(':');
+
+/** Encrypt exactly the way old versions did (salt + machine-derived key). */
+function legacyEncrypt(plaintext, salt) {
+  const key = crypto.pbkdf2Sync(machineId(), salt, CREDENTIAL_CONFIG.KEY_DERIVATION_ITERATIONS, 32, 'sha256');
+  const iv = crypto.randomBytes(CREDENTIAL_CONFIG.IV_LENGTH);
+  const cipher = crypto.createCipheriv(CREDENTIAL_CONFIG.ENCRYPTION_ALGORITHM, key, iv);
+  let enc = cipher.update(plaintext, 'utf8', 'base64');
+  enc += cipher.final('base64');
+  const tag = cipher.getAuthTag();
+  return Buffer.concat([iv, tag, Buffer.from(enc, 'base64')]).toString('base64');
+}
+
+const newVault = () => new CredentialVault(createMockLogger());
+
+beforeEach(async () => {
+  tmpDir = path.join(os.tmpdir(), `loxia-vault-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+  await fs.mkdir(tmpDir, { recursive: true });
+});
+afterEach(async () => {
+  await fs.rm(tmpDir, { recursive: true, force: true }).catch(() => {});
+});
+
+describe('CredentialVault durability (real crypto)', () => {
+  test('encrypt → persist → reload round-trips across instances', async () => {
+    const v1 = newVault();
+    await v1.initialize();
+    await v1.saveCredentials('linkedin', { username: 'u@e.com', password: 'secret-pw' });
+
+    const v2 = newVault();
+    await v2.initialize();
+    expect(v2.getCredentials('linkedin').password).toBe('secret-pw');
+    expect(v2.getStatus().healthy).toBe(true);
+  });
+
+  test('a fresh vault reports healthy + persistent', async () => {
+    const v = newVault();
+    await v.initialize();
+    expect(v.getStatus()).toMatchObject({ initialized: true, persistent: true, healthy: true, loadError: null });
+  });
+
+  test('canonicalization: saved via URL, found by slug and domain', async () => {
+    const v = newVault();
+    await v.initialize();
+    await v.saveCredentials('https://www.linkedin.com/login', { username: 'a', password: 'b' });
+
+    expect(v.getCredentials('linkedin')).toBeTruthy();
+    expect(v.getCredentials('linkedin.com')).toBeTruthy();
+    expect(v.getCredentials('www.linkedin.com')).toBeTruthy();
+    // and only one entry was stored (all forms collapsed to one key)
+    expect(v.credentials.size).toBe(1);
+  });
+
+  test('sessions round-trip too', async () => {
+    const v1 = newVault();
+    await v1.initialize();
+    await v1.saveSession('github', [{ name: 'c', value: '1' }]);
+
+    const v2 = newVault();
+    await v2.initialize();
+    expect(v2.getSession('github').cookies).toHaveLength(1);
+  });
+
+  test('migrates legacy machine-key data to the stable master key', async () => {
+    // Simulate an old install: a salt + credentials.enc encrypted with the
+    // legacy key, and NO master key yet.
+    const salt = crypto.randomBytes(32);
+    await fs.writeFile(saltFile(), salt);
+    const payload = JSON.stringify({
+      version: 1,
+      credentials: [['github', { siteId: 'github', name: 'GitHub', username: 'octo', password: 'pw' }]],
+    });
+    await fs.writeFile(credFile(), legacyEncrypt(payload, salt));
+
+    const v = newVault();
+    await v.initialize();
+
+    expect(v.getCredentials('github').password).toBe('pw'); // decrypted via legacy key
+    expect(v.getStatus().loadError).toBeNull();
+    await expect(fs.access(keyFile())).resolves.toBeUndefined(); // master key now exists
+
+    // A fresh instance loads with the master key alone → migration persisted.
+    const v2 = newVault();
+    await v2.initialize();
+    expect(v2.getCredentials('github').password).toBe('pw');
+  });
+
+  test('undecryptable data is backed up and surfaced (not silently emptied)', async () => {
+    await fs.writeFile(keyFile(), crypto.randomBytes(32));           // valid master key
+    await fs.writeFile(credFile(), 'not-valid-encrypted-payload');    // garbage; no salt → no legacy fallback
+
+    const v = newVault();
+    await v.initialize();
+
+    const st = v.getStatus();
+    expect(st.healthy).toBe(false);
+    expect(st.loadError.kind).toBe('undecryptable');
+    expect(v.credentials.size).toBe(0);
+
+    const files = await fs.readdir(tmpDir);
+    expect(files.some(f => f.includes('.corrupt-'))).toBe(true); // original preserved
+  });
+
+  test('a transient key-read error degrades to memory-only WITHOUT regenerating the key', async () => {
+    // A directory where the key file should be → readFile throws EISDIR (non-ENOENT).
+    await fs.mkdir(keyFile(), { recursive: true });
+
+    const v = newVault();
+    await v.initialize();
+
+    const st = v.getStatus();
+    expect(st.persistent).toBe(false);
+    expect(st.loadError.kind).toBe('key-unavailable');
+    // Crucially, the key path was NOT overwritten with a new key.
+    expect((await fs.stat(keyFile())).isDirectory()).toBe(true);
+  });
+
+  test('a corrupt (too-short) key file is NOT silently regenerated', async () => {
+    await fs.writeFile(keyFile(), crypto.randomBytes(10)); // too short to be a 32-byte key
+
+    const v = newVault();
+    await v.initialize();
+
+    expect(v.getStatus().loadError.kind).toBe('key-unavailable');
+    expect((await fs.readFile(keyFile())).length).toBe(10); // untouched
+  });
+
+  test('a credentials read error (non-ENOENT) is surfaced, not swallowed', async () => {
+    await fs.writeFile(keyFile(), crypto.randomBytes(32));
+    await fs.mkdir(credFile(), { recursive: true }); // reading a dir → EISDIR
+
+    const v = newVault();
+    await v.initialize();
+
+    expect(v.getStatus().loadError.kind).toBe('read-failed');
+    expect(v.credentials.size).toBe(0);
+  });
+
+  test('undecryptable sessions are backed up and started fresh (no user error)', async () => {
+    await fs.writeFile(keyFile(), crypto.randomBytes(32));
+    await fs.writeFile(path.join(tmpDir, CREDENTIAL_CONFIG.STORAGE.SESSIONS_FILE), 'garbage-session-blob');
+
+    const v = newVault();
+    await v.initialize();
+
+    expect(v.sessions.size).toBe(0);
+    const files = await fs.readdir(tmpDir);
+    expect(files.some(f => f.startsWith(`${CREDENTIAL_CONFIG.STORAGE.SESSIONS_FILE}.corrupt-`))).toBe(true);
+    // sessions are non-critical → not a surfaced credentials loadError
+    expect(v.getStatus().loadError).toBeNull();
+  });
+
+  test('a sessions read error (non-ENOENT) does not throw', async () => {
+    await fs.writeFile(keyFile(), crypto.randomBytes(32));
+    await fs.mkdir(path.join(tmpDir, CREDENTIAL_CONFIG.STORAGE.SESSIONS_FILE), { recursive: true });
+
+    const v = newVault();
+    await v.initialize();
+    expect(v.sessions.size).toBe(0);
+    expect(v.getStatus().healthy).toBe(true); // credentials fine → still healthy
+  });
+
+  test('_backupUnreadable swallows a rename failure (best-effort)', async () => {
+    const v = newVault();
+    await v.initialize();
+    // Renaming a file that doesn't exist throws ENOENT — must not propagate.
+    await expect(v._backupUnreadable(path.join(tmpDir, 'nope.enc'))).resolves.toBeUndefined();
+  });
+
+  test('memory-only vault still functions in-process (just does not persist)', async () => {
+    await fs.mkdir(keyFile(), { recursive: true }); // force memory-only
+    const v = newVault();
+    await v.initialize();
+    await v.saveCredentials('github', { username: 'x', password: 'y' });
+    expect(v.getCredentials('github').password).toBe('y'); // usable this session
+    // but nothing was written under the key path
+    expect((await fs.stat(keyFile())).isDirectory()).toBe(true);
+  });
+});

package/src/services/__tests__/credentialVault.test.js

@@ -89,7 +89,7 @@ jest.unstable_mockModule('../../utilities/stealthConstants.js', () => ({
   }
 }));
 
-const { default: CredentialVault } = await import('../../services/credentialVault.js');
+const { default: CredentialVault, getCredentialVault } = await import('../../services/credentialVault.js');
 
 describe('CredentialVault', () => {
   let vault;
@@ -372,6 +372,18 @@ describe('CredentialVault', () => {
     expect(result.saved).toBe(false);
   });
 
+  test('submitCredentials with saveForFuture persists the credential', async () => {
+    vault.credentialsFile = null;
+    vault.encryptionKey = null;
+    const { requestInfo, promise } = vault.createCredentialRequest('github');
+
+    await vault.submitCredentials(requestInfo.requestId, { username: 'octo', password: 'pw' }, true);
+
+    const result = await promise;
+    expect(result.saved).toBe(true);
+    expect(vault.credentials.get('github').username).toBe('octo');
+  });
+
   test('submitCredentials throws for unknown request', async () => {
     await expect(vault.submitCredentials('nonexistent', {}))
       .rejects.toThrow('No pending credential request found');
@@ -424,6 +436,20 @@ describe('CredentialVault', () => {
     expect(sites[0]).toHaveProperty('hasCredentials');
   });
 
+  test('getStatus reports health', () => {
+    expect(vault.getStatus()).toMatchObject({ initialized: false, persistent: false, healthy: false });
+    vault.persistent = true;
+    vault.initialized = true;
+    expect(vault.getStatus().healthy).toBe(true);
+  });
+
+  test('getCredentialVault returns a singleton', () => {
+    const a = getCredentialVault(logger);
+    const b = getCredentialVault();
+    expect(a).toBe(b);
+    expect(a).toBeInstanceOf(CredentialVault);
+  });
+
   // ── Static methods ──
   test('getEventTypes returns credential events', () => {
     const events = CredentialVault.getEventTypes();

package/src/services/__tests__/eventLoopMonitor.test.js

@@ -0,0 +1,90 @@
+import { describe, test, expect } from '@jest/globals';
+import { EventLoopMonitor, getEventLoopMonitor } from '../eventLoopMonitor.js';
+
+describe('EventLoopMonitor', () => {
+  test('snapshot returns ms metrics with the expected shape', async () => {
+    const m = new EventLoopMonitor({ resolution: 10 }).start();
+    // Let the loop run a little so the histogram has samples.
+    await new Promise((r) => setTimeout(r, 40));
+    const s = m.snapshot();
+    m.stop();
+
+    for (const k of ['meanMs', 'p50Ms', 'p99Ms', 'maxMs']) {
+      expect(typeof s[k]).toBe('number');
+      expect(s[k]).toBeGreaterThanOrEqual(0);
+    }
+    expect(typeof s.stalling).toBe('boolean');
+    expect(s.started).toBe(true); // snapshot taken before stop()
+  });
+
+  test('start/stop are idempotent and toggle `started`', () => {
+    const m = new EventLoopMonitor();
+    expect(m.snapshot().started).toBe(false);
+    m.start().start();
+    expect(m.snapshot().started).toBe(true);
+    m.stop().stop();
+    expect(m.snapshot().started).toBe(false);
+  });
+
+  test('reset clears the histogram without throwing', () => {
+    const m = new EventLoopMonitor().start();
+    expect(() => m.reset()).not.toThrow();
+    m.stop();
+  });
+
+  test('stalling flag reflects the configured threshold', () => {
+    // A tiny threshold makes any measured delay count as stalling.
+    const hot = new EventLoopMonitor({ stallMs: 0 }).start();
+    // Force some measurable delay would be flaky; instead assert the flag is a
+    // pure function of p99 vs threshold via a stopped monitor at 0 delay.
+    const s = hot.snapshot();
+    hot.stop();
+    expect(s.stalling).toBe(s.p99Ms > 0);
+  });
+
+  test('phases is empty by default', () => {
+    expect(new EventLoopMonitor().snapshot().phases).toEqual({});
+  });
+
+  test('recordPhase surfaces per-phase p99/max/count in ms', () => {
+    const m = new EventLoopMonitor();
+    m.recordPhase('agentProcessing', 5);
+    m.recordPhase('agentProcessing', 15);
+    m.recordPhase('agentProcessing', 25);
+    const p = m.snapshot().phases.agentProcessing;
+    expect(p.count).toBe(3);
+    expect(p.maxMs).toBeGreaterThanOrEqual(24); // ~25ms (µs rounding)
+    expect(p.p99Ms).toBeGreaterThan(0);
+    expect(p.p50Ms).toBeGreaterThan(0);
+  });
+
+  test('recordPhase ignores invalid input', () => {
+    const m = new EventLoopMonitor();
+    m.recordPhase('x', -1);
+    m.recordPhase('x', NaN);
+    m.recordPhase('', 5);
+    m.recordPhase(null, 5);
+    expect(m.snapshot().phases).toEqual({});
+  });
+
+  test('sub-ms phase samples still record (clamped to ≥1µs)', () => {
+    const m = new EventLoopMonitor();
+    m.recordPhase('tiny', 0);
+    m.recordPhase('tiny', 0.2);
+    expect(m.snapshot().phases.tiny.count).toBe(2);
+  });
+
+  test('reset clears phase histograms too', () => {
+    const m = new EventLoopMonitor();
+    m.recordPhase('p', 10);
+    m.reset();
+    expect(m.snapshot().phases).toEqual({}); // count 0 → omitted
+  });
+
+  test('getEventLoopMonitor returns a singleton', () => {
+    const a = getEventLoopMonitor();
+    const b = getEventLoopMonitor();
+    expect(a).toBe(b);
+    expect(a).toBeInstanceOf(EventLoopMonitor);
+  });
+});

package/src/services/__tests__/scheduleService.flow.test.js

@@ -18,13 +18,40 @@ jest.unstable_mockModule('fs', () => ({
     mkdir: jest.fn(),
   },
 }));
-jest.unstable_mockModule('child_process', () => ({ execSync: jest.fn() }));
+// Async exec/spawn mock. `execBehavior(cmd)` returns {stdout,stderr} or an Error
+// (rejection); `spawnCalls` records every spawn incl. what was written to stdin.
+let execBehavior = () => ({ stdout: '', stderr: '' });
+const spawnCalls = [];
+let spawnExitCode = 0;
+let spawnError = null;
+jest.unstable_mockModule('child_process', () => ({
+  exec: jest.fn((cmd, opts, cb) => {
+    const done = typeof opts === 'function' ? opts : cb;
+    const r = execBehavior(String(cmd));
+    if (r instanceof Error) done(r); else done(null, r);
+  }),
+  spawn: jest.fn((cmd, args) => {
+    const rec = { cmd, args, input: '' };
+    spawnCalls.push(rec);
+    const handlers = {};
+    const child = {
+      stdin: { write: (d) => { rec.input += d.toString(); }, end: () => {} },
+      stderr: { on: () => {} },
+      on: (ev, h) => { handlers[ev] = h; return child; },
+    };
+    setImmediate(() => {
+      if (spawnError && handlers.error) handlers.error(spawnError);
+      else if (handlers.close) handlers.close(spawnExitCode);
+    });
+    return child;
+  }),
+}));
 jest.unstable_mockModule('../../utilities/userDataDir.js', () => ({
   getUserDataDir: jest.fn().mockReturnValue('/tmp/test-loxia-data'),
 }));
 
 const { default: ScheduleService } = await import('../scheduleService.js');
-const { execSync } = await import('child_process');
+const { exec: execMock } = await import('child_process');
 const { promises: fsp } = await import('fs');
 const { readFile, writeFile, mkdir } = fsp;
 
@@ -47,7 +74,10 @@ const VALID = {
 beforeEach(() => {
   jest.clearAllMocks();
   // Re-establish default mock behavior after clearAllMocks wiped call history.
-  execSync.mockReturnValue('');
+  execBehavior = () => ({ stdout: '', stderr: '' });
+  spawnCalls.length = 0;
+  spawnExitCode = 0;
+  spawnError = null;
   readFile.mockRejectedValue(Object.assign(new Error('ENOENT'), { code: 'ENOENT' }));
   writeFile.mockResolvedValue(undefined);
   mkdir.mockResolvedValue(undefined);
@@ -220,6 +250,20 @@ describe('_executeAgentSchedule', () => {
 
     expect(importArchivedAgent).toHaveBeenCalledWith('a1', '/proj', expect.anything());
     expect(addUserMessage).toHaveBeenCalledWith('a1', expect.objectContaining({ source: 'schedule' }));
+    // A restored-on-fire agent must be announced so the UI shows it without a
+    // full page reload (frontend refreshes its agent list on 'agent-imported').
+    expect(svc.webSocketManager.broadcast).toHaveBeenCalledWith(
+      expect.objectContaining({ type: 'agent-imported', agent: expect.objectContaining({ id: 'a1' }) }));
+  });
+
+  test('load-on-fire: does NOT broadcast agent-imported when nothing was restored', async () => {
+    const svc = newSvc();
+    svc.setAgentPool({ getAgent: jest.fn().mockResolvedValue(null), updateAgent: jest.fn(), addUserMessage: jest.fn() });
+    svc.setOrchestrator({ stateManager: { importArchivedAgent: jest.fn().mockResolvedValue(null) }, config: {} });
+
+    await svc._loadAgentFromDisk('gone');
+    const imported = svc.webSocketManager.broadcast.mock.calls.filter(c => c[0]?.type === 'agent-imported');
+    expect(imported).toHaveLength(0);
   });
 
   test('load-on-fire: falls back to getAgent when import returns nothing but the agent is now resident', async () => {
@@ -363,14 +407,14 @@ describe('_broadcast', () => {
 // ─────────────────────── OS-scheduler sync ───────────────────────
 
 describe('_findLoxiaBin', () => {
-  test('returns the path reported by which/where', () => {
-    execSync.mockReturnValueOnce('/usr/local/bin/loxia\n');
-    expect(newSvc()._findLoxiaBin()).toBe('/usr/local/bin/loxia');
+  test('returns the path reported by which/where', async () => {
+    execBehavior = () => ({ stdout: '/usr/local/bin/loxia\n', stderr: '' });
+    expect(await newSvc()._findLoxiaBin()).toBe('/usr/local/bin/loxia');
   });
 
-  test('falls back to the local cli.js when which/where fails', () => {
-    execSync.mockImplementationOnce(() => { throw new Error('not found'); });
-    expect(newSvc()._findLoxiaBin()).toMatch(/cli\.js/);
+  test('falls back to the local cli.js when which/where fails', async () => {
+    execBehavior = () => new Error('not found');
+    expect(await newSvc()._findLoxiaBin()).toMatch(/cli\.js/);
   });
 });
 
@@ -420,72 +464,62 @@ describe('_syncToOS routing', () => {
 describe('crontab sync (posix)', () => {
   beforeEach(() => setPlatform('linux'));
 
-  test('replaces this schedule’s line, preserves unrelated lines', () => {
-    execSync.mockImplementation((cmd) => {
-      if (String(cmd).includes('crontab -l')) {
-        return '0 0 * * * /other/job # loxia-schedule:OTHER\n* * * * * old # loxia-schedule:s1\n';
-      }
-      return '';
-    });
+  test('replaces this schedule’s line, preserves unrelated lines', async () => {
+    execBehavior = (cmd) => cmd.includes('crontab -l')
+      ? { stdout: '0 0 * * * /other/job # loxia-schedule:OTHER\n* * * * * old # loxia-schedule:s1\n', stderr: '' }
+      : { stdout: '', stderr: '' };
     const svc = newSvc();
-    svc._syncToCrontab({ id: 's1', cronExpression: '0 9 * * *' }, 'loxia trigger-schedule s1');
+    await svc._syncToCrontab({ id: 's1', cronExpression: '0 9 * * *' }, 'loxia trigger-schedule s1');
 
-    const writeCall = execSync.mock.calls.find((c) => c[0] === 'crontab -');
-    expect(writeCall).toBeTruthy();
-    const written = writeCall[1].input;
-    expect(written).toContain('loxia-schedule:OTHER');          // unrelated kept
-    expect(written).toContain('0 9 * * * loxia trigger-schedule s1 # loxia-schedule:s1'); // new entry
-    expect(written).not.toContain('old # loxia-schedule:s1');    // stale entry dropped
+    const write = spawnCalls.find((c) => c.cmd === 'crontab' && c.args[0] === '-');
+    expect(write).toBeTruthy();
+    expect(write.input).toContain('loxia-schedule:OTHER');          // unrelated kept
+    expect(write.input).toContain('0 9 * * * loxia trigger-schedule s1 # loxia-schedule:s1'); // new entry
+    expect(write.input).not.toContain('old # loxia-schedule:s1');   // stale entry dropped
   });
 
-  test('_removeFromCrontab with no existing crontab does not write', () => {
-    execSync.mockImplementation((cmd) => {
-      if (String(cmd).includes('crontab -l')) throw new Error('no crontab');
-      return '';
-    });
+  test('_removeFromCrontab with no existing crontab does not write', async () => {
+    execBehavior = (cmd) => cmd.includes('crontab -l') ? new Error('no crontab') : { stdout: '', stderr: '' };
     const svc = newSvc();
-    svc._removeFromCrontab('s1');
-    expect(execSync.mock.calls.some((c) => c[0] === 'crontab -')).toBe(false);
+    await svc._removeFromCrontab('s1');
+    expect(spawnCalls.some((c) => c.cmd === 'crontab')).toBe(false);
   });
 
-  test('_removeFromCrontab strips this schedule’s line', () => {
-    execSync.mockImplementation((cmd) => {
-      if (String(cmd).includes('crontab -l')) {
-        return '* * * * * x # loxia-schedule:s1\n0 0 * * * y # loxia-schedule:keep\n';
-      }
-      return '';
-    });
+  test('_removeFromCrontab strips this schedule’s line', async () => {
+    execBehavior = (cmd) => cmd.includes('crontab -l')
+      ? { stdout: '* * * * * x # loxia-schedule:s1\n0 0 * * * y # loxia-schedule:keep\n', stderr: '' }
+      : { stdout: '', stderr: '' };
     const svc = newSvc();
-    svc._removeFromCrontab('s1');
-    const writeCall = execSync.mock.calls.find((c) => c[0] === 'crontab -');
-    expect(writeCall[1].input).toContain('loxia-schedule:keep');
-    expect(writeCall[1].input).not.toContain('loxia-schedule:s1');
+    await svc._removeFromCrontab('s1');
+    const write = spawnCalls.find((c) => c.cmd === 'crontab');
+    expect(write.input).toContain('loxia-schedule:keep');
+    expect(write.input).not.toContain('loxia-schedule:s1');
   });
 });
 
 describe('schtasks sync (win32)', () => {
   beforeEach(() => setPlatform('win32'));
 
-  test('deletes then creates the task for a simple cron', () => {
+  test('deletes then creates the task for a simple cron', async () => {
     const svc = newSvc();
-    svc._syncToWindows({ id: 's1', cronExpression: '0 9 * * *' }, 'loxia trigger-schedule s1');
-    const cmds = execSync.mock.calls.map((c) => String(c[0]));
+    await svc._syncToWindows({ id: 's1', cronExpression: '0 9 * * *' }, 'loxia trigger-schedule s1');
+    const cmds = execMock.mock.calls.map((c) => String(c[0]));
     expect(cmds.some((c) => c.includes('/Delete') && c.includes('LoxiaSchedule_s1'))).toBe(true);
     expect(cmds.some((c) => c.includes('/Create') && c.includes('/TN "LoxiaSchedule_s1"'))).toBe(true);
   });
 
-  test('a cron schtasks can’t express is skipped (delete only) with a warning', () => {
+  test('a cron schtasks can’t express is skipped (delete only) with a warning', async () => {
     const svc = newSvc();
-    svc._syncToWindows({ id: 's2', cronExpression: '*/7 3 * * *' }, 'cmd');
-    const cmds = execSync.mock.calls.map((c) => String(c[0]));
+    await svc._syncToWindows({ id: 's2', cronExpression: '*/7 3 * * *' }, 'cmd');
+    const cmds = execMock.mock.calls.map((c) => String(c[0]));
     expect(cmds.some((c) => c.includes('/Create'))).toBe(false);
     expect(svc.logger.warn).toHaveBeenCalled();
   });
 
-  test('_removeFromWindows deletes the task', () => {
+  test('_removeFromWindows deletes the task', async () => {
     const svc = newSvc();
-    svc._removeFromWindows('s3');
-    expect(execSync.mock.calls.some((c) => String(c[0]).includes('/Delete') && String(c[0]).includes('LoxiaSchedule_s3'))).toBe(true);
+    await svc._removeFromWindows('s3');
+    expect(execMock.mock.calls.some((c) => String(c[0]).includes('/Delete') && String(c[0]).includes('LoxiaSchedule_s3'))).toBe(true);
   });
 });
 
@@ -507,6 +541,45 @@ describe('_cronToSchtasksArgs', () => {
   });
 });
 
+describe('OS-sync is async + serialized (non-blocking)', () => {
+  test('_runSerialized runs tasks strictly in order and survives a rejection', async () => {
+    const svc = newSvc();
+    const order = [];
+    const p1 = svc._runSerialized(async () => { await new Promise(r => setImmediate(r)); order.push(1); });
+    const p2 = svc._runSerialized(async () => { throw new Error('boom'); });
+    const p3 = svc._runSerialized(async () => { order.push(3); });
+    await Promise.allSettled([p1, p2, p3]);
+    expect(order).toEqual([1, 3]);           // #2 rejected, but #3 still ran, after #1
+    await expect(p2).rejects.toThrow('boom'); // the rejection is surfaced to its caller
+  });
+
+  test('_execWithInput writes to stdin and resolves on a clean exit', async () => {
+    const svc = newSvc();
+    await svc._execWithInput('crontab', ['-'], 'my-crontab\n');
+    expect(spawnCalls.find(c => c.cmd === 'crontab').input).toBe('my-crontab\n');
+  });
+
+  test('_execWithInput rejects on a non-zero exit', async () => {
+    spawnExitCode = 1;
+    await expect(newSvc()._execWithInput('crontab', ['-'], 'x')).rejects.toThrow(/exited 1/);
+  });
+
+  test('_execWithInput rejects on a spawn error', async () => {
+    spawnError = new Error('ENOENT crontab');
+    await expect(newSvc()._execWithInput('crontab', ['-'], 'x')).rejects.toThrow('ENOENT crontab');
+  });
+
+  test('createSchedule returns without awaiting OS sync (fire-and-forget)', async () => {
+    // A slow OS sync must not block the API path.
+    const svc = newSvc();
+    const sync = jest.spyOn(svc, '_syncToOS').mockReturnValue(new Promise(() => {})); // never resolves
+    const created = await svc.createSchedule(VALID);
+    expect(created.id).toBeTruthy();       // returned despite the pending sync
+    expect(sync).toHaveBeenCalled();
+    sync.mockRestore();
+  });
+});
+
 // ─────────────────────── _tick edge branches ───────────────────────
 
 const pastISO = () => new Date(Date.now() - 60 * 1000).toISOString();