@semalt-ai/code 1.8.5 → 1.19.0

package/test/command-registry.test.js

@@ -0,0 +1,160 @@
+'use strict';
+
+// Characterization tests for the slash-command registry (Task 1.3). These lock
+// in the command SET, the /help text, and the resolve(text) → command dispatch
+// so the registry refactor is provably behavior-preserving versus the former
+// hardcoded if-chain + SLASH_CMDS array.
+
+const { test } = require('node:test');
+const assert = require('node:assert');
+
+const { resolveCommand, completionNames, helpText, commandNames } = require('../lib/commands/registry');
+
+// The exact completion set the hardcoded SLASH_CMDS array carried before 1.3.
+const ORIGINAL_COMPLETION = [
+  '/help', '/file', '/new', '/model', '/models', '/shell', '/compact',
+  '/clear', '/approve', '/debug', '/config', '/history', '/login', '/whoami', '/logout', '/chats',
+  '/memory', // added in Task 2.3 (project memory)
+  '/plan',   // added in Task 2.5 (plan mode)
+  '/doctor', // added in Task 2.6 (self-diagnostics)
+  '/mcp',    // added in Task 3.3 (MCP servers)
+  '/skills', // added in Task 3.5 (skills)
+  '/rewind', // added in Task 4.3 (checkpoints & rewind)
+  '/sandbox', // added in Task 4.4 (OS sandbox status)
+  '/image',  // added in Task 5.4 (multimodal image input)
+];
+
+// The exact /help body the chain emitted before 1.3.
+const ORIGINAL_HELP = [
+  'Commands:',
+  '  /file <path>    Load file or dir into context',
+  '  /image <path>   Attach an image (PNG/JPEG/WebP/GIF) to your next message',
+  '  /history        Browse local sessions',
+  '  /chats          Browse saved dashboard chats',
+  '  /new            Start fresh conversation',
+  '  /login          Authorize via browser',
+  '  /whoami         Show current user',
+  '  /logout         Clear CLI login',
+  '  /model          Show current model',
+  '  /model <name>   Switch model manually',
+  '  /models         Choose from dashboard models',
+  '  /clear          Clear conversation',
+  '  /compact        Show token usage',
+  '  /shell <cmd>    Run shell command',
+  '  !<cmd>          Run shell command',
+  '  /approve        Toggle auto-approve',
+  '  /debug [off]    Enable debug output + show last 5 audit entries',
+  '  /config         Show config',
+  '  /memory         Show loaded project memory files',
+  '  /mcp            Show MCP server connection status and tools',
+  '  /skills         List available skills (bodies load on invocation)',
+  '  /plan           Toggle plan mode (withhold changes until approved)',
+  '  /rewind         List file checkpoints (file changes only — shell not reversible)',
+  '  /rewind <seq> [code|conversation|both]   Restore files and/or conversation (default both; add "force" to override out-of-band edits)',
+  '  /doctor         Run self-diagnostics (config, dashboard, model, audit, key, memory)',
+  '  /sandbox        Show OS sandbox status (mode, tool, availability, network)',
+  '  exit            Quit',
+].join('\n');
+
+// ---------------------------------------------------------------------------
+// Command set / help / completion parity
+// ---------------------------------------------------------------------------
+
+test('completion set is unchanged from the old hardcoded SLASH_CMDS', () => {
+  assert.deepStrictEqual([...completionNames()].sort(), [...ORIGINAL_COMPLETION].sort());
+});
+
+test('input-field SLASH_CMDS is now sourced from the registry', () => {
+  const { SLASH_CMDS } = require('../lib/ui/input-field');
+  assert.deepStrictEqual(SLASH_CMDS, completionNames());
+});
+
+test('/help text is byte-for-byte identical to the old hardcoded help', () => {
+  assert.strictEqual(helpText(), ORIGINAL_HELP);
+});
+
+test('every command name is unique', () => {
+  const names = commandNames();
+  assert.strictEqual(new Set(names).size, names.length);
+});
+
+// ---------------------------------------------------------------------------
+// Dispatch resolution — exact, alias, optional-arg, required-arg, bang
+// ---------------------------------------------------------------------------
+
+const EXACT = ['/help', '/history', '/chats', '/new', '/login', '/whoami', '/logout', '/models', '/clear', '/compact', '/config', '/memory', '/mcp', '/skills', '/plan', '/doctor', '/approve', '/prompt'];
+for (const name of EXACT) {
+  test(`exact command resolves: ${name}`, () => {
+    const r = resolveCommand(name);
+    assert.ok(r, `${name} should resolve`);
+    assert.strictEqual(r.name, name);
+    assert.strictEqual(r.arg, '');
+  });
+}
+
+test('alias /cost resolves to /compact', () => {
+  assert.strictEqual(resolveCommand('/cost').name, '/compact');
+});
+
+test('exit and its aliases resolve to exit (case-insensitive)', () => {
+  for (const t of ['exit', 'quit', '/exit', '/quit', 'EXIT', 'Quit']) {
+    assert.strictEqual(resolveCommand(t).name, 'exit', `${t} should resolve to exit`);
+  }
+});
+
+test('required-arg command: /file resolves with its argument', () => {
+  const r = resolveCommand('/file a/b.js');
+  assert.strictEqual(r.name, '/file');
+  assert.strictEqual(r.arg, 'a/b.js');
+});
+
+test('bare /file (no arg) is NOT a command (falls through to the agent)', () => {
+  assert.strictEqual(resolveCommand('/file'), null);
+});
+
+test('optional-arg command: /model resolves both bare and with an argument', () => {
+  assert.strictEqual(resolveCommand('/model').name, '/model');
+  assert.strictEqual(resolveCommand('/model').arg, '');
+  assert.strictEqual(resolveCommand('/model gpt-4o').name, '/model');
+  assert.strictEqual(resolveCommand('/model gpt-4o').arg, 'gpt-4o');
+});
+
+test('optional-arg command: /debug resolves bare and with off', () => {
+  assert.strictEqual(resolveCommand('/debug').arg, '');
+  assert.strictEqual(resolveCommand('/debug off').arg, 'off');
+});
+
+test('/models is not shadowed by the /model prefix', () => {
+  assert.strictEqual(resolveCommand('/models').name, '/models');
+  assert.strictEqual(resolveCommand('/models').arg, '');
+});
+
+test('bang shorthand and /shell both resolve to /shell with the command as arg', () => {
+  assert.strictEqual(resolveCommand('!ls -la').name, '/shell');
+  assert.strictEqual(resolveCommand('!ls -la').arg, 'ls -la');
+  assert.strictEqual(resolveCommand('/shell echo hi').name, '/shell');
+  assert.strictEqual(resolveCommand('/shell echo hi').arg, 'echo hi');
+});
+
+test('bare /shell (no arg) is NOT a command', () => {
+  assert.strictEqual(resolveCommand('/shell'), null);
+});
+
+test('argument whitespace is trimmed', () => {
+  assert.strictEqual(resolveCommand('/file    spaced.txt   ').arg, 'spaced.txt');
+});
+
+// ---------------------------------------------------------------------------
+// Non-commands fall through
+// ---------------------------------------------------------------------------
+
+test('ordinary messages and unknown slashes are not commands', () => {
+  for (const t of ['hello world', '/unknown', '/hel', 'modelx', '', '  ']) {
+    assert.strictEqual(resolveCommand(t), null, `${JSON.stringify(t)} should not resolve`);
+  }
+});
+
+test('non-string input returns null', () => {
+  assert.strictEqual(resolveCommand(null), null);
+  assert.strictEqual(resolveCommand(undefined), null);
+});

package/test/compact.test.js

@@ -0,0 +1,116 @@
+'use strict';
+
+// Compaction tests (Task 2.7): the pure selection/replacement logic, the
+// auto-compaction decision, and the real /compact handler driven through the
+// chat harness with a scripted summary.
+
+const { test } = require('node:test');
+const assert = require('node:assert');
+
+const {
+  selectForCompaction, summarizationRequest, buildCompactedMessages,
+  approxTokens, shouldAutoCompact, DEFAULT_KEEP_RECENT,
+} = require('../lib/compact');
+const { startChat } = require('./harness/chat-harness');
+
+const est = (s) => Math.ceil((s || '').length / 4);
+
+// ---------------------------------------------------------------------------
+// Pure selection / replacement
+// ---------------------------------------------------------------------------
+
+test('selectForCompaction keeps the recent tail and summarizes the head', () => {
+  const msgs = Array.from({ length: 10 }, (_, i) => ({ role: 'user', content: `m${i}` }));
+  const { head, tail, pinned } = selectForCompaction(msgs, { keepRecent: 4 });
+  assert.strictEqual(head.length, 6);
+  assert.strictEqual(tail.length, 4);
+  assert.deepStrictEqual(tail.map((m) => m.content), ['m6', 'm7', 'm8', 'm9']);
+  assert.strictEqual(pinned.length, 0);
+});
+
+test('selectForCompaction does nothing when history is within keepRecent', () => {
+  const msgs = [{ role: 'user', content: 'a' }, { role: 'user', content: 'b' }];
+  const { head, tail } = selectForCompaction(msgs, { keepRecent: 6 });
+  assert.strictEqual(head.length, 0);
+  assert.strictEqual(tail.length, 2);
+});
+
+test('pinned messages survive in pinned, not head', () => {
+  const msgs = Array.from({ length: 8 }, (_, i) => ({ role: 'user', content: `m${i}`, pin: i === 0 }));
+  const { head, pinned } = selectForCompaction(msgs, { keepRecent: 4, isPinned: (m) => m.pin });
+  assert.deepStrictEqual(pinned.map((m) => m.content), ['m0']);
+  assert.ok(!head.some((m) => m.pin), 'pinned message not in the summarized head');
+});
+
+test('buildCompactedMessages = pinned + summary + tail, and drops the head', () => {
+  const sel = { pinned: [{ role: 'user', content: 'PIN' }], tail: [{ role: 'user', content: 'recent' }] };
+  const out = buildCompactedMessages(sel, 'THE SUMMARY');
+  assert.strictEqual(out.length, 3);
+  assert.strictEqual(out[0].content, 'PIN');
+  assert.ok(/\[Summary of earlier conversation\]/.test(out[1].content));
+  assert.ok(/THE SUMMARY/.test(out[1].content));
+  assert.strictEqual(out[2].content, 'recent');
+});
+
+test('compaction reduces the approximate token count', () => {
+  const msgs = Array.from({ length: 12 }, (_, i) => ({ role: 'user', content: 'x'.repeat(400) + i }));
+  const before = approxTokens(msgs, est);
+  const sel = selectForCompaction(msgs, { keepRecent: 4 });
+  const out = buildCompactedMessages(sel, 'short summary');
+  const after = approxTokens(out, est);
+  assert.ok(after < before, `compaction shrinks context (${before} → ${after})`);
+});
+
+test('summarizationRequest produces a system+user pair carrying the transcript', () => {
+  const req = summarizationRequest([{ role: 'user', content: 'hello' }, { role: 'assistant', content: 'hi' }]);
+  assert.strictEqual(req.length, 2);
+  assert.strictEqual(req[0].role, 'system');
+  assert.ok(/USER: hello/.test(req[1].content) && /ASSISTANT: hi/.test(req[1].content));
+});
+
+test('shouldAutoCompact triggers only past the ratio with a known limit and enough history', () => {
+  assert.strictEqual(shouldAutoCompact(900, 1000, 20), true);
+  assert.strictEqual(shouldAutoCompact(500, 1000, 20), false, 'below ratio');
+  assert.strictEqual(shouldAutoCompact(900, null, 20), false, 'no known limit');
+  assert.strictEqual(shouldAutoCompact(900, 1000, DEFAULT_KEEP_RECENT, 20), false, 'too little history');
+});
+
+// ---------------------------------------------------------------------------
+// /compact handler (real summarization through the harness)
+// ---------------------------------------------------------------------------
+
+test('/compact summarizes older messages and shrinks the history', async () => {
+  const c = await startChat({
+    config: { auth_token: 'tok' },
+    apiClient: { chatSync: async () => 'SUMMARY_OF_OLD' },
+  });
+  try {
+    for (let i = 0; i < 8; i++) await c.submit(`msg ${i}`); // 8 user messages > keepRecent(6)
+    await c.submit('/compact');
+    assert.ok(c.chatHistory.find(/Compacted 2 older message\(s\)/), 'before/after report shown');
+
+    // Next turn must run on the compacted history: summary first, old head gone.
+    await c.submit('after compact');
+    const last = c.calls.runAgentLoop[c.calls.runAgentLoop.length - 1];
+    const contents = last.messages.map((m) => m.content);
+    assert.ok(/\[Summary of earlier conversation\]/.test(contents[0]) && /SUMMARY_OF_OLD/.test(contents[0]), 'summary leads the history');
+    assert.ok(!contents.some((ct) => ct === 'msg 0' || ct === 'msg 1'), 'oldest messages were summarized away');
+    assert.ok(contents.includes('msg 2'), 'recent tail preserved');
+  } finally {
+    await c.submit('exit'); await c.done; c.cleanup();
+  }
+});
+
+test('/compact with too little history reports nothing to compact', async () => {
+  const c = await startChat({
+    config: { auth_token: 'tok' },
+    apiClient: { chatSync: async () => 'unused' },
+  });
+  try {
+    await c.submit('only one');
+    await c.submit('/compact');
+    assert.ok(c.chatHistory.find(/Nothing to compact/), 'no-op message shown');
+  } finally {
+    await c.submit('exit'); await c.done; c.cleanup();
+  }
+});

package/test/completion-lazy.test.js

@@ -0,0 +1,52 @@
+'use strict';
+
+// Lazy completion source (Task 3.1 follow-up). lib/ui/input-field.js used to
+// snapshot completionNames() at module load, so custom commands registered at
+// session start never reached tab-completion. These tests lock in that the
+// completion source is resolved live — both the exported SLASH_CMDS and the
+// InputField's own search sources reflect commands registered after load — while
+// the built-in set is unchanged.
+
+const { test } = require('node:test');
+const assert = require('node:assert');
+
+const { completionNames, registerCustomCommands, clearCustomCommands } = require('../lib/commands/registry');
+const inputFieldModule = require('../lib/ui/input-field');
+const { InputField } = inputFieldModule;
+
+test('built-in completion is unchanged at module load (no customs registered)', () => {
+  clearCustomCommands();
+  assert.deepStrictEqual(inputFieldModule.SLASH_CMDS, completionNames());
+  assert.ok(inputFieldModule.SLASH_CMDS.includes('/help'));
+  assert.ok(!inputFieldModule.SLASH_CMDS.includes('/deploy'));
+});
+
+test('a custom command registered after module load appears in the completion source', () => {
+  clearCustomCommands();
+  try {
+    registerCustomCommands([{ name: '/deploy', template: 'Deploy $ARGUMENTS', source: 'global' }]);
+
+    // Exported SLASH_CMDS is a live view, not a load-time snapshot.
+    assert.ok(inputFieldModule.SLASH_CMDS.includes('/deploy'), 'export reflects live registration');
+
+    // The InputField's search sources (driving fuzzy search + tab) include it.
+    const field = new InputField(null, null);
+    const sources = field._getSearchSources();
+    assert.ok(
+      sources.some((s) => s.type === 'command' && s.text === '/deploy'),
+      'search sources include the custom command',
+    );
+    // Built-ins are still present alongside the custom.
+    assert.ok(sources.some((s) => s.type === 'command' && s.text === '/help'));
+  } finally {
+    clearCustomCommands();
+  }
+});
+
+test('clearing custom commands removes them from the completion source', () => {
+  clearCustomCommands();
+  registerCustomCommands([{ name: '/temp', template: 't' }]);
+  assert.ok(inputFieldModule.SLASH_CMDS.includes('/temp'));
+  clearCustomCommands();
+  assert.ok(!inputFieldModule.SLASH_CMDS.includes('/temp'), 'completion source drops cleared customs');
+});

package/test/config-merge.test.js

@@ -0,0 +1,324 @@
+'use strict';
+
+// Tests-first for the layered config hierarchy (Task 2.2):
+//   user (~/.semalt-ai/config.json) → project (.semalt/config.json, found by
+//   walking up to the repo root) → environment variables → CLI flags
+// lowest-to-highest precedence. The merge is factored into pure functions so
+// every layer combination is unit-testable without touching the filesystem.
+
+const os = require('node:os');
+const fs = require('node:fs');
+const path = require('node:path');
+
+// CONFIG_PATH is computed from os.homedir() at module load — redirect HOME to a
+// temp dir BEFORE requiring any lib module so the user-config layer is isolated.
+const TMP_HOME = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'semalt-cfghome-')));
+const PREV_HOME = process.env.HOME;
+const PREV_USERPROFILE = process.env.USERPROFILE;
+process.env.HOME = TMP_HOME;
+process.env.USERPROFILE = TMP_HOME;
+
+const { test, before, after, beforeEach } = require('node:test');
+const assert = require('node:assert');
+
+const { DEFAULT_CONFIG, CONFIG_PATH } = require('../lib/constants');
+const {
+  mergeConfigLayers,
+  envConfigLayer,
+  flagsConfigLayer,
+  findProjectConfigPath,
+  loadProjectConfig,
+  loadConfig,
+  loadUserConfig,
+  configSet,
+  userLayerForPersist,
+} = require('../lib/config');
+
+after(() => {
+  if (PREV_HOME === undefined) delete process.env.HOME; else process.env.HOME = PREV_HOME;
+  if (PREV_USERPROFILE === undefined) delete process.env.USERPROFILE; else process.env.USERPROFILE = PREV_USERPROFILE;
+});
+
+function writeUserConfig(obj) {
+  fs.mkdirSync(path.dirname(CONFIG_PATH), { recursive: true });
+  fs.writeFileSync(CONFIG_PATH, JSON.stringify(obj));
+}
+function clearUserConfig() {
+  try { fs.unlinkSync(CONFIG_PATH); } catch {}
+}
+
+// ---------------------------------------------------------------------------
+// mergeConfigLayers — pure, the precedence engine
+// ---------------------------------------------------------------------------
+
+test('mergeConfigLayers: a later layer overrides an earlier one', () => {
+  const merged = mergeConfigLayers([
+    { api_base: 'http://user', temperature: 0.1 },
+    { api_base: 'http://project' },
+    { api_base: 'http://env' },
+    { api_base: 'http://flags' },
+  ]);
+  assert.strictEqual(merged.api_base, 'http://flags');
+  assert.strictEqual(merged.temperature, 0.1, 'unshadowed lower-layer keys survive');
+});
+
+test('mergeConfigLayers: null/undefined layers are skipped', () => {
+  const merged = mergeConfigLayers([null, { default_model: 'm' }, undefined, {}]);
+  assert.strictEqual(merged.default_model, 'm');
+});
+
+test('mergeConfigLayers: undefined values within a layer do not clobber', () => {
+  const merged = mergeConfigLayers([
+    { default_model: 'keep' },
+    { default_model: undefined },
+  ]);
+  assert.strictEqual(merged.default_model, 'keep');
+});
+
+test('mergeConfigLayers: empty input yields the normalized defaults', () => {
+  const merged = mergeConfigLayers([]);
+  assert.strictEqual(merged.api_base, DEFAULT_CONFIG.api_base);
+  assert.strictEqual(merged.temperature, DEFAULT_CONFIG.temperature);
+});
+
+// ---------------------------------------------------------------------------
+// mcp config scaffold (Task 3.2) — always normalized to { servers: {}, ... }.
+// Task W.8 adds max_result_tokens (the stricter MCP result cap; default applied).
+// ---------------------------------------------------------------------------
+
+const { DEFAULT_MCP_MAX_RESULT_TOKENS } = require('../lib/constants');
+
+test('mcp scaffold: default is an empty servers map (with the default result cap)', () => {
+  const merged = mergeConfigLayers([]);
+  assert.deepStrictEqual(merged.mcp, { servers: {}, max_result_tokens: DEFAULT_MCP_MAX_RESULT_TOKENS });
+});
+
+test('mcp scaffold: a valid servers map is preserved, unknown keys are dropped', () => {
+  const merged = mergeConfigLayers([
+    { mcp: { servers: { fs: { command: 'mcp-fs' } }, junk: 1 } },
+  ]);
+  assert.deepStrictEqual(merged.mcp, {
+    servers: { fs: { command: 'mcp-fs' } },
+    max_result_tokens: DEFAULT_MCP_MAX_RESULT_TOKENS,
+  });
+});
+
+test('mcp scaffold: a valid max_result_tokens is preserved', () => {
+  const merged = mergeConfigLayers([{ mcp: { servers: {}, max_result_tokens: 4321 } }]);
+  assert.strictEqual(merged.mcp.max_result_tokens, 4321);
+});
+
+test('mcp scaffold: malformed mcp values coerce to the empty scaffold', () => {
+  for (const bad of ['nope', 42, ['a'], null, { servers: 'x' }, { servers: ['a'] }]) {
+    assert.deepStrictEqual(mergeConfigLayers([{ mcp: bad }]).mcp, {
+      servers: {}, max_result_tokens: DEFAULT_MCP_MAX_RESULT_TOKENS,
+    });
+  }
+});
+
+test('mcp scaffold: a malformed max_result_tokens falls back to the default', () => {
+  for (const bad of ['x', 0, -5, null]) {
+    assert.strictEqual(
+      mergeConfigLayers([{ mcp: { servers: {}, max_result_tokens: bad } }]).mcp.max_result_tokens,
+      DEFAULT_MCP_MAX_RESULT_TOKENS,
+    );
+  }
+});
+
+// ---------------------------------------------------------------------------
+// envConfigLayer — pure (takes the env object)
+// ---------------------------------------------------------------------------
+
+test('envConfigLayer: maps the supported variables', () => {
+  const layer = envConfigLayer({
+    SEMALT_API_BASE: 'http://env-base',
+    SEMALT_MODEL: 'env-model',
+    HTTPS_PROXY: 'http://proxy:8443',
+    HTTP_PROXY: 'http://proxy:8080',
+  });
+  assert.deepStrictEqual(layer, {
+    api_base: 'http://env-base',
+    default_model: 'env-model',
+    https_proxy: 'http://proxy:8443',
+    http_proxy: 'http://proxy:8080',
+  });
+});
+
+test('envConfigLayer: lowercase proxy variables are honored', () => {
+  const layer = envConfigLayer({ https_proxy: 'http://lc:1', http_proxy: 'http://lc:2' });
+  assert.strictEqual(layer.https_proxy, 'http://lc:1');
+  assert.strictEqual(layer.http_proxy, 'http://lc:2');
+});
+
+test('envConfigLayer: unset variables produce no keys', () => {
+  assert.deepStrictEqual(envConfigLayer({}), {});
+});
+
+test('envConfigLayer: does NOT map SEMALT_API_KEY (owned by secrets.js)', () => {
+  const layer = envConfigLayer({ SEMALT_API_KEY: 'sk-secret' });
+  assert.ok(!('api_key' in layer), 'api_key sourcing stays in secrets.js (Phase 0)');
+});
+
+// ---------------------------------------------------------------------------
+// flagsConfigLayer — pure (takes argv)
+// ---------------------------------------------------------------------------
+
+test('flagsConfigLayer: maps the config-bearing flags', () => {
+  const layer = flagsConfigLayer([
+    '--api-base', 'http://flag-base',
+    '--api-key', 'flag-key',
+    '--dashboard-url', 'http://flag-dash',
+    '--default-model', 'flag-model',
+  ]);
+  assert.deepStrictEqual(layer, {
+    api_base: 'http://flag-base',
+    api_key: 'flag-key',
+    dashboard_url: 'http://flag-dash',
+    default_model: 'flag-model',
+  });
+});
+
+test('flagsConfigLayer: ignores unrelated flags and a trailing flag with no value', () => {
+  assert.deepStrictEqual(flagsConfigLayer(['--model', 'x', '--debug']), {});
+  assert.deepStrictEqual(flagsConfigLayer(['--api-base']), {});
+});
+
+test('flagsConfigLayer: Task 2.7 flags (reasoning-effort value, prompt-caching boolean)', () => {
+  assert.deepStrictEqual(
+    flagsConfigLayer(['--reasoning-effort', 'high', '--prompt-caching']),
+    { reasoning_effort: 'high', prompt_caching: true },
+  );
+});
+
+// ---------------------------------------------------------------------------
+// Project config discovery — upward walk, bounded by the repo root
+// ---------------------------------------------------------------------------
+
+test('findProjectConfigPath: discovers .semalt/config.json from a nested CWD', () => {
+  const root = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'semalt-proj-')));
+  fs.mkdirSync(path.join(root, '.git'), { recursive: true });
+  fs.mkdirSync(path.join(root, '.semalt'), { recursive: true });
+  fs.writeFileSync(path.join(root, '.semalt', 'config.json'), '{}');
+  const nested = path.join(root, 'a', 'b', 'c');
+  fs.mkdirSync(nested, { recursive: true });
+  assert.strictEqual(findProjectConfigPath(nested), path.join(root, '.semalt', 'config.json'));
+});
+
+test('findProjectConfigPath: returns null when there is no project config', () => {
+  const root = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'semalt-noproj-')));
+  fs.mkdirSync(path.join(root, '.git'), { recursive: true }); // repo root, no .semalt
+  const nested = path.join(root, 'x');
+  fs.mkdirSync(nested, { recursive: true });
+  assert.strictEqual(findProjectConfigPath(nested), null);
+});
+
+test('findProjectConfigPath: the nearest config wins', () => {
+  const root = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'semalt-near-')));
+  fs.mkdirSync(path.join(root, '.git'), { recursive: true });
+  fs.mkdirSync(path.join(root, '.semalt'), { recursive: true });
+  fs.writeFileSync(path.join(root, '.semalt', 'config.json'), JSON.stringify({ default_model: 'root' }));
+  const sub = path.join(root, 'pkg');
+  fs.mkdirSync(path.join(sub, '.semalt'), { recursive: true });
+  fs.writeFileSync(path.join(sub, '.semalt', 'config.json'), JSON.stringify({ default_model: 'pkg' }));
+  assert.strictEqual(loadProjectConfig(sub).default_model, 'pkg');
+});
+
+// ---------------------------------------------------------------------------
+// loadConfig — full precedence integration (real fs + env + argv)
+// ---------------------------------------------------------------------------
+
+const PREV_CWD = process.cwd();
+let PROJ_ROOT;
+let PROJ_NESTED;
+const SAVED_ENV = {};
+const ENV_KEYS = ['SEMALT_API_BASE', 'SEMALT_MODEL', 'HTTPS_PROXY', 'HTTP_PROXY'];
+
+before(() => {
+  PROJ_ROOT = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'semalt-load-')));
+  fs.mkdirSync(path.join(PROJ_ROOT, '.git'), { recursive: true });
+  PROJ_NESTED = path.join(PROJ_ROOT, 'deep', 'dir');
+  fs.mkdirSync(PROJ_NESTED, { recursive: true });
+});
+
+beforeEach(() => {
+  clearUserConfig();
+  for (const k of ENV_KEYS) { SAVED_ENV[k] = process.env[k]; delete process.env[k]; }
+  try { fs.rmSync(path.join(PROJ_ROOT, '.semalt'), { recursive: true, force: true }); } catch {}
+  process.chdir(PROJ_NESTED);
+});
+
+after(() => {
+  process.chdir(PREV_CWD);
+  for (const k of ENV_KEYS) { if (SAVED_ENV[k] === undefined) delete process.env[k]; else process.env[k] = SAVED_ENV[k]; }
+});
+
+function writeProjectConfig(obj) {
+  fs.mkdirSync(path.join(PROJ_ROOT, '.semalt'), { recursive: true });
+  fs.writeFileSync(path.join(PROJ_ROOT, '.semalt', 'config.json'), JSON.stringify(obj));
+}
+
+test('loadConfig: project config overrides user config', () => {
+  writeUserConfig({ api_base: 'http://user', default_model: 'user-model' });
+  writeProjectConfig({ default_model: 'project-model' });
+  const cfg = loadConfig([]);
+  assert.strictEqual(cfg.api_base, 'http://user', 'unshadowed user key survives');
+  assert.strictEqual(cfg.default_model, 'project-model', 'project overrides user');
+});
+
+test('loadConfig: env overrides both user and project', () => {
+  writeUserConfig({ api_base: 'http://user' });
+  writeProjectConfig({ api_base: 'http://project' });
+  process.env.SEMALT_API_BASE = 'http://env';
+  const cfg = loadConfig([]);
+  assert.strictEqual(cfg.api_base, 'http://env');
+});
+
+test('loadConfig: flags override env', () => {
+  writeUserConfig({ api_base: 'http://user' });
+  process.env.SEMALT_API_BASE = 'http://env';
+  const cfg = loadConfig(['--api-base', 'http://flag']);
+  assert.strictEqual(cfg.api_base, 'http://flag');
+});
+
+test('loadConfig: proxy env is read and exposed on the merged config', () => {
+  writeUserConfig({});
+  process.env.HTTPS_PROXY = 'http://corp-proxy:8443';
+  const cfg = loadConfig([]);
+  assert.strictEqual(cfg.https_proxy, 'http://corp-proxy:8443');
+});
+
+test('loadConfig: with no layers present, returns the normalized defaults', () => {
+  const cfg = loadConfig([]);
+  assert.strictEqual(cfg.api_base, DEFAULT_CONFIG.api_base);
+});
+
+// ---------------------------------------------------------------------------
+// Persistence never bakes higher-layer overrides into the user file
+// ---------------------------------------------------------------------------
+
+test('userLayerForPersist: only caller-changed keys are layered onto the user file', () => {
+  const prevMerged = { api_base: 'http://env-override', default_model: 'old', theme: 'dark' };
+  const userFile = { api_base: 'http://user-file', default_model: 'old', theme: 'dark' };
+  // Caller changes only default_model; it carries the merged api_base along.
+  const next = { ...prevMerged, default_model: 'new' };
+  const persisted = userLayerForPersist(next, prevMerged, userFile);
+  assert.strictEqual(persisted.default_model, 'new', 'the intended change is persisted');
+  assert.strictEqual(persisted.api_base, 'http://user-file', 'the env override is NOT baked in');
+});
+
+test('configSet writes against the user file only (no override leakage)', () => {
+  writeUserConfig({ api_base: 'http://user', theme: 'dark' });
+  writeProjectConfig({ api_base: 'http://project' });
+  process.env.SEMALT_API_BASE = 'http://env';
+  configSet('theme', 'light');
+  const onDisk = JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf8'));
+  assert.strictEqual(onDisk.theme, 'light', 'the set persisted');
+  assert.strictEqual(onDisk.api_base, 'http://user', 'env/project api_base not baked into the file');
+});
+
+test('loadUserConfig ignores project/env/flags (user file only)', () => {
+  writeUserConfig({ api_base: 'http://user' });
+  writeProjectConfig({ api_base: 'http://project' });
+  process.env.SEMALT_API_BASE = 'http://env';
+  assert.strictEqual(loadUserConfig().api_base, 'http://user');
+});