@serfab/cadre-host 0.7.1

package/src/server/static.ts

@@ -0,0 +1,191 @@
+/**
+ * Static-asset mount for the SPA bundle.
+ *
+ * The SPA bundle is produced by `6.5.2-cadre-host-local-ui-spa` into
+ * `<package>/dist/ui/`. When that directory exists we serve files from it
+ * with an `index.html` SPA fallback. When it's missing (running from source
+ * before the SPA ticket lands) we serve a placeholder page that explains
+ * how to install/build the SPA.
+ *
+ * Hand-rolled rather than pulling in `@fastify/static` — the surface area we
+ * need is tiny and the dep would only matter under tests that don't exercise
+ * static serving anyway.
+ */
+
+import { readFileSync, statSync, existsSync } from 'node:fs';
+import { dirname, extname, join, normalize, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import type { FastifyInstance, FastifyReply, FastifyRequest } from 'fastify';
+import debug from 'debug';
+
+const log = debug('cadre:host:static');
+
+const MIME_TYPES: Record<string, string> = {
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'application/javascript; charset=utf-8',
+  '.mjs': 'application/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.ico': 'image/x-icon',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+  '.txt': 'text/plain; charset=utf-8',
+  '.map': 'application/json; charset=utf-8',
+};
+
+/**
+ * Default location of the SPA bundle when `cadre-host` runs from its
+ * installed package.
+ * - dist/server/static.js → ../ui  → packages/cadre-host/dist/ui
+ */
+export function defaultStaticRoot(): string {
+  const here = dirname(fileURLToPath(import.meta.url));
+  return resolve(here, '..', 'ui');
+}
+
+export interface StaticMountOptions {
+  /** Absolute path to the SPA build output (defaults to `defaultStaticRoot()`). */
+  rootDir?: string;
+}
+
+export function registerStaticMount(app: FastifyInstance, opts: StaticMountOptions = {}): void {
+  const rootDir = opts.rootDir ?? defaultStaticRoot();
+
+  // Register *after* all routes so API paths win.
+  app.setNotFoundHandler((request: FastifyRequest, reply: FastifyReply) => {
+    if (request.method !== 'GET' && request.method !== 'HEAD') {
+      return reply.code(404).send({
+        ok: false,
+        error: { code: 'not_found', message: `No route for ${request.method} ${request.url}` },
+      });
+    }
+    // Don't try to serve API paths as static.
+    if (
+      request.url.startsWith('/api') ||
+      request.url.startsWith('/auth') ||
+      request.url.startsWith('/nat') ||
+      request.url.startsWith('/update')
+    ) {
+      return reply.code(404).send({
+        ok: false,
+        error: { code: 'not_found', message: `No route for ${request.method} ${request.url}` },
+      });
+    }
+    return serveStatic(rootDir, request, reply);
+  });
+}
+
+function serveStatic(rootDir: string, request: FastifyRequest, reply: FastifyReply): FastifyReply {
+  if (!existsSync(rootDir)) {
+    if (request.url === '/' || request.url === '/index.html') {
+      return reply.code(200).type('text/html; charset=utf-8').send(placeholderHtml());
+    }
+    return reply.code(404).send({
+      ok: false,
+      error: { code: 'not_found', message: 'SPA bundle not installed' },
+    });
+  }
+
+  const requested = stripQuery(request.url);
+  const target = resolveSafe(rootDir, requested);
+  if (!target) {
+    return reply.code(404).send({
+      ok: false,
+      error: { code: 'not_found', message: `No static asset for ${request.url}` },
+    });
+  }
+  try {
+    const stat = statSync(target);
+    if (stat.isFile()) return sendFile(reply, target);
+  } catch {
+    // fall through to SPA index
+  }
+  // SPA fallback: serve index.html for any GET that accepts HTML.
+  const accept = (request.headers.accept ?? '').toLowerCase();
+  if (accept.includes('text/html') || accept === '' || accept === '*/*') {
+    const index = join(rootDir, 'index.html');
+    if (existsSync(index)) return sendFile(reply, index);
+  }
+  return reply.code(404).send({
+    ok: false,
+    error: { code: 'not_found', message: `No static asset for ${request.url}` },
+  });
+}
+
+function resolveSafe(rootDir: string, urlPath: string): string | null {
+  const cleaned = decodeSafe(urlPath);
+  if (cleaned === null) return null;
+  const target = normalize(join(rootDir, cleaned === '/' ? '' : cleaned));
+  // Disallow path traversal above rootDir.
+  if (!target.startsWith(normalize(rootDir))) return null;
+  return target;
+}
+
+function decodeSafe(urlPath: string): string | null {
+  try {
+    const decoded = decodeURIComponent(urlPath);
+    if (decoded.includes('\0')) return null;
+    return decoded;
+  } catch {
+    return null;
+  }
+}
+
+function stripQuery(url: string): string {
+  const q = url.indexOf('?');
+  return q === -1 ? url : url.slice(0, q);
+}
+
+function sendFile(reply: FastifyReply, path: string): FastifyReply {
+  const buf = readFileSync(path);
+  const mime = MIME_TYPES[extname(path).toLowerCase()] ?? 'application/octet-stream';
+  return reply.code(200).type(mime).send(buf);
+}
+
+function placeholderHtml(): string {
+  return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>cadre-host — UI bundle missing</title>
+    <style>
+      body { font-family: system-ui, -apple-system, sans-serif; max-width: 40rem; margin: 4rem auto; padding: 0 1rem; color: #1a1a1a; }
+      h1 { font-weight: 600; }
+      code { background: #f4f4f4; padding: 0.125rem 0.375rem; border-radius: 0.25rem; }
+      pre { background: #f4f4f4; padding: 0.75rem 1rem; border-radius: 0.5rem; overflow: auto; }
+      .endpoint { font-family: ui-monospace, monospace; }
+    </style>
+  </head>
+  <body>
+    <h1>cadre-host is running — UI bundle is missing</h1>
+    <p>
+      The HTTP management API is fully available (see endpoints below), but the
+      Svelte SPA that normally renders at this URL hasn't been built into this
+      install. This page is most likely shown because the package was started
+      from a source checkout without running the UI build step.
+    </p>
+    <p>To build it:</p>
+    <pre>yarn workspace @serfab/cadre-host build</pre>
+    <p>or just the UI:</p>
+    <pre>yarn workspace @serfab/cadre-host build:ui</pre>
+    <p>Then refresh this page.</p>
+
+    <h2 style="font-size:1.1rem;margin-top:2rem;">Available API endpoints</h2>
+    <ul>
+      <li><span class="endpoint">GET /api/status</span></li>
+      <li><span class="endpoint">GET /api/nodes</span></li>
+      <li><span class="endpoint">GET /api/settings</span></li>
+      <li><span class="endpoint">GET /api/events</span> (Server-Sent Events)</li>
+      <li><span class="endpoint">/auth/*</span>, <span class="endpoint">/nat/*</span>, <span class="endpoint">/update/*</span></li>
+    </ul>
+    <p>See <a href="https://github.com/gotchoices/sereus/blob/master/docs/cadre-host.md">docs/cadre-host.md</a>.</p>
+  </body>
+</html>
+`;
+}

package/src/update/__tests__/apply.test.ts

@@ -0,0 +1,101 @@
+import { describe, expect, it } from 'vitest';
+
+import { applyUpdate, type NpmExecutor, type NpmResult } from '../apply.js';
+import { UpdateErrorException } from '../types.js';
+
+function recordingExecutor(responses: NpmResult[]): { exec: NpmExecutor; calls: string[][] } {
+  const calls: string[][] = [];
+  let i = 0;
+  return {
+    calls,
+    async exec(args) {
+      calls.push(args);
+      const res = responses[i++] ?? { exitCode: 0, stdout: '', stderr: '' };
+      return res;
+    },
+  };
+}
+
+describe('applyUpdate', () => {
+  it('happy path: install succeeds, restart called', async () => {
+    const { exec, calls } = recordingExecutor([{ exitCode: 0, stdout: 'ok', stderr: '' }]);
+    let restartCount = 0;
+    const result = await applyUpdate({
+      npmPackage: '@serfab/cadre-host',
+      fromVersion: '0.6.0',
+      toVersion: '0.7.0',
+      npmExecutor: exec,
+      restart: async () => { restartCount++; return undefined; },
+    });
+    expect(calls).toEqual([['install', '-g', '@serfab/cadre-host@0.7.0']]);
+    expect(restartCount).toBe(1);
+    expect(result).toMatchObject({ fromVersion: '0.6.0', toVersion: '0.7.0', restarted: true });
+  });
+
+  it('install succeeds but restart fails: result reports restartError, no throw', async () => {
+    const { exec } = recordingExecutor([{ exitCode: 0, stdout: 'ok', stderr: '' }]);
+    const result = await applyUpdate({
+      npmPackage: '@serfab/cadre-host',
+      fromVersion: '0.6.0',
+      toVersion: '0.7.0',
+      npmExecutor: exec,
+      restart: async () => 'systemctl returned 1',
+    });
+    expect(result.restarted).toBe(false);
+    expect(result.restartError).toBe('systemctl returned 1');
+  });
+
+  it('install fails: rollback invoked, restart NOT called, throws apply_failed', async () => {
+    const { exec, calls } = recordingExecutor([
+      { exitCode: 1, stdout: '', stderr: 'EACCES' },
+      { exitCode: 0, stdout: 'rolled back', stderr: '' },
+    ]);
+    let restartCount = 0;
+    await expect(applyUpdate({
+      npmPackage: '@serfab/cadre-host',
+      fromVersion: '0.6.0',
+      toVersion: '0.7.0',
+      npmExecutor: exec,
+      restart: async () => { restartCount++; return undefined; },
+    })).rejects.toBeInstanceOf(UpdateErrorException);
+    expect(calls).toEqual([
+      ['install', '-g', '@serfab/cadre-host@0.7.0'],
+      ['install', '-g', '@serfab/cadre-host@0.6.0'],
+    ]);
+    expect(restartCount).toBe(0);
+  });
+
+  it('install fails and rollback also fails: throws rollback_failed', async () => {
+    const { exec } = recordingExecutor([
+      { exitCode: 1, stdout: '', stderr: 'EACCES' },
+      { exitCode: 1, stdout: '', stderr: 'EACCES on rollback' },
+    ]);
+    await expect(applyUpdate({
+      npmPackage: '@serfab/cadre-host',
+      fromVersion: '0.6.0',
+      toVersion: '0.7.0',
+      npmExecutor: exec,
+    })).rejects.toMatchObject({ code: 'rollback_failed' });
+  });
+
+  it('install throws (spawn error): rollback still attempted', async () => {
+    let i = 0;
+    const calls: string[][] = [];
+    const exec: NpmExecutor = async (args) => {
+      calls.push(args);
+      i++;
+      if (i === 1) throw new Error('ENOENT npm');
+      return { exitCode: 0, stdout: '', stderr: '' };
+    };
+    await expect(applyUpdate({
+      npmPackage: '@serfab/cadre-host',
+      fromVersion: '0.6.0',
+      toVersion: '0.7.0',
+      npmExecutor: exec,
+    })).rejects.toMatchObject({ code: 'apply_failed' });
+    expect(calls).toEqual([
+      ['install', '-g', '@serfab/cadre-host@0.7.0'],
+      ['install', '-g', '@serfab/cadre-host@0.6.0'],
+    ]);
+  });
+});

package/src/update/__tests__/manifest.test.ts

@@ -0,0 +1,93 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { generateKeyPairSync, type KeyObject } from 'node:crypto';
+
+import { canonicalJson, signManifestForTesting, verifyManifest } from '../manifest.js';
+import type { UpdateManifest } from '../types.js';
+
+/** Generate a fresh Ed25519 keypair and surface the raw 32-byte public key. */
+function freshKeypair(): { publicKey: KeyObject; privateKey: KeyObject; publicRawB64: string } {
+  const { publicKey, privateKey } = generateKeyPairSync('ed25519');
+  // Extract the raw 32-byte public key from SPKI DER (strip the 12-byte header).
+  const spki = publicKey.export({ format: 'der', type: 'spki' });
+  const raw = spki.subarray(12);
+  return { publicKey, privateKey, publicRawB64: Buffer.from(raw).toString('base64') };
+}
+
+const sampleManifest: UpdateManifest = {
+  v: 1,
+  version: '0.7.0',
+  publishedAt: '2026-05-15T18:00:00.000Z',
+  channels: { npm: { package: '@serfab/cadre-host', tag: 'latest' } },
+  releaseNotesUrl: 'https://example.com/notes',
+  minPreviousVersion: '0.6.0',
+};
+
+describe('canonicalJson', () => {
+  it('sorts keys deterministically and omits whitespace', () => {
+    expect(canonicalJson({ b: 1, a: 2 })).toBe('{"a":2,"b":1}');
+    expect(canonicalJson({ outer: { z: 1, a: 2 }, top: true })).toBe('{"outer":{"a":2,"z":1},"top":true}');
+    expect(canonicalJson([3, 2, 1])).toBe('[3,2,1]');
+  });
+
+  it('omits undefined fields', () => {
+    expect(canonicalJson({ a: 1, b: undefined })).toBe('{"a":1}');
+  });
+});
+
+describe('verifyManifest', () => {
+  let kp: ReturnType<typeof freshKeypair>;
+
+  beforeEach(() => {
+    kp = freshKeypair();
+    process.env.CADRE_HOST_UPDATE_DEV_KEY = kp.publicRawB64;
+  });
+
+  afterEach(() => {
+    delete process.env.CADRE_HOST_UPDATE_DEV_KEY;
+  });
+
+  it('round-trips: sign + verify', () => {
+    const envelope = signManifestForTesting(sampleManifest, kp.privateKey);
+    const out = verifyManifest(envelope);
+    expect(out).toEqual(sampleManifest);
+  });
+
+  it('rejects a mutated payload (signature_invalid)', () => {
+    const envelope = signManifestForTesting(sampleManifest, kp.privateKey);
+    const tampered = { ...envelope, manifest: { ...envelope.manifest, version: '99.0.0' } };
+    expect(() => verifyManifest(tampered)).toThrow(/signature/i);
+  });
+
+  it('rejects a mutated signature (signature_invalid)', () => {
+    const envelope = signManifestForTesting(sampleManifest, kp.privateKey);
+    const sigBytes = Buffer.from(envelope.sig.slice('ed25519:'.length), 'base64');
+    sigBytes[0] ^= 0xff;
+    const tampered = { ...envelope, sig: `ed25519:${sigBytes.toString('base64')}` };
+    expect(() => verifyManifest(tampered)).toThrow(/signature/i);
+  });
+
+  it('rejects an envelope signed by a different key (signature_invalid)', () => {
+    const envelope = signManifestForTesting(sampleManifest, kp.privateKey);
+    // Swap the env-configured public key to a different fresh one.
+    const other = freshKeypair();
+    process.env.CADRE_HOST_UPDATE_DEV_KEY = other.publicRawB64;
+    expect(() => verifyManifest(envelope)).toThrow(/signature/i);
+  });
+
+  it('rejects malformed envelopes (manifest_invalid)', () => {
+    expect(() => verifyManifest(null)).toThrow(/malformed/);
+    expect(() => verifyManifest({})).toThrow(/malformed/);
+    expect(() => verifyManifest({ manifest: 'nope', sig: 'ed25519:AAAA' })).toThrow(/malformed/);
+  });
+
+  it('rejects manifests missing required fields (manifest_invalid)', () => {
+    const bad = { manifest: { v: 1, version: '0.7.0' }, sig: 'ed25519:AAAA' };
+    expect(() => verifyManifest(bad)).toThrow(/missing required fields/);
+  });
+
+  it('rejects unsupported signature schemes', () => {
+    const envelope = signManifestForTesting(sampleManifest, kp.privateKey);
+    const tampered = { ...envelope, sig: envelope.sig.replace('ed25519:', 'rsa:') };
+    expect(() => verifyManifest(tampered)).toThrow(/unsupported signature scheme/);
+  });
+});

package/src/update/__tests__/store.test.ts

@@ -0,0 +1,81 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { UpdateStateStore } from '../store.js';
+import type { UpdateState } from '../types.js';
+
+describe('UpdateStateStore', () => {
+  let tmp: string;
+
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), 'cadre-update-store-'));
+  });
+
+  afterEach(() => {
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it('returns an empty state when the file is missing', () => {
+    const store = new UpdateStateStore(tmp);
+    expect(store.load()).toEqual({ version: 1 });
+  });
+
+  it('round-trips a populated state', () => {
+    const store = new UpdateStateStore(tmp);
+    const state: UpdateState = {
+      version: 1,
+      lastChecked: '2026-05-15T18:00:00.000Z',
+      available: {
+        version: '0.7.0',
+        publishedAt: '2026-05-15T18:00:00.000Z',
+        releaseNotesUrl: 'https://example.com/notes',
+      },
+      applyInProgress: {
+        fromVersion: '0.6.0',
+        toVersion: '0.7.0',
+        startedAt: '2026-05-15T18:01:00.000Z',
+      },
+      lastError: {
+        code: 'apply_failed',
+        message: 'npm fell over',
+        at: '2026-05-15T18:02:00.000Z',
+      },
+    };
+    store.save(state);
+
+    // Re-open to bypass the in-memory cache.
+    const reopened = new UpdateStateStore(tmp);
+    expect(reopened.load()).toEqual(state);
+  });
+
+  it('rejects unsupported state versions', () => {
+    writeFileSync(join(tmp, 'update-state.json'), JSON.stringify({ version: 99 }));
+    const store = new UpdateStateStore(tmp);
+    expect(() => store.load()).toThrow(/unsupported version/);
+  });
+
+  it('rejects malformed JSON', () => {
+    writeFileSync(join(tmp, 'update-state.json'), 'definitely not json');
+    const store = new UpdateStateStore(tmp);
+    expect(() => store.load()).toThrow(/not valid JSON/);
+  });
+
+  it('update() merges patches into the persisted state', () => {
+    const store = new UpdateStateStore(tmp);
+    store.update({ lastChecked: '2026-05-15T18:00:00.000Z' });
+    store.update({ available: { version: '0.7.0', publishedAt: '2026-05-15T18:00:00.000Z' } });
+    const state = store.load();
+    expect(state.lastChecked).toBe('2026-05-15T18:00:00.000Z');
+    expect(state.available).toEqual({ version: '0.7.0', publishedAt: '2026-05-15T18:00:00.000Z' });
+  });
+
+  it('clearField() drops a key from the persisted state', () => {
+    const store = new UpdateStateStore(tmp);
+    store.update({ available: { version: '0.7.0', publishedAt: '2026-05-15T18:00:00.000Z' } });
+    store.clearField('available');
+    const reopened = new UpdateStateStore(tmp);
+    expect(reopened.load().available).toBeUndefined();
+  });
+});

package/src/update/__tests__/update-service.integration.test.ts

@@ -0,0 +1,221 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { generateKeyPairSync, type KeyObject } from 'node:crypto';
+
+import { signManifestForTesting } from '../manifest.js';
+import { UpdateService } from '../index.js';
+import type { UpdateManifest } from '../types.js';
+
+function freshKeypair(): { privateKey: KeyObject; publicRawB64: string } {
+  const { publicKey, privateKey } = generateKeyPairSync('ed25519');
+  const spki = publicKey.export({ format: 'der', type: 'spki' });
+  return { privateKey, publicRawB64: Buffer.from(spki.subarray(12)).toString('base64') };
+}
+
+function manifest(version: string, opts: Partial<UpdateManifest> = {}): UpdateManifest {
+  return {
+    v: 1,
+    version,
+    publishedAt: '2026-05-15T18:00:00.000Z',
+    channels: { npm: { package: '@serfab/cadre-host', tag: 'latest' } },
+    ...opts,
+  };
+}
+
+function fakeFetch(envelope: unknown): typeof fetch {
+  return (async (_url: string, _init?: RequestInit) => {
+    return {
+      ok: true,
+      status: 200,
+      json: async () => envelope,
+    } as Response;
+  }) as typeof fetch;
+}
+
+describe('UpdateService', () => {
+  let tmp: string;
+  let kp: ReturnType<typeof freshKeypair>;
+
+  beforeEach(() => {
+    tmp = mkdtempSync(join(tmpdir(), 'cadre-update-svc-'));
+    kp = freshKeypair();
+    process.env.CADRE_HOST_UPDATE_DEV_KEY = kp.publicRawB64;
+  });
+
+  afterEach(() => {
+    delete process.env.CADRE_HOST_UPDATE_DEV_KEY;
+    rmSync(tmp, { recursive: true, force: true });
+  });
+
+  it('check(): records an available update when manifest > current', async () => {
+    const envelope = signManifestForTesting(manifest('0.7.0', { releaseNotesUrl: 'https://x' }), kp.privateKey);
+    const svc = new UpdateService({
+      dataDir: tmp,
+      currentVersion: '0.6.0',
+      fetcher: fakeFetch(envelope),
+      manifestUrl: 'https://example.com/m',
+    });
+    await svc.check();
+    const state = await svc.getState();
+    expect(state.available).toEqual({
+      version: '0.7.0',
+      publishedAt: '2026-05-15T18:00:00.000Z',
+      releaseNotesUrl: 'https://x',
+    });
+    expect(state.lastChecked).toBeDefined();
+    expect(state.lastError).toBeUndefined();
+  });
+
+  it('check(): clears stale available when up-to-date', async () => {
+    const envelope = signManifestForTesting(manifest('0.6.0'), kp.privateKey);
+    const svc = new UpdateService({
+      dataDir: tmp,
+      currentVersion: '0.7.0',
+      fetcher: fakeFetch(envelope),
+      manifestUrl: 'https://example.com/m',
+    });
+    await svc.check();
+    const state = await svc.getState();
+    expect(state.available).toBeUndefined();
+    expect(state.lastChecked).toBeDefined();
+  });
+
+  it('check(): silent on network failure', async () => {
+    const svc = new UpdateService({
+      dataDir: tmp,
+      currentVersion: '0.6.0',
+      fetcher: (async () => { throw new Error('ECONNREFUSED'); }) as typeof fetch,
+      manifestUrl: 'https://example.com/m',
+    });
+    await svc.check();
+    const state = await svc.getState();
+    expect(state.lastChecked).toBeUndefined();
+    expect(state.lastError).toBeUndefined();
+  });
+
+  it('check(): records signature_invalid as lastError', async () => {
+    const envelope = signManifestForTesting(manifest('0.7.0'), kp.privateKey);
+    // Swap the trusted key after signing.
+    const other = freshKeypair();
+    process.env.CADRE_HOST_UPDATE_DEV_KEY = other.publicRawB64;
+    const svc = new UpdateService({
+      dataDir: tmp,
+      currentVersion: '0.6.0',
+      fetcher: fakeFetch(envelope),
+      manifestUrl: 'https://example.com/m',
+    });
+    await svc.check();
+    const state = await svc.getState();
+    expect(state.lastError?.code).toBe('signature_invalid');
+    expect(state.available).toBeUndefined();
+  });
+
+  it('apply(): records applyInProgress, calls npm + restart, clears on success', async () => {
+    const envelope = signManifestForTesting(manifest('0.7.0'), kp.privateKey);
+    const calls: string[][] = [];
+    const svc = new UpdateService({
+      dataDir: tmp,
+      currentVersion: '0.6.0',
+      fetcher: fakeFetch(envelope),
+      manifestUrl: 'https://example.com/m',
+      npmExecutor: async (args) => { calls.push(args); return { exitCode: 0, stdout: '', stderr: '' }; },
+      restart: async () => undefined,
+    });
+    const result = await svc.apply();
+    expect(result).toMatchObject({ fromVersion: '0.6.0', toVersion: '0.7.0', restarted: true });
+    expect(calls).toEqual([['install', '-g', '@serfab/cadre-host@0.7.0']]);
+    const state = await svc.getState();
+    expect(state.applyInProgress).toBeUndefined();
+    expect(state.lastError).toBeUndefined();
+  });
+
+  it('apply(): rejects when current is below minPreviousVersion', async () => {
+    const envelope = signManifestForTesting(manifest('0.8.0', { minPreviousVersion: '0.7.0' }), kp.privateKey);
+    const svc = new UpdateService({
+      dataDir: tmp,
+      currentVersion: '0.6.0',
+      fetcher: fakeFetch(envelope),
+      manifestUrl: 'https://example.com/m',
+    });
+    await expect(svc.apply()).rejects.toMatchObject({ code: 'min_previous_version' });
+  });
+
+  it('apply(): rejects when current >= latest', async () => {
+    const envelope = signManifestForTesting(manifest('0.6.0'), kp.privateKey);
+    const svc = new UpdateService({
+      dataDir: tmp,
+      currentVersion: '0.7.0',
+      fetcher: fakeFetch(envelope),
+      manifestUrl: 'https://example.com/m',
+    });
+    await expect(svc.apply()).rejects.toMatchObject({ code: 'no_update_available' });
+  });
+
+  it('apply(): records lastError + clears applyInProgress when npm install fails', async () => {
+    const envelope = signManifestForTesting(manifest('0.7.0'), kp.privateKey);
+    let installCount = 0;
+    const svc = new UpdateService({
+      dataDir: tmp,
+      currentVersion: '0.6.0',
+      fetcher: fakeFetch(envelope),
+      manifestUrl: 'https://example.com/m',
+      npmExecutor: async () => {
+        installCount++;
+        return { exitCode: installCount === 1 ? 1 : 0, stdout: '', stderr: installCount === 1 ? 'EACCES' : '' };
+      },
+    });
+    await expect(svc.apply()).rejects.toMatchObject({ code: 'apply_failed' });
+    const state = await svc.getState();
+    expect(state.applyInProgress).toBeUndefined();
+    expect(state.lastError?.code).toBe('apply_failed');
+  });
+
+  it('settings: onSettingsChanged fires when putSettings mutates state', async () => {
+    const svc = new UpdateService({
+      dataDir: tmp,
+      currentVersion: '0.6.0',
+      fetcher: fakeFetch({}),
+      manifestUrl: 'https://example.com/m',
+      settings: { autoApply: false },
+    });
+    let observed: { autoApply: boolean } | null = null;
+    svc.onSettingsChanged((next) => { observed = { autoApply: next.autoApply }; });
+    await svc.putSettings({ autoApply: true });
+    expect(observed).toEqual({ autoApply: true });
+    expect(svc.getSettings().autoApply).toBe(true);
+  });
+
+  it('autoApply: check() triggers apply when settings.autoApply is true', async () => {
+    const envelope = signManifestForTesting(manifest('0.7.0'), kp.privateKey);
+    const calls: string[][] = [];
+    const svc = new UpdateService({
+      dataDir: tmp,
+      currentVersion: '0.6.0',
+      fetcher: fakeFetch(envelope),
+      manifestUrl: 'https://example.com/m',
+      settings: { autoApply: true },
+      npmExecutor: async (args) => { calls.push(args); return { exitCode: 0, stdout: '', stderr: '' }; },
+      restart: async () => undefined,
+    });
+    await svc.check();
+    expect(calls.some((c) => c[2] === '@serfab/cadre-host@0.7.0')).toBe(true);
+  });
+
+  it('start()/stop(): timer can be armed and cleared', async () => {
+    const svc = new UpdateService({
+      dataDir: tmp,
+      currentVersion: '0.6.0',
+      fetcher: (async () => { throw new Error('no'); }) as typeof fetch,
+      manifestUrl: 'https://example.com/m',
+      checkIntervalMs: 1_000_000,
+    });
+    svc.start();
+    // Calling start a second time is a no-op (no thrown error).
+    svc.start();
+    svc.stop();
+    // Calling stop without an active timer is safe.
+    svc.stop();
+  });
+});