Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

84.6 KB
Raw Blame
import { describe, it, expect, vi, beforeEach, afterEach, afterAll } from 'vitest';
import express from 'express';
import { request } from '../lib/testHelper.js';

const settingsDataRoot = await vi.hoisted(async () => {
  const { mkdtempSync } = await import('node:fs');
  const { tmpdir } = await import('node:os');
  const { join } = await import('node:path');
  return mkdtempSync(join(tmpdir(), 'portos-settings-routes-'));
});
vi.mock('../lib/fileUtils.js', async (importOriginal) => {
  const actual = await importOriginal();
  const { makePathsProxy } = await import('../lib/mockPathsDataRoot.js');
  return makePathsProxy({
    ...actual,
    tryReadFileStrict: vi.fn(actual.tryReadFileStrict),
    atomicWrite: vi.fn(actual.atomicWrite),
  }, { dataRoot: settingsDataRoot });
});
afterAll(async () => {
  const { rmSync } = await import('node:fs');
  rmSync(settingsDataRoot, { recursive: true, force: true });
});

const reconcileEidoverseRuntime = vi.hoisted(() => vi.fn(async () => ({ running: true })));
vi.mock('../services/eidoverseRuntime.js', () => ({ reconcileEidoverseRuntime }));

const clearPendingMergeAssessmentHolds = vi.hoisted(() => vi.fn(async () => {}));
vi.mock('../services/prWatcher.js', () => ({ clearPendingMergeAssessmentHolds }));

// In-memory settings store backing the mocked service.
let store = {};

vi.mock('../services/userActions.js', () => ({ recordUserAction: vi.fn(async () => ({ id: 'evt' })) }));

vi.mock('../services/settings.js', async () => {
  const { EventEmitter } = await import('node:events');
  const settingsEvents = new EventEmitter();
  return {
    settingsEvents,
    refreshSettingsIfChangedOnDisk: vi.fn(),
    getSettings: vi.fn(async () => ({ ...store })),
    getSettingsWithStatus: vi.fn(async () => ({ corrupt: false, settings: { ...store } })),
    updateSettings: vi.fn(async (patch) => {
      store = { ...store, ...patch };
      return { ...store };
    }),
    // The PUT handler uses updateSettingsWith so it can merge the multi-owner
    // federation slice per sub-key and re-inject persisted sub-keys this route
    // does not own but the patch omits (see mergeFederationSlice /
    // preserveExternallyOwnedKeys).
    updateSettingsWith: vi.fn(async (mutate) => {
      store = await mutate({ ...store });
      settingsEvents.emit('settings:updated');
      return { ...store };
    }),
  };
});
// Defaults and settings persistence stay real; inventory probes must not spawn
// CLIs or inspect the install's configured providers in a route test.
vi.mock('../services/codeReview.js', async (importOriginal) => ({
  ...await importOriginal(),
  getReviewerCliInstalled: vi.fn(async () => ({})),
  getProviderReviewUnsupported: vi.fn(async () => ({})),
}));
// The settings route now refuses a standing render route naming a peer that
// could never run it (see services/federatedMedia/routingPolicy.js), so this
// suite owns a peer registry. Mocked rather than real: the routing policy loads
// the registry lazily, and letting it fall through would read this developer's
// own data/instances.json.
let peers = [];
vi.mock('../services/instances.js', () => ({ getPeers: vi.fn(async () => peers) }));
vi.mock('../services/aiAssignments.js', () => ({
  getAiAssignments: vi.fn(async () => ({})),
  updateAiAssignment: vi.fn(async () => ({})),
}));
vi.mock('../services/mediaJobQueue/index.js', () => ({
  setCodexParallelLimit: vi.fn(),
  CODEX_PARALLEL_MIN: 1,
  CODEX_PARALLEL_MAX: 8,
  CODEX_PARALLEL_DEFAULT: 2,
}));
vi.mock('../services/datadog.js', () => ({
  hasConfiguredInstances: vi.fn(async () => false),
}));
vi.mock('../services/jira.js', () => ({
  hasConfiguredInstances: vi.fn(async () => false),
}));
vi.mock('../lib/gitRemote.js', () => ({
  getOriginInfo: vi.fn(async () => ({ isGithub: true, owner: 'example-owner' })),
}));
vi.mock('../services/eidoverse.js', () => ({
  DEFAULT_EIDOVERSE_WORLDS_REPO: 'https://github.com/anima-research/eidoverse-worlds',
  normalizeEidoverseWorldsRepo: vi.fn((url) => url),
  getEidoverseStatus: vi.fn(async () => ({ installed: false, bunAvailable: true, registryAvailable: true })),
  assertEidoverseInstalled: vi.fn(async () => ({ installed: true })),
  setEidoverseWorldsOrigin: vi.fn(async () => ({ appId: 'app-eidoverse' })),
  installEidoverse: vi.fn(async () => ({ installed: true })),
}));
vi.mock('../services/eidoverseHost.js', () => ({
  ensureEidoverseHost: vi.fn(async () => ({ running: true, protocol: 'https', port: 5563 })),
}));
vi.mock('../services/credentialInventory.js', () => ({
  getCredentialInventory: vi.fn(async () => ({ headline: 'Most of PortOS works with no key at all.', credentials: [] })),
}));
// The Beeper feature toggle now reconciles the sweep + realtime transport
// against the gate it just moved (fork issue #1). Mocked here because the real
// module reaches the whole Beeper service graph; what a reconcile actually does
// is covered by services/beeperArming.test.js.
vi.mock('../services/beeperArming.js', () => ({
  reconcileBeeperIngestion: vi.fn(async () => ({ armed: false, changed: false })),
}));
// The interval-change half of fork issue #79: a Beeper save that changes only
// `intervalMinutes` restarts the scheduler directly rather than going through
// `reconcileBeeperIngestion` (that stays reserved for an `enabled` flip). Mocked
// for the same reason `beeperArming.js` is above — what a restart actually does
// is covered by services/beeperScheduler.test.js.
// `isBeeperSchedulerRegistered` defaults to `false` (mimicking a scheduler
// that was never registered) so the existing interval-change tests below,
// which never set this, keep exercising that path; the fork issue #94 test
// under "beeper sync-toggle arming" overrides it to `true` for the
// already-registered case.
vi.mock('../services/beeperScheduler.js', () => ({
  restartBeeperScheduler: vi.fn(async () => {}),
  isBeeperSchedulerRegistered: vi.fn(() => false),
}));

// The iTerm2 bridge connects only while its feature is on (#8114); what a
// reconcile does is covered by services/itermBridge.test.js.
vi.mock('../services/itermBridge.js', () => ({
  reconcileItermBridge: vi.fn(async () => ({ enabled: false, connected: false })),
}));

import settingsRoutes from './settings.js';
import { hostControlBodyGate } from '../services/authGate.js';
import codeReviewRoutes from './codeReview.js';
import { reconcileBeeperIngestion } from '../services/beeperArming.js';
import { reconcileItermBridge } from '../services/itermBridge.js';
import { restartBeeperScheduler, isBeeperSchedulerRegistered } from '../services/beeperScheduler.js';
import { updateSettingsWith } from '../services/settings.js';
import { updateAiAssignment } from '../services/aiAssignments.js';
import { hasConfiguredInstances as hasConfiguredDatadogInstances } from '../services/datadog.js';
import { hasConfiguredInstances as hasConfiguredJiraInstances } from '../services/jira.js';
import { assertEidoverseInstalled, installEidoverse, setEidoverseWorldsOrigin } from '../services/eidoverse.js';
import { ensureEidoverseHost } from '../services/eidoverseHost.js';

const buildApp = () => {
  const app = express();
  app.use(express.json());
  app.use('/api/settings', settingsRoutes);
  app.use('/api/code-review', codeReviewRoutes);
  return app;
};

describe('Settings routes — configured reviewer pins', () => {
  it('persists and clears provider model/effort defaults through settings and defaults readback', async () => {
    store = {};
    const app = buildApp();
    const codeReview = {
      reviewers: ['provider:example-reviewer', 'codex'],
      providerModels: { 'provider:example-reviewer': 'example-model' },
      providerEfforts: { 'provider:example-reviewer': 'high' },
      codexModel: 'gpt-5.6-sol', codexEffort: 'low',
    };
    const saved = await request(app).put('/api/settings').send({ codeReview });
    expect(saved.status).toBe(200);
    const defaults = await request(app).get('/api/code-review/defaults');
    expect(defaults.status).toBe(200);
    expect(defaults.body).toMatchObject(codeReview);

    const cleared = { ...codeReview, providerModels: {}, providerEfforts: {} };
    expect((await request(app).put('/api/settings').send({ codeReview: cleared })).status).toBe(200);
    expect((await request(app).get('/api/code-review/defaults')).body).toMatchObject(cleared);
    expect((await request(app).get('/api/settings')).body.codeReview).toEqual(cleared);
  });
});

// The operator-action ledger (#5594) distinguishes a human on the Settings page
// from every other settings writer purely by this argument, so the route has to
// keep passing it. The row it produces is asserted end-to-end in
// services/settings.userActions.test.js.
describe('Settings routes — operator-action actor (#5594)', () => {
  it('marks a settings PUT as a user action', async () => {
    const res = await request(buildApp()).put('/api/settings').send({ timezone: 'America/Los_Angeles' });
    expect(res.status).toBe(200);
    expect(updateSettingsWith).toHaveBeenCalledWith(expect.any(Function), { actor: 'user' });
  });
});

describe('Settings routes — untrusted-content policy', () => {
  beforeEach(() => { store = {}; vi.clearAllMocks(); });
  it('ships classifier-required defaults and persists source-specific constraints', async () => {
    const defaults = await request(buildApp()).get('/api/settings');
    expect(defaults.body.untrustedContent.defaults).toMatchObject({ classifierMode: 'required', minBenignScore: 0.9 });
    const policy = { defaults: { classifierMode: 'required' }, sources: { signal: { providerId: 'local-api', model: 'example-model', maxInputChars: 5000 }, 'github-issue': { classifierMode: 'optional' } } };
    const saved = await request(buildApp()).put('/api/settings').send({ untrustedContent: policy });
    expect(saved.status).toBe(200);
    expect(store.untrustedContent).toEqual(policy);
    expect(clearPendingMergeAssessmentHolds).toHaveBeenCalledTimes(1);
    const read = await request(buildApp()).get('/api/settings');
    expect(read.body.untrustedContent.sources).toEqual(policy.sources);
  });
  it('rejects invalid or weakening policy shapes before replacing the saved settings', async () => {
    store = { untrustedContent: { defaults: { classifierMode: 'required' } } };
    const previous = structuredClone(store);
    for (const patch of [
      { defaults: { classifierMode: 'off' } },
      { sources: { signal: { maxInputChars: 999999999 } } },
      { sources: { email: { providerId: {} } } },
      { defaults: { minBenignScore: 0.1 } },
      { sources: { unknown: {} } },
    ]) {
      const result = await request(buildApp()).put('/api/settings').send({ untrustedContent: patch });
      expect(result.status).toBe(400);
      expect(store).toEqual(previous);
    }
    expect(updateSettingsWith).not.toHaveBeenCalled();
    expect(clearPendingMergeAssessmentHolds).not.toHaveBeenCalled();
  });
});

describe('Settings routes — apiAccess slice', () => {
  beforeEach(() => {
    store = {};
    vi.clearAllMocks();
  });

  it('accepts a valid apiAccess patch and persists it', async () => {
    const res = await request(buildApp())
      .put('/api/settings')
      .send({ apiAccess: { voice: { exposed: true, requireAuth: false } } });
    expect(res.status).toBe(200);
    expect(res.body.apiAccess.voice.exposed).toBe(true);
  });

  it('rejects a non-boolean exposed flag', async () => {
    const res = await request(buildApp())
      .put('/api/settings')
      .send({ apiAccess: { voice: { exposed: 'yes' } } });
    expect(res.status).toBe(400);
    expect(res.body.code).toBe('VALIDATION_ERROR');
  });

  it('rejects unknown keys inside an apiAccess entry (strict)', async () => {
    const res = await request(buildApp())
      .put('/api/settings')
      .send({ apiAccess: { voice: { open: true } } });
    expect(res.status).toBe(400);
  });

  it('rejects an unknown API id (strict)', async () => {
    const res = await request(buildApp())
      .put('/api/settings')
      .send({ apiAccess: { elevenlabs: { exposed: true } } });
    expect(res.status).toBe(400);
  });

  it('GET returns apiAccess (not stripped like secrets)', async () => {
    store = { apiAccess: { sdapi: { exposed: true, requireAuth: false } } };
    const res = await request(buildApp()).get('/api/settings');
    expect(res.status).toBe(200);
    expect(res.body.apiAccess.sdapi.exposed).toBe(true);
  });
});

describe('Settings routes — instance feature participation', () => {
  beforeEach(() => {
    store = {};
    vi.clearAllMocks();
  });

  it('lists local feature participation with the backward-compatible default', async () => {
    const res = await request(buildApp()).get('/api/settings/features');

    expect(res.status).toBe(200);
    expect(res.body.features).toContainEqual(expect.objectContaining({ id: 'post', label: 'POST', enabled: true }));
    // Integration-backed features ride the same list; the suite pins their
    // detector responses so this default is independent of this host's setup.
    expect(res.body.features).toContainEqual(expect.objectContaining({ id: 'datadog', enabled: false, source: 'auto' }));
    expect(res.body.features).toContainEqual(expect.objectContaining({ id: 'jira', enabled: false, source: 'auto' }));
    expect(res.body.features).toContainEqual(expect.objectContaining({
      id: 'eidoverse',
      enabled: false,
      setup: expect.objectContaining({ installed: false }),
    }));
    // GSD and OpenClaw ship disabled by default; the install opts in.
    expect(res.body.features).toContainEqual(expect.objectContaining({ id: 'gsd', enabled: false }));
    expect(res.body.features).toContainEqual(expect.objectContaining({ id: 'cos-task-templates', enabled: false, source: 'default' }));
    expect(res.body.features).toContainEqual(expect.objectContaining({ id: 'openclaw', enabled: false }));
    expect(res.body.features).toContainEqual(expect.objectContaining({ id: 'health', enabled: true }));
    // #40 — iMessage and Signal join the comms group, defaulting to enabled
    // with no settings write, exactly like an existing install saw before.
    expect(res.body.features).toContainEqual(expect.objectContaining({ id: 'imessage', enabled: true, group: 'comms' }));
    expect(res.body.features).toContainEqual(expect.objectContaining({ id: 'signal', enabled: true, group: 'comms' }));
    expect(res.body.groups).toContainEqual(expect.objectContaining({ id: 'comms', enabled: true }));
  });

  it('lists an integration-backed feature as auto-enabled when its detector finds configuration', async () => {
    hasConfiguredDatadogInstances.mockResolvedValueOnce(true);

    const res = await request(buildApp()).get('/api/settings/features');

    expect(res.status).toBe(200);
    expect(res.body.features).toContainEqual(expect.objectContaining({ id: 'datadog', enabled: true, source: 'auto' }));
  });

  it('detects each integration independently, so one configured integration does not enable another', async () => {
    hasConfiguredJiraInstances.mockResolvedValueOnce(true);

    const res = await request(buildApp()).get('/api/settings/features');

    expect(res.status).toBe(200);
    expect(res.body.features).toContainEqual(expect.objectContaining({ id: 'jira', enabled: true, source: 'auto' }));
    // Detection is per-feature; a configured JIRA must not switch Datadog on.
    expect(res.body.features).toContainEqual(expect.objectContaining({ id: 'datadog', enabled: false, source: 'auto' }));
  });

  it('keeps an explicit opt-out off even when the integration is configured', async () => {
    hasConfiguredJiraInstances.mockResolvedValueOnce(true);
    store = { instanceFeatures: { jira: { enabled: false } } };

    const res = await request(buildApp()).get('/api/settings/features');

    expect(res.body.features).toContainEqual(expect.objectContaining({ id: 'jira', enabled: false, source: 'explicit' }));
  });

  it('updates one feature without replacing unrelated settings', async () => {
    store = { theme: 'dark', instanceFeatures: { post: { enabled: true } } };

    const res = await request(buildApp())
      .put('/api/settings/features/post')
      .send({ enabled: false });

    expect(res.status).toBe(200);
    expect(res.body.features).toContainEqual(expect.objectContaining({ id: 'post', enabled: false }));
    expect(store).toEqual({ theme: 'dark', instanceFeatures: { post: { enabled: false } } });
    // Only Beeper's own gate is reconciled; an unrelated toggle must not reach
    // into the Beeper service graph at all.
    expect(reconcileBeeperIngestion).not.toHaveBeenCalled();
  });

  it('reconciles Eidoverse when the general settings save changes its feature gate', async () => {
    const res = await request(buildApp()).put('/api/settings')
      .send({ instanceFeatures: { eidoverse: { enabled: true } } });
    expect(res.status).toBe(200);
    expect(store.instanceFeatures.eidoverse.enabled).toBe(true);
    expect(reconcileEidoverseRuntime).toHaveBeenCalledOnce();
  });

  // Fork issue #1, final live pass: the Beeper sweep + realtime transport arm on
  // the instance feature plus a token, and that gate was read at boot only — so
  // turning the feature on left both down until the next restart.
  it('reconciles Beeper ingestion when the Beeper feature is toggled', async () => {
    const res = await request(buildApp())
      .put('/api/settings/features/beeper')
      .send({ enabled: true });

    expect(res.status).toBe(200);
    expect(reconcileBeeperIngestion).toHaveBeenCalledWith({ reason: 'feature-toggle' });
  });

  // #8114: turning iTerm2 sessions off must drop the live connection now, and a
  // reconcile failure must not turn the already-saved toggle into a 500.
  it('reconciles the iTerm2 bridge when its feature is toggled, without failing the save', async () => {
    reconcileItermBridge.mockRejectedValueOnce(new Error('bridge exploded'));
    const res = await request(buildApp())
      .put('/api/settings/features/iterm')
      .send({ enabled: false });

    expect(res.status).toBe(200);
    expect(reconcileItermBridge).toHaveBeenCalledWith({ reason: 'feature-toggle' });
  });

  // Beeper sits in the Comms group, so the group toggle moves the same gate.
  it('reconciles Beeper ingestion when the Comms group is toggled', async () => {
    const res = await request(buildApp())
      .put('/api/settings/features/groups/comms')
      .send({ enabled: false });

    expect(res.status).toBe(200);
    expect(reconcileBeeperIngestion).toHaveBeenCalledWith({ reason: 'feature-group-toggle' });
  });

  it('installs and explicitly enables Eidoverse from its consent endpoint', async () => {
    const worldsRepoUrl = 'https://github.com/example-owner/eidoverse-worlds';
    const res = await request(buildApp())
      .post('/api/settings/features/eidoverse/install')
      .send({ worldsRepoUrl });

    expect(res.status).toBe(201);
    expect(installEidoverse).toHaveBeenCalledWith({ worldsRepoUrl });
    expect(store.instanceFeatures.eidoverse.enabled).toBe(true);
    expect(store.instanceFeatures.eidoverse.worldsRepoUrl).toBe(worldsRepoUrl);
    expect(res.body.features).toContainEqual(expect.objectContaining({ id: 'eidoverse', enabled: true }));
  });

  it.each(['feature/worlds', ''])('persists and forwards clone branch %j', async (worldsBranch) => {
    const worldsRepoUrl = 'https://github.com/example-owner/eidoverse-worlds';
    const res = await request(buildApp())
      .post('/api/settings/features/eidoverse/install')
      .send({ worldsRepoUrl, worldsBranch });

    expect(res.status).toBe(201);
    expect(installEidoverse).toHaveBeenCalledWith({ worldsRepoUrl, worldsBranch });
    expect(store.instanceFeatures.eidoverse.worldsBranch).toBe(worldsBranch);
    expect(res.body.features.find(feature => feature.id === 'eidoverse').setup.worldsBranch).toBe(worldsBranch);
  });

  it('updates the installed Eidoverse source without changing feature participation', async () => {
    const worldsRepoUrl = '[email protected]:example-owner/eidoverse-worlds.git';
    store = { instanceFeatures: { eidoverse: { enabled: true } } };

    const res = await request(buildApp())
      .put('/api/settings/features/eidoverse/source')
      .send({ worldsRepoUrl });

    expect(res.status).toBe(200);
    expect(setEidoverseWorldsOrigin).toHaveBeenCalledWith(worldsRepoUrl, undefined);
    expect(store.instanceFeatures.eidoverse).toMatchObject({ enabled: true, worldsRepoUrl });
  });

  it('rejects an invalid Eidoverse source update before mutating the checkout', async () => {
    const res = await request(buildApp())
      .put('/api/settings/features/eidoverse/source')
      .send({ worldsRepoUrl: 'https://example.com/not-github' });

    expect(res.status).toBe(400);
    expect(setEidoverseWorldsOrigin).not.toHaveBeenCalled();
  });

  it('opens the Eidoverse host bridge only after verifying the managed app installation', async () => {
    const res = await request(buildApp()).post('/api/settings/features/eidoverse/host');

    expect(res.status).toBe(200);
    expect(assertEidoverseInstalled).toHaveBeenCalledOnce();
    expect(ensureEidoverseHost).toHaveBeenCalledOnce();
    expect(res.body).toEqual({ running: true, protocol: 'https', port: 5563 });
  });

  it('rejects a non-GitHub Worlds repository', async () => {
    const res = await request(buildApp())
      .post('/api/settings/features/eidoverse/install')
      .send({ worldsRepoUrl: 'https://example.com/untrusted.git' });

    expect(res.status).toBe(400);
    expect(installEidoverse).not.toHaveBeenCalled();
  });

  it('rejects unexpected install payload fields', async () => {
    const res = await request(buildApp())
      .post('/api/settings/features/eidoverse/install')
      .send({
        worldsRepoUrl: 'https://github.com/example-owner/eidoverse-worlds',
        repository: 'unexpected',
      });

    expect(res.status).toBe(400);
    expect(installEidoverse).not.toHaveBeenCalled();
  });

  it('clears a grouped feature override back to inherit with enabled: null', async () => {
    store = { instanceFeatures: { facetime: { enabled: true } } };

    const res = await request(buildApp())
      .put('/api/settings/features/facetime')
      .send({ enabled: null });

    expect(res.status).toBe(200);
    expect(store).toEqual({ instanceFeatures: {} });
    // This suite doesn't mock voice/facetimeBridge.js, so only the storage and
    // the no-longer-`explicit` source are pinned — the resolved boolean depends
    // on the real (unmocked) detector's answer on the machine running the test.
    const facetime = res.body.features.find((f) => f.id === 'facetime');
    expect(facetime.source).not.toBe('explicit');
  });

  it('uses iMessage as a grouped feature with no override to prove the same clear-to-inherit path on a feature with no detector', async () => {
    store = { instanceFeatures: { imessage: { enabled: false } } };

    const res = await request(buildApp())
      .put('/api/settings/features/imessage')
      .send({ enabled: null });

    expect(res.status).toBe(200);
    expect(store).toEqual({ instanceFeatures: {} });
    expect(res.body.features).toContainEqual(expect.objectContaining({ id: 'imessage', enabled: true, source: 'default' }));
  });

  it('toggles the comms feature group and reflects it on the group and member list', async () => {
    const res = await request(buildApp())
      .put('/api/settings/features/groups/comms')
      .send({ enabled: false });

    expect(res.status).toBe(200);
    expect(store).toEqual({ instanceFeatureGroups: { comms: { enabled: false } } });
    expect(res.body.groups).toContainEqual(expect.objectContaining({ id: 'comms', enabled: false }));
    expect(res.body.features).toContainEqual(expect.objectContaining({ id: 'imessage', enabled: false, source: 'group-off' }));
  });

  it('lets an explicit per-feature override outrank an off group', async () => {
    store = { instanceFeatureGroups: { comms: { enabled: false } } };

    const res = await request(buildApp())
      .put('/api/settings/features/imessage')
      .send({ enabled: true });

    expect(res.status).toBe(200);
    expect(res.body.features).toContainEqual(expect.objectContaining({ id: 'imessage', enabled: true, source: 'explicit' }));
    // Signal has no override of its own, so it stays hidden by the off group.
    expect(res.body.features).toContainEqual(expect.objectContaining({ id: 'signal', enabled: false, source: 'group-off' }));
  });

  it('rejects an unknown feature group id and a non-boolean group enabled value', async () => {
    const unknown = await request(buildApp())
      .put('/api/settings/features/groups/not-registered')
      .send({ enabled: false });
    const malformed = await request(buildApp())
      .put('/api/settings/features/groups/comms')
      .send({ enabled: 'false' });
    // Unlike the per-feature route, a group has no inherit state of its own —
    // null is rejected rather than treated as a third value.
    const nullEnabled = await request(buildApp())
      .put('/api/settings/features/groups/comms')
      .send({ enabled: null });

    expect(unknown.status).toBe(400);
    expect(malformed.status).toBe(400);
    expect(nullEnabled.status).toBe(400);
    expect(unknown.body.code).toBe('VALIDATION_ERROR');
    expect(malformed.body.code).toBe('VALIDATION_ERROR');
    expect(nullEnabled.body.code).toBe('VALIDATION_ERROR');
  });

  it('validates the instanceFeatureGroups slice on the generic settings PUT', async () => {
    const ok = await request(buildApp())
      .put('/api/settings')
      .send({ instanceFeatureGroups: { comms: { enabled: false } } });
    const malformed = await request(buildApp())
      .put('/api/settings')
      .send({ instanceFeatureGroups: { comms: { enabled: 'nope' } } });
    const unknownGroup = await request(buildApp())
      .put('/api/settings')
      .send({ instanceFeatureGroups: { 'not-a-group': { enabled: false } } });

    expect(ok.status).toBe(200);
    expect(store.instanceFeatureGroups).toEqual({ comms: { enabled: false } });
    expect(malformed.status).toBe(400);
    expect(unknownGroup.status).toBe(400);
  });

  it('rejects unknown feature ids and malformed enabled values', async () => {
    const unknown = await request(buildApp())
      .put('/api/settings/features/not-registered')
      .send({ enabled: false });
    const malformed = await request(buildApp())
      .put('/api/settings/features/post')
      .send({ enabled: 'false' });

    expect(unknown.status).toBe(400);
    expect(malformed.status).toBe(400);
    expect(unknown.body.code).toBe('VALIDATION_ERROR');
    expect(malformed.body.code).toBe('VALIDATION_ERROR');
  });
});

// A peer that satisfies every durable gate the routing policy checks: enabled,
// enabled as a provider, allowlisted for the routed pair, and on the tailnet.
const routablePeer = (overrides = {}) => ({
  id: 'peer-1',
  name: 'Render Box',
  host: 'render-box.tailnet-example.ts.net',
  enabled: true,
  mediaProvider: { enabled: true, imageModels: [{ engine: 'ltx', modelId: 'ltx-1' }], videoModels: [] },
  ...overrides,
});

describe('Settings routes — agent context and federated media provider slices', () => {
  beforeEach(() => {
    store = {};
    peers = [];
    vi.clearAllMocks();
  });

  it('accepts and returns a strict disabled-by-default context configuration', async () => {
    const res = await request(buildApp())
      .put('/api/settings')
      .send({ agentContext: { enabled: true, profile: 'metadata', scopes: ['navigation', 'workspaces'] } });
    expect(res.status).toBe(200);
    expect(res.body.agentContext).toEqual({
      enabled: true,
      profile: 'metadata',
      scopes: ['navigation', 'workspaces'],
    });
  });

  it('rejects unknown, empty, duplicate, and misspelled scopes', async () => {
    for (const agentContext of [
      { enabled: true, scopes: [] },
      { enabled: true, scopes: ['brain', 'brain'] },
      { enabled: true, scopes: ['privacy-vault'] },
      { enabled: true, scopes: ['navigation'], extra: true },
    ]) {
      const res = await request(buildApp()).put('/api/settings').send({ agentContext });
      expect(res.status).toBe(400);
      expect(res.body.code).toBe('VALIDATION_ERROR');
    }
  });

  it('accepts a disabled-by-default provider config and preserves future federation keys', async () => {
    const res = await request(buildApp())
      .put('/api/settings')
      .send({ federation: {
        strictPullAuthorization: true,
        futureFederationField: 'preserve',
        mediaProvider: {
          enabled: false,
          maxQueuedJobs: 2,
          audioModels: [{ engine: 'minimax-music3', modelId: 'minimax-music3', futureModelField: true }],
          futureProviderField: 'preserve',
        },
      } });
    expect(res.status).toBe(200);
    expect(res.body.federation.mediaProvider).toMatchObject({
      enabled: false,
      maxQueuedJobs: 2,
      futureProviderField: 'preserve',
    });
    expect(res.body.federation.futureFederationField).toBe('preserve');
  });

  // #4703 — Sharing owns federation.mediaProvider + strictPullAuthorization,
  // Instances owns federation.mediaRouting. Each now patches ONLY the sub-keys
  // it owns; the server carries the rest of the slice forward. Two saves issued
  // from the same stale page load must therefore both survive.
  it('merges federation sub-keys so two writes from the same stale page load both survive', async () => {
    const app = buildApp();
    store = { federation: { strictPullAuthorization: false } };
    const route = { peerId: 'peer-1', engine: 'ltx', modelId: 'ltx-1' };
    peers = [routablePeer()];

    const sharing = await request(app)
      .put('/api/settings')
      .send({ federation: { strictPullAuthorization: true } });
    expect(sharing.status).toBe(200);

    // Instances never saw the toggle above — it patches its own sub-key only.
    const routing = await request(app)
      .put('/api/settings')
      .send({ federation: { mediaRouting: { image: route } } });
    expect(routing.status).toBe(200);
    expect(routing.body.federation).toEqual({
      strictPullAuthorization: true,
      mediaRouting: { image: route },
    });
  });

  it('preserves unknown federation sub-keys a patch omits (mixed-version client)', async () => {
    store = { federation: { futureFederationField: 'preserve', strictPullAuthorization: true } };
    const res = await request(buildApp())
      .put('/api/settings')
      .send({ federation: { mediaProvider: { enabled: true } } });
    expect(res.status).toBe(200);
    expect(res.body.federation).toEqual({
      futureFederationField: 'preserve',
      strictPullAuthorization: true,
      mediaProvider: { enabled: true },
    });
  });

  it('applies an intentional federation sub-key clear rather than restoring the stored value', async () => {
    store = { federation: {
      mediaRouting: { image: { peerId: 'peer-1', engine: 'ltx', modelId: 'ltx-1' } },
      strictPullAuthorization: true,
    } };
    const res = await request(buildApp())
      .put('/api/settings')
      .send({ federation: { mediaRouting: {} } });
    expect(res.status).toBe(200);
    expect(res.body.federation).toEqual({ mediaRouting: {}, strictPullAuthorization: true });
  });

  // #4348 — a standing route is validated where it is SAVED, not only where it
  // is used. An unattended render has no human at the moment it fails, so a
  // route that can never run must not reach disk in the first place.
  it('saves a standing route to an allowlisted model on an enabled tailnet provider', async () => {
    peers = [routablePeer()];
    const res = await request(buildApp())
      .put('/api/settings')
      .send({ federation: { mediaRouting: { image: { peerId: 'peer-1', engine: 'ltx', modelId: 'ltx-1' } } } });
    expect(res.status).toBe(200);
    expect(res.body.federation.mediaRouting.image).toEqual({ peerId: 'peer-1', engine: 'ltx', modelId: 'ltx-1' });
  });

  it('refuses a standing route whose model was never allowlisted for that peer', async () => {
    peers = [routablePeer()];
    const res = await request(buildApp())
      .put('/api/settings')
      .send({ federation: { mediaRouting: { image: { peerId: 'peer-1', engine: 'ltx', modelId: 'not-allowlisted' } } } });
    expect(res.status).toBe(403);
    expect(res.body.code).toBe('MEDIA_PROVIDER_MODEL_NOT_ALLOWED');
    expect(store.federation).toBeUndefined();
  });

  it('refuses a standing route to a peer reachable outside the tailnet (ADR rule 5)', async () => {
    peers = [routablePeer({ host: undefined, address: '192.0.2.10' })];
    const res = await request(buildApp())
      .put('/api/settings')
      .send({ federation: { mediaRouting: { image: { peerId: 'peer-1', engine: 'ltx', modelId: 'ltx-1' } } } });
    expect(res.status).toBe(403);
    expect(res.body.code).toBe('MEDIA_ROUTING_PEER_NOT_TAILNET');
  });

  // Clearing must survive whatever happened to the peer, or a bad route becomes
  // permanent — the exact failure a save-time gate would otherwise create.
  it('still clears a route whose peer has since been unregistered', async () => {
    store = { federation: { mediaRouting: { image: { peerId: 'peer-1', engine: 'ltx', modelId: 'ltx-1' } } } };
    peers = [];
    const res = await request(buildApp())
      .put('/api/settings')
      .send({ federation: { mediaRouting: { image: null } } });
    expect(res.status).toBe(200);
    expect(res.body.federation.mediaRouting).toEqual({ image: null });
  });

  it('rejects invalid limits and duplicate engine/model pairs', async () => {
    const invalidLimit = await request(buildApp())
      .put('/api/settings')
      .send({ federation: { mediaProvider: { maxQueuedJobs: 0 } } });
    expect(invalidLimit.status).toBe(400);

    const duplicate = await request(buildApp())
      .put('/api/settings')
      .send({ federation: { mediaProvider: { audioModels: [
        { engine: 'musicgen', modelId: 'm' },
        { engine: 'musicgen', modelId: 'm' },
      ] } } });
    expect(duplicate.status).toBe(400);
  });
});

describe('Settings routes — imageGen.grok slice (#2859)', () => {
  beforeEach(() => {
    store = {};
    vi.clearAllMocks();
  });

  it('accepts a valid grok slice and persists it', async () => {
    const res = await request(buildApp())
      .put('/api/settings')
      .send({ imageGen: { grok: { enabled: true, grokPath: '/usr/local/bin/grok', aspectRatio: '16:9' } } });
    expect(res.status).toBe(200);
    expect(res.body.imageGen.grok.enabled).toBe(true);
    expect(res.body.imageGen.grok.aspectRatio).toBe('16:9');
  });

  it('accepts empty-string UI sentinels for path and ratio', async () => {
    const res = await request(buildApp())
      .put('/api/settings')
      .send({ imageGen: { grok: { enabled: false, grokPath: '', aspectRatio: '' } } });
    expect(res.status).toBe(200);
  });

  it('rejects a malformed aspect ratio (would land verbatim in the grok prompt)', async () => {
    const res = await request(buildApp())
      .put('/api/settings')
      .send({ imageGen: { grok: { aspectRatio: '16:9; rm -rf /' } } });
    expect(res.status).toBe(400);
  });

  it('rejects a non-boolean enabled gate', async () => {
    const res = await request(buildApp())
      .put('/api/settings')
      .send({ imageGen: { grok: { enabled: 'yes' } } });
    expect(res.status).toBe(400);
  });

  it('leaves an imageGen patch without a grok key unvalidated (polymorphic parent)', async () => {
    const res = await request(buildApp())
      .put('/api/settings')
      .send({ imageGen: { mode: 'local' } });
    expect(res.status).toBe(200);
  });
});

describe('Settings routes — imageGen.agy slice', () => {
  beforeEach(() => {
    store = {};
    vi.clearAllMocks();
  });

  it('accepts a valid Agy slice and persists the selected model', async () => {
    const res = await request(buildApp())
      .put('/api/settings')
      .send({ imageGen: { agy: { enabled: true, agyPath: '/usr/local/bin/agy', model: 'gemini/image-v2' } } });
    expect(res.status).toBe(200);
    expect(res.body.imageGen.agy).toEqual(expect.objectContaining({
      enabled: true,
      model: 'gemini/image-v2',
    }));
  });

  it('accepts empty-string UI sentinels for path and model', async () => {
    const res = await request(buildApp())
      .put('/api/settings')
      .send({ imageGen: { agy: { enabled: false, agyPath: '', model: '' } } });
    expect(res.status).toBe(200);
  });

  it('rejects a model id containing shell syntax', async () => {
    const res = await request(buildApp())
      .put('/api/settings')
      .send({ imageGen: { agy: { model: 'gemini; rm -rf /' } } });
    expect(res.status).toBe(400);
  });
});

describe('Settings routes — imageGen.local.pythonPath (#8751)', () => {
  beforeEach(() => {
    store = {};
    vi.clearAllMocks();
  });

  it('refuses a pythonPath that is not a python interpreter, persisting nothing', async () => {
    const res = await request(buildApp())
      .put('/api/settings')
      .send({ imageGen: { local: { pythonPath: '/bin/sh' } } });
    expect(res.status).toBe(400);
    expect(res.body.code).toBe('INVALID_PYTHON_PATH');
    expect(store.imageGen).toBeUndefined();
  });

  it('accepts a venv interpreter and a cleared value', async () => {
    for (const pythonPath of ['/opt/example/.venv/bin/python3.12', '']) {
      const res = await request(buildApp())
        .put('/api/settings')
        .send({ imageGen: { local: { pythonPath } } });
      expect(res.status).toBe(200);
    }
  });
});

describe('Settings routes — renderDefaults slice (#3231)', () => {
  beforeEach(() => {
    store = {};
    vi.clearAllMocks();
  });

  it('accepts per-target backend + model pins and persists them', async () => {
    const res = await request(buildApp())
      .put('/api/settings')
      .send({ renderDefaults: {
        'universe-bible': { imageMode: 'codex' },
        'sprite-reference': { imageMode: 'agy', imageModel: 'gemini-3.6-flash-low' },
      } });
    expect(res.status).toBe(200);
    expect(res.body.renderDefaults).toEqual({
      'universe-bible': { imageMode: 'codex' },
      'sprite-reference': { imageMode: 'agy', imageModel: 'gemini-3.6-flash-low' },
    });
  });

  it('tolerates and preserves unknown target keys (forward compat after rollback)', async () => {
    // A newer build's target (or field) must not 400 every Image Gen save on
    // an older build — the UI round-trips the whole stored object. Unknown
    // keys pass validation and persist raw, so the newer pins survive.
    const res = await request(buildApp())
      .put('/api/settings')
      .send({ renderDefaults: { 'future-target': { imageMode: 'codex' }, 'universe-bible': { imageMode: 'codex', futureField: 'x' } } });
    expect(res.status).toBe(200);
    expect(res.body.renderDefaults['future-target']).toEqual({ imageMode: 'codex' });
    expect(res.body.renderDefaults['universe-bible'].futureField).toBe('x');
  });

  it('rejects a non-queueable backend and a shell-syntax model id', async () => {
    const external = await request(buildApp())
      .put('/api/settings')
      .send({ renderDefaults: { 'universe-bible': { imageMode: 'external' } } });
    expect(external.status).toBe(400);
    const shell = await request(buildApp())
      .put('/api/settings')
      .send({ renderDefaults: { 'universe-bible': { imageModel: 'x; rm -rf /' } } });
    expect(shell.status).toBe(400);
  });

  it('accepts a per-target video backend pin and rejects a non-video backend (#3231 Phase 4)', async () => {
    const ok = await request(buildApp())
      .put('/api/settings')
      .send({ renderDefaults: { 'music-video': { videoMode: 'grok' } } });
    expect(ok.status).toBe(200);
    expect(ok.body.renderDefaults['music-video']).toEqual({ videoMode: 'grok' });
    const bad = await request(buildApp())
      .put('/api/settings')
      .send({ renderDefaults: { 'music-video': { videoMode: 'codex' } } });
    expect(bad.status).toBe(400);
  });
});

describe('Settings routes — videoGen slice (#3231 Phase 4)', () => {
  beforeEach(() => {
    store = {};
    vi.clearAllMocks();
  });

  it('accepts the install-wide video pin fields and the null clear', async () => {
    // NOTE: the settings PUT replaces top-level slices wholesale, so sibling-key
    // preservation (defaultModelId surviving a mode-only save) is the CLIENT's
    // job — ImageGenTab round-trips the loaded slice (videoGenSliceRef); the
    // client suite pins that wire body. This test only pins schema acceptance.
    const res = await request(buildApp())
      .put('/api/settings')
      .send({ videoGen: { mode: 'grok', defaultModelId: 'ltx23_distilled_q4' } });
    expect(res.status).toBe(200);
    expect(res.body.videoGen).toEqual({ mode: 'grok', defaultModelId: 'ltx23_distilled_q4' });
    // Clearing via null is the intentional no-pin state.
    const cleared = await request(buildApp())
      .put('/api/settings')
      .send({ videoGen: { mode: null } });
    expect(cleared.status).toBe(200);
  });

  it('rejects a non-video backend as the install-wide video pin', async () => {
    const res = await request(buildApp())
      .put('/api/settings')
      .send({ videoGen: { mode: 'codex' } });
    expect(res.status).toBe(400);
  });

  // Restricted-model license acknowledgements are owned by
  // /api/video-gen/model-terms. Losing them to an unrelated Settings save would
  // silently start 403ing every gated render again.
  it('preserves acceptedModelTerms when a settings save replaces the videoGen slice without it', async () => {
    store = { videoGen: { mode: null, acceptedModelTerms: ['minimax-h3-community-license-2026-08-02'] } };
    const res = await request(buildApp())
      .put('/api/settings')
      .send({ videoGen: { mode: 'grok' } });
    expect(res.status).toBe(200);
    expect(res.body.videoGen).toEqual({
      mode: 'grok',
      acceptedModelTerms: ['minimax-h3-community-license-2026-08-02'],
    });
  });

  // /api/video-gen/model-terms is where an id is checked against a model that
  // actually declares it, so this route can't be a second write path — it would
  // let arbitrary strings accumulate in the list that authorizes renders.
  it('ignores an acceptedModelTerms written through the settings patch', async () => {
    store = { videoGen: { acceptedModelTerms: ['recorded-license'] } };
    const res = await request(buildApp())
      .put('/api/settings')
      .send({ videoGen: { acceptedModelTerms: ['smuggled-license'] } });
    expect(res.status).toBe(200);
    expect(res.body.videoGen.acceptedModelTerms).toEqual(['recorded-license']);
  });

  it('does not let a settings patch mint the list on an install that has accepted nothing', async () => {
    store = { videoGen: { mode: null } };
    const res = await request(buildApp())
      .put('/api/settings')
      .send({ videoGen: { mode: 'local', acceptedModelTerms: ['smuggled-license'] } });
    expect(res.status).toBe(200);
    expect(res.body.videoGen).toEqual({ mode: 'local' });
  });
});

describe('Settings routes — beeper slice (#30)', () => {
  beforeEach(() => {
    store = {};
    vi.clearAllMocks();
  });

  it('accepts a valid beeper slice and persists it', async () => {
    const res = await request(buildApp())
      .put('/api/settings')
      .send({ beeper: { enabled: true, intervalMinutes: 10, baseUrl: 'http://127.0.0.1:23373', attachmentBudgetGb: 5 } });
    expect(res.status).toBe(200);
    expect(res.body.beeper).toEqual({ enabled: true, intervalMinutes: 10, baseUrl: 'http://127.0.0.1:23373', attachmentBudgetGb: 5 });
  });

  it('rejects a non-boolean enabled gate', async () => {
    const res = await request(buildApp())
      .put('/api/settings')
      .send({ beeper: { enabled: 'yes' } });
    expect(res.status).toBe(400);
  });

  it('rejects an out-of-range interval', async () => {
    const res = await request(buildApp())
      .put('/api/settings')
      .send({ beeper: { intervalMinutes: 0 } });
    expect(res.status).toBe(400);
  });

  // The security-load-bearing case (#30/#31): this slice must never add a
  // plaintext write path for the token, and `.strict()` is what enforces it —
  // a client attempting to smuggle one through the generic settings route
  // gets a 400, not a silent write to disk.
  it('rejects a beeper patch that carries a token — no plaintext write path through this route', async () => {
    const res = await request(buildApp())
      .put('/api/settings')
      .send({ beeper: { enabled: true, token: 'smuggled-token' } });
    expect(res.status).toBe(400);
  });

  it('never echoes a stored beeper token back on GET /api/settings', async () => {
    store = { beeper: { enabled: true, token: 'super-secret-token' } };
    const res = await request(buildApp()).get('/api/settings');
    expect(res.status).toBe(200);
    expect(res.body.beeper.token).toBeUndefined();
    expect(JSON.stringify(res.body)).not.toMatch(/super-secret-token/);
  });

  // Without this, the generic top-level shallow merge would REPLACE
  // current.beeper wholesale and silently wipe out a token stored by another
  // write path (#31's vault, or a hand-edited settings.json) the instant the
  // user saves an unrelated field like `enabled` from this slice's settings
  // card — same posture as imageGen.hfToken / civitai.apiKey above. The
  // ordinary ingestion-config fields (baseUrl, intervalMinutes,
  // attachmentBudgetGb) follow the existing iMessage/Signal convention
  // instead: the settings card always PUTs its complete known slice, so
  // there's no separate "don't drop this on a partial patch" guard for them.
  it('preserves a stored token across a beeper patch that only touches other fields', async () => {
    store = { beeper: { enabled: false, token: 'existing-token' } };
    const res = await request(buildApp())
      .put('/api/settings')
      .send({ beeper: { enabled: true } });
    expect(res.status).toBe(200);
    // The response itself redacts the token (see the GET test above); assert
    // against the mocked store, which reflects what was actually persisted.
    expect(store.beeper).toEqual({ enabled: true, token: 'existing-token' });
  });
});

// The general settings PUT persists `settings.beeper.enabled` but, unlike the
// feature and comms-group toggles above, used to never reconcile arming — so a
// save made right after connecting (enabled still false at that point) left
// the sweep unregistered until the next restart. These pin the fix: reconcile
// only fires when the effective (boolean-coerced) value actually changes.
describe('Settings routes — beeper sync-toggle arming', () => {
  beforeEach(() => {
    store = {};
    vi.clearAllMocks();
  });

  it('reconnects after a saved endpoint change without requiring a sync-toggle change', async () => {
    store = { beeper: { enabled: true, intervalMinutes: 5, baseUrl: 'http://127.0.0.1:23373' } };
    const res = await request(buildApp()).put('/api/settings').send({
      beeper: { ...store.beeper, baseUrl: 'http://127.0.0.1:23374' },
    });
    expect(res.status).toBe(200);
    expect(reconcileBeeperIngestion).toHaveBeenCalledWith({ reason: 'connection-settings', restartSocket: true });
    expect(updateSettingsWith.mock.invocationCallOrder[0]).toBeLessThan(reconcileBeeperIngestion.mock.invocationCallOrder[0]);
  });

  it('reconciles a group gate changed through the general settings route', async () => {
    store = { instanceFeatureGroups: { comms: { enabled: true } } };
    const res = await request(buildApp()).put('/api/settings').send({
      instanceFeatureGroups: { comms: { enabled: false } },
    });
    expect(res.status).toBe(200);
    expect(reconcileBeeperIngestion).toHaveBeenCalledWith({ reason: 'connection-settings', restartSocket: false });
  });

  it('reconciles once, after the settings are persisted, when enabled flips false→true', async () => {
    store = { beeper: { enabled: false, intervalMinutes: 5 } };

    const res = await request(buildApp())
      .put('/api/settings')
      .send({ beeper: { enabled: true, intervalMinutes: 5 } });

    expect(res.status).toBe(200);
    expect(reconcileBeeperIngestion).toHaveBeenCalledTimes(1);
    expect(reconcileBeeperIngestion).toHaveBeenCalledWith({ reason: 'sync-toggle' });
    // Ordering: the write must land before the reconcile fires, so the
    // scheduler's own settings re-read (and the reconcile itself) see the
    // value that was actually persisted, not the request body.
    const [writeOrder] = updateSettingsWith.mock.invocationCallOrder;
    const [reconcileOrder] = reconcileBeeperIngestion.mock.invocationCallOrder;
    expect(writeOrder).toBeLessThan(reconcileOrder);
  });

  // Registering the scheduler is `reconcileBeeperArming`'s job; stopping it on
  // a true→false flip is not — `reconcileBeeperIngestion` only disarms on the
  // feature+token gate, not on this opt-in (see beeperArming.js), so it is the
  // scheduler's own per-tick `getBeeperSyncConfig()` re-read that actually
  // stops runs here. This still calls reconcile, for symmetry and so the
  // transition is logged/serialized on the same tail as every other trigger.
  it('reconciles once when enabled flips true→false', async () => {
    store = { beeper: { enabled: true, intervalMinutes: 5 } };

    const res = await request(buildApp())
      .put('/api/settings')
      .send({ beeper: { enabled: false, intervalMinutes: 5 } });

    expect(res.status).toBe(200);
    expect(reconcileBeeperIngestion).toHaveBeenCalledTimes(1);
    expect(reconcileBeeperIngestion).toHaveBeenCalledWith({ reason: 'sync-toggle' });
  });

  it('does not reconcile arming when a save leaves enabled unchanged (interval-only)', async () => {
    store = { beeper: { enabled: true, intervalMinutes: 5 } };

    const res = await request(buildApp())
      .put('/api/settings')
      .send({ beeper: { enabled: true, intervalMinutes: 15 } });

    expect(res.status).toBe(200);
    expect(reconcileBeeperIngestion).not.toHaveBeenCalled();
  });

  it('does not fail the PUT when the reconcile rejects', async () => {
    reconcileBeeperIngestion.mockRejectedValueOnce(new Error('boom'));
    store = { beeper: { enabled: false, intervalMinutes: 5 } };

    const res = await request(buildApp())
      .put('/api/settings')
      .send({ beeper: { enabled: true, intervalMinutes: 5 } });

    expect(res.status).toBe(200);
    expect(res.body.beeper.enabled).toBe(true);
  });

  // Fork issue #94: a true→false save leaves the scheduler registered (see
  // "reconciles once when enabled flips true→false" above) — it just gates
  // per tick — so a false→true flip right after finds
  // `isBeeperSchedulerRegistered()` already true and the reconcile is a no-op
  // for the scheduler. When this save also changes the interval, the still-
  // registered event is holding the stale `intervalMs`, so the route has to
  // restart the scheduler explicitly, after reconciling, to pick up what was
  // just persisted.
  it('restarts the scheduler, after reconciling, when enabled flips and the interval changes on an already-registered scheduler', async () => {
    isBeeperSchedulerRegistered.mockReturnValueOnce(true);
    store = { beeper: { enabled: false, intervalMinutes: 5 } };

    const res = await request(buildApp())
      .put('/api/settings')
      .send({ beeper: { enabled: true, intervalMinutes: 15 } });

    expect(res.status).toBe(200);
    expect(reconcileBeeperIngestion).toHaveBeenCalledTimes(1);
    expect(restartBeeperScheduler).toHaveBeenCalledTimes(1);
    const [reconcileOrder] = reconcileBeeperIngestion.mock.invocationCallOrder;
    const [restartOrder] = restartBeeperScheduler.mock.invocationCallOrder;
    expect(reconcileOrder).toBeLessThan(restartOrder);
  });
});

// Fork issue #79's other half: an interval-only save (no `enabled` flip) used
// to take effect only at the next process restart, because the registered
// event's `intervalMs` is locked in at `schedule()` time and
// `startBeeperScheduler()` deliberately no-ops once `beeper-sync` is already
// registered. `restartBeeperScheduler()` (cancel, then register fresh) is the
// fix; this describe block pins WHEN the route calls it, not what it does —
// that lives in services/beeperScheduler.test.js.
describe('Settings routes — beeper interval change', () => {
  beforeEach(() => {
    store = {};
    vi.clearAllMocks();
  });

  it('restarts the scheduler, after the settings are persisted, when only the interval changes', async () => {
    store = { beeper: { enabled: true, intervalMinutes: 5 } };

    const res = await request(buildApp())
      .put('/api/settings')
      .send({ beeper: { enabled: true, intervalMinutes: 15 } });

    expect(res.status).toBe(200);
    expect(restartBeeperScheduler).toHaveBeenCalledTimes(1);
    expect(reconcileBeeperIngestion).not.toHaveBeenCalled();
    // Same ordering requirement as the arming reconcile: the restart has to
    // read the interval AFTER it lands on disk, or a fast save/restart race
    // could re-register against the value that was about to be overwritten.
    const [writeOrder] = updateSettingsWith.mock.invocationCallOrder;
    const [restartOrder] = restartBeeperScheduler.mock.invocationCallOrder;
    expect(writeOrder).toBeLessThan(restartOrder);
  });

  it('does not restart the scheduler when the interval is unchanged', async () => {
    store = { beeper: { enabled: true, intervalMinutes: 5 } };

    const res = await request(buildApp())
      .put('/api/settings')
      .send({ beeper: { enabled: true, intervalMinutes: 5 } });

    expect(res.status).toBe(200);
    expect(restartBeeperScheduler).not.toHaveBeenCalled();
  });

  // With the scheduler not yet registered (`isBeeperSchedulerRegistered()`
  // defaults to `false` in this file's mock — a fresh install / first
  // enable), the `enabled`-flip branch's reconcile does the fresh
  // registration itself and picks up the just-persisted interval, so
  // restarting the scheduler too would just cancel and re-register a second
  // time for nothing. When the scheduler IS already registered going in, the
  // route restarts it explicitly — see the "already-registered scheduler"
  // test under "beeper sync-toggle arming" above (fork issue #94).
  it('does not also restart the scheduler when enabled flips, even if the interval changed in the same save', async () => {
    store = { beeper: { enabled: false, intervalMinutes: 5 } };

    const res = await request(buildApp())
      .put('/api/settings')
      .send({ beeper: { enabled: true, intervalMinutes: 15 } });

    expect(res.status).toBe(200);
    expect(reconcileBeeperIngestion).toHaveBeenCalledTimes(1);
    expect(restartBeeperScheduler).not.toHaveBeenCalled();
  });

  it('does not fail the PUT when the scheduler restart rejects', async () => {
    restartBeeperScheduler.mockRejectedValueOnce(new Error('boom'));
    store = { beeper: { enabled: true, intervalMinutes: 5 } };

    const res = await request(buildApp())
      .put('/api/settings')
      .send({ beeper: { enabled: true, intervalMinutes: 20 } });

    expect(res.status).toBe(200);
    expect(res.body.beeper.intervalMinutes).toBe(20);
  });
});

describe('Settings routes — credential inventory', () => {
  it('returns presence and source without secret values', async () => {
    const { getCredentialInventory } = await import('../services/credentialInventory.js');
    getCredentialInventory.mockResolvedValueOnce({
      headline: 'Most of PortOS works with no key at all.',
      credentials: [{
        id: 'huggingface',
        label: 'Hugging Face',
        unlocks: 'Downloads',
        tier: 'free',
        getUrl: 'https://huggingface.co/settings/tokens',
        configurePath: '/media/image?settings=1',
        feature: null,
        configured: true,
        source: 'settings',
        unavailableFeatures: [],
      }],
    });
    const res = await request(buildApp()).get('/api/settings/credentials');
    expect(res.status).toBe(200);
    expect(res.body.headline).toMatch(/no key at all/i);
    expect(res.body.credentials[0]).toMatchObject({ id: 'huggingface', configured: true, source: 'settings' });
    expect(JSON.stringify(res.body)).not.toMatch(/hf_|sk-|ghp_/);
  });
});

describe('Settings routes — hideFirstRunCard (#5640)', () => {
  beforeEach(() => {
    store = {};
    vi.clearAllMocks();
  });

  it('accepts a boolean durable suppress on the general settings record', async () => {
    const res = await request(buildApp()).put('/api/settings').send({ hideFirstRunCard: true });
    expect(res.status).toBe(200);
    expect(res.body.hideFirstRunCard).toBe(true);
  });

  it('rejects a non-boolean hideFirstRunCard', async () => {
    const res = await request(buildApp()).put('/api/settings').send({ hideFirstRunCard: 'yes' });
    expect(res.status).toBe(400);
    expect(res.body.code).toBe('VALIDATION_ERROR');
  });
});

describe('Settings routes — orchestration profiles (#5992)', () => {
  beforeEach(() => {
    store = {};
    vi.clearAllMocks();
  });

  it('GET /api/settings/orchestration-profiles returns profiles including built-ins', async () => {
    const res = await request(buildApp()).get('/api/settings/orchestration-profiles');
    expect(res.status).toBe(200);
    expect(Array.isArray(res.body)).toBe(true);
    expect(res.body.some(p => p.id === 'heavy-planner')).toBe(true);
  });

  it('POST /api/settings/orchestration-profiles saves a valid profile', async () => {
    const payload = {
      id: 'custom-team',
      name: 'Custom Team',
      description: 'Opus + Sonnet',
      profile: {
        architect: { provider: 'anthropic', model: 'claude-3-opus', effort: 'max' },
        implementer: { provider: 'anthropic', model: 'claude-3-5-sonnet', effort: 'low' },
      },
    };
    const res = await request(buildApp()).post('/api/settings/orchestration-profiles').send(payload);
    expect(res.status).toBe(201);
    expect(res.body.id).toBe('custom-team');
    expect(store.orchestrationProfiles?.some(p => p.id === 'custom-team')).toBe(true);
  });

  it('POST rejects an invalid role reasoning effort', async () => {
    const payload = {
      id: 'bad-effort',
      name: 'Bad',
      profile: {
        architect: { effort: 'invalid-rung' },
      },
    };
    const res = await request(buildApp()).post('/api/settings/orchestration-profiles').send(payload);
    expect(res.status).toBe(400);
    expect(res.body.code).toBe('VALIDATION_ERROR');
  });

  it('PUT /api/settings validates orchestrationProfiles array', async () => {
    const res = await request(buildApp()).put('/api/settings').send({
      orchestrationProfiles: [{
        id: 'valid',
        name: 'Valid Profile',
        profile: {
          architect: { effort: 'high' },
        },
      }],
    });
    expect(res.status).toBe(200);
  });
});


it('accepts only registered private keys and never returns the submitted secret', async () => {
  const { getCredentialInventory } = await import('../services/credentialInventory.js');
  getCredentialInventory.mockResolvedValue({ credentials: [{ id: 'artificial-analysis', configured: true, source: 'settings', editable: true }] });
  const app = buildApp();
  const result = await request(app).put('/api/settings/credentials/artificial-analysis').send({ value: 'example-private-key' });
  expect(result.status).toBe(200);
  expect(result.body).toMatchObject({ configured: true });
  expect(JSON.stringify(result.body)).not.toContain('example-private-key');
  expect(store.secrets.artificialAnalysis.apiKey).toBe('example-private-key');
  const publicSettings = await request(app).get('/api/settings');
  expect(JSON.stringify(publicSettings.body)).not.toContain('example-private-key');
  expect((await request(app).put('/api/settings/credentials/auth').send({ value: 'example' })).status).toBe(400);
  expect((await request(app).put('/api/settings/credentials/civitai').send({ value: {}, extra: true })).status).toBe(400);
  await request(app).put('/api/settings/credentials/artificial-analysis').send({ value: '' });
  expect(store.secrets.artificialAnalysis.apiKey).toBe('');
});

describe('Settings routes — optional networking preference', () => {
  beforeEach(() => { store = {}; vi.clearAllMocks(); });
  it('persists all supported choices and rejects invalid preferences without replacing the saved choice', async () => {
    for (const networkSetupPreference of ['tailscale', 'tailcat', 'none']) {
      const saved = await request(buildApp()).put('/api/settings').send({ networkSetupPreference });
      expect(saved.status).toBe(200);
      const loaded = await request(buildApp()).get('/api/settings');
      expect(loaded.body.networkSetupPreference).toBe(networkSetupPreference);
    }
    const invalid = await request(buildApp()).put('/api/settings').send({ networkSetupPreference: 'invalid' });
    expect(invalid.status).toBe(400);
    expect(store.networkSetupPreference).toBe('none');
  });
});

describe('Settings routes — backup schedule resolution (#6632)', () => {
  beforeEach(() => {
    store = {};
    vi.clearAllMocks();
  });

  // The stored slice is sparse — the user only ever typed a destination. The
  // screen used to read that as "disabled, 02:00" while the scheduler read it as
  // "enabled, midnight", so the screen's next save cancelled a running schedule.
  it('projects the scheduler-compatible effective schedule for a destination-only config', async () => {
    store = { backup: { destPath: '/example-backups' } };
    const res = await request(buildApp()).get('/api/settings');
    expect(res.body.backup).toMatchObject({
      destPath: '/example-backups',
      enabled: true,
      cronExpression: '0 0 * * *'
    });
  });

  it('leaves an explicit disable and a custom cron untouched', async () => {
    store = { backup: { destPath: '/example-backups', enabled: false, cronExpression: '0 3 * * *' } };
    const res = await request(buildApp()).get('/api/settings');
    expect(res.body.backup).toMatchObject({ enabled: false, cronExpression: '0 3 * * *' });
  });

  it('resolves a null destination when none is configured', async () => {
    const res = await request(buildApp()).get('/api/settings');
    expect(res.body.backup).toMatchObject({ destPath: null, enabled: true, cronExpression: '0 0 * * *' });
  });

  // #8334: an install that predates the retention setting has no stored value —
  // that must resolve to unlimited (null), never to the new-install default of
  // 30. A migration/reference-seed is what gives a genuinely new install 30 on
  // disk; the resolver itself must never invent that default for an absence.
  it('resolves retentionCount to null (unlimited) when absent', async () => {
    store = { backup: { destPath: '/example-backups' } };
    const res = await request(buildApp()).get('/api/settings');
    expect(res.body.backup.retentionCount).toBeNull();
  });

  it('preserves an explicitly stored retentionCount', async () => {
    store = { backup: { destPath: '/example-backups', retentionCount: 14 } };
    const res = await request(buildApp()).get('/api/settings');
    expect(res.body.backup.retentionCount).toBe(14);
  });

  it('rejects an out-of-range retentionCount on save', async () => {
    const res = await request(buildApp()).put('/api/settings').send({ backup: { retentionCount: 366 } });
    expect(res.status).toBe(400);
    expect(res.body.code).toBe('VALIDATION_ERROR');
  });

  it('accepts an explicit null retentionCount (operator choosing Unlimited) on save', async () => {
    store = { backup: { destPath: '/example-backups', retentionCount: 30 } };
    const res = await request(buildApp()).put('/api/settings').send({ backup: { retentionCount: null } });
    expect(res.status).toBe(200);
    expect(store.backup.retentionCount).toBeNull();
  });

  // Resolution is read-time only: the sparse shape survives on disk, so an older
  // peer/client reading settings.json still sees exactly what it wrote.
  it('does not persist the resolved values back into the store', async () => {
    store = { backup: { destPath: '/example-backups' } };
    await request(buildApp()).get('/api/settings');
    expect(store.backup).toEqual({ destPath: '/example-backups' });
  });

  // The round trip the bug actually took: read the effective values, edit only an
  // exclusion, save. The saved slice must still register the same schedule.
  it('keeps schedule eligibility when only an exclusion is edited and saved back', async () => {
    store = { backup: { destPath: '/example-backups' } };
    const loaded = await request(buildApp()).get('/api/settings');
    const saved = await request(buildApp())
      .put('/api/settings')
      .send({ backup: { ...loaded.body.backup, excludePaths: ['/scratch'] } });
    expect(saved.status).toBe(200);
    expect(store.backup).toMatchObject({ enabled: true, cronExpression: '0 0 * * *', destPath: '/example-backups' });
  });
});

describe('Settings routes — backup excludePaths bounds (#7241)', () => {
  beforeEach(() => {
    store = {};
    vi.clearAllMocks();
  });

  // These are rsync filter patterns handed straight to `--exclude`. A `..`
  // segment walks out of the data root and a NUL truncates the argument, so the
  // boundary rejects rather than sanitizes — a silently-trimmed pattern would
  // exclude something other than what the user typed.
  it.each([
    ['a parent-directory escape', ['../../etc']],
    ['a nested parent-directory escape', ['a/../../b']],
    ['a NUL byte', [`repos${String.fromCharCode(0)}/etc`]],
    ['a blank entry', ['']],
    ['a pattern that overflows the cap once anchored', ['x'.repeat(256)]],
    ['a pattern far past the cap', ['/'.padEnd(300, 'x')]],
  ])('rejects %s', async (_label, excludePaths) => {
    const res = await request(buildApp()).put('/api/settings').send({ backup: { excludePaths } });
    expect(res.status).toBe(400);
    expect(store.backup).toBeUndefined();
  });

  it('accepts anchored and wildcard-led patterns and stores them as typed', async () => {
    const excludePaths = ['/repos/', '**/raw/', 'cache/'];
    const res = await request(buildApp()).put('/api/settings').send({ backup: { excludePaths } });
    expect(res.status).toBe(200);
    // Stored verbatim — anchoring is a read-time concern in
    // `computeEffectiveExcludes`, so nothing is rewritten under the user.
    expect(store.backup.excludePaths).toEqual(excludePaths);
  });
});

it('generic settings updates cannot replace the password-risk revision', async () => {
  store = { passwordRiskRevision: 'current-revision' };
  const res = await request(buildApp()).put('/api/settings').send({ passwordRiskRevision: 'old-revision' });
  expect(res.status).toBe(200);
  expect(store.passwordRiskRevision).toBe('current-revision');
});

describe('autofixer settings slice', () => {
  it('round-trips promotion options without losing provider selection on independent saves', async () => {
    const app = buildApp();
    expect((await request(app).put('/api/settings').send({ autofixer: { providerId: 'example-cli', model: 'example-model' } })).status).toBe(200);
    expect((await request(app).put('/api/settings').send({ autofixer: { autoPromote: true, verifyCommand: 'npm test' } })).status).toBe(200);
    expect((await request(app).put('/api/settings').send({ autofixer: { model: 'another-model' } })).status).toBe(200);
    const loaded = await request(app).get('/api/settings');
    expect(loaded.body.autofixer).toEqual({ providerId: 'example-cli', model: 'another-model', autoPromote: true, verifyCommand: 'npm test' });
    expect((await request(app).put('/api/settings').send({ autofixer: { autoPromote: 'true' } })).status).toBe(400);
    expect((await request(app).get('/api/settings')).body.autofixer).toEqual(loaded.body.autofixer);
  });
});


// Real queued persistence through HTTP: a mock merge cannot prove independent
// requests retain each other's changes or refuse corrupt on-disk snapshots.
describe('Settings routes — atomic partial saves (#11045)', () => {
  let actual;
  let fs;
  let settingsFile;
  let fileUtils;
  let originalMutation;
  beforeEach(async () => {
    actual = await vi.importActual('../services/settings.js');
    fs = await import('node:fs');
    settingsFile = (await import('node:path')).join(settingsDataRoot, 'settings.json');
    fileUtils = await import('../lib/fileUtils.js');
    originalMutation = updateSettingsWith.getMockImplementation();
    updateSettingsWith.mockImplementation(actual.updateSettingsWith);
    vi.clearAllMocks();
    fs.writeFileSync(settingsFile, JSON.stringify({
      localLlm: { ollama: { disabled: true }, mtplx: { launch: { model: 'example-model' }, idleMinutes: 20 } },
      imageGen: { local: { pythonPath: '/example/python3', denoise: true }, codex: { enabled: true } },
      pipeline: { videoGen: { mode: 'i2v' } },
      secrets: { example: 'private-placeholder' },
      timezone: 'UTC',
    }));
    actual.__resetSettingsCache();
  });
  afterEach(() => {
    updateSettingsWith.mockImplementation(originalMutation);
    fileUtils.tryReadFileStrict.mockRestore();
    fileUtils.atomicWrite.mockRestore();
  });
  const patch = (app, slicePath, partial) => request(app).patch('/api/settings/slice').send({ slicePath, partial });
  const persisted = () => JSON.parse(fs.readFileSync(settingsFile, 'utf8'));

  it('retains sibling runtimes and keys when separate clients patch concurrently', async () => {
    const emitted = vi.fn();
    actual.settingsEvents.on('settings:updated', emitted);
    try {
      const responses = await Promise.all([
        patch(buildApp(), 'localLlm.ollama', { disabled: false }),
        patch(buildApp(), 'localLlm.mtplx', { idleMinutes: 5 }),
        patch(buildApp(), 'localLlm.mtplx', { keepLoaded: true }),
      ]);
      expect(responses.map((response) => response.status)).toEqual([200, 200, 200]);
      expect(persisted()).toMatchObject({
        localLlm: { ollama: { disabled: false }, mtplx: { launch: { model: 'example-model' }, idleMinutes: 5, keepLoaded: true } },
        timezone: 'UTC',
      });
      expect(emitted).toHaveBeenCalledTimes(3);
      await actual.flushSettingsLedger();
      const { recordUserAction } = await import('../services/userActions.js');
      expect(recordUserAction).toHaveBeenCalledWith(expect.objectContaining({ type: 'settings.update', actor: 'user' }));
    } finally {
      actual.settingsEvents.off('settings:updated', emitted);
    }
  });

  it('keeps unrelated fields, permits explicit clearing, and reconciles saved settings', async () => {
    const app = buildApp();
    expect((await patch(app, 'imageGen.local', { pythonPath: null })).status).toBe(200);
    expect((await patch(app, 'localLlm.mtplx', { launch: {} })).status).toBe(200);
    expect((await patch(app, 'pipeline', { imageGen: { mode: 'external', quantize: '5', cfgScale: 7, steps: '' } })).status).toBe(200);
    expect((await patch(app, 'pipeline', { imageGen: null })).status).toBe(200);
    expect((await patch(app, 'seriesAutopilot', { schedules: [] })).status).toBe(200);
    expect(persisted()).toMatchObject({
      imageGen: { local: { pythonPath: null, denoise: true }, codex: { enabled: true } },
      localLlm: { mtplx: { launch: {}, idleMinutes: 20 } },
      pipeline: { imageGen: null, videoGen: { mode: 'i2v' } },
      seriesAutopilot: { schedules: [] },
    });
    const { setCodexParallelLimit } = await import('../services/mediaJobQueue/index.js');
    expect(setCodexParallelLimit).toHaveBeenCalled();
    const saved = await actual.getSettings();
    expect(saved.secrets.example).toBe('private-placeholder');
  });

  // The Media settings drawer saves one slice per changed field group; a
  // sibling panel's later write to a field the drawer did not touch must
  // survive, and a cleared render-target pin travels as an explicit null.
  it('merges the Media drawer slices per field and clears a render-target pin with null', async () => {
    const app = buildApp();
    expect((await patch(app, 'imageGen.codex', { model: 'gpt-example', parallelLimit: 4 })).status).toBe(200);
    expect((await patch(app, 'imageGen', { mode: 'codex' })).status).toBe(200);
    expect((await patch(app, 'imageGen.local', { modelId: 'example-model', cleanC2PA: false })).status).toBe(200);
    expect((await patch(app, 'imageGen.expose', { a1111: true })).status).toBe(200);
    expect((await patch(app, 'renderDefaults', { 'universe-bible': { imageMode: 'codex' }, 'sprite-reference': { imageMode: 'agy' } })).status).toBe(200);
    expect((await patch(app, 'renderDefaults', { 'universe-bible': null })).status).toBe(200);
    expect((await patch(app, 'videoGen', { defaultModelId: 'example-video', displaySleep: true })).status).toBe(200);
    expect((await patch(app, 'videoGen', { mode: 'grok' })).status).toBe(200);
    expect(persisted()).toMatchObject({
      imageGen: {
        mode: 'codex',
        local: { pythonPath: '/example/python3', denoise: true, modelId: 'example-model', cleanC2PA: false },
        codex: { enabled: true, model: 'gpt-example', parallelLimit: 4 },
        expose: { a1111: true },
      },
      renderDefaults: { 'universe-bible': null, 'sprite-reference': { imageMode: 'agy' } },
      videoGen: { mode: 'grok', defaultModelId: 'example-video', displaySleep: true },
    });
  });

  // Each music panel and the LoRA caption picker patch only the keys they own,
  // so a save from one never drops a sibling's prefs or the hand-set knobs.
  it('merges the music and LoRA caption prefs into their owned sub-slices', async () => {
    fs.writeFileSync(settingsFile, JSON.stringify({
      music: { designer: { describeTemplate: 'Example describe', lyricsTemplate: 'Example lyrics' }, chiptune: { publishSubdir: 'game/assets/music' } },
      loraTraining: { displaySleep: false, segmentation: false, defaults: { steps: 1200 } },
    }));
    actual.__resetSettingsCache();
    const app = buildApp();
    expect((await patch(app, 'music.chiptune', { providerId: 'example-provider', model: 'example-model' })).status).toBe(200);
    expect((await patch(app, 'music.designer', { describeTemplate: 'Example revised' })).status).toBe(200);
    expect((await patch(app, 'loraTraining', { captionProviderId: 'example-provider', captionModel: 'example-vision' })).status).toBe(200);
    expect(persisted()).toMatchObject({
      music: {
        designer: { describeTemplate: 'Example revised', lyricsTemplate: 'Example lyrics' },
        chiptune: { publishSubdir: 'game/assets/music', providerId: 'example-provider', model: 'example-model' },
      },
      loraTraining: {
        displaySleep: false, segmentation: false, defaults: { steps: 1200 }, captionProviderId: 'example-provider', captionModel: 'example-vision',
      },
    });
  });

  it('rejects invalid values, unapproved paths and credential/prototype keys without writes', async () => {
    const before = fs.readFileSync(settingsFile, 'utf8');
    for (const [path, partial] of [
      ['secrets.auth', { enabled: false }],
      ['imageGen', { hfToken: 'example-token' }],
      ['imageGen', { mode: 'not-a-backend' }],
      ['imageGen.local', { hfToken: 'example-token' }],
      ['imageGen.local', { pythonPath: '/example/sh' }],
      ['imageGen.codex', { parallelLimitBounds: { min: 1, max: 1 } }],
      ['imageGen.grok', { aspectRatio: 'wide' }],
      ['renderDefaults', { 'universe-bible': { imageMode: 'not-a-backend' } }],
      ['videoGen', { acceptedModelTerms: [] }],
      ['videoGen', { mode: 'not-a-backend' }],
      ['localLlm.mtplx', { idleMinutes: -1 }],
      ['localLlm.mtplx', { launch: { model: [] } }],
      ['autoUpdate', { enabled: 'yes' }],
      ['pipeline', { imageGen: { width: 'invalid' } }],
      ['pipelineEditorialChecks', { enabled: 'yes' }],
      ['seriesAutopilot', { schedules: [{ seriesId: 'example', cron: '99 99 * * *' }] }],
      ['localLlm.__proto__', {}],
      ['pipeline', JSON.parse('{"imageGen":{"constructor":{}}}')],
      ['pipeline', JSON.parse('{"__proto__":{"polluted":true}}')],
      ['pipeline', { imageGen: { steps: 'not-a-number' } }],
      ['music.chiptune', { describeTemplate: 'Example template' }],
      ['music.designer', { describeTemplate: 'x'.repeat(8001) }],
      ['loraTraining', { displaySleep: true }],
    ]) {
      expect((await patch(buildApp(), path, partial)).status, path).toBe(400);
    }
    expect(fs.readFileSync(settingsFile, 'utf8')).toBe(before);
    expect(fileUtils.atomicWrite).not.toHaveBeenCalled();
  });

  it('refuses malformed or unreadable persisted settings and recovers on a later valid read', async () => {
    const before = fs.readFileSync(settingsFile, 'utf8');
    fs.writeFileSync(settingsFile, '{ truncated');
    expect((await patch(buildApp(), 'localLlm.mtplx', { keepLoaded: true })).status).toBe(500);
    expect(fs.readFileSync(settingsFile, 'utf8')).toBe('{ truncated');
    fs.writeFileSync(settingsFile, before);
    fileUtils.tryReadFileStrict.mockResolvedValueOnce({ ok: false, value: null });
    expect((await patch(buildApp(), 'localLlm.mtplx', { keepLoaded: true })).status).toBe(500);
    expect(fileUtils.atomicWrite).not.toHaveBeenCalled();
    expect(fs.readFileSync(settingsFile, 'utf8')).toBe(before);
    expect((await patch(buildApp(), 'localLlm.mtplx', { keepLoaded: true })).status).toBe(200);
    expect(persisted().localLlm.mtplx.launch.model).toBe('example-model');
  });

  it('propagates persistence failures without emitting success or replacing state', async () => {
    const before = fs.readFileSync(settingsFile, 'utf8');
    const emitted = vi.fn();
    actual.settingsEvents.on('settings:updated', emitted);
    fileUtils.atomicWrite.mockRejectedValueOnce(new Error('Synthetic write failure'));
    try {
      expect((await patch(buildApp(), 'localLlm.mtplx', { keepLoaded: true })).status).toBe(500);
      expect(fs.readFileSync(settingsFile, 'utf8')).toBe(before);
      expect(emitted).not.toHaveBeenCalled();
    } finally {
      actual.settingsEvents.off('settings:updated', emitted);
    }
  });

  it('creates missing slices on a fresh install without spreading malformed parent values', async () => {
    fs.unlinkSync(settingsFile);
    expect((await patch(buildApp(), 'localLlm.mtplx', { idleMinutes: 5 })).status).toBe(200);
    expect(persisted().localLlm).toEqual({ mtplx: { idleMinutes: 5 } });
    fs.writeFileSync(settingsFile, JSON.stringify({ imageGen: 'legacy-malformed-parent' }));
    expect((await patch(buildApp(), 'imageGen.local', { pythonPath: '' })).status).toBe(200);
    expect(persisted().imageGen).toEqual({ local: { pythonPath: '' } });
  });

  it('keeps legacy PUT slice replacement semantics', async () => {
    const response = await request(buildApp()).put('/api/settings').send({ localLlm: { mtplx: { idleMinutes: 5 } } });
    expect(response.status).toBe(200);
    expect(persisted().localLlm).toEqual({ mtplx: { idleMinutes: 5 } });
  });
});

const guardedSettingsApp = (authority) => {
  const app = express();
  app.use(express.json());
  app.use((req, _res, next) => {
    Object.defineProperty(req.socket, 'remoteAddress', { value: authority === 'local' ? '127.0.0.1' : '192.0.2.10', configurable: true });
    // authGate supplies this verified context for both human and agent sessions.
    req.portosAuthContext = authority === 'session'
      ? { enabled: true, authenticated: true, method: 'session' }
      : { enabled: false, authenticated: false, method: null };
    next();
  });
  app.use(hostControlBodyGate);
  app.use('/api/settings', settingsRoutes);
  return app;
};

// Regression: generic settings writes must not let a remote caller repoint,
// disable or prune the backups that hold the install's private records.
describe('backup settings operator authority', () => {
  beforeEach(() => { store = { backup: { destPath: '/example-backups', enabled: true } }; vi.clearAllMocks(); });


  it.each([{ destPath: '/example-other-backups' }, { enabled: false }, { retentionCount: 1 }, null])(
    'refuses unauthorized backup policy changes before persistence: %j', async (backup) => {
      const previous = structuredClone(store);
      const res = await request(guardedSettingsApp('remote')).put('/api/settings').send({ backup });
      expect(res.status).toBe(403);
      expect(res.body.code).toBe('HOST_CONTROL_FORBIDDEN');
      expect(updateSettingsWith).not.toHaveBeenCalled();
      expect(store).toEqual(previous);
    },
  );

  it.each(['local', 'session'])('preserves authorized backup configuration: %s', async (authority) => {
    const res = await request(guardedSettingsApp(authority)).put('/api/settings').send({ backup: { destPath: '/example-other-backups' } });
    expect(res.status).toBe(200);
    expect(store.backup.destPath).toBe('/example-other-backups');
  });
});

// A generic settings PUT replaces the whole voice root. Even an empty or null
// value can reset protected instructions; it is not the dedicated deep-merge API.
describe('generic voice settings operator authority', () => {
  const original = { stt: { endpoint: 'https://example.com/trusted-stt' }, llm: { systemPrompt: 'Synthetic trusted instructions', tools: { enabled: false } }, tts: { rate: 1 } };
  beforeEach(() => { store = { voice: structuredClone(original) }; vi.clearAllMocks(); });

  it.each([
    { stt: { endpoint: 'https://example.com/other-stt' } },
    { llm: { systemPrompt: 'Synthetic replacement', tools: { enabled: true } } },
    {},
    null,
  ])('refuses an unauthorized root replacement or reset before persistence: %j', async voice => {
    const res = await request(guardedSettingsApp('remote')).put('/api/settings').send({ voice });
    expect(res.status).toBe(403);
    expect(res.body.code).toBe('HOST_CONTROL_FORBIDDEN');
    expect(updateSettingsWith).not.toHaveBeenCalled();
    expect(store.voice).toEqual(original);
  });

  it.each(['local', 'session'])('preserves authorized voice replacement: %s', async authority => {
    const voice = { ...original, stt: { endpoint: 'https://example.com/other-stt' } };
    const res = await request(guardedSettingsApp(authority)).put('/api/settings').send({ voice });
    expect(res.status).toBe(200);
    expect(store.voice).toEqual(voice);
  });

  it('keeps unrelated generic settings writes open without changing voice policy', async () => {
    const res = await request(guardedSettingsApp('remote')).put('/api/settings').send({ theme: 'dark' });
    expect(res.status).toBe(200);
    expect(store.voice).toEqual(original);
  });
});


// A remote policy write must not become a trusted shell command on a later
// Autofixer repair, or turn a staged patch into an automatic live promotion.
describe('autofixer settings operator authority', () => {
  const original = { providerId: 'example-cli', model: 'example-model', verifyCommand: 'npm test', autoPromote: false };
  beforeEach(() => { store = { autofixer: { ...original } }; vi.clearAllMocks(); });

  it('refuses command, promotion, provider and clearing writes before persistence', async () => {
    for (const autofixer of [
      { verifyCommand: 'echo example-verification' },
      { autoPromote: true },
      { providerId: 'another-cli' },
      { verifyCommand: '' },
      {},
      null,
    ]) {
      const response = await request(guardedSettingsApp('remote')).put('/api/settings').send({ autofixer });
      expect([response.status, response.body.code]).toEqual([403, 'HOST_CONTROL_FORBIDDEN']);
      expect(store.autofixer).toEqual(original);
    }
    expect(updateSettingsWith).not.toHaveBeenCalled();
  });

  it.each(['local', 'session'])('preserves %s repair policy updates and explicit clears', async authority => {
    const app = guardedSettingsApp(authority);
    const response = await request(app).put('/api/settings').send({ autofixer: { verifyCommand: 'echo example-verification', autoPromote: true } });
    expect(response.status).toBe(200);
    expect(store.autofixer).toEqual({ ...original, verifyCommand: 'echo example-verification', autoPromote: true });
    expect((await request(app).put('/api/settings').send({ autofixer: { verifyCommand: '', autoPromote: false } })).status).toBe(200);
    expect(store.autofixer).toEqual({ ...original, verifyCommand: '' });
  });

  it('gates the assignment facade that can replace the same repair policy', async () => {
    const body = { providerId: 'example-cli', model: 'another-model' };
    for (const id of ['settings.autofixer', 'settings%2Eautofixer']) {
      const denied = await request(guardedSettingsApp('remote')).put(`/api/settings/ai-assignments/${id}`).send(body);
      expect([denied.status, denied.body.code]).toEqual([403, 'HOST_CONTROL_FORBIDDEN']);
    }
    expect(updateAiAssignment).not.toHaveBeenCalled();
    for (const authority of ['local', 'session']) {
      expect((await request(guardedSettingsApp(authority)).put('/api/settings/ai-assignments/settings.autofixer').send(body)).status).toBe(200);
    }
    expect(updateAiAssignment).toHaveBeenCalledTimes(2);
    expect(updateAiAssignment).toHaveBeenLastCalledWith('settings.autofixer', body);
  });

  it('keeps unrelated remote settings saves open without changing deferred repair policy', async () => {
    expect((await request(guardedSettingsApp('remote')).put('/api/settings').send({ theme: 'dark' })).status).toBe(200);
    expect(store.autofixer).toEqual(original);
  });
});

describe('Settings routes — saved film looks', () => {
  beforeEach(() => { store = {}; vi.clearAllMocks(); });
  it('stores named looks and refuses a malformed one without touching the saved list', async () => {
    const presets = [{ id: 'dusk-ab12', label: 'Dusk', look: { preset: 'custom', warmth: 0.3, grain: 0.2 } }];
    const saved = await request(buildApp()).put('/api/settings').send({ filmLookPresets: presets });
    expect(saved.status).toBe(200);
    expect(store.filmLookPresets).toEqual(presets);
    for (const bad of [
      [{ id: 'x', label: 'Out of range', look: { warmth: 5 } }],
      [{ id: 'x', label: 'Typo', look: { warmht: 0.2 } }],
      [{ id: 'Bad Id', label: 'Id', look: {} }],
      [{ id: 'x', label: '', look: {} }],
    ]) {
      const result = await request(buildApp()).put('/api/settings').send({ filmLookPresets: bad });
      expect(result.status).toBe(400);
      expect(store.filmLookPresets).toEqual(presets);
    }
  });
});