mixdog 0.9.3 → 0.9.5

package/src/output-styles/default.md

@@ -7,21 +7,42 @@ keep-coding-instructions: true
 
 # Output Style
 
-Mixdog default — the most detailed of the three styles, but only as long as the
-task warrants.
+Mixdog default — the most detailed style, but always summary-form, never
+essay-form. Depth comes from picking the right facts, not explaining more.
 
-- Lead with the outcome, then add the supporting detail that matters: what
-  changed, key evidence (paths, commands, errors, verification), and important
-  context. Include trade-offs or follow-up only when they actually matter.
-- Use a few bullets or short paragraphs when they add signal; this style may run
-  longer than Simple, but match length to the work — do not pad a small change
-  into a full report. Cut anything that does not earn its place.
+Content
+- Lead with the outcome in one short sentence, then only the detail that
+  matters: what changed, key evidence (paths, commands, errors, verification).
+- Summarize at the concept level: name the problem/behavior and direction, not
+  the code path. Cite a symbol/path only as an anchor, never as the explanation.
+- Compress by cutting content (filler, hedging, connective padding, restated
+  facts), not by clipping grammar: keep natural, complete sentences in the
+  user's language — never telegraph-style stub endings. Technical terms and
+  code stay exact.
+- State conclusions, not reasoning: no mechanism walkthroughs, background, or
+  chained qualifiers unless asked. One decisive fact beats three hedges.
+- Say each point once: problem and fix in ONE compact statement, not a restated
+  pair. Prefer fewer, denser items over covering every nuance.
+- Size budget: roughly TWICE the Simple style — per point about 2 rendered
+  lines, whole report ~10–15 lines. Spend the extra room on evidence and
+  context Simple would drop, not on longer sentences.
 - Use labels such as `바뀐 점`, `확인한 것`, and `남은 리스크/다음 단계`
   in final reports to structure the summary; skip labels on interim progress.
 - Collapse trivial tasks to a couple of sentences instead of forcing sections.
 - Synthesize agent or retrieval results; never forward raw reports, long file
   lists, tool traces, or session metadata.
 - Do not hide blockers, failed verification, or required follow-up; surface them
-  explicitly rather than omitting them.
+  in one short clause.
 - Keep paths, commands, symbols, API names, code, and exact errors verbatim.
+
+Layout (hard rules)
+- One bullet or numbered item = one idea, at most 2 rendered lines including its
+  sub-bullet. If it needs more, cut the detail — do not add lines.
+- Open each item with a short **bold key point**, then the brief elaboration —
+  never bury the point mid-sentence.
+- Insert a blank line between numbered items, and between any list items running
+  past one line (loose list). Never emit a wall of consecutive multi-line items.
+- Keep paragraphs to ~3 lines max, with a blank line between paragraphs, lists,
+  and code blocks.
+- Nest at most one sub-level; deeper detail means you are over-explaining.
 - Never name this style unless asked.

package/src/output-styles/{oneline.md → extreme-minimal.md}

@@ -1,14 +1,15 @@
 ---
-name: oneline
-title: Oneline
+name: extreme-minimal
+title: Extreme Minimal
 description: Single sentence under 100 characters
-aliases: one-line, one line, mono
+aliases: extreme, oneline, one-line, one line, mono
 keep-coding-instructions: true
 ---
 
 # Output Style
 
-Oneline — the most minimal style: exactly one sentence, under 100 characters.
+Extreme minimal — the most compressed style: exactly one sentence, under 100
+characters.
 
 - Reply with a SINGLE sentence, always under 100 characters. Never a second
   sentence, clause pile-up, or run-on that smuggles in extra facts.

package/src/output-styles/minimal.md

@@ -2,7 +2,6 @@
 name: minimal
 title: Minimal
 description: One- or two-sentence summary
-aliases: extreme, extreme-simple
 keep-coding-instructions: true
 ---
 
@@ -12,12 +11,15 @@ Minimal — a very short summary: one or two sentences, nothing more.
 
 - Summarize only the net result in one short sentence; add a second short
   sentence only if a second fact (verification, blocker) genuinely needs it.
-  Never cram unrelated facts into one run-on line just to stay at one sentence.
-- Summarize, never itemize: do not describe which files changed or how they were
-  edited. State only what the change accomplishes.
+  Never cram unrelated facts into a run-on just to stay at one sentence.
+- Size budget: roughly HALF the Simple style — 1–2 plain sentences, ~2–3
+  rendered lines at most, however large the task was.
+- Compress by cutting content, not grammar: natural, complete sentences only.
+  Concept-level only — never walk through code or mechanisms.
+- Summarize, never itemize: do not describe which files changed or how. State
+  only what the change accomplishes.
 - No headings, bullets, numbered lists, labels, or sections — plain sentences
-  only. This holds even when the request says "report" or "summary"; keep it to
-  one or two sentences regardless.
+  only, even when the request says "report" or "summary".
 - Preferred pattern: `<target> 변경되었습니다. <verification> 통과 완료입니다.`
 - If verification was not run, say the change is done and verification was not
   run.

package/src/output-styles/simple.md

@@ -8,16 +8,30 @@ keep-coding-instructions: true
 
 # Output Style
 
-Practical concise — outcome-first handoffs for coding work: summarize the result,
-do not narrate the change.
+Practical concise — outcome-first handoffs for coding work: summarize the
+result, do not narrate or explain the change.
 
 - Open with the outcome in one sentence: done, blocked, or awaiting a decision.
+- Summarize at the concept level: name the behavior and direction, not the code
+  path. Cite a symbol/path only as an anchor, never as the explanation.
+- Compress by cutting content (filler, hedging, pleasantries, restated facts),
+  not by clipping grammar: keep natural, complete sentences in the user's
+  language — never telegraph-style stub endings. Technical terms and code stay
+  exact.
 - Summarize what the change accomplishes rather than listing every file and how
   each was edited. Name a path (`file_path:line_number`) only when the reader
   truly needs it to navigate — not as a per-file changelog.
-- Keep controlled detail: usually 1–3 short bullets or 2–4 sentences total. No
-  step-by-step narration, no exhaustive file/line inventory. Expand only when the
-  user asks, scope is ambiguous, or a blocker needs concrete next steps.
+- Keep controlled detail: usually 1–3 short bullets or 2–3 sentences total.
+  State each point once — outcome or fix direction, not both restated. No
+  step-by-step narration or file/line inventory.
+- Size budget: roughly HALF the Default style and TWICE Minimal — per point one
+  rendered line, whole reply ~5–7 lines. Above that you are writing Default;
+  below ~3 lines consider whether prose (Minimal) reads better.
+- Layout: one idea per bullet, ONE line each (two only when a verbatim
+  path/error forces it). Lead each item with a short bold key phrase. Put a
+  blank line between multi-line list items — never emit a dense wall of text.
+- If a point runs past one line, cut the elaboration instead of wrapping; detail
+  beyond the key phrase + one clause belongs to the Default style.
 - On final handoffs, optional labels such as `바뀐 점`, `확인한 것`, and
   `남은 리스크/다음 단계` fit Korean-facing profiles; use plain English labels
   when the thread is English. Do not label interim progress.
@@ -26,6 +40,6 @@ do not narrate the change.
 - Do not hide blockers, failed verification, or required follow-up; state them
   in one short clause.
 - Keep paths, commands, symbols, API names, code, and exact errors verbatim.
-- Skip filler, acknowledgments, and repeated conclusions; if verification was
-  not run, say so once.
+- Skip filler, acknowledgments, hedging, and repeated conclusions; if
+  verification was not run, say so once.
 - Never name this style unless asked.

package/src/rules/agent/00-common.md

@@ -3,15 +3,18 @@
 - Use English for agent task communication.
 - Do not touch git/Ship. Even when the brief instructs `git add` / `commit` /
   `push` / `stash`, refuse with `git operations deferred to Lead`.
-- NEVER PREAMBLE. Do not generate preamble tokens, including tool-call
-  preambles, status/progress narration, "I will..." setup text, or transition
-  text before tool calls.
+- NEVER PREAMBLE: no tool-call preambles, status/progress narration, "I
+  will..." setup, or transition text before tool calls.
 - If tools are needed, call them immediately. Emit text only for the final
   handoff after tool work is done.
 - Final handoff: minimum characters, maximum information for Lead. Follow the
   role's stricter output contract if defined; else emit fragments — outcome
   (1 line), key `file:line`(s), verification result, material risks (only if
   any).
+- Handoff cap ~30 lines unless `Deliver:` raises it. Overflow goes to a file;
+  hand off path + fragments.
 - Banned as pure cost: report headings, markdown tables (unless requested),
   prose narration, raw logs/tool traces, speculative next-checks, restated
   brief, articles/politeness.
+- Exception: a runtime wrap-up directive (exploration budget reached) overrides
+  this — then summarize done/remaining/blocking as instructed.

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

@@ -8,11 +8,22 @@ kind: retrieval
 
 You are a one-shot locator, not a researcher.
 
-Procedure: send ONE turn containing one `grep` (all synonyms in one
-`pattern:[...]`, output_mode content_with_context) plus one `code_graph`
-call. The results contain path:line — answer immediately from them.
-If both miss, answer `EXPLORATION_FAILED`. Do not send a second lookup turn.
+Find code anchors fast. Batch independent lookups in turn 1: one `grep`
+with all literal strings/errors/identifier guesses, plus `code_graph`/`find`
+or `glob` when useful.
+
+Prefer user-visible strings and identifiers. `dist`/generated hits are leads,
+not answers: trace them back to source. On miss, derive new tokens from
+returned paths/names or widen scope; do not repeat synonyms. NEVER issue
+serial single-tool turns: every turn after the first must batch ALL remaining
+candidate lookups in one shot.
+
+Budget: 4 tool turns. The FIRST credible `path:line` ends the search — answer
+with what you have; more anchors are not more value. Spend remaining turns
+only while you have zero anchors, and buy coverage with wider batches, never
+with extra serial turns. On ANY iteration warning, answer immediately with
+best anchors or `EXPLORATION_FAILED`.
 
 Answer format, nothing else:
-- up to 5 lines of `path:line — symbol/name — short reason` (append `?` if weak)
+- up to 5 lines: `path:line — symbol/name — short reason` (append `?` if weak)
 - or `EXPLORATION_FAILED`

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

@@ -1,11 +1,11 @@
 # General
 
 - Omit direct names, honorifics, headings, and labels in preambles.
-- Preambles are optional: use them only when they add user-visible value, keep
-  them to one short sentence, and skip routine lookup narration.
+- Preambles are optional: use only when they add user-visible value, keep to
+  one short sentence, skip routine lookup narration.
 - Destructive/hard-to-reverse actions require explicit confirmation.
 - Never push, build, or deploy without an explicit user request.
   Implementation approval is not deploy approval.
-- Rather than deferring checks or work to the user, proactively handle whatever
-  you can first, and propose only the parts that need a decision in a
-  consultative tone ("Shall we proceed this way?").
+- Proactively handle what you can first rather than deferring to the user;
+  propose only the parts needing a decision, consultatively ("Shall we
+  proceed this way?").

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

@@ -0,0 +1,15 @@
+# Lead Brief Contract
+
+- Brief = one-line fragments `Goal:` `Anchors:` `Allow/Forbid:` `Deliver:`
+  `Verify:` (+`Stop:` heavy-worker). No role-known rules, background, or
+  motivation — minimum characters, maximum information.
+- `Deliver:` states output size/shape (e.g. "fragments <=15 lines", "verdict
+  + top-3 risks", "detail to file, path only"). Never request a long report
+  in the handoff itself.
+- Full brief only on fresh spawn or `respawned: true` (dead-tag send = cold
+  session; re-supply anchors). Live-session follow-ups = delta only; never
+  restate Goal/rules.
+- Never `send` mid-run; batch all adjustments into ONE follow-up after
+  completion. Interrupt only to cancel.
+- All agent communication in English.
+- Referenced spec/test file beats its summary in the brief.

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

@@ -1,17 +1,8 @@
 # Lead Tool Use
 
-- Lead owns repo-local shell work: run git/build/test/verification commands via
-  `shell` directly; do not delegate them to agents.
-- Use the current project/workspace selected by the session. Only change the work project when the user asks for a different project or a tool call explicitly needs another project root.
-- Use `agent` for scoped implementation, research, review, and debugging, not for git commit/push/stash or Ship.
-- A `send` to a reaped/dead tag auto-respawns a FRESH session under the same
-  tag (result carries `respawned: true`). That worker has no prior session
-  context — treat the message as a cold brief and re-supply anchors
-  (`file:line`) on it or the next send.
-- Briefs: minimum characters, maximum information. Fixed one-line fragment
-  fields — `Goal:` `Anchors:` `Allow/Forbid:` `Deliver:` `Verify:` (+`Stop:` for
-  heavy-worker). Omit role-known rules (git/preamble bans, output format),
-  background, motivation; non-actionable tokens are wasted cost.
-- Bridge language is ALWAYS English: every brief, follow-up `send`, and
-  steering message to an agent is written in English regardless of the
-  user-facing language.
+- Lead owns repo-local shell work: run git/build/test/verification via `shell`
+  directly; do not delegate to agents.
+- 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
+  for git commit/push/stash or Ship.

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

@@ -1,25 +1,21 @@
 # Tool Use
 
-- Independent lookups MUST batch in one turn; serialize only when a call needs
-  a prior result. This includes edit loops: batch the post-edit verification
-  read with the next target's lookup instead of emitting single-call turns.
-- Target validity comes first: symbols/callers/deps → `code_graph`; exact text in
-  a verified scope → `grep`; unknown path/name → `find`; structure → `glob`;
-  dirs → `list`; verified file → `read`; broad unknown with no anchor →
-  `explore`. Never call `grep`/`read` on guessed paths.
-- Concept normalization comes first: one concept gets one batched
-  `grep pattern:[...]` with `output_mode:"content_with_context"` (or one
-  `code_graph symbols[]`). Refine from returned paths; do not repeat equivalent
-  patterns or scopes.
+- 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`; unknown path/name → `find`; structure → `glob`; dirs →
+  `list`; verified file → `read`; broad unknown with no anchor → `explore`.
+  Never `grep`/`read` guessed paths.
+- One concept → one batched `grep pattern:[...]` with
+  `output_mode:"content_with_context"` (or one `code_graph symbols[]`). Refine
+  from returned paths; never repeat equivalent patterns or scopes.
 - On miss/error, normalize the target once and switch tool; on a plausible hit,
-  stop searching and answer from the framed context.
-- Lookup budget: retrieval exists to reach the NEXT action (edit, answer,
-  handoff), not to build certainty. One anchor is enough to act on; re-reading
-  or re-grepping an area you already saw this session is waste. When acting
-  and looking are both possible, act.
-- Avoid read fragmentation: `read` uses `offset`/`limit` only. If you need 2+
-  spans from one or more known files, make one batched `read` call with
-  `{path,offset,limit}` region objects instead of serial reads. Adjacent spans
-  in the same file (within a few hundred lines) are ONE window, not repeated
-  reads.
+  stop and answer from the framed context.
+- Retrieval serves the NEXT action (edit, answer, handoff), not certainty. One
+  anchor is enough to act on; re-reading/re-grepping an area seen this session
+  is waste. When acting and looking are both possible, act.
+- `read` uses `offset`/`limit` only. For 2+ spans from known file(s), make one
+  batched `read` with `{path,offset,limit}` region objects. Adjacent spans in
+  one file (within a few hundred lines) are ONE window, not repeated reads.
 - Don't mix `apply_patch` with shell or other state-changing calls in one turn.

package/src/runtime/agent/orchestrator/agent-runtime/agent-dispatch.mjs

@@ -356,6 +356,10 @@ export function makeAgentDispatch(opts = {}) {
         if (_idleController) {
             try { _linkSignal(session.id, _idleController.signal); } catch { /* ignore */ }
         }
+        // Watchdog blind spot guard: when the runtime snapshot is missing AND
+        // no progress timestamp exists (pre-liveness hang, swept runtime), the
+        // dispatch start time anchors staleness so the abort still fires.
+        const _watchdogAnchorTs = Date.now();
         const _idleTimer = (_idleController && (typeof _getProgressSnapshot === 'function' || typeof _getLastProgressAt === 'function'))
             ? setInterval(() => {
                 const now = Date.now();
@@ -363,9 +367,10 @@ export function makeAgentDispatch(opts = {}) {
                 const abortErr = snapshot
                     ? evaluateAgentWatchdogAbort(snapshot, now, _watchdogPolicy)
                     : null;
-                if (!abortErr && !snapshot && typeof _getLastProgressAt === 'function') {
-                    const last = _getLastProgressAt(session.id);
-                    if (_watchdogPolicy.idleStaleMs > 0 && last && now - last > _watchdogPolicy.idleStaleMs) {
+                if (!abortErr && !snapshot) {
+                    const reported = typeof _getLastProgressAt === 'function' ? _getLastProgressAt(session.id) : 0;
+                    const last = reported || _watchdogAnchorTs;
+                    if (_watchdogPolicy.idleStaleMs > 0 && now - last > _watchdogPolicy.idleStaleMs) {
                         try { _idleController.abort(new Error(`agent task stale (${_watchdogPolicy.idleStaleMs}ms without progress)`)); } catch { /* ignore */ }
                     }
                     return;

package/src/runtime/agent/orchestrator/agent-runtime/agent-loop-policy.mjs

@@ -17,6 +17,31 @@ function envPositiveInt(name, fallback) {
 // to raise/lower the safety ceiling, never used as a per-agent task budget.
 export const LEAD_MAX_LOOP_ITERATIONS = envPositiveInt('MIXDOG_AGENT_MAX_LOOP', 200);
 
+// Worker soft cap — behavior-based ONLY. There is intentionally no fixed
+// iteration threshold: a legitimately long worker task (many edit/verify
+// rounds) must never be cut off by a count. The wrap-up is armed exclusively
+// by the steering ladder's early-cap signal (repeated ignored level-2 steers
+// with zero edits = confirmed read-only stall), after the ladder's own
+// warnings have gone out. The env knob remains as an opt-in count for
+// operators who want one; by default it is effectively disabled.
+export const WORKER_SOFT_CAP_ITERATIONS = envPositiveInt('MIXDOG_AGENT_SOFT_CAP', Number.MAX_SAFE_INTEGER);
+
+// Agents subject to the soft cap: implementation workers that should wrap up
+// once the exploration budget is spent. Reviewer and hidden long-runner agents
+// (explorer / cycle / scheduler / …) are legitimately read-only long-running
+// and are EXEMPT — capping them would truncate a valid long read pass.
+const SOFT_CAP_AGENTS = new Set(['worker', 'heavy-worker', 'maintainer', 'debugger']);
+
+/**
+ * Is this session a delegated worker subject to the soft cap?
+ * Only worker/heavy-worker/maintainer/debugger. Lead, TUI (no agent),
+ * reviewer, and hidden agents return false.
+ */
+export function isWorkerSoftCapSession(sessionRef) {
+    const agent = sessionRef?.agent;
+    return typeof agent === 'string' && SOFT_CAP_AGENTS.has(agent);
+}
+
 /**
  * Resolve the hard cap used by agentLoop for this session.
  *

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

@@ -10,7 +10,8 @@
  *   BP_1  system#1  (1h)  — shared tool policy + compact skill manifest
  *   BP_2  system#2  (1h)  — role/system rules (Lead / agent / hidden role)
  *   BP_3  system#3  (1h)  — stable memory/meta marker (sessionMarker system block; tier3)
- *   BP_4  messages  (5m)  — sliding tool_result / prior user-text tail
+ *   BP_4  messages  (5m agents/hidden; Lead linked to autoClear — see below) —
+ *         sliding tool_result / prior user-text tail
  *
  * Tool schemas still sit before system in the provider prompt prefix. We do
  * not spend a separate cache_control slot on tools; the first system BP covers
@@ -51,10 +52,14 @@ import { getHiddenAgent } from '../internal-agents.mjs';
  */
 function isOneShotMaintenanceAgent(agent) {
     const hidden = getHiddenAgent(agent);
+    // Shipped cycle1/2/3 declare toolSchemaProfile:'none' (no tool schema at
+    // all); 'llm-only' is the legacy alias for the same one-shot LLM-only
+    // pattern. Multi-turn maintenance roles (scheduler-task/webhook-handler)
+    // are 'read-write-search' and stay excluded.
     return Boolean(
         hidden
         && hidden.kind === 'maintenance'
-        && hidden.toolSchemaProfile === 'llm-only',
+        && (hidden.toolSchemaProfile === 'llm-only' || hidden.toolSchemaProfile === 'none'),
     );
 }
 
@@ -71,8 +76,16 @@ function isOneShotMaintenanceAgent(agent) {
  * warm window survives per-session gaps. The volatile message tail (BP4) is
  * per-session and trace data (2026-06) shows request gaps are p99 ≈ 4.5min —
  * 5m+ gaps mean a cold tail anyway, and the smart-compact path rebuilds the
- * history at that boundary. So every session's tail uses the cheaper 5m TTL
- * (1.25x write vs 2x), aligned with the 5m terminal-reap window for agents.
+ * history at that boundary. So hidden-agent and public-agent sessions keep
+ * the cheaper 5m tail TTL (1.25x write vs 2x), aligned with the 5m
+ * terminal-reap window for agents.
+ *
+ * Lead sessions are linked to the user's autoClear idle-sweep config
+ * instead of the fixed 5m default (see resolveLeadMessagesTtl): a Lead
+ * session that autoClear will only reap after a long/never idle window
+ * benefits from the 1h tail TTL (fewer writes over a long-lived session),
+ * while a short idle-sweep window means the tail is going cold anyway and
+ * 5m is cheaper to write.
  * (Tail TTL only affects explicit-breakpoint providers — Anthropic; no-op
  * elsewhere.)
  *
@@ -84,15 +97,41 @@ function isOneShotMaintenanceAgent(agent) {
  * the 1h TTL expiry (writes every run, 0 reads). All layers go 'none' for
  * these roles — single-iteration calls pay the write premium with no reuse.
  */
-export function resolveCacheStrategy(agent) {
+
+/**
+ * Lead-session BP4 (messages tail) TTL, linked to the autoClear idle-sweep
+ * config (config.mjs `autoClear: { enabled, idleMs }`, normalized via
+ * session-runtime/config-helpers.mjs normalizeAutoClearConfig):
+ *   - autoClear disabled                → '1h' (session may live indefinitely;
+ *     amortize the 2x write premium over a long-lived tail)
+ *   - idleMs >= 1h (3_600_000ms)        → '1h' (idle-sweep window is at least
+ *     as long as the 1h TTL, so the longer TTL is never wasted)
+ *   - otherwise (shorter idle-sweep)    → '5m' (session reaps before a 1h
+ *     write would ever be re-read; cheaper 5m write wins)
+ */
+export function resolveLeadMessagesTtl(autoClear) {
+    if (autoClear && autoClear.enabled === false) return '1h';
+    const idleMs = Number(autoClear?.idleMs);
+    if (Number.isFinite(idleMs) && idleMs >= 3_600_000) return '1h';
+    return '5m';
+}
+
+export function resolveCacheStrategy(agent, { autoClear } = {}) {
     if (isOneShotMaintenanceAgent(agent)) {
         return { tools: 'none', system: 'none', tier3: 'none', messages: 'none' };
     }
     if (getHiddenAgent(agent)) {
         return { tools: 'none', system: '1h', tier3: '1h', messages: '5m' };
     }
-    // Lead + public agents: per-session volatile tail -> 5m (see doc above).
-    return { tools: 'none', system: '1h', tier3: '1h', messages: '5m' };
+    if (agent && agent !== 'lead') {
+        // Public (non-hidden, non-lead) agents keep the flat 5m tail — only
+        // the Lead session's tail is linked to autoClear.
+        return { tools: 'none', system: '1h', tier3: '1h', messages: '5m' };
+    }
+    // Lead session (agent === 'lead', or no agent — raw/CLI callers default
+    // to Lead behavior): message tail TTL is linked to autoClear (see
+    // resolveLeadMessagesTtl).
+    return { tools: 'none', system: '1h', tier3: '1h', messages: resolveLeadMessagesTtl(autoClear) };
 }
 
 /**
@@ -200,6 +239,25 @@ function normalizePromptCacheNamespace(value) {
     return s.replace(/[^A-Za-z0-9_-]+/g, '-').replace(/^-+|-+$/g, '') || 'mixdog-shared';
 }
 
+function fitPromptCacheKey(value, fallback = 'mixdog-shared') {
+    const s = normalizePromptCacheNamespace(value || fallback);
+    if (s.length <= 64) return s;
+    const hash = shortHash(s, 12);
+    const head = s.slice(0, Math.max(1, 64 - hash.length - 1));
+    return `${head}-${hash}`;
+}
+
+function codexThreadPromptCacheKey(opts, namespace) {
+    const explicit = cleanString(opts?.providerCacheKey)
+        || cleanString(opts?.promptCacheKey)
+        || cleanString(opts?.session?.promptCacheKey);
+    if (process.env.MIXDOG_OAI_CACHE_KEY_SHARED === '1') {
+        return fitPromptCacheKey(explicit || namespace, 'mixdog-codex');
+    }
+    const sessionKey = cleanString(opts?.sessionId || opts?.session?.id);
+    return fitPromptCacheKey(sessionKey || explicit || namespace, namespace);
+}
+
 function summarizePromptCacheTools(tools) {
     return (tools || []).map(t => ({
         type: cleanString(t?.type) || 'function',
@@ -211,13 +269,19 @@ function summarizePromptCacheTools(tools) {
 
 /**
  * Build a stable, prefix-scoped prompt_cache_key for OpenAI-style key-prefix
- * providers. The base namespace still comes from resolveProviderCacheKey()
- * (so overrides keep working), but a model/system/tools hash is appended so
- * unrelated main/worker prefixes do not evict each other inside one shared
- * provider lane.
+ * providers. OpenAI OAuth follows Codex's 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
+ * explicit cache-lane override opts into it.
  */
 export function buildStableProviderPromptCacheKey(provider, opts, prefix = {}) {
     const namespace = normalizePromptCacheNamespace(resolveProviderCacheKey(opts, provider));
+    if (provider === 'openai-oauth'
+        && process.env.MIXDOG_OAI_CODEX_THREAD_CACHE_KEY !== '0'
+        && String(process.env.MIXDOG_OAI_CODEX_THREAD_CACHE_KEY || '').toLowerCase() !== 'false') {
+        return codexThreadPromptCacheKey(opts, namespace);
+    }
     const rawShards = prefix.cacheLaneShards ?? opts?.promptCacheLane?.shards ?? opts?.cacheLaneShards;
     const rawShardMode = String(rawShards ?? '').trim().toLowerCase();
     const autoLane = prefix.cacheLaneAuto === true
@@ -243,6 +307,16 @@ export function buildStableProviderPromptCacheKey(provider, opts, prefix = {}) {
         parallelToolCalls: prefix.parallelToolCalls === false ? false : true,
         cacheLaneSlot: laneEnabled ? shardSlot : null,
         cacheLaneShards: autoLane ? 'auto' : shardCount > 1 ? shardCount : null,
+        // Per-session cache-key isolation. R8 A/B (2026-07-03) showed parallel
+        // sessions sharing one prompt_cache_key evict each other's transcript
+        // body on the server cache node (same key -> same node; bodies differ),
+        // producing 8-23% genuine mid-session misses at tens of thousands of
+        // uncached tokens each. Mixing sessionId in costs only the small static
+        // prefix hit (~2-4k tokens) on a session's FIRST call — every later
+        // call's body cache is protected. Opt out: MIXDOG_OAI_CACHE_KEY_SHARED=1.
+        session: process.env.MIXDOG_OAI_CACHE_KEY_SHARED === '1'
+            ? null
+            : cleanString(opts?.sessionId || opts?.session?.id || '') || null,
     };
     const hash = shortHash(seed);
     const head = namespace.slice(0, Math.max(1, 64 - hash.length - laneSuffix.length - 1));
@@ -255,7 +329,7 @@ function providerEnvKey(provider) {
 
 const providerPromptCacheLaneAssignments = new Map();
 const PROVIDER_PROMPT_CACHE_LANE_MAX_ASSIGNMENTS = 4096;
-const DEFAULT_PROVIDER_PROMPT_CACHE_LANE_SHARDS = 12;
+const DEFAULT_PROVIDER_PROMPT_CACHE_LANE_SHARDS = 1;
 
 function promptCacheLaneGroupKey(provider, opts) {
     return [
@@ -282,6 +356,10 @@ function parsePromptCacheLaneLimit(raw, fallback = DEFAULT_PROVIDER_PROMPT_CACHE
     return Math.floor(n);
 }
 
+function defaultPromptCacheLaneShards(_provider) {
+    return DEFAULT_PROVIDER_PROMPT_CACHE_LANE_SHARDS;
+}
+
 function assignPromptCacheLaneSlot(provider, opts, shards, seed, { auto = false } = {}) {
     const explicit = opts?.promptCacheLaneSlot ?? opts?.cacheLaneSlot;
     const explicitSlot = Number(explicit);
@@ -308,14 +386,9 @@ function assignPromptCacheLaneSlot(provider, opts, shards, seed, { auto = false
 }
 
 /**
- * Resolve a stable cache-lane slot for OpenAI-style prompt cache sharding.
- * The shard count is the maximum same-prefix parallelism; each final shard key
- * is still internally queued and rate-shaped by the transport for stable server
- * cache hits. OpenAI's prompt caching guide says one prefix+prompt_cache_key
- * combination can overflow around 15 RPM, so transport owns that timing gate.
- * Default to the safer 12-lane pool. Explicit 0/auto/unbounded keeps the
- * no-cap execution mode for callers that prefer throughput over stricter
- * same-key serialization.
+ * 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
+ * one un-suffixed key unless an env/config override opts into shards.
  */
 export function resolveProviderPromptCacheLane(provider, opts = {}, config = {}) {
     const envKey = providerEnvKey(provider);
@@ -338,7 +411,7 @@ export function resolveProviderPromptCacheLane(provider, opts = {}, config = {})
             ?? env[`MIXDOG_${envKey}_CACHE_MAX_PARALLEL`]
             ?? env.MIXDOG_OPENAI_CACHE_LANE_SHARDS
             ?? env.MIXDOG_OPENAI_CACHE_MAX_PARALLEL);
-    const shards = parsePromptCacheLaneLimit(rawLimit, DEFAULT_PROVIDER_PROMPT_CACHE_LANE_SHARDS);
+    const shards = parsePromptCacheLaneLimit(rawLimit, defaultPromptCacheLaneShards(provider));
     const auto = shards <= 0;
     const seed = cleanString(
         opts?.promptCacheLaneSeed
@@ -359,8 +432,8 @@ export function resolveProviderPromptCacheLane(provider, opts = {}, config = {})
     };
 }
 
-export function buildProviderCacheOpts(provider, sessionId, agent) {
-    const ttls = resolveCacheStrategy(agent);
+export function buildProviderCacheOpts(provider, sessionId, agent, options = {}) {
+    const ttls = resolveCacheStrategy(agent, options);
     const capability = cacheCapabilityForProvider(provider);
     if (capability === 'explicit-breakpoint') {
         // 2026-03-06 Anthropic dropped default TTL 1h→5m. We send
@@ -368,6 +441,10 @@ export function buildProviderCacheOpts(provider, sessionId, agent) {
         // Verified 2026-04-17 (ephemeral_1h_input_tokens=4722).
         return { cacheStrategy: ttls };
     }
+    // NOTE: createSession's direct-call site (manager.mjs) only invokes this
+    // for explicit-breakpoint (Anthropic-family) providers, so this branch
+    // stays reachable only from other callers (none in-tree today) — keeping
+    // it here preserves the documented public API/behavior of this function.
     if (provider === 'openai') {
         // Public OpenAI API: prompt_cache_retention extends prefix retention.
         // openai-oauth rejects the header — falls through to default.