mixdog 0.9.18 → 0.9.19

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

@@ -8,27 +8,58 @@ kind: retrieval
 
 Coordinate locator. Deliverable = WHERE as `path:line`, never WHY — no
 explaining or tracing. You ARE the `explore` tool: never call it; shared
-rules pointing at `explore` don't apply — use grep/code_graph/find/glob
-directly.
+rules pointing at `explore` don't apply.
+
+Tools: grep/find/glob/code_graph ONLY. `read` and `list` are FORBIDDEN —
+grep match lines already carry every `path:line` you may output; opening a
+file to "confirm" or "understand" a hit is the WHY you must not answer.
+This ban has NO exception: not after a hit, not for the reason field, not
+"just one read" — a `read`/`list` call anywhere in the session is a defect.
+
+Turn 1 is the whole search, ONE message: one grep whose `pattern[]` packs
+3-6 token variants (camelCase/kebab-case/snake_case/SCREAMING_SNAKE casings,
+synonyms, library/domain names), plus `find` with name fragments, plus `code_graph`
+symbol_search when the query names an identifier. A single-pattern,
+single-tool first turn is a defect.
+
+Search tokens are CODE tokens: first translate natural-language or
+non-English queries into probable English identifiers (e.g. "최대 루프 반복
+횟수" → maxLoop, loop-policy, iterations). Grep non-ASCII text only when
+the query quotes a literal string.
+
+Search scope is ALWAYS the session working directory: omit `path` (default
+scope) or pass ONLY a path that appeared in an earlier result this session.
+Inventing a directory (`/workspace/...`, guessed `src/lib`, another repo's
+layout) is a defect — those results are always empty; on zero hits change
+TOKENS, never guess paths.
 
 Credibility is mechanical: hit = line/path contains ANY query token or
-obvious synonym. No other standard — "is this the real implementation" is
-the caller's question. Sole exception: a generic-word-only match (schema,
-handler, config, resolver…) with no SPECIFIC query token (product/library/
-domain name) = zero, not a hit.
-
-Rule zero — after EVERY tool result: ≥1 `path:line` matching a query
-token → answer NOW with those coordinates; no verify, no re-grep, no
-ranking; mark weak anchors `?`. Zero → one more batch if budget remains.
-No third branch: "hits exist but I want better ones" IS branch one.
-
-Turns: 3 tool turns HARD max; start each tool message with `turn N/3`.
-Turn 1 → answer; turns 2-3 are miss-recovery only, and must change tokens
-OR scope — never reword. One turn = ONE batch of AT MOST 5 calls: a single
-grep packing ALL variants in pattern[] plus code_graph/find/glob; a 6th
-call = packing failure. Flow/how questions: return first matching entry
-anchors (≤5); the caller traces the chain.
-
-Answer, nothing else: up to 5 lines `path:line — symbol — short reason`
-(`?` if weak), or `EXPLORATION_FAILED` — only after 3 turns of zero
-anchors, or when every anchor matches only generic words.
+obvious synonym — never judge "is this the real implementation". Sole
+exception: a generic-word-only match (schema, handler, config, resolver…)
+with no SPECIFIC query token (product/library/domain name) = zero, not a hit.
+A `code_graph` symbol hit (find_symbol/symbol_search returning `path:line`)
+IS an anchor — emit it directly; never re-locate it with grep.
+
+Rule zero — after EVERY tool result: ≥1 `path:line` matching a query token
+→ answer NOW with those coordinates, mark weak anchors `?`; zero → one more
+batch if budget remains. No third branch: "hits exist but I want better
+ones" IS branch one. Once ANY turn yields a matching line, the only legal
+next output is the final answer text — every further tool call is a defect.
+
+Turns: hard max 3, expected 1; start each tool message with `turn N/3`.
+Turns 2-3 are miss-recovery only (prior turn had ZERO matching lines) and
+must change tokens OR scope, never reword.
+Flow/how questions: first matching entry/definition anchors ARE the answer,
+one anchor per concept — never trace the chain.
+Compound queries ("where is X and what value/default does it use"): the
+definition anchor answers BOTH parts — never launch extra searches for the
+value, threshold, or content; one anchor per concept, all from the same batch.
+
+Answer, nothing else: anchor lines `path:line — symbol — short reason`
+(`?` if weak), max 3 lines — extra anchors are cost, not quality; pick the
+3 with the most specific token match. Or `EXPLORATION_FAILED` — only after
+the turn budget is
+spent with zero anchors, or when every anchor matches only generic words.
+Before emitting `EXPLORATION_FAILED`, re-scan ALL earlier tool results: if
+any line anywhere matched a specific query token, answer with that anchor
+(`?` if weak) instead — a weak anchor beats a false miss.

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

@@ -1,7 +1,8 @@
 # Lead Tool Use
 
-- Lead owns repo-local shell work: run git/build/test/verification via `shell`
-  directly; do not delegate to agents.
+- Write-role agents run their own build/test verification via `shell`; Lead
+  runs cross-scope verification, benches, and everything git via `shell`
+  directly.
 - Use the session's current project/workspace. Change the work project only
   when the user asks for another project or a tool call needs another root.
 - Use `agent` for scoped implementation, research, review, and debugging — not

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

@@ -1,32 +1,27 @@
 # Tool Use
 
-- Batch independent lookups in one turn; serialize only when a call needs a
-  prior result — including edit loops: batch the post-edit verification read
-  with the next target's lookup.
-- Pick by target: symbols/callers/deps → `code_graph`; exact text in a verified
-  scope → `grep`; dirs → `list`; verified file → `read`.
-  Locating files: concept-level or cross-file questions ("where is X handled",
-  "how does Y flow") → `explore`, even when you could guess a keyword — its
-  fan-out spends explorer context, not yours, and guess-and-retry keywords
-  belong to it, not grep. Confident name fragment → `find`; exact name
-  pattern → `glob`; exact content literal → `grep`. Flow/trace with a known
-  symbol → `code_graph`, never `explore` — it returns entry-point anchors
-  only; follow the chain yourself. Never `grep`/`read` guessed paths.
-- One concept → ONE search call: all synonyms/variants in one
-  `grep pattern:[...]` (or `code_graph symbols[]`), scopes as `path[]`;
-  single-pattern bursts = packing failure. A second call on the same concept
-  is a defect unless the first returned zero — then change tokens or scope,
-  never reword.
-- Content-mode `grep` always carries `-C 5`+ ; re-reading the same file after
-  a content grep is a wasted round-trip. Bare match lines = existence checks
-  only.
-- Any path not returned by a tool this session is a guess: find first, then
-  grep/read the returned path. On ENOENT the next call is find on the
-  basename — never a second guess or the same path with changed args.
-- Retrieval serves the NEXT action (edit, answer, handoff), not certainty:
-  the FIRST anchor ends the search — no verifying, ranking, or re-checking a
-  hit already on screen. When acting and looking are both possible, act.
-- `read` uses `offset`/`limit` only; 2+ spans from known file(s) = ONE batched
-  `read` with `{path,offset,limit}` regions. Adjacent spans in one file
-  (within a few hundred lines) are ONE window, not repeated reads.
+- Batch independent calls in one turn; serialize only when a call needs a
+  prior result. Merge equivalent variants/scopes into ONE call wherever the
+  schema accepts arrays (`pattern[]`, `path[]`, `symbols[]`, `query[]`).
+- Route by what is already known: known symbol/relation → `code_graph`;
+  exact text in a known scope → `grep`; unknown location or concept-level
+  question → `explore`; name fragment → `find`; exact name pattern → `glob`;
+  known directory → `list`; known file/region → `read`.
+- Valid anchors come from user input or tool output in this session; locate
+  anything else with `find` before `grep`/`read`. On ENOENT the next call is
+  `find` on the basename — never a retried guess.
+- Retrieval stops when evidence covers the deliverable: single-answer tasks
+  end at the first sufficient anchor; enumeration tasks (review, audit) end
+  when the stated scope is covered. Never re-verify a hit already on screen;
+  a plausible anchor means the next call is the action itself
+  (patch/answer/handoff) — never "one more confirming read".
+- Content-mode `grep` requests enough context (`-C`) to act without
+  re-reading the same file; bare match lines are existence checks only.
+- Repeat a search concept only after a zero-result call, changing tokens or
+  scope — never wording alone.
+- `read` windows use `offset`/`limit`; multiple spans or files = ONE call
+  with `{path,offset,limit}[]` regions. Size the window to the whole logical
+  unit (function/section) — over-read once instead of paging the same file
+  in small windows across turns; a 3rd window into one file means the first
+  should have been wider.
 - Don't mix `apply_patch` with shell or other state-changing calls in one turn.

package/src/runtime/agent/orchestrator/providers/anthropic-oauth.mjs

@@ -376,7 +376,7 @@ function toAnthropicMessages(messages) {
             continue;
         }
 
-        // Claude Code parity: fold a user text turn that directly follows a
+        // First-party client parity: fold a user text turn that directly follows a
         // tool_result turn into that tool_result's content. A sibling text
         // turn after tool_result renders as `</function_results>\n\nHuman:`
         // on the wire and trains the model toward 3-token empty end_turn

package/src/runtime/agent/orchestrator/providers/anthropic.mjs

@@ -378,7 +378,7 @@ function toAnthropicMessages(messages) {
             }
             continue;
         }
-        // Claude Code parity: fold a user text turn that directly follows a
+        // First-party client parity: fold a user text turn that directly follows a
         // tool_result turn into that tool_result's content (empty end_turn
         // livelock prevention; see foldUserTextIntoToolResultTail).
         if (m.role === 'user' && foldUserTextIntoToolResultTail(result, normalizeContentForAnthropic(m.content))) {

package/src/runtime/agent/orchestrator/providers/oauth-usage.mjs

@@ -241,14 +241,35 @@ function windowFromPercent(label, value, source) {
   return Object.keys(out).length > 2 ? out : null;
 }
 
+// Grok Build billing periods are migrating from monthly to a shared weekly
+// pool (xAI rollout is per-account). Derive the window cadence from the
+// actual billing period length instead of hardcoding monthly: <=10 days
+// means a weekly cycle, anything longer (or unknown) stays monthly.
+function grokBillingCadence(config) {
+  if (config?.weeklyLimit !== undefined || config?.weekly_limit !== undefined) {
+    return { label: 'W', period: 'weekly' };
+  }
+  const start = resetAtMs(config?.billingPeriodStart ?? config?.billing_period_start);
+  const end = resetAtMs(config?.billingPeriodEnd ?? config?.billing_period_end);
+  if (start && end && end > start && (end - start) <= 10 * 24 * 60 * 60_000) {
+    return { label: 'W', period: 'weekly' };
+  }
+  return { label: 'M', period: 'monthly' };
+}
+
 function creditWindowFromBilling(config) {
   if (!config || typeof config !== 'object') return null;
-  const limit = num(config.monthlyLimit?.val ?? config.monthlyLimit ?? config.includedLimit?.val, null);
+  const limit = num(
+    config.weeklyLimit?.val ?? config.weeklyLimit
+      ?? config.monthlyLimit?.val ?? config.monthlyLimit
+      ?? config.includedLimit?.val,
+    null,
+  );
   const used = num(config.used?.val ?? config.includedUsed?.val ?? config.used, null);
   if (limit === null || used === null || !(limit > 0)) return null;
   const resetAt = resetAtMs(config.billingPeriodEnd ?? config.billing_period_end);
   return {
-    label: 'M',
+    label: grokBillingCadence(config).label,
     source: 'grok-build-billing',
     usedPct: round(Math.min(100, used * 100 / limit), 2),
     usedCredits: round(used, 2),
@@ -265,7 +286,7 @@ function balanceFromGrokBilling(config) {
   if (cap === null || !(cap > 0)) return null;
   return {
     source: 'grok-build-on-demand',
-    period: 'monthly',
+    period: grokBillingCadence(config).period,
     budgetCredits: round(cap, 2),
     spentCredits: round(used, 2),
     remainingCredits: round(Math.max(0, cap - used), 2),

package/src/runtime/agent/orchestrator/providers/retry-classifier.mjs

@@ -29,15 +29,15 @@ import {
 //   408 — request timeout
 //   500/502/503/504 — server errors (overload / bad gateway / timeout)
 //   429 is excluded from blanket transient retry, but withRetry() honors a
-//   SHORT Retry-After header (< SHORT_RETRY_AFTER_MAX_MS) the way Claude Code
-//   does (refs/claude-code withRetry.ts SHORT_RETRY_THRESHOLD_MS = 20s):
+//   SHORT Retry-After header (< SHORT_RETRY_AFTER_MAX_MS): a short-retry
+//   threshold of 20s matches first-party client behavior:
 //   brief throttle windows retry once the server-stated wait elapses; long or
 //   headerless 429s still surface immediately (quota windows are
 //   deterministic — sleeping into an outer watchdog just relabels the error).
 const TRANSIENT_STATUSES = new Set([408, 500, 502, 503, 504])
 
 // Max server-stated Retry-After we are willing to sleep on a 429 before
-// surfacing it. Mirrors Claude Code's 20s short-retry threshold.
+// surfacing it. Mirrors the first-party client's 20s short-retry threshold.
 const SHORT_RETRY_AFTER_MAX_MS = 20_000
 
 // HTTP statuses that mean "permanent: stop retrying, surface to caller".

package/src/runtime/agent/orchestrator/session/context-utils.mjs

@@ -651,8 +651,8 @@ export function sanitizeAnthropicContentPairs(messages) {
 
 /**
  * Fold a plain user text turn into the trailing tool_result block of the
- * previous user message (Claude Code parity: utils/messages.ts
- * mergeUserContentBlocks / smooshIntoToolResult). Any sibling text after a
+ * previous user message (first-party client parity: merge user content
+ * blocks into the trailing tool_result). Any sibling text after a
  * tool_result renders as `</function_results>\n\nHuman:<...>` on the
  * Anthropic wire; repeated mid-conversation this teaches the model to emit
  * 3-token empty end_turn completions (upstream A/B sai-20260310-161901:

package/src/runtime/agent/orchestrator/session/loop/steering-ladder.mjs

@@ -8,6 +8,91 @@ import { appendAgentTrace } from '../../agent-trace.mjs';
 import { level2SteerMessage } from './completion-guards.mjs';
 import { isEagerDispatchable } from './tool-helpers.mjs';
 
+// --- Steering detector helpers (pure) ---
+const _WORD_RE = /[A-Za-z_$][\w$]*/g;
+const _IDENT_RE = /^[A-Za-z_$][\w$]{2,}$/;
+const _SRC_DIR_RE = /(^|[\\/])(src|lib|app|packages|components|pages)([\\/]|$)/i;
+function _grepPatterns(c) {
+    const p = c?.arguments?.pattern;
+    if (typeof p === 'string') return [p];
+    if (Array.isArray(p)) return p.filter((x) => typeof x === 'string');
+    return [];
+}
+function _patternTokens(c) {
+    const out = new Set();
+    for (const pat of _grepPatterns(c)) {
+        for (const t of (String(pat).match(_WORD_RE) || [])) {
+            if (t.length >= 3) out.add(t.toLowerCase());
+        }
+    }
+    return out;
+}
+function _pathsOf(arg) {
+    const out = [];
+    const push = (v) => {
+        if (typeof v === 'string' && v) out.push(v);
+        else if (v && typeof v === 'object' && typeof v.path === 'string' && v.path) out.push(v.path);
+    };
+    if (Array.isArray(arg)) arg.forEach(push); else push(arg);
+    return out;
+}
+// Case-insensitive (win32 paths) forward-slash normalization for all path compares.
+function _normPath(p) { return String(p).replace(/\\/g, '/').toLowerCase(); }
+function _baseName(p) { const s = _normPath(p); const i = s.lastIndexOf('/'); return i >= 0 ? s.slice(i + 1) : s; }
+function _dirName(p) { const s = _normPath(p); const i = s.lastIndexOf('/'); return i >= 0 ? s.slice(0, i) : ''; }
+// Exact (normalized) same-file test — used where "related" is too loose.
+function _samePath(a, b) { return !!a && !!b && _normPath(a) === _normPath(b); }
+// Loose sibling/variant relation — cluster detector pairs this WITH token overlap.
+function _pathsRelated(a, b) {
+    if (!a || !b) return false;
+    const na = _normPath(a); const nb = _normPath(b);
+    if (na === nb) return true;                                 // identical
+    if (na.includes(nb) || nb.includes(na)) return true;        // normalized variant
+    if (_dirName(na) && _dirName(na) === _dirName(nb)) return true; // siblings
+    const ba = _baseName(na); const bb = _baseName(nb);
+    return !!ba && ba === bb;                                    // same file name
+}
+function _setsOverlap(a, b) { for (const x of a) { if (b.has(x)) return true; } return false; }
+// A single chained segment is read-only only if it STARTS with a read-only verb.
+function _isReadOnlyShellSegment(seg) {
+    const s = seg.trim();
+    if (!s) return null;                                        // empty (trailing operator)
+    if (/^git\s+(status|log)\b/.test(s)) return true;
+    if (/^git\s+diff\b[^\n]*--stat\b/.test(s)) return true;
+    if (/^get-childitem\b/.test(s)) return true;
+    return /^(cat|ls|dir|type)\b/.test(s);
+}
+// Read-only only when EVERY chained segment is read-only — a single mutating
+// segment (e.g. `git status && npm test`) disqualifies the whole command.
+function _isReadOnlyShellCmd(cmd) {
+    const s = String(cmd || '').toLowerCase().trim();
+    if (!s) return false;
+    let sawCmd = false;
+    for (const seg of s.split(/&&|\|\||[;&|]/)) {
+        const verdict = _isReadOnlyShellSegment(seg);
+        if (verdict === null) continue;                         // blank segment
+        if (verdict === false) return false;                    // a mutating segment
+        sawCmd = true;
+    }
+    return sawCmd;
+}
+// Extract (path, offset) windows from a read call: path may be a string, an
+// array of strings, or an array of {path,offset,limit} regions; a top-level
+// offset applies to string entries.
+function _readWindows(c) {
+    const a = c?.arguments || {};
+    const out = [];
+    const push = (p, off) => { if (typeof p === 'string' && p) out.push({ path: p, offset: Number(off) }); };
+    const v = a.path;
+    if (Array.isArray(v)) {
+        for (const e of v) {
+            if (typeof e === 'string') push(e, a.offset);
+            else if (e && typeof e === 'object') push(e.path, e.offset ?? a.offset);
+        }
+    } else if (typeof v === 'string') push(v, a.offset);
+    return out;
+}
+
 // Build the completion-first steering-ladder controller. `ctx` supplies live
 // accessors so every read reflects the loop's current mutable state:
 //   - messages, sessionId, sessionAgent, tools           (stable refs/values)
@@ -43,13 +128,26 @@ export function createSteeringLadder(ctx) {
     // call (missed parallelism). Not reset per-iteration — only by the
     // steering-hint fire below or by a turn that batches/edits.
     let _serialReadOnlyStreak = 0;
-    // Tracks consecutive grep calls scoped to the SAME path (any patterns) —
-    // the "serial rewording" spiral: re-grepping one file with reworded
-    // patterns instead of reading it. Only counts turns whose every call is a
-    // grep on that path; any other tool/path resets it.
-    let _sameFileGrepStreak = 0;
-    let _sameFileGrepPath = null;
+    // Same-concept grep cluster (broadened serial-rewording spiral): counts
+    // consecutive grep-only turns that stay on ONE concept — related by
+    // identical/normalized/sibling paths OR pattern-token overlap, not just an
+    // identical path. `_sameGrepPrev` holds the prior turn's {paths,tokens}.
+    let _sameGrepStreak = 0;
+    let _sameGrepPrev = null;
+    // Prior turn's uncapped content/context grep paths — seeds the
+    // grep-context-then-read detector (a read of the same file next turn).
+    let _lastGrepContentPaths = null;
+    // Consecutive turns grepping the SAME identifier-like token in source dirs
+    // (symbol lookups that belong in code_graph).
+    let _identGrepStreak = 0;
+    let _identGrepToken = null;
     let _level2FireCount = 0;
+    // Read-fragmentation detector state: normalized path -> cumulative
+    // single-window offset reads. Mirrors session-bench read_fragmentation
+    // (3+ windowed reads of one file within an 800-line span). Multi-window
+    // same-path regions in ONE call are the recommended batched form and are
+    // never counted. Fires once per path per session.
+    const _readWindowsByPath = new Map();
 
     // Level-2 steering emitter shared by both ladder paths (single-call
     // level-1 streak and the independent all-read-only streak). Sets the latch
@@ -78,14 +176,14 @@ export function createSteeringLadder(ctx) {
             const iterations = getIterations();
             const editCount = getEditCount();
             // Steering hint gate: at most ONE hint per turn (priority:
-            // level-2 > same-file grep > level-1).
+            // level-2 > grep/shell detectors > level-1).
             let _hintFiredThisTurn = hintAlreadyFired;
-            // Missed-parallelism steering: 3+ consecutive turns of a single
+            // Missed-parallelism steering: 2+ consecutive turns of a single
             // read-only tool call suggest the model isn't batching independent
-            // lookups. Nudge once, then reset (fires again after 3 more).
+            // lookups. Nudge once, then reset (fires again after 2 more).
             if (calls.length === 1 && isEagerDispatchable(calls[0].name, tools)) {
                 _serialReadOnlyStreak += 1;
-                if (_serialReadOnlyStreak >= 3 && !_hintFiredThisTurn) {
+                if (_serialReadOnlyStreak >= 2 && !_hintFiredThisTurn) {
                     _serialReadOnlyStreak = 0;
                     // Escalation ladder (Step 1). Cumulative level-1 fires are
                     // tracked and NEVER reset. Once level-1 has fired >=3 times with
@@ -96,7 +194,7 @@ export function createSteeringLadder(ctx) {
                     if (_level1FireCount >= 3 && editCount === 0 && (iterations - _level2LatchAtIteration) >= 5) {
                         _emitLevel2Steer();
                     } else {
-                        pushSystemReminder('Last 3 turns each ran a single read-only tool. Batch independent lookups (read/grep/glob/code_graph) into ONE turn, or start editing if you have enough context.');
+                        pushSystemReminder('Last 2 turns each ran a single read-only tool. Batch independent lookups (read/grep/glob/code_graph) into ONE turn, or start editing if you have enough context.');
                     }
                     _hintFiredThisTurn = true;
                 }
@@ -121,36 +219,153 @@ export function createSteeringLadder(ctx) {
                     _allReadOnlyStreak = 0;
                 }
             }
-            // Serial-rewording steering: 4+ consecutive turns grepping the SAME
-            // path with reworded patterns = a search spiral that single-call
-            // batching cannot catch. Crisis-only: fires once per spiral, then
-            // resets. Read-the-file is almost always the answer at that point.
+            const _grepCalls = calls.filter((c) => c?.name === 'grep');
+            const _allGrep = calls.length > 0 && _grepCalls.length === calls.length;
+            // Detector: repeated identifier-like grep in source dirs → code_graph.
+            // Symbol lookups (a bare \w+ token scoped to src/) belong in
+            // code_graph (find_symbol/references/callers), not text grep. Fires
+            // when the same token is grepped on 2+ consecutive qualifying turns.
             {
-                const _grepPathOf = (c) => {
-                    if (c?.name !== 'grep') return null;
-                    const p = c?.arguments?.path;
-                    return typeof p === 'string' && p ? p : null;
-                };
-                const _turnPaths = calls.map(_grepPathOf);
-                const _uniq = [...new Set(_turnPaths)];
-                if (_uniq.length === 1 && _uniq[0] !== null) {
-                    if (_uniq[0] === _sameFileGrepPath) _sameFileGrepStreak += 1;
-                    else { _sameFileGrepPath = _uniq[0]; _sameFileGrepStreak = 1; }
-                    if (_sameFileGrepStreak >= 4 && !_hintFiredThisTurn) {
-                        pushSystemReminder(`4+ consecutive grep turns on the same path (${_sameFileGrepPath}). Rewording patterns is not converging — read the relevant span directly (read with offset/limit) or act on what you have.`);
-                        _sameFileGrepStreak = 0;
-                        _sameFileGrepPath = null;
+                let _identTok = null;
+                for (const c of _grepCalls) {
+                    const _srcScoped = _pathsOf(c?.arguments?.path).some((p) => _SRC_DIR_RE.test(p));
+                    if (!_srcScoped) continue;
+                    const _hit = _grepPatterns(c).map((p) => p.trim()).find((p) => _IDENT_RE.test(p));
+                    if (_hit) { _identTok = _hit.toLowerCase(); break; }
+                }
+                if (_identTok) {
+                    if (_identTok === _identGrepToken) _identGrepStreak += 1;
+                    else { _identGrepToken = _identTok; _identGrepStreak = 1; }
+                    if (_identGrepStreak >= 2 && !_hintFiredThisTurn) {
+                        pushSystemReminder(`Grepping the symbol "${_identGrepToken}" across source dirs again — use code_graph (find_symbol/references/callers) for symbol lookups instead of text grep.`);
+                        _identGrepStreak = 0;
+                        _identGrepToken = null;
+                        _hintFiredThisTurn = true;
+                    }
+                } else {
+                    _identGrepStreak = 0;
+                    _identGrepToken = null;
+                }
+            }
+            // Same-concept grep cluster (broadened serial-rewording): 3+
+            // consecutive grep-only turns on one concept — related by
+            // an exact-same path, OR a sibling/variant path that ALSO shares a
+            // pattern token (sibling alone is too loose to count).
+            // Fires once per spiral, then resets; read-the-span is the answer.
+            {
+                if (_allGrep) {
+                    const _paths = [];
+                    const _tokens = new Set();
+                    for (const c of _grepCalls) {
+                        for (const p of _pathsOf(c?.arguments?.path)) _paths.push(p);
+                        for (const t of _patternTokens(c)) _tokens.add(t);
+                    }
+                    let _related = false;
+                    if (_sameGrepPrev) {
+                        // Exact same-path spiral fires alone; a merely sibling/
+                        // variant path must ALSO share a pattern token to count.
+                        const _pathExact = _paths.some((a) => _sameGrepPrev.paths.some((b) => _samePath(a, b)));
+                        const _pathRel = _paths.some((a) => _sameGrepPrev.paths.some((b) => _pathsRelated(a, b)));
+                        const _tokRel = _setsOverlap(_tokens, _sameGrepPrev.tokens);
+                        _related = _pathExact || (_pathRel && _tokRel);
+                    }
+                    _sameGrepStreak = _related ? _sameGrepStreak + 1 : 1;
+                    const _label = _paths[0] || [..._tokens][0] || 'same concept';
+                    _sameGrepPrev = { paths: _paths, tokens: _tokens };
+                    if (_sameGrepStreak >= 3 && !_hintFiredThisTurn) {
+                        pushSystemReminder(`3+ consecutive grep turns on the same concept (${_label}) — reworded patterns / sibling paths are not converging. Read the relevant span (read with offset/limit) or act on what you have.`);
+                        _sameGrepStreak = 0;
+                        _sameGrepPrev = null;
                         _hintFiredThisTurn = true;
                     }
                 } else {
-                    _sameFileGrepStreak = 0;
-                    _sameFileGrepPath = null;
+                    _sameGrepStreak = 0;
+                    _sameGrepPrev = null;
                 }
             }
+            // Detector: content/context grep on X then read of X next turn — the
+            // grep context should have sufficed. Fire off the PRIOR turn's
+            // uncapped content grep, then recompute for the next turn (skip when
+            // the grep was capped via head_limit or paths-only mode).
+            {
+                if (_lastGrepContentPaths && !_hintFiredThisTurn) {
+                    const _readCall = calls.find((c) => c?.name === 'read');
+                    if (_readCall) {
+                        const _rp = _pathsOf(_readCall?.arguments?.path);
+                        // Same-file only — a sibling read is a new lookup, not a re-read.
+                        const _hit = _rp.find((p) => [..._lastGrepContentPaths].some((g) => _samePath(p, g)));
+                        if (_hit) {
+                            pushSystemReminder(`Reading ${_baseName(_hit)} right after a content grep on it — the grep context should have sufficed; answer from grep output or widen -C instead of re-reading.`);
+                            _hintFiredThisTurn = true;
+                        }
+                    }
+                }
+                const _next = new Set();
+                for (const c of _grepCalls) {
+                    const a = c?.arguments || {};
+                    const _hasCtx = a['-A'] != null || a['-B'] != null || a['-C'] != null;
+                    const _isContent = a.output_mode === 'content' || a.output_mode === 'content_with_context' || _hasCtx;
+                    const _pathsOnly = a.output_mode === 'files_with_matches' || a.output_mode === 'count';
+                    const _capped = a.head_limit != null;
+                    if (_isContent && !_pathsOnly && !_capped) {
+                        for (const p of _pathsOf(a.path)) _next.add(p);
+                    }
+                }
+                _lastGrepContentPaths = _next.size ? _next : null;
+            }
+            // Detector: read fragmentation — 2nd+ single-window read into the
+            // SAME file with offsets inside an 800-line span means the model is
+            // paging small windows across turns instead of reading one wider
+            // span (or batching {path,offset,limit}[] regions in one call).
+            {
+                for (const c of calls.filter((x) => x?.name === 'read')) {
+                    const _byPath = new Map();
+                    for (const w of _readWindows(c)) {
+                        const k = _normPath(w.path);
+                        if (!_byPath.has(k)) _byPath.set(k, []);
+                        _byPath.get(k).push(w);
+                    }
+                    for (const [k, ws] of _byPath) {
+                        if (ws.length !== 1) continue; // batched regions on one path — the good form
+                        const off = ws[0].offset;
+                        if (!Number.isFinite(off) || off <= 0) continue;
+                        let rec = _readWindowsByPath.get(k);
+                        if (!rec) {
+                            rec = { offsets: [], fired: false };
+                            _readWindowsByPath.set(k, rec);
+                            if (_readWindowsByPath.size > 32) _readWindowsByPath.delete(_readWindowsByPath.keys().next().value);
+                        }
+                        rec.offsets.push(off);
+                        if (!rec.fired && !_hintFiredThisTurn && rec.offsets.length >= 2
+                            && (Math.max(...rec.offsets) - Math.min(...rec.offsets)) <= 800) {
+                            pushSystemReminder(`Windowed reads are fragmenting ${_baseName(k)} — stop paging small windows; read ONE wider span, or batch all needed spans as {path,offset,limit}[] regions in a single call.`);
+                            rec.fired = true;
+                            _hintFiredThisTurn = true;
+                        }
+                    }
+                }
+            }
+            // Detector: read-only shell (git status/log/diff --stat, ls/dir/cat/
+            // type/Get-ChildItem) inspects state the dedicated tools cover.
+            // Nudge toward them; never blocks execution.
+            {
+                if (!_hintFiredThisTurn && calls.some((c) => c?.name === 'shell' && _isReadOnlyShellCmd(c?.arguments?.command))) {
+                    pushSystemReminder('Read-only shell (git status/log/diff --stat, ls/dir/cat/type/Get-ChildItem) inspects state the dedicated tools cover — use grep/read/list/find/code_graph; shell is for changing state or running programs.');
+                    _hintFiredThisTurn = true;
+                }
+            }
+        },
+        // Reviewer fix: a zero-tool turn must not bridge ANY cross-turn streak
+        // across non-tool turns — that would fire level-2 (or the grep/read
+        // detectors) early on a worker that paused to synthesize text mid-run.
+        resetAllReadOnlyStreak() {
+            _allReadOnlyStreak = 0;
+            _serialReadOnlyStreak = 0;
+            _sameGrepStreak = 0;
+            _sameGrepPrev = null;
+            _lastGrepContentPaths = null;
+            _identGrepStreak = 0;
+            _identGrepToken = null;
         },
-        // Reviewer fix: a zero-tool turn must not bridge the all-read-only
-        // streak across non-tool turns — that would fire level-2 early on a
-        // worker that paused to synthesize text mid-run.
-        resetAllReadOnlyStreak() { _allReadOnlyStreak = 0; },
     };
 }

package/src/runtime/agent/orchestrator/session/manager/tool-resolution.mjs

@@ -87,10 +87,10 @@ function stringToolPermissionAllowList(toolPermission) {
     return null;
 }
 
-// Read-write agent bundle: edit surface (apply_patch) WITHOUT shell/task.
-// Repo-local shell work (git/build/test/verification) is Lead-owned by
-// workflow contract; write-role agents patch files and hand verification
-// back. Only permission 'full' (no narrowing) retains shell.
+// Read-write agent bundle: full edit surface INCLUDING shell/task so
+// write-role agents can run their own verification (build/test) without
+// bouncing it back to Lead. Deploy/ship remains a workflow-level rule,
+// not a tool-surface restriction.
 const AGENT_STRING_PERMISSION_READ_WRITE_ALLOW = Object.freeze([
     'code_graph',
     'find',
@@ -99,6 +99,8 @@ const AGENT_STRING_PERMISSION_READ_WRITE_ALLOW = Object.freeze([
     'grep',
     'read',
     'apply_patch',
+    'shell',
+    'task',
     'explore',
     'search',
     'web_fetch',