mixdog 0.7.1

package/scripts/builtin-utils-smoke.mjs

@@ -0,0 +1,392 @@
+// Smoke test: builtin.mjs public utility helpers (path normalize / shape
+// coercion / cache key builders). Edit-input normalization helpers are
+// covered separately in edit-normalize-smoke.mjs; this file targets the
+// rest of the cross-tool surface so a regression there doesn't slip
+// through CI just because edit invariants still pass.
+
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
+
+const ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
+process.env.CLAUDE_PLUGIN_ROOT ||= ROOT;
+process.env.CLAUDE_PLUGIN_DATA ||= join(tmpdir(), `mixdog-builtin-utils-smoke-data-${process.pid}`);
+process.env.MIXDOG_HINT_LEVEL ||= 'normal';
+
+const {
+    posixPathToWindowsPath,
+    normalizeInputPath,
+    normalizeOutputPath,
+    coerceShapeFlex,
+    canonicalizeBuiltinToolName,
+    executeBuiltinTool,
+    formatUnknownBuiltinToolMessage,
+    isBuiltinTool,
+} = await import('../src/agent/orchestrator/tools/builtin.mjs');
+const {
+    clearReadDedupSession,
+    clearScopedToolsForSessionPaths,
+    drainPrefetchDiskWrites,
+    invalidatePrefetchCache,
+    setPrefetchCached,
+    setScopedToolCached,
+    setReadCached,
+    tryPrefetchCached,
+    tryScopedToolCached,
+    tryReadCached,
+} = await import('../src/agent/orchestrator/session/read-dedup.mjs');
+const {
+    TOOL_RESULT_OFFLOAD_PREFIX,
+    _internals: offloadInternals,
+    compactOffloadedToolResultText,
+} = await import('../src/agent/orchestrator/session/tool-result-offload.mjs');
+const {
+    normalizeGrepLine,
+} = await import('../src/agent/orchestrator/tools/builtin/grep-formatting.mjs');
+const {
+    _pruneCodeGraphManifestForBudget,
+} = await import('../src/agent/orchestrator/tools/code-graph.mjs');
+
+let failures = 0;
+function fail(name, msg) { console.error(`FAIL ${name}: ${msg}`); failures++; }
+
+// ── coerceShapeFlex ────────────────────────────────────────────────────────
+// Transports occasionally JSON-stringify array parameters. Helper must:
+//   • parse `[a,b]` style strings to arrays,
+//   • unwrap `"quoted"` strings to their inner value,
+//   • leave plain strings, arrays, and primitives untouched.
+const coerceCases = [
+    { name: 'plain-string',         input: 'foo',           expected: 'foo' },
+    { name: 'json-array',           input: '["a","b"]',     expected: ['a', 'b'] },
+    { name: 'json-array-numbers',   input: '[1,2,3]',       expected: [1, 2, 3] },
+    { name: 'quoted-string',        input: '"hello"',       expected: 'hello' },
+    { name: 'actual-array',         input: ['a', 'b'],      expected: ['a', 'b'] },
+    { name: 'empty-string',         input: '',              expected: '' },
+    { name: 'malformed-json',       input: '[foo',          expected: '[foo' },
+    { name: 'undefined',            input: undefined,       expected: undefined },
+    { name: 'number',               input: 42,              expected: 42 },
+];
+
+const jsonEq = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+for (const { name, input, expected } of coerceCases) {
+    const got = coerceShapeFlex(input);
+    if (!jsonEq(got, expected)) {
+        fail(`coerce:${name}`, `got ${JSON.stringify(got)}, expected ${JSON.stringify(expected)}`);
+    }
+}
+
+// ── builtin tool name recovery ─────────────────────────────────────────────
+if (canonicalizeBuiltinToolName('grop') !== 'grep') fail('tool-alias:grop', 'expected grop -> grep');
+if (canonicalizeBuiltinToolName('glbo') !== 'glob') fail('tool-alias:glbo', 'expected glbo -> glob');
+if (!isBuiltinTool('grop')) fail('tool-alias:is-builtin', 'expected grop to be treated as builtin alias');
+const unknownToolHint = formatUnknownBuiltinToolMessage('grepp', { pattern: 'needle', path: 'src' }, 'tool');
+if (!unknownToolHint.includes('Did you mean "grep"') || unknownToolHint.includes('next_call:')) {
+    fail('tool-alias:unknown-hint', `expected concise grep suggestion, got ${JSON.stringify(unknownToolHint)}`);
+}
+
+// ── normalizeInputPath / normalizeOutputPath ───────────────────────────────
+// Path normalization round-trips: Windows forward-slash and backslash
+// representations of the same path collapse to one form; POSIX-style
+// `/c/Users/...` drive paths decode back to Windows drive form.
+// Output normalization is the inverse — the user-facing form mixdog
+// always emits regardless of how it received the path.
+const pathCases = [
+    { name: 'windows-backslash',    input: 'C:\\Users\\foo\\bar', shouldHaveSlashes: true },
+    { name: 'windows-forwardslash', input: 'C:/Users/foo/bar',    shouldHaveSlashes: true },
+    { name: 'posix-style',          input: '/c/Users/foo/bar',    shouldHaveSlashes: true },
+    { name: 'relative-path',        input: 'src/foo.js',          shouldHaveSlashes: true },
+    { name: 'empty-string',         input: '',                    shouldHaveSlashes: false },
+];
+
+// Looser invariant: idempotent + string-typed. mixdog uses a mix of
+// forward and backward slashes internally; what matters is that the
+// second normalization pass produces the same output as the first.
+for (const { name, input } of pathCases) {
+    const a = normalizeInputPath(input);
+    if (typeof a !== 'string') { fail(`path-in:${name}`, `expected string, got ${typeof a}`); continue; }
+    const b = normalizeInputPath(a);
+    if (a !== b) fail(`path-in:${name}:idempotent`, `normalizeInputPath not idempotent: ${JSON.stringify(a)} -> ${JSON.stringify(b)}`);
+}
+
+const out1 = normalizeOutputPath('C:\\Users\\foo');
+if (typeof out1 !== 'string') fail('path-out:windows', `expected string, got ${typeof out1}`);
+const out2 = normalizeOutputPath('src/foo.js');
+if (typeof out2 !== 'string') fail('path-out:relative', `expected string, got ${typeof out2}`);
+
+// posixPathToWindowsPath: `/c/Users/foo` → drive-letter prefix.
+// Accept either case for the drive letter (POSIX `/c/` doesn't carry case).
+const winFromPosix = posixPathToWindowsPath('/c/Users/foo');
+if (typeof winFromPosix !== 'string') {
+    fail('posix-to-win:basic', `expected string, got ${typeof winFromPosix}`);
+} else if (!/^[a-zA-Z]:/.test(winFromPosix)) {
+    fail('posix-to-win:basic', `expected drive-letter prefix, got ${JSON.stringify(winFromPosix)}`);
+}
+
+// ── read cache key shape ───────────────────────────────────────────────────
+// Object-array reads include line/context/full and file_path aliases in their
+// key. Otherwise read({path:[{path, line:10}]}) could be reused for line:20.
+const cacheWork = join(tmpdir(), `mixdog-builtin-cache-smoke-${process.pid}-${Date.now()}`);
+mkdirSync(cacheWork, { recursive: true });
+try {
+    writeFileSync(join(cacheWork, 'cache-key.txt'), 'line-1\nline-2\nline-3\n');
+    const sessionId = `builtin-utils-${process.pid}`;
+    clearReadDedupSession(sessionId);
+    setReadCached({
+        sessionId,
+        cwd: cacheWork,
+        args: { path: [{ file_path: 'cache-key.txt', line: 1, context: 0 }] },
+        content: 'line one',
+        toolUseId: 'tool-1',
+    });
+    const hit = tryReadCached({
+        sessionId,
+        cwd: cacheWork,
+        args: { path: [{ path: 'cache-key.txt', line: 1, context: 0 }] },
+    });
+    if (!hit || hit.content !== 'line one') fail('read-cache:file_path-alias', `expected cache hit, got ${JSON.stringify(hit)}`);
+    setReadCached({
+        sessionId,
+        cwd: cacheWork,
+        args: { path: [{ path: 'cache-key.txt', line: 1, context: 0 }] },
+        content: 'line one again',
+        toolUseId: 'tool-2',
+    });
+    const miss = tryReadCached({
+        sessionId,
+        cwd: cacheWork,
+        args: { path: [{ path: 'cache-key.txt', line: 2, context: 0 }] },
+    });
+    if (miss !== null) fail('read-cache:line-partition', `line:2 should not hit line:1 cache, got ${JSON.stringify(miss)}`);
+    setReadCached({
+        sessionId,
+        cwd: cacheWork,
+        args: { path: 'cache-key.txt', line: 1, context: 0 },
+        content: 'scalar line one',
+        toolUseId: 'tool-3',
+    });
+    const scalarMiss = tryReadCached({
+        sessionId,
+        cwd: cacheWork,
+        args: { path: 'cache-key.txt', line: 2, context: 0 },
+    });
+    if (scalarMiss !== null) fail('read-cache:scalar-line-partition', `scalar line:2 should not hit line:1 cache, got ${JSON.stringify(scalarMiss)}`);
+    clearReadDedupSession(sessionId);
+} finally {
+    rmSync(cacheWork, { recursive: true, force: true });
+}
+
+// Full-file snapshots must not collapse later line-window reads.
+const readWindowWork = join(tmpdir(), `mixdog-read-window-smoke-${process.pid}-${Date.now()}`);
+mkdirSync(readWindowWork, { recursive: true });
+try {
+    writeFileSync(join(readWindowWork, 'window.txt'), Array.from({ length: 20 }, (_, i) => `line-${i + 1}`).join('\n') + '\n');
+    const sessionId = `builtin-read-window-${process.pid}`;
+    clearReadDedupSession(sessionId);
+    await executeBuiltinTool('read', { path: 'window.txt' }, readWindowWork, { readStateScope: sessionId, sessionId });
+    const reread = await executeBuiltinTool('read', { path: 'window.txt', line: 10, context: 1 }, readWindowWork, { readStateScope: sessionId, sessionId });
+    // Separator-agnostic: the read formatter renders `N<sep>content` (currently
+    // `→`). Assert the actual intent — a FRESH line-10±1 window (lines 9-11 of 20)
+    // that the prior full-file read did not collapse — not a hardcoded glyph.
+    if (!String(reread).includes('line-10') || !String(reread).includes('lines 9-11 of 20')) {
+        fail('read-window-after-full', `expected fresh window after full read, got ${JSON.stringify(reread)}`);
+    }
+    clearReadDedupSession(sessionId);
+} finally {
+    rmSync(readWindowWork, { recursive: true, force: true });
+}
+
+// ── grep context byte-exactness ───────────────────────────────────────────
+// Windows rg omits the path for a single-file search, so context lines arrive
+// as `N-content`. The formatter must not treat a later colon inside CONTENT as
+// a path delimiter and normalize source backslashes (`\n` -> `/n`).
+const grepContextWork = join(tmpdir(), `mixdog-grep-context-smoke-${process.pid}-${Date.now()}`);
+mkdirSync(grepContextWork, { recursive: true });
+try {
+    const fixture = join(grepContextWork, 'context.txt');
+    writeFileSync(fixture, 'context literal \\n \\r \\t ? a : b\nneedle\ntrailing\n');
+    const numericDir = join(grepContextWork, '12-x');
+    mkdirSync(numericDir, { recursive: true });
+    const numericFixture = join(numericDir, 'path.txt');
+    writeFileSync(numericFixture, 'numeric path literal \\n \\t ? a : b\nnumeric-needle\ntrailing\n');
+    const grepOutputs = [
+        ['single-file', await executeBuiltinTool(
+            'grep',
+            { pattern: 'needle', path: fixture, output_mode: 'content', '-C': 1 },
+            grepContextWork,
+            { sessionId: `grep-context-file-${process.pid}` },
+        )],
+        ['absolute-dir', await executeBuiltinTool(
+            'grep',
+            { pattern: 'needle', path: grepContextWork, output_mode: 'content', '-C': 1 },
+            grepContextWork,
+            { sessionId: `grep-context-dir-${process.pid}` },
+        )],
+    ];
+    for (const [caseName, rawOut] of grepOutputs) {
+        const out = String(rawOut);
+        if (!out.includes('context literal \\n \\r \\t ? a : b')) {
+            fail(`grep-context:${caseName}:literal-backslashes`, `expected literal backslash escapes in context, got ${JSON.stringify(out)}`);
+        }
+        if (out.includes('context literal /n /r /t ? a : b')) {
+            fail(`grep-context:${caseName}:no-slash-corruption`, `context backslashes were corrupted, got ${JSON.stringify(out)}`);
+        }
+    }
+    const numericOut = String(await executeBuiltinTool(
+        'grep',
+        { pattern: 'numeric-needle', path: '.', output_mode: 'content', '-C': 1 },
+        grepContextWork,
+        { sessionId: `grep-context-numeric-dir-${process.pid}` },
+    ));
+    if (!numericOut.includes('12-x/path.txt-1-numeric path literal \\n \\t ? a : b')) {
+        fail('grep-context:numeric-leading-path-normalized', `expected digit-hyphen-leading path prefix normalized and content preserved, got ${JSON.stringify(numericOut)}`);
+    }
+    if (numericOut.includes('numeric path literal /n /t ? a : b')) {
+        fail('grep-context:numeric-leading-content-exact', `numeric-leading path context backslashes were corrupted, got ${JSON.stringify(numericOut)}`);
+    }
+} finally {
+    rmSync(grepContextWork, { recursive: true, force: true });
+}
+
+if (process.platform === 'win32') {
+    const filenameOmittedContext = String.raw`1-context literal \n \t -5- ? a : b`;
+    const normalizedFilenameOmitted = normalizeGrepLine(filenameOmittedContext, false, 'content', true);
+    if (normalizedFilenameOmitted !== filenameOmittedContext) {
+        fail('grep-context:filename-omitted-exact', `expected byte-exact filename-omitted context, got ${JSON.stringify(normalizedFilenameOmitted)}`);
+    }
+    const filenamePresentContext = String.raw`12-x\path.txt-5-context literal \n \t ? a : b`;
+    const expectedFilenamePresent = String.raw`12-x/path.txt-5-context literal \n \t ? a : b`;
+    const normalizedFilenamePresent = normalizeGrepLine(filenamePresentContext);
+    if (normalizedFilenamePresent !== expectedFilenamePresent) {
+        fail('grep-context:filename-present-exact', `expected exact filename-present context prefix normalization, got ${JSON.stringify(normalizedFilenamePresent)}`);
+    }
+}
+
+// ── code graph disk cache budget pruning ──────────────────────────────────
+// The code-graph cache is per-cwd, so entry count alone is not enough:
+// a handful of large workspaces can exceed the doctor storage warning.
+// Budget pruning must keep the newest entries that fit the byte cap and
+// drop stale or missing manifest rows.
+const codeGraphCacheWork = join(tmpdir(), `mixdog-code-graph-cache-smoke-${process.pid}-${Date.now()}`);
+mkdirSync(codeGraphCacheWork, { recursive: true });
+try {
+    writeFileSync(join(codeGraphCacheWork, 'aaaaaaaaaaaaaaaa.json'), 'a'.repeat(40));
+    writeFileSync(join(codeGraphCacheWork, 'bbbbbbbbbbbbbbbb.json'), 'b'.repeat(40));
+    writeFileSync(join(codeGraphCacheWork, 'cccccccccccccccc.json'), 'c'.repeat(40));
+    const pruned = _pruneCodeGraphManifestForBudget({
+        old: { hash: 'aaaaaaaaaaaaaaaa', builtAt: 1 },
+        mid: { hash: 'bbbbbbbbbbbbbbbb', builtAt: 2 },
+        newest: { hash: 'cccccccccccccccc', builtAt: 3 },
+        missing: { hash: 'dddddddddddddddd', builtAt: 4 },
+        unsafe: { hash: '../escape', builtAt: 5 },
+    }, codeGraphCacheWork, { maxEntries: 2, maxBytes: 70 });
+    const keptKeys = Object.keys(pruned.manifest).sort();
+    if (!jsonEq(keptKeys, ['newest'])) {
+        fail('code-graph-cache:budget-prune', `expected newest only, got ${JSON.stringify(pruned)}`);
+    }
+    const reasons = new Set((pruned.evicted || []).map((row) => row.reason));
+    if (!reasons.has('max-entries') || !reasons.has('max-bytes')) {
+        fail('code-graph-cache:prune-reasons', `expected entry and byte prune reasons, got ${JSON.stringify(pruned.evicted)}`);
+    }
+} finally {
+    rmSync(codeGraphCacheWork, { recursive: true, force: true });
+}
+
+// ── scoped cache invalidation ──────────────────────────────────────────────
+// grep/list/glob cache entries are path-root scoped. Editing src/a.txt must
+// evict a prior grep({path:"src"}) result even though the exact touched path
+// differs from the cached root.
+const scopedWork = join(tmpdir(), `mixdog-scoped-cache-smoke-${process.pid}-${Date.now()}`);
+mkdirSync(join(scopedWork, 'src'), { recursive: true });
+try {
+    writeFileSync(join(scopedWork, 'src', 'a.txt'), 'needle\n');
+    const sessionId = `scoped-utils-${process.pid}`;
+    clearReadDedupSession(sessionId);
+    setScopedToolCached({
+        sessionId,
+        toolName: 'grep',
+        cwd: scopedWork,
+        args: { query: 'needle', root: 'src', mode: 'content' },
+        content: 'src/a.txt:1:needle',
+        toolUseId: 'grep-1',
+    });
+    const aliasHit = tryScopedToolCached({
+        sessionId,
+        toolName: 'grep',
+        cwd: scopedWork,
+        args: { pattern: 'needle', path: 'src', output_mode: 'content' },
+    });
+    if (!aliasHit || aliasHit.content !== 'src/a.txt:1:needle') fail('scoped-cache:alias-hit', `expected canonical alias hit, got ${JSON.stringify(aliasHit)}`);
+    setScopedToolCached({
+        sessionId,
+        toolName: 'grep',
+        cwd: scopedWork,
+        args: { pattern: 'needle', path: 'src', output_mode: 'content' },
+        content: 'src/a.txt:1:needle',
+        toolUseId: 'grep-2',
+    });
+    clearScopedToolsForSessionPaths(sessionId, ['src/a.txt'], scopedWork);
+    const stale = tryScopedToolCached({
+        sessionId,
+        toolName: 'grep',
+        cwd: scopedWork,
+        args: { pattern: 'needle', path: 'src', output_mode: 'content' },
+    });
+    if (stale !== null) fail('scoped-cache:root-invalidation', `edit under cached root should evict, got ${JSON.stringify(stale)}`);
+    clearReadDedupSession(sessionId);
+} finally {
+    rmSync(scopedWork, { recursive: true, force: true });
+}
+
+// ── prefetch cache invalidation ────────────────────────────────────────────
+const prefetchWork = join(tmpdir(), `mixdog-prefetch-cache-smoke-${process.pid}-${Date.now()}`);
+mkdirSync(prefetchWork, { recursive: true });
+try {
+    const filePath = join(prefetchWork, 'prefetch.txt');
+    writeFileSync(filePath, 'prefetch source\n');
+    invalidatePrefetchCache(filePath, prefetchWork);
+    setPrefetchCached(filePath, 'cached prefetch body');
+    const hit = tryPrefetchCached(filePath);
+    if (!hit || hit.content !== 'cached prefetch body') fail('prefetch-cache:hit', `expected prefetch cache hit, got ${JSON.stringify(hit)}`);
+    writeFileSync(filePath, 'prefetch source changed and longer\n');
+    const stale = tryPrefetchCached(filePath);
+    if (stale !== null) fail('prefetch-cache:stat-invalidate', `expected stale miss, got ${JSON.stringify(stale)}`);
+    drainPrefetchDiskWrites();
+    invalidatePrefetchCache(filePath, prefetchWork);
+} finally {
+    rmSync(prefetchWork, { recursive: true, force: true });
+}
+
+// ── offload helpers ────────────────────────────────────────────────────────
+// countLines must preserve the old split('\n') semantics without allocating
+// an array for very large tool outputs.
+if (offloadInternals.countLines('') !== 0) fail('offload:empty-lines', `expected 0, got ${offloadInternals.countLines('')}`);
+if (offloadInternals.countLines('one') !== 1) fail('offload:single-line', `expected 1, got ${offloadInternals.countLines('one')}`);
+if (offloadInternals.countLines('one\ntwo\n') !== 3) fail('offload:trailing-newline', `expected 3, got ${offloadInternals.countLines('one\ntwo\n')}`);
+const compactedOffload = compactOffloadedToolResultText(`${TOOL_RESULT_OFFLOAD_PREFIX} grep -> /tmp/r1.txt (1 KB, 2 lines)]\nline-1\nline-2`);
+if (!compactedOffload.includes('[preview omitted')) fail('offload:compact-stub', `expected compact preview marker, got ${JSON.stringify(compactedOffload)}`);
+
+// Note: cache key + rg argv builders are internal helpers with implicit
+// option-bag schemas that drift faster than this smoke can keep up with.
+// They are exercised end-to-end by the live grep / glob / list tools, so
+// invariant drift would surface there rather than as a silent miss.
+
+const totalChecks = coerceCases.length + pathCases.length + 2 /* output paths */
+    + 1 /* posix-to-win */
+    + 4 /* builtin tool name recovery */
+    + 3 /* read-cache key shape */
+    + 8 /* grep context byte-exactness */
+    + 2 /* scoped-cache root invalidation */
+    + 2 /* prefetch cache invalidation */
+    + 4 /* offload helpers */;
+
+if (failures > 0) {
+    console.error(`\n${failures} smoke check(s) failed.`);
+    process.exit(1);
+}
+console.log(`builtin-utils-smoke: ${totalChecks} checks passed.`);
+// Explicit success exit: imported builtin/read-dedup/offload modules keep a
+// background flush timer alive, so without this the process never exits and
+// the ci:core `&&` chain stalls after this step. Mirrors the failure path
+// and the sibling smokes (guard-smoke / edit-normalize) which exit explicitly.
+process.exit(0);

package/scripts/check-json.mjs

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+import { readFileSync, readdirSync } from 'fs';
+import { join, relative } from 'path';
+
+const ROOT = process.cwd();
+const SKIP_DIRS = new Set([
+  '.git',
+  '.mixdog',
+  'build',
+  'coverage',
+  'dist',
+  'node_modules',
+  'refs',
+  'target',
+]);
+
+function walk(dir, out = []) {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.isDirectory()) {
+      if (SKIP_DIRS.has(entry.name)) continue;
+      walk(join(dir, entry.name), out);
+      continue;
+    }
+    if (entry.isFile() && entry.name.endsWith('.json')) out.push(join(dir, entry.name));
+  }
+  return out;
+}
+
+const files = walk(ROOT).sort();
+let failed = 0;
+for (const file of files) {
+  try {
+    JSON.parse(readFileSync(file, 'utf8'));
+  } catch (e) {
+    failed++;
+    process.stderr.write(`FAIL ${relative(ROOT, file)}: ${e.message}\n`);
+  }
+}
+
+if (failed > 0) {
+  process.stderr.write(`JSON check failed: ${failed}/${files.length}\n`);
+  process.exit(1);
+}
+
+process.stdout.write(`JSON check passed: ${files.length} files\n`);

package/scripts/check-syntax-changed.mjs

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+import { spawnSync } from 'child_process';
+import { existsSync, statSync } from 'fs';
+import { join, relative, resolve } from 'path';
+import { fileURLToPath } from 'url';
+
+const ROOT = process.cwd();
+const EXTENSIONS = new Set(['.mjs', '.cjs']);
+
+function extname(file) {
+  const idx = file.lastIndexOf('.');
+  return idx >= 0 ? file.slice(idx) : '';
+}
+
+function runGit(args) {
+  const res = spawnSync('git', args, {
+    cwd: ROOT,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  return res;
+}
+
+function isGitRepo() {
+  const res = runGit(['rev-parse', '--is-inside-work-tree']);
+  return res.status === 0 && res.stdout.trim() === 'true';
+}
+
+function collectChanged() {
+  const out = new Set();
+  const diff = runGit(['diff', '--name-only', 'HEAD']);
+  if (diff.status === 0) {
+    for (const line of diff.stdout.split(/\r?\n/)) {
+      const p = line.trim();
+      if (p) out.add(p);
+    }
+  }
+  const untracked = runGit(['ls-files', '--others', '--exclude-standard']);
+  if (untracked.status === 0) {
+    for (const line of untracked.stdout.split(/\r?\n/)) {
+      const p = line.trim();
+      if (p) out.add(p);
+    }
+  }
+  return [...out];
+}
+
+function fallbackFull() {
+  const here = fileURLToPath(import.meta.url);
+  const full = resolve(here, '..', 'check-syntax.mjs');
+  const res = spawnSync(process.execPath, [full], {
+    cwd: ROOT,
+    stdio: 'inherit',
+  });
+  process.exit(res.status ?? 1);
+}
+
+if (!isGitRepo()) {
+  process.stdout.write('check:changed: not a git repo, running full check:syntax\n');
+  fallbackFull();
+}
+
+const candidates = collectChanged()
+  .filter((p) => EXTENSIONS.has(extname(p)))
+  .map((p) => join(ROOT, p))
+  .filter((abs) => {
+    if (!existsSync(abs)) return false;
+    try {
+      return statSync(abs).isFile();
+    } catch {
+      return false;
+    }
+  });
+
+const files = [...new Set(candidates)].sort();
+
+if (files.length === 0) {
+  process.stdout.write('check:changed: no changed .mjs/.cjs files, running full check:syntax\n');
+  fallbackFull();
+}
+
+let failed = 0;
+for (const file of files) {
+  const rel = relative(ROOT, file);
+  const res = spawnSync('node', ['--check', file], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  if (res.status !== 0) {
+    failed++;
+    process.stderr.write(`FAIL ${rel}\n`);
+    if (res.stderr) process.stderr.write(res.stderr);
+    if (res.stdout) process.stderr.write(res.stdout);
+  }
+}
+
+if (failed > 0) {
+  process.stderr.write(`JavaScript syntax check (changed) failed: ${failed}/${files.length}\n`);
+  process.exit(1);
+}
+
+process.stdout.write(`JavaScript syntax check (changed) passed: ${files.length} files\n`);

package/scripts/check-syntax.mjs

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+import { readdirSync } from 'fs';
+import { join, relative } from 'path';
+import { spawnSync } from 'child_process';
+
+const ROOT = process.cwd();
+const SKIP_DIRS = new Set([
+  '.git',
+  '.mixdog',
+  'build',
+  'coverage',
+  'dist',
+  'node_modules',
+  'refs',
+  'target',
+]);
+const EXTENSIONS = new Set(['.js', '.cjs', '.mjs']);
+
+function extname(file) {
+  const idx = file.lastIndexOf('.');
+  return idx >= 0 ? file.slice(idx) : '';
+}
+
+function walk(dir, out = []) {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.isDirectory()) {
+      if (SKIP_DIRS.has(entry.name)) continue;
+      walk(join(dir, entry.name), out);
+      continue;
+    }
+    if (!entry.isFile()) continue;
+    if (EXTENSIONS.has(extname(entry.name))) out.push(join(dir, entry.name));
+  }
+  return out;
+}
+
+const files = walk(ROOT).sort();
+let failed = 0;
+for (const file of files) {
+  const rel = relative(ROOT, file);
+  const res = spawnSync('node', ['--check', file], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  if (res.status !== 0) {
+    failed++;
+    process.stderr.write(`FAIL ${rel}\n`);
+    if (res.stderr) process.stderr.write(res.stderr);
+    if (res.stdout) process.stderr.write(res.stdout);
+  }
+}
+
+if (failed > 0) {
+  process.stderr.write(`JavaScript syntax check failed: ${failed}/${files.length}\n`);
+  process.exit(1);
+}
+
+process.stdout.write(`JavaScript syntax check passed: ${files.length} files\n`);

package/scripts/code-graph-batch.test.mjs

@@ -0,0 +1,33 @@
+// Regression: code_graph runs batchable symbol modes (find_symbol/callers/
+// callees/references) once per name when several are requested, so N lookups
+// cost ONE call. A single name (or single-element symbols[]) stays byte-identical
+// to the legacy single-symbol output (no per-symbol header).
+// Uses this repo's own exported symbols. Run: node scripts/code-graph-batch.test.mjs
+import { executeCodeGraphTool } from '../src/agent/orchestrator/tools/code-graph.mjs';
+
+const CWD = process.cwd();
+const call = (args) => executeCodeGraphTool('code_graph', args, CWD, null, {});
+let pass = 0, fail = 0;
+const ok = (label, cond, detail = '') => {
+  console.log(`${cond ? 'PASS' : 'FAIL'}  ${label}${detail ? '  -> ' + detail : ''}`);
+  cond ? pass++ : fail++;
+};
+
+// 1. Batch via symbols[] — one call, one section per symbol.
+const r1 = await call({ mode: 'find_symbol', symbols: ['peekShellJob', 'killShellJob'] });
+ok('batch find_symbol via symbols[]', /# find_symbol peekShellJob/.test(r1) && /# find_symbol killShellJob/.test(r1));
+
+// 2. Batch via space-separated symbol field (most portable across MCP schema caches).
+const r2 = await call({ mode: 'callers', symbol: 'peekShellJob killShellJob' });
+ok('batch callers via space-separated symbol', /# callers peekShellJob/.test(r2) && /# callers killShellJob/.test(r2));
+
+// 3. Single symbol — unchanged, NO batch header.
+const r3 = await call({ mode: 'find_symbol', symbol: 'peekShellJob' });
+ok('single find_symbol unchanged (no header)', !/# find_symbol /.test(r3) && r3.length > 0);
+
+// 4. Single-element symbols[] resolves (no "provide symbol" error, no header).
+const r4 = await call({ mode: 'find_symbol', symbols: ['peekShellJob'] });
+ok('single-element symbols[] resolves', !/# find_symbol /.test(r4) && r4.length > 0 && !/provide .symbol./.test(r4));
+
+console.log(`\n${fail === 0 ? 'ALL OK' : 'FAILURES'}: ${pass} passed, ${fail} failed`);
+process.exit(fail === 0 ? 0 : 1);