mixdog 0.9.37 → 0.9.39

package/scripts/execution-resume-esc-integration-test.mjs

@@ -0,0 +1,174 @@
+// Production-path regression: runtime completion notification -> feed enqueue
+// -> session drain -> real runTurn -> Esc. This deliberately uses the real
+// feed, queue, API, and turn implementations rather than fabricating restore
+// state, so ownership survives the same path used by the TUI.
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { createAgentJobFeed } from '../src/tui/engine/agent-job-feed.mjs';
+import { createSessionFlow } from '../src/tui/engine/session-flow.mjs';
+import { createRunTurn } from '../src/tui/engine/turn.mjs';
+import { createEngineApiA } from '../src/tui/engine/session-api.mjs';
+import { _clearDeliveredCompletions } from '../src/runtime/agent/orchestrator/session/manager/delivered-completions.mjs';
+
+const tick = () => new Promise((resolve) => setImmediate(resolve));
+const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+function completion(executionId, body) {
+  return {
+    content: `Async agent task ${executionId} completed finished.\n\nResult:\n> ${body}`,
+    meta: { type: 'agent_task_result', execution_id: executionId, status: 'completed' },
+  };
+}
+
+function makeHarness() {
+  let seq = 0;
+  let notify = null;
+  let activeAsk = null;
+  let feed = null;
+  const asks = [];
+  const pending = [];
+  const itemIndexById = new Map();
+  const state = {
+    items: [],
+    queued: [],
+    busy: false,
+    commandBusy: false,
+    spinner: null,
+    thinking: null,
+    lastTurn: null,
+    stats: { turns: 0, inputTokens: 0, outputTokens: 0 },
+  };
+  const runtime = {
+    id: null,
+    toolMode: 'auto',
+    onNotification: (fn) => { notify = fn; return () => {}; },
+    consumePendingSessionReset: () => null,
+    ask: async (text, options) => new Promise((resolve, reject) => {
+      activeAsk = { text, options, reject };
+      asks.push(activeAsk);
+    }),
+    abort: () => {
+      const error = new Error('interrupted');
+      error.name = 'SessionClosedError';
+      activeAsk?.reject(error);
+      return true;
+    },
+  };
+  const bag = {
+    runtime,
+    nextId: () => `id_${++seq}`,
+    tuiDebug: () => {},
+    LEAD_TURN_TIMEOUT_MS: 300_000,
+    flags: { leadTurnEpoch: 0, drainEpoch: 0, disposed: false, draining: false, activePromptRestore: null },
+    pending,
+    pendingNotificationKeys: new Set(),
+    displayedExecutionNotificationKeys: new Set(),
+    listeners: new Set(),
+    itemIndexById,
+    getState: () => state,
+    set: (patch) => Object.assign(state, patch),
+    pushItem: (item) => {
+      state.items = [...state.items, item];
+      if (item?.id != null) itemIndexById.set(item.id, state.items.length - 1);
+    },
+    patchItem: (id, patch) => {
+      const index = state.items.findIndex((item) => item.id === id);
+      if (index < 0) return false;
+      state.items = state.items.map((item, i) => i === index ? { ...item, ...patch } : item);
+      return true;
+    },
+    replaceItems: (items) => items,
+    pushNotice: () => {},
+    pushUserOrSyntheticItem: (text, id) => {
+      state.items = [...state.items, { kind: 'injected', id, text }];
+    },
+    autoClearState: () => ({ enabled: false }),
+    agentStatusState: () => ({}),
+    routeState: () => ({}),
+    syncContextStats: () => {},
+    denyAllToolApprovals: () => {},
+    requestToolApproval: async () => ({ approved: false }),
+    markToolCallActive: () => {},
+    markToolCallDone: () => {},
+    clearActiveToolSummary: () => {},
+    patchToolCardResult: () => {},
+    flushToolResults: () => {},
+    // session-flow captures this dependency before the feed is constructed;
+    // keep that production ordering while forwarding to the live feed.
+    flushDeferredExecutionPendingResumeKick: () => feed?.flushDeferredExecutionPendingResumeKick(),
+  };
+
+  Object.assign(bag, createSessionFlow(bag));
+  feed = createAgentJobFeed({
+    runtime,
+    getState: bag.getState,
+    set: bag.set,
+    nextId: bag.nextId,
+    getDisposed: () => bag.flags.disposed,
+    patchItem: bag.patchItem,
+    enqueue: (...args) => bag.enqueue(...args),
+    drain: (...args) => bag.drain(...args),
+    pushUserOrSyntheticItem: bag.pushUserOrSyntheticItem,
+    makeQueueEntry: (...args) => bag.makeQueueEntry(...args),
+    getPending: () => pending,
+    agentStatusState: bag.agentStatusState,
+    displayedExecutionNotificationKeys: bag.displayedExecutionNotificationKeys,
+    pushNotice: bag.pushNotice,
+  });
+  Object.assign(bag, feed);
+  bag.runTurn = createRunTurn(bag);
+  const api = createEngineApiA(bag);
+  feed.subscribeRuntimeNotifications();
+
+  return {
+    api,
+    state,
+    asks,
+    deliver: (event) => notify(event),
+    activeAsk: () => activeAsk,
+  };
+}
+
+for (const phase of ['before first delta', 'after response progress']) {
+  test(`runtime completion Esc ${phase} does not restart it, while a new completion wakes`, async () => {
+    _clearDeliveredCompletions();
+    const harness = makeHarness();
+
+    const first = completion('execution_A', 'first result');
+    harness.deliver(first);
+    await tick();
+    assert.equal(harness.asks.length, 1, 'runtime notification drained into a real turn');
+    assert.match(harness.activeAsk().text, /first result/, 'completion body reached runtime.ask');
+    assert.equal(first.modelVisibleDelivered, true, 'notification was acknowledged on the TUI path');
+
+    if (phase === 'after response progress') {
+      harness.activeAsk().options.onTextDelta('partial response\n');
+      await wait(40);
+      assert.equal(
+        harness.state.items.some((item) => item.kind === 'assistant' && /partial response/.test(item.text)),
+        true,
+        'response progress reached the live turn',
+      );
+    }
+
+    assert.equal(harness.api.abort().aborted, true, 'Esc aborts the active runTurn');
+    await tick();
+    assert.equal(harness.state.busy, false, 'busy clears after the real abort unwind');
+    assert.equal(harness.state.spinner, null, 'spinner clears after Esc');
+    assert.equal(harness.state.thinking, null, 'thinking clears after Esc');
+
+    harness.deliver(completion('execution_A', 'duplicate retry'));
+    await tick();
+    assert.equal(harness.asks.length, 1, 'duplicate execution delivery cannot restart the aborted completion');
+
+    harness.deliver(completion('execution_B', 'later result'));
+    await tick();
+    assert.equal(harness.asks.length, 2, 'a genuinely new execution still wakes a turn');
+    assert.match(harness.activeAsk().text, /later result/);
+
+    // Finish the second intentionally-open mocked provider request.
+    harness.api.abort();
+    await tick();
+  });
+}

package/scripts/explore-bench.mjs

@@ -6,13 +6,77 @@
 //   node scripts/explore-bench.mjs [roundLabel]
 // Fresh process per run = no in-memory result cache carryover.
 import { readFileSync, existsSync } from 'node:fs';
-import { join } from 'node:path';
+import { join, isAbsolute } from 'node:path';
 import { homedir } from 'node:os';
 import { runExplore } from '../src/standalone/explore-tool.mjs';
 
 const ROUND = process.argv[2] || 'r0';
 const CWD = 'C:/Project/mixdog';
 
+// Anchor helpers: an anchor line carries a `path:line`. Strict quality =
+// expected token must land ON such a line (not merely somewhere in the text),
+// and anchors===0 is always a miss (except expectFail). Spot-accuracy verifies
+// the referenced file exists and the line number is within the file length.
+function anchorLinesOf(text) {
+  return text.split('\n').filter((l) => /:\d+/.test(l));
+}
+// Variant-aware token matching for the fabricated-line guard. Split
+// camelCase and snake_case/kebab joins into atomic sub-tokens, then compare
+// on a light stem so plural/verb forms unify (importance/importanceScore/
+// chunk_importance -> {importance,score,chunk}; scoring~score, memories~memory).
+// Matching is exact stem-equality of sub-tokens (never substring), so it does
+// not loosen into generic-word overlap.
+function splitSubtokens(s) {
+  return String(s)
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2') // camelCase boundary
+    .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2') // ACRONYMWord boundary
+    .split(/[^A-Za-z0-9]+/) // snake_case / kebab / punctuation
+    .map((t) => t.toLowerCase())
+    .filter(Boolean);
+}
+function stemToken(t) {
+  if (t.length <= 4) return t;
+  return t
+    .replace(/ies$/, 'y')
+    .replace(/(ings|ing|edly|ed|es|ly|s)$/, '')
+    .replace(/e$/, '');
+}
+function checkAnchorLine(line, ctxTokens = []) {
+  const m = line.match(/([A-Za-z0-9_.\/\\-]+):(\d+)/);
+  if (!m) return null; // no parseable path:line
+  const p = m[1];
+  const ln = Number(m[2]);
+  const full = isAbsolute(p) ? p : join(CWD, p);
+  if (!existsSync(full)) return false;
+  try {
+    const fileLines = readFileSync(full, 'utf8').split('\n');
+    if (!(ln >= 1 && ln <= fileLines.length)) return false;
+    // Fabricated-line guard: the cited line's ±2 window must contain a
+    // query/expected token, so a plausible-but-wrong line number fails.
+    if (ctxTokens.length) {
+      // ±2 lines around the 1-based cited line (indices ln-3 .. ln+1 inclusive).
+      const win = fileLines.slice(Math.max(0, ln - 3), ln + 2).join('\n');
+      const winStems = [...new Set(splitSubtokens(win).map(stemToken))];
+      const wantStems = ctxTokens.map((t) => stemToken(t.toLowerCase()));
+      // Exact stem-equality unifies plural/verb variants; a prefix relation
+      // additionally bridges derivational forms (compact/compaction) without
+      // matching generic filler. Guard the bridge so a short generic line
+      // token can't satisfy a longer wanted token (impl~implementation,
+      // clas~classifier): require the shorter stem >=5 chars AND a
+      // shorter/longer length ratio >=0.6.
+      const prefixBridge = (s, w) => {
+        if (!(s.startsWith(w) || w.startsWith(s))) return false;
+        const short = Math.min(s.length, w.length);
+        const long = Math.max(s.length, w.length);
+        return short >= 5 && short / long >= 0.6;
+      };
+      const hitStem = (w) => winStems.some((s) => s === w || prefixBridge(s, w));
+      if (!wantStems.some(hitStem)) return false;
+    }
+    return true;
+  } catch { return false; }
+}
+
 // High-fanout timing attribution: emit lightweight per-iteration send_ms
 // loop rows (no verbose payload estimate) so we can split LLM send time
 // from tool time under the parallel round below. Trace-only; no behavior
@@ -68,6 +132,13 @@ const QUERIES = [
     q: 'where is the mixdog config json file path resolved (data dir)',
     expect: ['config', 'plugin-paths'],
   },
+  {
+    // path-only class: the correct answer is a verified file/dir location on
+    // disk; a bare path (no :line) is an allowed HIT for this query.
+    q: 'where does mixdog store background shell job stdout logs on disk',
+    expect: ['shell-jobs', 'shell-job-paths', 'getShellJobsDir', 'shellJobStdout'],
+    pathOnly: true,
+  },
   {
     q: 'GraphQL schema stitching resolver implementation', // not in this repo
     expectFail: true,
@@ -98,17 +169,38 @@ function readTraceSince(ts) {
 const t0 = Date.now();
 // Parallel round: all queries fire at once. Per-session trace attribution is
 // by session_id so counts stay correct; per-query ms includes queueing.
-const results = await Promise.all(QUERIES.map(async ({ q, expect, expectFail }) => {
+const results = await Promise.all(QUERIES.map(async ({ q, expect, expectFail, pathOnly }) => {
   const qt0 = Date.now();
   const res = await runExplore({ query: q, cwd: CWD }, { callerCwd: CWD });
   const text = res?.content?.[0]?.text || '';
-  const anchors = text.split('\n').filter((l) => /:\d+/.test(l)).length;
+  const aLines = anchorLinesOf(text);
+  const anchors = aLines.length;
   const failed = /EXPLORATION_FAILED/.test(text);
-  const lower = text.toLowerCase();
+  // Context tokens for the fabricated-line guard: expanded expected + query
+  // words, length>=4 to drop filler.
+  const ctxTokens = [
+    ...(expect || []).flatMap((e) => e.toLowerCase().split(/[^a-z0-9]+/)),
+    ...q.toLowerCase().split(/[^a-z0-9]+/),
+  ].filter((t) => t.length >= 4);
+  // Spot-check up to 2 anchors per query for file/line validity + line context.
+  let badAnchors = 0;
+  for (const l of aLines.slice(0, 2)) {
+    if (checkAnchorLine(l, ctxTokens) === false) badAnchors++;
+  }
+  const allLines = text.split('\n').filter((l) => l.trim());
+  // Strict hit: expected token must appear ON an anchor line (>=1 anchor). For
+  // the path-only class, an expected token on any verified path line HITs even
+  // without :line. expectFail wants EXPLORATION_FAILED with zero anchors.
   const hit = expectFail
     ? (failed && anchors === 0)
-    : (!failed && (expect || []).some((e) => lower.includes(e.toLowerCase())));
-  return { q: q.slice(0, 48), ms: Date.now() - qt0, anchors, failed, hit, bytes: text.length };
+    : pathOnly
+      ? (!failed && (expect || []).some(
+          (e) => allLines.some((l) => l.toLowerCase().includes(e.toLowerCase())),
+        ))
+      : (!failed && anchors > 0 && (expect || []).some(
+          (e) => aLines.some((l) => l.toLowerCase().includes(e.toLowerCase())),
+        ));
+  return { q: q.slice(0, 48), ms: Date.now() - qt0, anchors, failed, hit, badAnchors, bytes: text.length };
 }));
 
 // Identify explorer sessions from trace rows, then attribute both tool calls
@@ -145,9 +237,10 @@ const sendCount = [...sendBySession.values()].reduce((a, s) => a + s.sends, 0);
 
 console.log(`\n=== explore-bench round=${ROUND} ===`);
 for (const r of results) {
-  console.log(`  [${String(r.ms).padStart(6)}ms] ${r.hit ? 'HIT ' : 'MISS'} anchors=${r.anchors} failed=${r.failed} bytes=${r.bytes}  ${r.q}`);
+  console.log(`  [${String(r.ms).padStart(6)}ms] ${r.hit ? 'HIT ' : 'MISS'} anchors=${r.anchors} bad=${r.badAnchors} failed=${r.failed} bytes=${r.bytes}  ${r.q}`);
 }
-console.log(`  quality: ${results.filter((r) => r.hit).length}/${results.length} hits`);
+const badTotal = results.reduce((a, r) => a + r.badAnchors, 0);
+console.log(`  quality: ${results.filter((r) => r.hit).length}/${results.length} hits (strict)  bad-anchors=${badTotal}`);
 console.log(`  sessions=${bySession.size} toolcalls p50=${p50} max=${callCounts[callCounts.length - 1] ?? 0} total=${callCounts.reduce((a, b) => a + b, 0)}`);
 for (const [id, s] of bySession) console.log(`    ${id.slice(-8)}: ${s.tools.join(',')}`);
 const wallMs = Date.now() - t0;

package/scripts/explore-prompt-policy-test.mjs

@@ -3,25 +3,170 @@ import test from 'node:test';
 import assert from 'node:assert/strict';
 import { readFileSync } from 'node:fs';
 import { buildExplorerPrompt } from '../src/standalone/explore-tool.mjs';
+import { EXPLORE_TOOL } from '../src/standalone/explore-tool.mjs';
 import { BUILTIN_TOOLS } from '../src/runtime/agent/orchestrator/tools/builtin/builtin-tools.mjs';
+import { CODE_GRAPH_TOOL_DEFS } from '../src/runtime/agent/orchestrator/tools/code-graph-tool-defs.mjs';
+import { isEagerDispatchable } from '../src/runtime/agent/orchestrator/session/loop/tool-helpers.mjs';
 
-test('explore per-query prompt leaves path policy to tool schemas', () => {
+test('explore per-query prompt contains only escaped query XML', () => {
   const prompt = buildExplorerPrompt('display model usage show usage model_usage provider_usage session cache usage state');
-  assert.doesNotMatch(prompt, /Path policy:/i);
-  assert.doesNotMatch(prompt, /run find for that fragment before any grep\/glob/i);
+  assert.equal(prompt, '<query>display model usage show usage model_usage provider_usage session cache usage state</query>');
+  assert.doesNotMatch(prompt, /Reminder:|BUDGET|TURN 1|STOP and answer|verdicts|ratings|recommendations/i);
+  assert.equal(buildExplorerPrompt('where is <agent> & status?'), '<query>where is &lt;agent&gt; &amp; status?</query>');
 });
 
-test('grep glob find tool schemas carry unverified path policy', () => {
+test('builtin route descriptions carry the shortest verified-path policy', () => {
   const byName = Object.fromEntries(BUILTIN_TOOLS.map((tool) => [tool.name, tool]));
-  assert.match(byName.grep.description, /Unknown path\/name → find first/i);
+  // Conditional find-first: only genuinely guessed fragments route through
+  // find, and in the SAME turn — project root itself is a verified scope.
+  assert.match(byName.grep.description, /project root counts as verified/i);
+  assert.match(byName.grep.description, /guessed path fragment → find first/i);
   assert.match(byName.grep.description, /no path "\." \+ guessed src\/\*\*/i);
-  assert.match(byName.glob.description, /Unknown root\/name → find first/i);
-  assert.match(byName.find.description, /verify roots before grep\/glob/i);
+  assert.match(byName.glob.description, /project root is verified/i);
+  assert.match(byName.glob.description, /Guessed root\/name → find first/i);
+  assert.match(byName.find.description, /output paths are verified/i);
+  assert.match(byName.read.description, /guessed path\/name → find first/i);
+  assert.match(byName.read.description, /Batch paths\/regions as real arrays.*path\[\]/i);
+  assert.match(byName.shell.description, /Shell\/write calls are serial/i);
+  assert.doesNotMatch(byName.shell.description, /parallel calls/i);
+  assert.match(byName.find.description, /lookup only for unknown partial paths\/names/i);
+  assert.match(byName.find.description, /project root or already-verified roots/i);
+  assert.doesNotMatch(byName.grep.description, /find for that fragment before any grep\/glob/i);
+  assert.match(byName.grep.description, /nonzero content_with_context result resolves that search concept/i);
+  assert.match(byName.grep.description, /Only zero\/error results may change tokens or scope/i);
+  assert.match(`${byName.code_graph?.description || ''} ${CODE_GRAPH_TOOL_DEFS[0]?.inputSchema?.properties?.symbols?.description || ''}`, /multiple exact symbols use one symbols\[\] call/i);
+  assert.match(CODE_GRAPH_TOOL_DEFS[0]?.description || '', /verified source files only/i);
 });
 
-test('explorer turn-1 contract includes batched find for unknown broad targets', () => {
+test('shared tool policy routes facets without duplicate content acquisition', () => {
+  const rule = readFileSync(new URL('../src/rules/shared/01-tool.md', import.meta.url), 'utf8');
+  const policy = rule.replace(/\s+/g, ' ');
+  assert.match(policy, /for each facet choose exactly one shortest locator route/i);
+  assert.match(policy, /broad\/uncertain→\s*`explore`.*partial path\/name→\s*`find`.*verified root\+wildcard→\s*`glob`.*quoted\/non-identifier literal or regex→\s*`grep`.*exact code identifier\/relation→\s*`code_graph` before grep/i);
+  assert.match(policy, /grep only for a requested literal occurrence or after graph zero\/error/i);
+  assert.match(policy, /batch compatible targets/i);
+  assert.match(policy, /parallelize distinct facets only, never alternative routes for one facet/i);
+  assert.match(policy, /put independent read-only calls in one turn; they may run concurrently regardless of tool/i);
+  assert.match(policy, /after locator results, collect all known candidate files\/regions before inspection/i);
+  assert.match(policy, /batch compatible reads.*same-file regions.*in one `path\[\]` call and graph targets in arrays/i);
+  assert.match(policy, /parallelize independent incompatible read-only inspections/i);
+  assert.match(policy, /do not start a singleton while a known compatible candidate remains/i);
+  assert.match(policy, /shell\/write calls are serial/i);
+  assert.match(policy, /later turns are only for targets dependent on prior results or unresolved facets/i);
+  assert.match(policy, /stop when evidence covers the deliverable/i);
+  assert.match(policy, /sufficient contextual grep means no overlapping `read`/i);
+  assert.match(policy, /files_with_matches.*count.*capped.*insufficient context.*inspect only missing content/i);
+  assert.match(policy, /known file\/span→`read` directly without `grep`/i);
+  assert.doesNotMatch(policy, /retrieval[^.]{0,120}\b(?:one|at most \d+)\s+(?:lookup|inspection|turn|call)/i);
+  assert.doesNotMatch(policy, /\bput independent calls in one turn\b/i);
+  assert.doesNotMatch(policy, /\b(?:all|every)\s+(?:independent\s+)?(?:calls|tool calls)\b[^.]{0,80}\bone turn\b/i);
+  assert.doesNotMatch(policy, /\bone lookup\b[^.]{0,80}\bat most\b[^.]{0,40}\binspection\b/i);
+  assert.doesNotMatch(policy, /all (?:independent )?(?:calls|tool calls|targets)[^.]{0,100}\bone (?:tool )?(?:message|call)/i);
+});
+
+test('explorer locator policy retains its compact behavioral contract', () => {
   const rule = readFileSync(new URL('../src/rules/agent/30-explorer.md', import.meta.url), 'utf8');
-  assert.match(rule, /Turn 1 is the whole search in ONE message/i);
-  assert.match(rule, /unknown\/broad\s+targets\)\s+find `query\[\]`/i);
-  assert.match(rule, /path\/name fragments from multiple tokens/i);
+  const policy = rule.replace(/\s+/g, ' ');
+  const required = [
+    /Locator only:[\s\S]*WHERE \(`path:line`\), never WHY[\s\S]*You ARE `explore`; never[\s\S]*call it/i,
+    /ONLY grep\/find\/glob\/code_graph[\s\S]*`read`\/`list` are forbidden/i,
+    /Turn 1 \(`turn 1\/3`\)[\s\S]*gathers all known facets in ONE message[\s\S]*Broad\/uncertain is Explorer input[\s\S]*split it into concrete facets[\s\S]*apply the shared one-route\/batch contract[\s\S]*concept facets use grep[\s\S]*single-tool turn is valid[\s\S]*follow-up is only for unresolved pre-anchor\/\s*zero-hit facets/i,
+    /follow-up is only for unresolved pre-anchor\/\s*zero-hit facets under this budget/i,
+    /broad searches use `output_mode:"files_with_matches"`[\s\S]*`content_with_context` plus `head_limit` only on a path returned THIS session/i,
+    /Each pattern is one identifier or camel\/snake variant[\s\S]*spaces are only verbatim copied quoted\s*error\/log literals[\s\S]*Translate non-English queries to English identifiers first[\s\S]*non-ASCII only for quoted literals[\s\S]*Include concept synonyms[\s\S]*not prose phrases/i,
+    /Scope is session cwd; omit `path` freely[\s\S]*only from an exact find-returned path \(turn-2 recovery earliest\)[\s\S]*never guess or\s*invent directories[\s\S]*`path:"\."` with guessed `src\/\*\*`[\s\S]*After zero hits, change TOKENS\/scope, not wording\/guessed paths/i,
+    /anchor is any `path:line` with a query token\/synonym[\s\S]*code_graph hits[\s\S]*generic-only schema\/handler\/config\/resolver\/index\/error words are zero[\s\S]*Never re-locate an anchor[\s\S]*without `:line`[\s\S]*PRE-anchor/i,
+    /After every result[\s\S]*specific-token anchor means STOP and answer NOW[\s\S]*pre-anchors count as zero[\s\S]*Never re-confirm\/upgrade an anchor/i,
+    /sole legal follow-up[\s\S]*code-location query[\s\S]*only with pre-anchors[\s\S]*one scoped `content_with_context` grep with `head_limit` on those paths[\s\S]*If zero, remaining zero-anchor recovery turns are legal under the 3-turn budget but must change tokens\/scope[\s\S]*never a second minting hop, anchor upgrade, or fabricated\/estimated line/i,
+    /at most 3 turns \(expect 1\)[\s\S]*every tool message `turn N\/3`[\s\S]*normally two messages[\s\S]*third\/extra tool call[\s\S]*unless turn 1 has zero anchors[\s\S]*must change tokens\/scope/i,
+    /Single-hop exception[\s\S]*first matching entry\/definition anchors concept\/value\/\s*default[\s\S]*do not trace chains\/value-search[\s\S]*explicit flow or default-resolution query[\s\S]*entry anchor but not its resolved value[\s\S]*ONE resolving hop, then stop/i,
+    /Answer in ≤3 lines[\s\S]*`path:line — symbol — short reason`[\s\S]*Copy every cited `path:line` VERBATIM[\s\S]*THIS-session tool result[\s\S]*never estimate\/adjust\/recall/i,
+    /Code-location answers require `:line` on every line[\s\S]*`EXPLORATION_FAILED`[\s\S]*never a bare filename or vague prose/i,
+    /file\/dir-location queries[\s\S]*exact verified file\/dir path without `:line`[\s\S]*do not force a line\/failure/i,
+    /Emit `EXPLORATION_FAILED` only after the budget is spent with zero anchors[\s\S]*prefer a weak anchor to a false miss/i,
+  ];
+  for (const behavior of required) assert.match(policy, behavior);
+  assert.doesNotMatch(policy, /grep[^.]{0,120}\band\b[^.]{0,120}code_graph[^.]{0,120}\band\b[^.]{0,120}find/i);
+});
+
+test('canonical schemas advertise safe batching without changing tool shapes', () => {
+  const graph = readFileSync(new URL('../src/runtime/agent/orchestrator/tools/code-graph-tool-defs.mjs', import.meta.url), 'utf8');
+  const patch = readFileSync(new URL('../src/runtime/agent/orchestrator/tools/patch-tool-defs.mjs', import.meta.url), 'utf8');
+  assert.match(graph, /Batch symbols\[\]\/files\[\] by mode/i);
+  assert.match(patch, /one patch/i);
+  assert.match(patch, /one file block per target/i);
+});
+
+test('code graph and eager-dispatch boundaries preserve runtime shape', () => {
+  const schema = CODE_GRAPH_TOOL_DEFS[0]?.inputSchema?.properties || {};
+  const fileModes = ['overview', 'imports', 'dependents', 'related', 'impact', 'symbols'];
+  const symbolModes = ['symbols', 'find_symbol', 'symbol_search', 'search', 'references', 'callers', 'callees'];
+  assert.deepEqual(new Set(schema.mode?.enum), new Set([...fileModes, ...symbolModes]));
+  const assertBatchShape = (field) => {
+    assert.equal(field?.anyOf?.length, 2);
+    assert.deepEqual(field.anyOf.map((entry) => entry.type), ['string', 'array']);
+    assert.equal(field.anyOf[1].items.type, 'string');
+    assert.equal(field.anyOf[1].minItems, 1);
+  };
+  assertBatchShape(schema.files);
+  assertBatchShape(schema.symbols);
+  assert.equal(schema.file, undefined);
+  assert.equal(schema.symbol, undefined);
+  assert.equal(schema.language, undefined);
+  const tools = [
+    ...BUILTIN_TOOLS,
+    { name: 'mcp_read', annotations: { readOnlyHint: true } },
+    { name: 'mcp_write', annotations: { readOnlyHint: false } },
+  ];
+  assert.equal(isEagerDispatchable('read', tools), true);
+  assert.equal(isEagerDispatchable('shell', tools), false);
+  assert.equal(isEagerDispatchable('mcp_read', tools), true);
+  assert.equal(isEagerDispatchable('mcp_write', tools), false);
+});
+
+test('code graph descriptions partition file and symbol targets', () => {
+  const description = CODE_GRAPH_TOOL_DEFS[0]?.description || '';
+  const mode = CODE_GRAPH_TOOL_DEFS[0]?.inputSchema?.properties?.mode?.description || '';
+  assert.match(mode, /file modes=\{overview,imports,dependents,related,impact\}.*symbols with files.*files\[\].*file outline/i);
+  assert.match(mode, /symbol modes=\{find_symbol,symbol_search,search,references,callers,callees\}.*fileless symbols.*symbol_search keywords/i);
+  assert.match(description, /exact identifiers.*find_symbol\/references\/callers\/callees.*keywords.*symbol_search\/search/i);
+  assert.match(description, /IDs→graph; literal\/zero→grep/i);
+  assert.match(description, /unsupported target arrays.*omitted.*never silently mixed/i);
+  assert.match(CODE_GRAPH_TOOL_DEFS[0]?.inputSchema?.properties?.files?.description || '', /supported targets only/i);
+  assert.match(CODE_GRAPH_TOOL_DEFS[0]?.inputSchema?.properties?.symbols?.description || '', /exact identifiers.*keywords/i);
+  const grep = Object.fromEntries(BUILTIN_TOOLS.map((tool) => [tool.name, tool])).grep;
+  assert.match(grep.description, /quoted\/non-identifier literal or regex→grep/i);
+  assert.doesNotMatch(grep.inputSchema.properties.pattern.description, /code_graph/i);
+});
+
+test('retrieval schemas require their primary arguments and preserve region paths', () => {
+  const byName = Object.fromEntries(BUILTIN_TOOLS.map((tool) => [tool.name, tool]));
+  const read = byName.read.inputSchema;
+  assert.deepEqual(read.required, ['path']);
+  const region = read.properties.path.anyOf[1].items.anyOf[1];
+  assert.deepEqual(region.required, ['path']);
+  assert.deepEqual(byName.grep.inputSchema.anyOf, [{ required: ['pattern'] }, { required: ['glob'] }]);
+  assert.deepEqual(byName.grep.inputSchema.properties.output_mode.enum, ['content_with_context', 'files_with_matches', 'count']);
+  const grepSchema = byName.grep.inputSchema;
+  const valid = (value) => grepSchema.anyOf.some((branch) => branch.required.every((key) => Object.hasOwn(value, key)));
+  assert.equal(valid({ pattern: 'x' }), true);
+  assert.equal(valid({ glob: '*.mjs' }), true);
+  assert.equal(valid({}), false);
+});
+
+test('grep scopes do not masquerade as read regions', () => {
+  const pattern = Object.fromEntries(BUILTIN_TOOLS.map((tool) => [tool.name, tool])).grep.inputSchema.properties.pattern.description;
+  assert.match(pattern, /path\[\] batches verified scopes only/i);
+  assert.match(pattern, /file\/span reads use read path\[\] regions/i);
+  assert.doesNotMatch(pattern, /known files\/spans use path\[\]/i);
+});
+
+test('explore freezes returned facets and avoids re-location', () => {
+  assert.match(EXPLORE_TOOL.description, /freezes the LOCATION only/i);
+  assert.match(EXPLORE_TOOL.description, /read\/code_graph detail inspection is valid when content was not returned/i);
+  assert.match(EXPLORE_TOOL.description, /never re-locate it/i);
+  assert.match(EXPLORE_TOOL.description, /search only unresolved facets/i);
+  const rule = readFileSync(new URL('../src/rules/shared/01-tool.md', import.meta.url), 'utf8');
+  assert.match(rule, /freezes the LOCATION only[\s\S]*read or[\s\S]*code_graph detail inspection is valid[\s\S]*never re-locate it/i);
+  assert.match(rule, /nonzero[\s\S]*content_with_context[\s\S]*result resolves[\s\S]*act directly/i);
 });

package/scripts/find-fuzzy-hidden-test.mjs

@@ -32,6 +32,93 @@ test('fuzzyRank floor drops a purely scattered subsequence but keeps a substring
     assert.deepEqual(ranked.map((r) => r.item.path), ['src/abcdef.txt']);
 });
 
+// Frozen copy of the pre-optimization scorer: this must not call production
+// fuzzy helpers, so rank parity also detects scoring regressions.
+function legacyFuzzyScore(query, str) {
+    if (!query) return 0;
+    const normalizedQuery = String(query).replace(/[\/\\_.\-\s]+/g, '');
+    if (!normalizedQuery) return 0;
+    const q = normalizedQuery.toLowerCase();
+    const s = str.toLowerCase();
+    const qlen = q.length;
+    const slen = s.length;
+    if (qlen === 0) return 0;
+    if (qlen > slen) return null;
+
+    const lastSep = Math.max(str.lastIndexOf('/'), str.lastIndexOf('\\'));
+    let score = 0;
+    let si = 0;
+    let prevMatch = -2;
+    let firstMatchIdx = -1;
+    for (let qi = 0; qi < qlen; qi++) {
+        const qc = q[qi];
+        let found = -1;
+        for (let k = si; k < slen; k++) {
+            if (s[k] === qc) { found = k; break; }
+        }
+        if (found === -1) return null;
+        if (firstMatchIdx === -1) firstMatchIdx = found;
+        score += 1;
+        if (found === prevMatch + 1) score += 5;
+        const prevCh = found > 0 ? str[found - 1] : undefined;
+        if (prevCh === undefined
+            || prevCh === '/' || prevCh === '\\' || prevCh === '_' || prevCh === '-'
+            || prevCh === '.' || prevCh === ' '
+            || (/[a-z0-9]/.test(prevCh) && /[A-Z]/.test(str[found]))) {
+            score += 8;
+        }
+        if (str[found] === normalizedQuery[qi]) score += 1;
+        prevMatch = found;
+        si = found + 1;
+    }
+    if (firstMatchIdx > lastSep) score += 10;
+    score -= Math.floor(slen / 16);
+    score -= Math.floor(firstMatchIdx / 8);
+    return score;
+}
+
+function referenceFuzzyRank(query, items, limit = 0) {
+    const normQuery = String(query || '').toLowerCase().replace(/[\/\\_.\-\s]+/g, '');
+    const floor = normQuery.length * 4;
+    const scored = [];
+    for (const item of items) {
+        const p = String(item.path || '');
+        const pathScore = legacyFuzzyScore(query, p);
+        const base = p.split(/[\\/]/).pop() || '';
+        const baseScore = legacyFuzzyScore(query, base);
+        const score = Math.max(pathScore ?? -Infinity, baseScore === null ? -Infinity : baseScore + 40);
+        if (!Number.isFinite(score)) continue;
+        const strong = normQuery.length > 0
+            && (String(base || '').toLowerCase().replace(/[\/\\_.\-\s]+/g, '').includes(normQuery)
+                || String(p || '').toLowerCase().replace(/[\/\\_.\-\s]+/g, '').includes(normQuery));
+        if (!strong && score < floor) continue;
+        scored.push({ item, score });
+    }
+    scored.sort((a, b) => (b.score - a.score)
+        || (a.item.path < b.item.path ? -1 : a.item.path > b.item.path ? 1 : 0));
+    return limit > 0 ? scored.slice(0, limit) : scored;
+}
+
+test('fuzzyRank exactly matches the frozen legacy full-sort reference ranker', () => {
+    const fragments = ['alpha', 'Beta', 'tool-events', 'src', 'x_y', 'log', 'camelCase', 'archive'];
+    const items = Array.from({ length: 1200 }, (_, i) => ({
+        path: i % 97 === 0
+            ? 'duplicate/tool-events.log'
+            : `${fragments[i % fragments.length]}/${fragments[(i * 7) % fragments.length]}-${i}.mjs`,
+    }));
+    for (const query of ['', 'tool', 'ToolEvents', 'a_b', 'camel']) {
+        for (const limit of [-5, 0, 0.5, 1, 2, 25, 300, 2000]) {
+            const expected = referenceFuzzyRank(query, items, limit);
+            const actual = fuzzyRank(query, items, limit);
+            assert.deepEqual(
+                actual.map(({ item, score }) => ({ index: items.findIndex((candidate) => candidate === item), score })),
+                expected.map(({ item, score }) => ({ index: items.findIndex((candidate) => candidate === item), score })),
+                `query=${JSON.stringify(query)}, limit=${limit}`,
+            );
+        }
+    }
+});
+
 // ── hidden-directory discovery via the find tool ─────────────────────────
 
 function makeRepo() {
@@ -69,6 +156,41 @@ test('find hidden:false skips dot-directories', async () => {
     }
 });
 
+test('find respects .gitignore on the common path, then deterministically falls back for an exact ignored filename', async () => {
+    const root = mkdtempSync(join(tmpdir(), 'mixdog-find-gitignore-'));
+    try {
+        writeFileSync(join(root, '.gitignore'), 'ignored-tree/\n');
+        mkdirSync(join(root, 'src'), { recursive: true });
+        mkdirSync(join(root, 'ignored-tree'), { recursive: true });
+        writeFileSync(join(root, 'src', 'common-visible.mjs'), 'x\n');
+        writeFileSync(join(root, 'ignored-tree', 'common-ignored.mjs'), 'x\n');
+        writeFileSync(join(root, 'src', 'needle-target.mjs.bak'), 'x\n');
+        writeFileSync(join(root, 'ignored-tree', 'needle-target.mjs'), 'x\n');
+        writeFileSync(join(root, 'ignored-tree', 'LICENSE'), 'x\n');
+        writeFileSync(join(root, 'ignored-tree', '[slug].tsx'), 'x\n');
+        writeFileSync(join(root, 'ignored-tree', 'my file.txt'), 'x\n');
+
+        const common = await executeFuzzyFindTool({ query: 'common-visible.mjs', head_limit: 1 }, root);
+        assert.ok(common.includes('src/common-visible.mjs'), `common path must keep visible files: ${common}`);
+        assert.ok(!common.includes('ignored-tree/common-ignored.mjs'), `common path must skip .gitignored trees: ${common}`);
+        assert.ok(common.includes('[gitignored trees not searched; retry with include_noise:true]'), `filled common path must disclose skipped trees: ${common}`);
+
+        const exact = await executeFuzzyFindTool({ query: 'needle-target.mjs' }, root);
+        assert.ok(exact.includes('src/needle-target.mjs.bak'), `visible fuzzy decoy must remain in pass one: ${exact}`);
+        assert.ok(exact.includes('ignored-tree/needle-target.mjs'), `exact ignored filename must trigger fallback: ${exact}`);
+        assert.ok(!exact.includes('[gitignored trees not searched'), `fallback result must not claim ignored trees were skipped: ${exact}`);
+
+        const extensionless = await executeFuzzyFindTool({ query: 'LICENSE' }, root);
+        assert.ok(extensionless.includes('ignored-tree/LICENSE'), `extensionless exact filename must trigger fallback: ${extensionless}`);
+        const literalGlob = await executeFuzzyFindTool({ query: '[slug].tsx' }, root);
+        assert.ok(literalGlob.includes('ignored-tree/[slug].tsx'), `literal-glob exact filename must trigger fallback: ${literalGlob}`);
+        const spaced = await executeFuzzyFindTool({ query: 'my file.txt' }, root);
+        assert.ok(spaced.includes('ignored-tree/my file.txt'), `space-containing exact filename must trigger fallback: ${spaced}`);
+    } finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+});
+
 // ── narrowed-pass merge / dedup backstop ─────────────────────────────────
 
 test('exact-name hit survives among many decoys and is not duplicated', async () => {