mixdog 0.9.93 → 0.9.95

package/NOTICE.md

@@ -0,0 +1,72 @@
+# NOTICE
+
+Mixdog itself is MIT-licensed (see `LICENSE`). Parts of it were written
+against the public source of the projects listed below. Their terms are
+preserved here in one place so the individual source files can stay free of
+scattered attribution comments.
+
+## MIT
+
+### Visual Studio Code — Copyright (c) Microsoft Corporation
+
+<https://github.com/microsoft/vscode>
+
+Explorer name-validation and sort grammar, editor/terminal defaults, the Seti
+icon-theme resolution rules, shell-profile detection, and the built-in
+language contributions used to generate the Monaco pane languages.
+
+- `apps/desktop/src/renderer/explorer-logic.ts`, `ExplorerTree.tsx`,
+  `editor-ansi.ts`, `file-icons.tsx`, `seti-icons.ts`
+- `apps/desktop/src/shared/editor-languages.ts`
+- `apps/desktop/src/main/shell-profiles.ts`
+- `apps/desktop/scripts/generate-seti-icons.mjs`,
+  `apps/desktop/scripts/generate-editor-languages.mjs`
+
+### Seti UI — Copyright (c) 2014 Jesse Weed
+
+Bundled glyphs and colour tables. Full license text in
+`apps/desktop/THIRD-PARTY-NOTICES.txt`.
+
+### Files — Copyright (c) Files Community
+
+<https://github.com/files-community/Files>
+
+Folder-pane grouping keys, date-span labels, size buckets and the discrete
+layout size ladder in `apps/desktop/src/renderer/FolderPane.lazy.tsx`.
+
+### OpenCode — Copyright (c) Anomaly / SST
+
+<https://github.com/anomalyco/opencode>
+
+Transcript auto-scroll gesture grammar, virtual-timeline anchoring and the
+streaming-markdown projection model.
+
+- `apps/desktop/src/renderer/use-transcript-follow.ts`, `TranscriptList.tsx`,
+  `transcript-measure.ts`, `transcript-rows.ts`, `transcript-virtual-cache.ts`,
+  `StreamingMarkdownBody.tsx`, `streaming-markdown.ts`, `Conversation.tsx`
+
+### Ink — Copyright (c) Vadim Demedes
+
+Vendored under `vendor/ink` together with its own license file.
+
+## Apache License 2.0
+
+### OpenAI Codex CLI — Copyright (c) OpenAI
+
+<https://github.com/openai/codex>
+
+The V4A `apply_patch` grammar with its seek/replacement semantics.
+
+- `src/runtime/agent/orchestrator/tools/patch/`
+- `native/mixdog-patch/`
+
+### AiderDesk — Copyright (c) Hotovo
+
+<https://github.com/hotovo/aider-desk>
+
+electron-vite configuration structure in
+`apps/desktop/electron.vite.config.ts`.
+
+The Apache-2.0 terms require this notice to travel with any redistribution of
+the derived files. Full license text:
+<https://www.apache.org/licenses/LICENSE-2.0>.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mixdog",
-  "version": "0.9.93",
+  "version": "0.9.95",
   "private": false,
   "type": "module",
   "description": "Standalone mixdog coding-agent CLI/TUI workspace.",
@@ -25,6 +25,7 @@
   },
   "files": [
     "README.md",
+    "NOTICE.md",
     "scripts/",
     "!scripts/bench/",
     "!scripts/recall-bench-*.txt",
@@ -46,6 +47,7 @@
     "prepublishOnly": "node -e \"if(!process.env.CI){console.error('local npm publish is disabled — run npm run release:patch');process.exit(1)}\"",
     "start": "node src/cli.mjs",
     "smoke": "node scripts/smoke.mjs",
+    "test:contract": "node scripts/run-suite.mjs contract",
     "smoke:all": "npm run smoke && npm run smoke:boot && npm run smoke:patch && npm run smoke:output && npm run smoke:tui && npm run smoke:live-worker",
     "smoke:boot": "node scripts/boot-smoke.mjs",
     "smoke:compact": "node scripts/compact-smoke.mjs",
@@ -68,7 +70,7 @@
     "test:toolcall": "node --test scripts/toolcall-args-test.mjs",
     "test:tool-batching": "node --test scripts/eager-patch-shell-order-test.mjs scripts/session-bench-batching-test.mjs",
     "test:shipmode": "node --test scripts/ship-mode-test.mjs",
-    "test:shellhardening": "node --test scripts/shell-hardening-test.mjs scripts/shell-failure-diagnostics-test.mjs scripts/windows-hide-spawn-options-test.mjs",
+    "test:shellhardening": "node --test scripts/shell-hardening-test.mjs scripts/shell-failure-diagnostics-test.mjs scripts/windows-hide-spawn-options-test.mjs scripts/shell-job-session-scope-test.mjs",
     "test:placeholder": "node --test scripts/compacted-placeholder-scrub-test.mjs",
     "test:providers": "node --test scripts/provider-toolcall-test.mjs scripts/provider-contract-test.mjs scripts/provider-stream-stall-test.mjs scripts/provider-stream-outcome-test.mjs scripts/stream-frame-fault-matrix-test.mjs scripts/gemini-provider-test.mjs scripts/anthropic-transport-policy-test.mjs scripts/anthropic-native-block-replay-test.mjs scripts/openai-oauth-ws-1006-retry-test.mjs scripts/openai-end-turn-signal-test.mjs",
     "test:provider-admission": "node --test scripts/provider-admission-scheduler-test.mjs",
@@ -83,7 +85,6 @@
     "test:embedding-runtime:core": "node --test scripts/embedding-runtime-prune-test.mjs scripts/memory-pg-recovery-test.mjs && node scripts/verify-embedding-runtime.mjs --core",
     "test:embedding-runtime:warmup": "node scripts/verify-embedding-runtime.mjs --warmup",
     "test:code-graph-dispatch": "node --test scripts/code-graph-dispatch-test.mjs",
-    "test:code-graph-clean-cache": "node --test scripts/code-graph-dispatch-test.mjs",
     "test:tui-queue": "node --test scripts/submit-commandbusy-race-test.mjs scripts/steering-drain-buckets-test.mjs scripts/abort-recovery-test.mjs scripts/execution-pending-resume-kick-test.mjs scripts/execution-resume-esc-integration-test.mjs scripts/pending-stale-injection-test.mjs",
     "test:tui-input-render": "node --test scripts/prompt-immediate-render-test.mjs",
     "test:tui-streaming-window": "node --test scripts/streaming-tail-window-test.mjs scripts/tui-store-frame-batch-test.mjs && node scripts/tui-transcript-jitter-harness.mjs",
@@ -92,11 +93,13 @@
     "test:release-focused": "npm run test:release-assets && npm run test:tool-contracts && npm run test:tool-batching && npm run test:placeholder && npm run smoke:patch && npm run test:patch-binary-cache && npm run test:providers && npm run test:deferred-tools && npm run smoke:compact && npm run test:compact && npm run test:context && node --test scripts/code-graph-root-federation-test.mjs scripts/code-graph-aggregate-cwd-test.mjs && npm run test:code-graph-dispatch && node --test scripts/code-graph-disk-hit-test.mjs && npm run test:shellhardening && npm run test:project-registry && npm run test:session && npm run test:workflow-editor && npm run test:embedding-runtime && node --test scripts/tui-transcript-perf-test.mjs",
     "test:native-edit-wire": "node --test scripts/native-edit-wire-test.mjs",
     "test:patch-binary-cache": "node --test scripts/patch-binary-cache-test.mjs",
-    "test:patch-parity": "node --test scripts/v4a-codex-parity-test.mjs",
+    "test:patch-parity": "node --test scripts/v4a-parity-test.mjs",
     "test:project-registry": "node --test scripts/project-registry-isolation-test.mjs",
+    "test:engine-daemon": "node --test scripts/engine-daemon-test.mjs scripts/engine-daemon-local-bridge-test.mjs scripts/engine-daemon-tui-parity-test.mjs scripts/engine-daemon-recovery-test.mjs scripts/engine-daemon-submit-delivery-test.mjs scripts/engine-daemon-process-lifetime-test.mjs scripts/engine-daemon-multipane-stress-test.mjs",
+    "smoke:engine-daemon": "node scripts/engine-daemon-smoke.mjs",
     "test:session": "node --test scripts/session-orphan-sweep-test.mjs scripts/interrupted-turn-history-test.mjs scripts/turn-checkpoint-crash-test.mjs scripts/turn-outcome-fault-matrix-test.mjs scripts/session-save-fault-store-test.mjs scripts/session-disk-authority-test.mjs scripts/session-load-cache-race-test.mjs scripts/agent-loop-complete-turn-test.mjs scripts/session-heartbeat-lifecycle-test.mjs scripts/remote-transition-order-test.mjs scripts/session-new-reset-test.mjs",
     "test:live-canary": "node --test scripts/live-canary-test.mjs",
-    "test:rebindtail": "node --test scripts/forwarder-rebind-tail-test.mjs",
+    "test:rebindtail": "node --test scripts/forwarder-rebind-tail-test.mjs scripts/channel-remote-format-test.mjs",
     "test:workflow-editor": "node --test scripts/workflow-id-test.mjs scripts/workflow-pack-editor-test.mjs",
     "test:route-scope": "node --test scripts/route-scope-isolation-test.mjs",
     "test:schedule-reload": "node --test scripts/schedule-reload-arm-test.mjs",
@@ -105,13 +108,20 @@
     "failures": "node scripts/tool-failures.mjs",
     "trace:llm": "node scripts/llm-trace-summary.mjs",
     "diag:sessions": "node scripts/session-diag.mjs",
-    "diag:session": "node scripts/session-diag.mjs",
+    "diag:tools": "node scripts/tool-efficiency-diag.mjs",
+    "diag:sweep": "node scripts/session-sweep.mjs",
     "bench:session": "node scripts/session-bench.mjs",
     "bench:task": "node scripts/task-bench.mjs",
     "bench:corpus": "node scripts/routing-corpus.mjs",
     "bench:run": "node scripts/bench-run.mjs",
     "bench:recall": "node scripts/recall-bench.mjs",
     "bench:tui-load": "node scripts/tui-runtime-load-bench.mjs",
+    "bench:explore": "node scripts/explore-bench.mjs",
+    "bench:output-style": "node scripts/output-style-bench.mjs",
+    "bench:session-context": "node scripts/session-context-bench.mjs",
+    "bench:engine-daemon": "node scripts/engine-daemon-bench.mjs",
+    "bench:tool-overhead": "node scripts/tool-overhead-microbench.mjs",
+    "bench:internal-comms": "node scripts/internal-comms-bench.mjs",
     "audit:models": "node scripts/model-catalog-audit.mjs",
     "patch:replay": "node scripts/patch-replay.mjs",
     "build:tui": "node scripts/build-tui.mjs",

package/scripts/lib/isolated-root-cleanup.mjs

@@ -0,0 +1,19 @@
+// Isolated-root test hygiene. A session engine spawns its OWN memory runtime
+// (Postgres + embeddings) under the root it was given, and a hard-killed daemon
+// cannot reap it. Tests that use a throwaway root call this so a run can never
+// leave a live cluster behind pointing at a deleted directory.
+import { spawnSync } from 'node:child_process';
+
+export function killProcessesUnder(root) {
+  if (!root) return;
+  if (process.platform === 'win32') {
+    const escaped = String(root).replace(/'/g, "''");
+    spawnSync('powershell', [
+      '-NoProfile', '-NonInteractive', '-Command',
+      `Get-CimInstance Win32_Process | Where-Object { $_.ExecutablePath -like '${escaped}*' } `
+      + '| ForEach-Object { Stop-Process -Id $_.ProcessId -Force -ErrorAction SilentlyContinue }',
+    ], { stdio: 'ignore' });
+    return;
+  }
+  spawnSync('bash', ['-lc', `pkill -f ${JSON.stringify(root)} || true`], { stdio: 'ignore' });
+}

package/scripts/run-suite.mjs

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+// Named test suites, so package.json keeps one entry per suite instead of a
+// 2KB command line. Files listed here are RUN; anything under scripts/ that is
+// not in a suite (or another npm script) is dead weight by definition.
+import { spawnSync } from 'node:child_process';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+// contract: the cheap, always-true invariants (tool args, session/steering
+// persistence, memory rules, routing sanitizers). Live-model, UI-frame and
+// bench suites deliberately stay out — they belong to smoke:*/bench:*.
+export const SUITES = {
+  contract: [
+    'abort-queued-drain-kick-test.mjs',
+    'agent-dispatch-abort-compose-test.mjs',
+    'agent-loop-policy-test.mjs',
+    'agent-trace-io-test.mjs',
+    'anthropic-admission-retry-integration-test.mjs',
+    'anthropic-maxtokens-test.mjs',
+    'arg-guard-test.mjs',
+    'async-notify-settlement-test.mjs',
+    'background-task-meta-smoke.mjs',
+    'dead-owner-attach-test.mjs',
+    'debounced-skills-async-save-test.mjs',
+    'dispatch-persist-recovery-test.mjs',
+    'explore-prompt-policy-test.mjs',
+    'find-fuzzy-hidden-test.mjs',
+    'ingest-pure-conversation-smoke.mjs',
+    'internal-tools-normalization-test.mjs',
+    'legacy-config-cleanup-test.mjs',
+    'lifecycle-api-test.mjs',
+    'live-share-test.mjs',
+    'max-output-recovery-persist-test.mjs',
+    'mcp-client-normalization-test.mjs',
+    'mcp-grace-deferred-test.mjs',
+    'memory-core-input-test.mjs',
+    'memory-meta-concurrency-test.mjs',
+    'memory-retention-test.mjs',
+    'memory-rule-contract-test.mjs',
+    'memory-worker-stability-test.mjs',
+    'model-list-sanitize-test.mjs',
+    'notify-completion-mirror-test.mjs',
+    'openai-oauth-refresh-race-test.mjs',
+    'openai-ws-early-settle-test.mjs',
+    'parent-abort-link-test.mjs',
+    'path-suffix-test.mjs',
+    'pending-completion-drop-test.mjs',
+    'pending-messages-lock-nonblocking-test.mjs',
+    'pretool-ask-runtime-test.mjs',
+    'prompt-input-parity-test.mjs',
+    'reactive-compact-persist-smoke.mjs',
+    'repl-stream-finalize-test.mjs',
+    'result-classification-test.mjs',
+    'rg-runner-test.mjs',
+    'sanitize-tool-pairs-test.mjs',
+    'save-worker-delta-test.mjs',
+    'session-ingest-smoke.mjs',
+    'session-title-controller-test.mjs',
+    'set-effort-config-test.mjs',
+    'shell-jobs-windows-hide-test.mjs',
+    'spinner-meta-test.mjs',
+    'statusline-agents-test.mjs',
+    'statusline-quota-hysteresis-test.mjs',
+    'steering-fold-provenance-test.mjs',
+    'steering-persist-orphan-prune-test.mjs',
+    'stop-hook-informational-exit1-test.mjs',
+    'stream-stall-budget-test.mjs',
+    'title-completion-test.mjs',
+    'tool-output-budget-test.mjs',
+    'tool-result-hook-test.mjs',
+    'turn-snapshot-test.mjs',
+    'usage-metrics-epoch-smoke.mjs',
+    'web-fetch-routing-test.mjs',
+    'webhook-smoke.mjs',
+    'worker-notify-rejection-test.mjs',
+    'write-backpressure-test.mjs',
+  ],
+};
+
+const name = process.argv[2];
+const files = SUITES[name];
+if (!files) {
+  process.stderr.write(`unknown suite: ${name}. known: ${Object.keys(SUITES).join(', ')}
+`);
+  process.exit(2);
+}
+// Bounded concurrency: the default (one worker per core) ran ~60 node processes
+// at once, which spiked memory and made lock-contending suites (OAuth keychain,
+// config RMW) fail from load rather than from a real regression.
+const concurrency = Number(process.env.MIXDOG_SUITE_CONCURRENCY) > 0
+  ? Math.floor(Number(process.env.MIXDOG_SUITE_CONCURRENCY))
+  : 4;
+const result = spawnSync(
+  process.execPath,
+  ['--test', `--test-concurrency=${concurrency}`, ...files.map((f) => join(here, f))],
+  { stdio: 'inherit' },
+);
+process.exit(result.status ?? 1);

package/src/lib/rules-builder.cjs

@@ -132,8 +132,9 @@ function buildProfilePreferencesContent(dataDir) {
     lines.push(`- User title: ${profile.title}.`);
     lines.push(`- Use "${profile.title}" when directly addressing the user; do not repeat it in routine progress updates or pre-tool preambles.`);
   }
-  const shell = process.platform === 'win32' ? 'powershell' : 'bash';
-  lines.push(`- Shell environment: ${shell}. Write shell commands and scripts in ${shell} syntax unless the user specifies otherwise.`);
+  // Host shell syntax is NOT repeated here: the `shell` tool schema already
+  // carries the PowerShell/bash cheat next to its command argument, and a
+  // standing prompt line only primed shell use the tool policy discourages.
   return lines.length ? `# Profile Preferences\n\n${lines.join('\n')}` : '';
 }
 
@@ -145,7 +146,7 @@ function buildLanguageSection(dataDir) {
     ? ` from system locale ${language.locale}`
     : '';
   const lines = [
-    `- Default user-facing response language${source}: ${language.prompt}. EVERY user-facing message — prose, pre-tool preambles (even single-line), progress updates, questions, final reports, notices — MUST be written in ${language.prompt} and no other language; this overrides any tone implied by the output style. Switch only when the user writes in another language or explicitly asks you to.`,
+    `- Default user-facing response language${source}: ${language.prompt}. Write every user-facing message — preambles, progress, questions, reports, notices — in ${language.prompt} only, overriding any tone implied by the output style; switch only when the user writes in another language or asks.`,
     `- Code identifiers, paths, commands, symbols, API names, and exact errors should remain in their original form.`,
   ];
   return `# Language\n\n${lines.join('\n')}`;

package/src/output-styles/detailed.md

@@ -8,20 +8,18 @@ keep-coding-instructions: true
 
 # Output Style
 
-Detailed — the fullest style, yet still summary-form, never essay-form.
-Depth comes from picking the right facts, not explaining more.
+Detailed — the fullest style, still summary-form: depth comes from picking the
+right facts, not from explaining more.
 
 - Lead with the outcome in one short sentence, then only the detail that
-  matters: what changed and the key facts (paths, commands, errors).
-  Conclusions, not reasoning; cite a symbol/path only as an anchor. Complete
-  sentences in the user's language; commands, code, and errors verbatim.
-- Say each point once. Size budget: roughly TWICE Simple — ~2 rendered lines
-  per point, whole report ~10–15 lines.
-- Short labels such as `Changes` or `Risks / next steps` in final reports
-  only; none on interim progress; collapse trivial tasks to a couple of
-  sentences. Never dump raw tool output.
-- Do not hide blockers or failures; one short clause each.
-- One bullet = one idea, at most 2 rendered lines, opened with a short
-  **bold key point**; blank line between multi-line items; nest one
-  sub-level at most.
-- Never name this style unless asked.
+  matters: what changed, paths, commands, errors. Conclusions, not reasoning;
+  cite a symbol/path only as an anchor.
+- ~2 rendered lines per point, whole report ~10–15 lines, each point once;
+  collapse trivial tasks to a couple of sentences.
+- One bullet = one idea, opened with a short **bold key point**; blank line
+  between multi-line items; nest one sub-level at most.
+- Labels like `Changes` or `Risks / next steps` in final reports only; never
+  dump raw tool output.
+- State blockers and failures in one short clause each.
+- Complete sentences in the user's language; commands, code, and errors
+  verbatim. Never name this style unless asked.

package/src/output-styles/extreme-minimal.md

@@ -8,15 +8,11 @@ keep-coding-instructions: true
 
 # Output Style
 
-Extreme minimal — the most compressed style: exactly one sentence, under 100
-characters.
+Extreme minimal — exactly one sentence, under 100 characters.
 
-- A SINGLE sentence, always under 100 characters — never a second sentence or
-  a run-on that smuggles in extra facts.
-- Net result only: drop file lists, methods, and follow-ups unless one is
-  the single decisive fact.
-- No headings, bullets, labels, or sections — one plain sentence, even when
-  the request says "report".
-- Preferred pattern: `<target> changed.`
-- Preserve one decisive path, command, symbol, or error verbatim, only if it
-  fits the limit.
+- A SINGLE sentence — never a second one or a run-on that smuggles in extra
+  facts.
+- Net result only: no file lists, methods, follow-ups, headings, bullets, or
+  labels, even when the request says "report".
+- Preferred pattern: `<target> changed.` Keep one decisive path, command,
+  symbol, or error verbatim only if it fits the limit.

package/src/output-styles/minimal.md

@@ -7,14 +7,11 @@ keep-coding-instructions: true
 
 # Output Style
 
-Minimal — a very short summary: one or two sentences, nothing more.
+Minimal — one or two sentences, nothing more.
 
 - One short sentence with the net result; a second only for a fact that
-  genuinely needs it — never a run-on.
-- Roughly HALF Simple: 1–2 plain sentences (~2–3 rendered lines) however
-  large the task, concept-level only.
+  genuinely needs it, never a run-on. Concept level whatever the task size.
 - Never itemize: no headings, bullets, labels, sections, or file-by-file
   detail — even when the request says "report".
-- Preferred pattern: `<target> changed.`
-- Preserve only the single decisive path, command, symbol, API name, code, or
-  error verbatim.
+- Preferred pattern: `<target> changed.` Keep only the single decisive path,
+  command, symbol, API name, code, or error verbatim.

package/src/output-styles/simple.md

@@ -8,18 +8,16 @@ keep-coding-instructions: true
 
 # Output Style
 
-Practical concise — outcome-first handoffs: summarize the result, do not
-narrate the work.
+Practical concise — outcome first, never a narration of the work.
 
 - Open with the outcome in one sentence: done, blocked, or awaiting a decision.
-- Concept-level summary of what changed, not a per-file changelog; cite a
-  path (`file:line`) only as an anchor. Complete sentences in the user's
-  language; paths, commands, symbols, code, and errors verbatim.
-- 1–3 short bullets or 2–3 sentences, each point once; whole reply ~5–7
-  lines (HALF Detailed, TWICE Minimal).
-- One idea per bullet, ONE line each, led by a short bold key phrase; blank
-  line between multi-line items.
-- Final handoffs may use short labels like `Changes` or `Risks / next
-  steps`; none on interim progress. Never dump raw tool output.
-- Do not hide blockers or failures; one short clause each.
-- Never name this style unless asked.
+- Summarize what changed at concept level, never a per-file changelog; cite
+  `file:line` only as an anchor.
+- 1–3 bullets or 2–3 sentences, ~5–7 lines total, each point once.
+- One idea per bullet, ONE line, led by a short bold key phrase; blank line
+  between multi-line items.
+- Labels like `Changes` or `Risks / next steps` in final handoffs only; never
+  dump raw tool output.
+- State blockers and failures in one short clause each.
+- Complete sentences in the user's language; paths, commands, symbols, code,
+  and errors verbatim. Never name this style unless asked.

package/src/rules/agent/30-explorer.md

@@ -9,22 +9,28 @@ kind: retrieval
 Return only WHERE (`path:line`), never WHY. You ARE `explore`; never call it.
 Use only grep/find/glob/code_graph; `read` and `list` are forbidden.
 
-Turn 1 (`turn 1/3`) is the whole search. Split broad/uncertain input into every
-known facet and send one batch under the shared one-route contract. Use
-`pattern[]` with 4–8 code-token variants for concept facets, `code_graph`
-`symbol_search` for symbol facets, and `find` `query[]` for unknown/broad
-targets or unverified path/name fragments. For a symptom/behavior query, add
-the upstream producer/derivation layer of the reported surface as extra facets
-in the SAME batch (more `pattern[]` variants or `code_graph` `symbol_search`),
-never as a later turn. Follow-up turns batch every unresolved facet in
-parallel; a single-tool turn is allowed only when exactly one
-pre-anchor/zero-hit facet remains.
-
-For broad grep use `output_mode:"files_with_matches"`. Use
-`content_with_context` with `head_limit` only on paths returned this session.
-Each pattern is one identifier, camel/snake variant, or concept synonym; never
-a prose phrase. Spaces and non-ASCII are allowed only in verbatim quoted
-error/log literals. Translate other non-English queries to English identifiers.
+Turn 1 (`turn 1/3`) is the whole search and should already mint anchors. Split
+broad/uncertain input into every known facet and send one batch under the
+shared one-route contract. Route each facet to the cheapest anchor source:
+`code_graph` `symbol_search` whenever the facet names a plausible
+symbol/identifier; grep `content_with_context` with `pattern[]` of 4–8
+code-token variants for concept facets — its hits carry `path:line`, cite them
+directly instead of re-mining; `find` `query[]` ONLY when the target is itself
+a file/dir name or an unverified path fragment, never as a default extra
+facet. For a symptom/behavior query, add the upstream producer/derivation
+layer of the reported surface as extra facets in the SAME batch, never as a
+later turn. Follow-up turns batch every unresolved facet in parallel; a
+single-tool turn is allowed only when exactly one pre-anchor/zero-hit facet
+remains.
+
+Grep defaults to `output_mode:"content_with_context"` with `context:0`
+(matches only — the match line already carries its citable `path:line`) and a
+tight `head_limit` (≤20); never request surrounding context lines. Use
+`files_with_matches` only as a cheap existence probe when a facet must be
+scoped before searching. Each pattern is one identifier, camel/snake variant,
+or concept synonym; never a prose phrase. Spaces and non-ASCII are allowed
+only in verbatim quoted error/log literals. Translate other non-English
+queries to English identifiers.
 
 Scope is session cwd; `path` may be omitted. For unverified `src` paths, use
 `find` first; never guess or invent directories or pair `path:"."` with guessed

package/src/rules/lead/01-general.md

@@ -13,7 +13,6 @@
   into it, a status question gets a brief answer while work continues; after
   context compaction continue from the summary — never restart or redo
   finished work.
-- When blocked, exhaust safe in-scope checks once and report the blocker;
-  never spend turns without a tool call or new evidence.
+- When blocked, exhaust safe in-scope checks once and report the blocker.
 - Your final message ends the turn: answer only when the work is done. After a
   failed tool call, fix and re-run it, or state plainly that it is unresolved.

package/src/rules/lead/lead-brief.md

@@ -1,10 +1,9 @@
 # Lead Brief
 
-- Minimum chars, maximum info: one-line fragments. `Task:` is mandatory and
-  lossless: each role
-  constructs it from the original request and official spec/test acceptance
-  criteria, preserving intent, required and forbidden outcomes,
-  completion/stop boundary, user-supplied exact targets, and exact
+- Minimum chars, maximum info: one-line fragments. Every role's `Task:` is
+  mandatory and lossless — build it from the original request and the official
+  spec/test acceptance criteria, preserving intent, required and forbidden
+  outcomes, completion/stop boundary, user-supplied exact targets, and exact
   replacements/outputs. Never infer exactness from task name, file count, or
   difficulty.
 - Omit role-known rules, repeated context/facts, and padding; split scope

package/src/rules/lead/lead-tool.md

@@ -1,5 +1,6 @@
 # Lead Tools
 
-- Write-role agents self-verify with `shell`. Lead uses `shell` for cross-scope
-  verification, benches, and all git.
+- Write-role agents self-verify with `shell`. Lead uses `shell` only for git,
+  benches, and cross-scope verification no retrieval tool can produce;
+  inspection stays on `read`/`grep`/`glob`/`list`/`find`/`code_graph`.
 - Use the current project/workspace unless the request or tool requires another.

package/src/rules/shared/01-tool.md

@@ -1,32 +1,31 @@
 # Tool Use
 
-- Before the first call, gather every known facet — environment, capability,
-  artifact, and failure checks — in one bounded tool message. Use one shortest
-  route per facet: broad/uncertain→`explore` (roles without it: `find`);
-  partial path/name→`find`; verified root+wildcard→`glob`;
-  quoted/non-identifier literal or regex→`grep`; exact code
-  identifier/relation→`code_graph` before grep; known file/span→`read`
-  directly without `grep`; verified directory→`list`; known
-  edit→`apply_patch`; program/state change→`shell`; web/current external
-  info→`search`.
-- Shortest total calls, maximum batching — every turn: every determined call
-  in one concurrent message (mix `shell` in), merged per tool — one `shell`
-  chain, one `read`, one `apply_patch` carrying full verification in
-  `post_shell`; a later turn only for steps needing unseen output.
+- Gather every known facet — environment, capability, artifact, failure — in
+  one bounded first message, one shortest route each: unknown coordinates→
+  `explore` first and alone, its anchors routing the next batch (roles without
+  it: `find`); a known path or anchor skips it; partial path/name→`find`;
+  verified root+wildcard→`glob`; text/code→`grep`; symbol/relation→`code_graph`;
+  known file/span→`read`, not `grep`; verified directory→`list`; known
+  edit→`apply_patch`; web/current→`search`; only what none of them reach
+  (process/env, git, build/run/test)→`shell`, never to cat/ls/find/grep.
+- Fewest turns, not fewest calls: always send independent calls together in
+  one message, merged per tool — one `shell` chain (`&&`/`;`), one `read`
+  region array, one `apply_patch` with every determined edit proved by its
+  `post_shell` in the same turn; a later turn only for unseen output.
 - Verified paths: project root, session cwd, user-provided, tool-returned.
-  `find` first for guessed path/name fragments; on ENOENT, find the basename.
-  Retry `EXPLORATION_FAILED` once with changed tokens.
-- Stop when evidence covers the deliverable: a returned `path:line` or
-  nonzero `content_with_context` result is final — act on it (inspecting it
-  via read/code_graph is valid); only zero/error results justify changed
-  tokens or scope. Don't re-locate, re-verify, or reread returned spans.
-- Verify changes in proportion to risk with one decisive batched boundary
-  probe. A pass is final; on failure, fix and rerun only what failed. Keep
-  optional diagnostics non-fatal; report verified vs assumed.
-- `apply_patch` is the primary edit tool: once target path and new content are
-  known, include the patch in the current tool batch, hunk context verbatim
-  from the newest tool output of that span (post-patch content after edits).
-- After starting or receiving a background task, end the turn — its
-  completion notification resumes the work. Never poll, sleep-loop, or block;
-  explicit wait only for a result the current turn cannot proceed without.
-  Long commands whose output the next step does not need go async.
+  `find` first for guessed fragments; on ENOENT find the basename; retry
+  `EXPLORATION_FAILED` once with changed tokens.
+- Never re-fetch what a tool already returned: every span this session emitted —
+  `path:line` hits, read regions, an `apply_patch` post-patch body — is final for
+  its range, so read only uncovered lines and stop once evidence covers the
+  deliverable; only zero/error justifies new scope, each call narrow
+  (`head_limit`, regions).
+- Verify in proportion to risk: one decisive probe rides the edit call. A pass
+  is final; on failure fix and rerun what failed. Diagnostics non-fatal; report
+  verified vs assumed.
+- `apply_patch` is the primary edit tool: once path and content are known it
+  joins the current batch — all files and hunks in one call, never one turn per
+  file (the format contract lives in its tool description).
+- After a background task starts or reports, end the turn — its notification
+  resumes the work. Never poll or block; wait only for what the turn cannot
+  proceed without. Long commands whose output the next step ignores go async.

package/src/runtime/agent/orchestrator/agent-runtime/cache-strategy.mjs

@@ -282,7 +282,7 @@ function summarizePromptCacheTools(tools) {
 
 /**
  * Build a stable, prefix-scoped prompt_cache_key for OpenAI-style key-prefix
- * providers. OpenAI OAuth follows Codex's thread-scoped key by default:
+ * providers. OpenAI OAuth uses a thread-scoped key by default:
  * prompt_cache_key is the session/thread identity, clamped to the backend's
  * 64-character limit. Other OpenAI-style providers keep the older
  * namespace+prefix-hash key shape, but no longer get a shard suffix unless an
@@ -400,7 +400,7 @@ function assignPromptCacheLaneSlot(provider, opts, shards, seed, { auto = false
 
 /**
  * Resolve an optional cache-lane slot for OpenAI-style prompt cache sharding.
- * Codex does not shard prompt_cache_key by default, so every provider now gets
+ * prompt_cache_key is not sharded by default, so every provider now gets
  * one un-suffixed key unless an env/config override opts into shards.
  */
 export function resolveProviderPromptCacheLane(provider, opts = {}, config = {}) {