mixdog 0.9.37 → 0.9.38

package/src/runtime/agent/orchestrator/session/store.mjs

@@ -256,7 +256,16 @@ function _flushScheduled(id) {
 // Single long-lived Worker serializes all saveSessionAsync calls.
 // The worker's message queue preserves generation-race ordering.
 let _saveWorker = null;
-let _saveWorkerPending = new Map(); // reqId → { resolve, reject, session, opts }
+// In-flight writes, keyed by reqId. Value: { id, session, opts, waiters:[{resolve,reject}] }.
+// At most ONE entry per session id at a time (single-in-flight-per-id).
+let _saveWorkerPending = new Map();
+// Latest-wins queued payload per session, keyed by id. Value: { session, opts, waiters:[] }.
+// At most ONE queued write per id: a newer saveSessionAsync while a write is in
+// flight overwrites session/opts here and appends its resolver to waiters, so
+// every superseded caller resolves when this single queued write finally lands.
+let _saveAsyncQueued = new Map();
+// id → reqId of the in-flight write for that id (enforces one-in-flight-per-id).
+let _saveAsyncInflight = new Map();
 let _saveWorkerReqId = 0;
 let _saveWorkerRefCount = 0;
 
@@ -273,12 +282,37 @@ function _getOrSpawnWorker() {
         // becomes unref'd again once all in-flight writes settle. _saveWorker
         // null-check covers the error/exit race where the worker died first.
         if (--_saveWorkerRefCount === 0 && _saveWorker) _saveWorker.unref();
-        if (ok) p.resolve();
-        else p.reject(new Error(`[session-store] worker save failed: ${error}`));
+        const { id, waiters } = p;
+        _saveAsyncInflight.delete(id);
+        // Resolve/reject every caller whose payload this write represents
+        // (the originating call plus any that coalesced onto it before it was
+        // posted). A supersede never lands here as a rejection — only a real
+        // worker failure does.
+        if (ok) { for (const w of waiters) w.resolve(); }
+        else {
+            const e = new Error(`[session-store] worker save failed: ${error}`);
+            for (const w of waiters) w.reject(e);
+        }
+        // Promote the latest-wins queued payload (if any) into the now-free
+        // in-flight slot for this id. Runs regardless of ok: the queued write
+        // is a newer, independent payload and must still be attempted so its
+        // (possibly superseded) waiters resolve when it lands.
+        const q = _saveAsyncQueued.get(id);
+        if (q) {
+            _saveAsyncQueued.delete(id);
+            try {
+                _postAsyncWrite(id, q.session, q.opts, q.waiters);
+            } catch (err) {
+                for (const w of q.waiters) w.reject(err);
+            }
+        }
     });
     _saveWorker.on('error', (err) => {
-        for (const [, p] of _saveWorkerPending) p.reject(err);
+        for (const [, p] of _saveWorkerPending) for (const w of p.waiters) w.reject(err);
         _saveWorkerPending.clear();
+        for (const [, q] of _saveAsyncQueued) for (const w of q.waiters) w.reject(err);
+        _saveAsyncQueued.clear();
+        _saveAsyncInflight.clear();
         _saveWorkerRefCount = 0;
         _saveWorker = null;
     });
@@ -290,8 +324,11 @@ function _getOrSpawnWorker() {
         // saveSessionAsync registered a resolver but before the worker
         // received the message.
         const err = new Error(`[session-store] save worker exited with code ${code}`);
-        for (const [, p] of _saveWorkerPending) p.reject(err);
+        for (const [, p] of _saveWorkerPending) for (const w of p.waiters) w.reject(err);
         _saveWorkerPending.clear();
+        for (const [, q] of _saveAsyncQueued) for (const w of q.waiters) w.reject(err);
+        _saveAsyncQueued.clear();
+        _saveAsyncInflight.clear();
         _saveWorkerRefCount = 0;
         _saveWorker = null;
     });
@@ -299,14 +336,45 @@ function _getOrSpawnWorker() {
     return _saveWorker;
 }
 
+/**
+ * Post one in-flight write for `id` to the worker and register it as the
+ * single in-flight entry for that id. Callers guarantee no write is already
+ * in flight for `id`. Throws (after cleaning its own map entries) if the
+ * worker postMessage fails so the caller can reject the affected waiters.
+ */
+function _postAsyncWrite(id, session, opts, waiters) {
+    const reqId = ++_saveWorkerReqId;
+    _saveWorkerPending.set(reqId, { id, session, opts, waiters });
+    _saveAsyncInflight.set(id, reqId);
+    try {
+        const w = _getOrSpawnWorker();
+        w.postMessage({ session, opts, reqId });
+        // Ref AFTER successful postMessage so a queue/throw failure path does
+        // not leave the worker held alive with no pending message. Paired with
+        // the unref in the message handler when count hits 0.
+        if (++_saveWorkerRefCount === 1) w.ref();
+    } catch (err) {
+        _saveWorkerPending.delete(reqId);
+        _saveAsyncInflight.delete(id);
+        throw err;
+    }
+}
+
 /**
  * Async save via a dedicated Worker thread.
  * Errors surface as thrown Errors — callers must not silently swallow them.
+ *
+ * Per-session latest-wins coalescing: for a given id there is at most one
+ * write in flight plus one queued follow-up. N rapid saves for the same id in
+ * a turn collapse to (in-flight + one queued-latest), keeping the single
+ * worker's backlog bounded. Per-id write ORDERING is preserved (a queued write
+ * is only posted once the prior in-flight write for that id settles); different
+ * ids interleave freely as before.
  */
 export function saveSessionAsync(session, opts) {
     _ensureLifecycleFields(session);
     setLiveSession(session);
-    const reqId = ++_saveWorkerReqId;
+    const id = session.id;
     const safeOpts = opts || null;
     // The Worker `postMessage` below structured-clones the whole session on the
     // main thread. `session.liveTurnMessages` (live working transcript) and
@@ -322,18 +390,28 @@ export function saveSessionAsync(session, opts) {
         ? (() => { const { liveTurnMessages: _dropLTM, toolApprovalHook: _dropTAH, ...rest } = session; return rest; })()
         : session;
     return new Promise((resolve, reject) => {
-        // Persist {session, opts} so drainSessionStore can sync-flush
-        // outstanding writes if process exit interrupts the worker queue.
-        _saveWorkerPending.set(reqId, { resolve, reject, session: clonePayload, opts: safeOpts });
+        const waiter = { resolve, reject };
+        if (_saveAsyncInflight.has(id)) {
+            // A write is already on disk for this id — coalesce into the single
+            // latest-wins queued slot. Existing queued waiters carry over so a
+            // superseded caller resolves when THIS newer write lands (never
+            // hang, never reject on supersede).
+            const q = _saveAsyncQueued.get(id);
+            if (q) {
+                q.session = clonePayload;
+                q.opts = safeOpts;
+                q.waiters.push(waiter);
+            } else {
+                _saveAsyncQueued.set(id, { session: clonePayload, opts: safeOpts, waiters: [waiter] });
+            }
+            return;
+        }
+        // Idle for this id — post immediately as the in-flight write. The
+        // in-flight entry persists {session, opts} so drainSessionStore can
+        // sync-flush outstanding writes if process exit interrupts the queue.
         try {
-            const w = _getOrSpawnWorker();
-            w.postMessage({ session: clonePayload, opts: safeOpts, reqId });
-            // Ref AFTER successful postMessage so a queue/throw failure path
-            // does not leave the worker held alive with no pending message.
-            // Paired with the unref in the message handler when count hits 0.
-            if (++_saveWorkerRefCount === 1) w.ref();
+            _postAsyncWrite(id, clonePayload, safeOpts, [waiter]);
         } catch (err) {
-            _saveWorkerPending.delete(reqId);
             reject(err);
         }
     });
@@ -431,18 +509,35 @@ export function drainSessionStore() {
     // is sync-flushed directly here. The Promise is then rejected so the
     // caller's await site does not leak unresolved (caller is at process
     // exit so the rejection is informational, not actionable).
+    const _drainErr = new Error('[session-store] drain: worker-queue interrupted by process exit');
+    // Flush in-flight writes FIRST, then the latest-wins queued payloads, so
+    // for any id with both an in-flight and a queued write the queued (newest)
+    // state is written LAST and wins on disk — no lost last write.
     for (const [, pending] of _saveWorkerPending) {
-        if (!pending.session) continue;
+        if (pending.session) {
+            try {
+                _saveSessionSync(pending.session, pending.opts);
+            } catch (err) {
+                process.stderr.write(`[session-store] drain worker-queue save failed: ${err?.message}\n`);
+            }
+        }
+        for (const w of pending.waiters) {
+            try { w.reject(_drainErr); } catch { /* best-effort */ }
+        }
+    }
+    for (const [, q] of _saveAsyncQueued) {
         try {
-            _saveSessionSync(pending.session, pending.opts);
+            _saveSessionSync(q.session, q.opts);
         } catch (err) {
             process.stderr.write(`[session-store] drain worker-queue save failed: ${err?.message}\n`);
         }
-        try {
-            pending.reject(new Error('[session-store] drain: worker-queue interrupted by process exit'));
-        } catch { /* best-effort */ }
+        for (const w of q.waiters) {
+            try { w.reject(_drainErr); } catch { /* best-effort */ }
+        }
     }
     _saveWorkerPending.clear();
+    _saveAsyncQueued.clear();
+    _saveAsyncInflight.clear();
     _saveWorkerRefCount = 0;
 }
 

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

@@ -191,6 +191,43 @@ export const PROVIDER_WS_ACQUIRE_TIMEOUT_MS = resolveTimeoutMs(
     { minMs: 5_000, maxMs: PROVIDER_MAX_BEFORE_WARN_MS },
 );
 
+// WS pool liveness (ping/pong) — closes the gap between a socket going
+// half-open (peer gone / TLS wedge) and the semantic-idle watchdog noticing
+// (120s). Node `ws` send() is fire-and-forget, so a dead pooled socket
+// silently blackholes response.create frames until a downstream timeout. An
+// idle pooled socket is pinged on this cadence; a reused socket that has been
+// quiet longer than the stale window is ping-probed before hand-out.
+// Gated OFF by default for codex/opencode parity — neither pings model
+// sockets. Enable with MIXDOG_PROVIDER_WS_PING_ENABLED=1. When disabled, no
+// liveness interval is armed and the acquire-reuse ping probe is skipped (the
+// non-OPEN eviction scan still runs); lastAliveAt stamping is harmless.
+const _wsPingRaw = process.env.MIXDOG_PROVIDER_WS_PING_ENABLED;
+export const PROVIDER_WS_PING_ENABLED = _wsPingRaw === '1' || _wsPingRaw === 'true' || _wsPingRaw === 'yes';
+
+export const PROVIDER_WS_PING_INTERVAL_MS = resolveTimeoutMs(
+    'MIXDOG_PROVIDER_WS_PING_INTERVAL_MS',
+    30_000,
+    { minMs: 5_000, maxMs: PROVIDER_MAX_BEFORE_WARN_MS },
+);
+
+// Missed-pong grace: after a ping, the pong must land within this bound or the
+// socket is treated as dead (closed + evicted). Doubles as the short probe
+// bound on the acquire-reuse path so a busy caller is never handed a wedged
+// socket.
+export const PROVIDER_WS_PONG_TIMEOUT_MS = resolveTimeoutMs(
+    'MIXDOG_PROVIDER_WS_PONG_TIMEOUT_MS',
+    5_000,
+    { minMs: 1_000, maxMs: 60_000 },
+);
+
+// Activity freshness window: a pooled socket with observed activity (pong /
+// release) newer than this is assumed live and skips the acquire-reuse probe.
+export const PROVIDER_WS_LIVENESS_STALE_MS = resolveTimeoutMs(
+    'MIXDOG_PROVIDER_WS_LIVENESS_STALE_MS',
+    30_000,
+    { minMs: 5_000, maxMs: PROVIDER_MAX_BEFORE_WARN_MS },
+);
+
 // Single inter-chunk idle timer (300s), matching the upstream WS provider's
 // default stream idle timeout. Mixdog resets one idle timer on every received
 // WS frame (openai-oauth-ws messageHandler resets on every parsed event). There

package/src/runtime/agent/orchestrator/tools/builtin/builtin-tools.mjs

@@ -39,7 +39,7 @@ export const BUILTIN_TOOLS = [
         name: 'read',
         title: 'Mixdog Read',
         annotations: { title: 'Mixdog Read', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false, compressible: false },
-        description: 'Read verified file path(s). Unknown path → find first. Batch paths/regions as real arrays in one call. Not for directory listing.',
+        description: 'Read verified file path(s); guessed path → find first (same turn as other probes). Batch paths/regions as real arrays in one call. Not for directory listing.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -109,7 +109,7 @@ export const BUILTIN_TOOLS = [
         name: 'grep',
         title: 'Mixdog Grep',
         annotations: { title: 'Mixdog Grep', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false, compressible: true },
-        description: 'Exact text/regex in verified scope. Unknown path/name → find first; no path "." + guessed src/**. Broad: files_with_matches/count; narrow: content_with_context.',
+        description: 'Exact text/regex in verified scope (project root counts as verified — unscoped search needs no find). Only a guessed path fragment → find first, same turn. No path "." + guessed src/**. Broad: files_with_matches/count; narrow: content_with_context.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -125,7 +125,7 @@ export const BUILTIN_TOOLS = [
                         { type: 'string' },
                         { type: 'array', items: { type: 'string' }, minItems: 1 },
                     ],
-                    description: 'Verified file/dir only; unknown → find first.',
+                    description: 'Verified file/dir, or project root; guessed → find first.',
                 },
                 glob: {
                     anyOf: [
@@ -148,7 +148,7 @@ export const BUILTIN_TOOLS = [
         name: 'glob',
         title: 'Mixdog Glob',
         annotations: { title: 'Mixdog Glob', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false, compressible: true },
-        description: 'Exact glob from verified roots. Unknown root/name → find first; no path "." + guessed src/**. Batch arrays.',
+        description: 'Exact glob from verified roots (project root is verified). Guessed root/name → find first, same turn. No path "." + guessed src/**. Batch arrays.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -164,7 +164,7 @@ export const BUILTIN_TOOLS = [
                         { type: 'string' },
                         { type: 'array', items: { type: 'string' }, minItems: 1 },
                     ],
-                    description: 'Verified base dir(s); unknown → find first. Batch path[].',
+                    description: 'Verified base dir(s) or project root; guessed → find first. Batch path[].',
                 },
                 head_limit: { type: 'number', description: 'Max entries.' },
                 offset: { type: 'number', description: 'Skip entries.' },
@@ -197,7 +197,7 @@ export const BUILTIN_TOOLS = [
         name: 'list',
         title: 'Mixdog List Directory',
         annotations: { title: 'Mixdog List Directory', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false, compressible: true },
-        description: 'List verified directories. Unknown dir → find first. Batch dirs as path[].',
+        description: 'List verified directories (project root included). Guessed dir → find first. Batch dirs as path[].',
         inputSchema: {
             type: 'object',
             properties: {

package/src/runtime/agent/orchestrator/tools/code-graph-tool-defs.mjs

@@ -3,7 +3,7 @@ export const CODE_GRAPH_TOOL_DEFS = [
     name: 'code_graph',
     title: 'Code Graph',
     annotations: { title: 'Code Graph', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false, compressible: false, compressibleLossless: true },
-    description: 'Repo-local code structure/flow lookup (not web): symbols/references/calls/deps. Known symbols or verified files only. Batch symbols[]/files[].',
+    description: 'Repo-local code structure/flow lookup (not web): symbols/references/calls/deps. Symbols by name need no pre-verification; files[] must be verified paths. Batch symbols[]/files[].',
     inputSchema: {
       type: 'object',
       properties: {

package/src/session-runtime/provider-models.mjs

@@ -277,13 +277,13 @@ export function createProviderModels({
     return providerModelsFromCacheRows(await caches.providerModelsPromise);
   }
 
-  function warmProviderModelCache() {
+  function warmProviderModelCache({ loadSecrets = false } = {}) {
     if (Array.isArray(caches.providerModelsCache.models) || caches.providerModelsPromise) return caches.providerModelsPromise;
     profile('warm:start');
     const seq = ++caches.providerModelsLoadSeq;
-    caches.providerModelsPromise = loadProviderModelsFresh({ loadSecrets: false })
+    caches.providerModelsPromise = loadProviderModelsFresh({ loadSecrets })
       .then((models) => {
-        if (seq === caches.providerModelsLoadSeq && shouldAdoptProviderModelCache(models, { loadSecrets: false })) {
+        if (seq === caches.providerModelsLoadSeq && shouldAdoptProviderModelCache(models, { loadSecrets })) {
           caches.providerModelsCache = { models, at: Date.now() };
         }
         bootProfile('provider-models:warm-ready', { count: models.length });

package/src/session-runtime/runtime-core.mjs

@@ -306,6 +306,26 @@ export function __saveModelSettingsForTest(cfgMod, route, options = {}) {
   return saveModelSettings(cfgMod, route, options);
 }
 
+// Decide whether notifyFnForSession should mirror a terminal tool completion
+// into the pending-message queue. Only the TUI execution-ui path actually
+// injects the model-visible twin of the completion into the active loop, and it
+// signals that with an EXPLICIT ack (modelVisibleDelivered) — never a generic
+// truthy onNotification return. Skipping the mirror on a bare `handled===true`
+// would let a display-only / API listener suppress the sole model-visible copy,
+// so the model would never see the completion body. Mirror UNLESS the body was
+// explicitly delivered; unknown/generic-handled → keep the mirror.
+export function shouldMirrorCompletionToPendingQueue({
+  callerSessionId,
+  modelVisibleDelivered,
+  hasEnqueue,
+  text,
+  meta = {},
+} = {}) {
+  if (!callerSessionId || !hasEnqueue) return false;
+  if (modelVisibleDelivered) return false;
+  return shouldPersistModelVisibleToolCompletion(text, meta);
+}
+
 export async function createMixdogSessionRuntime({
   provider,
   model,
@@ -742,7 +762,7 @@ export async function createMixdogSessionRuntime({
 
   function emitRuntimeNotification(content, meta = {}) {
     const text = String(content || '').trim();
-    if (!text) return false;
+    if (!text) return { handled: false, modelVisibleDelivered: false };
     const event = { content: text, meta: meta && typeof meta === 'object' ? meta : {} };
     let handled = false;
     for (const listener of [...notificationListeners]) {
@@ -750,19 +770,34 @@ export async function createMixdogSessionRuntime({
         if (listener(event) === true) handled = true;
       } catch {}
     }
-    return handled;
+    // EXPLICIT model-visible-delivery ack: only the TUI execution-ui path sets
+    // event.modelVisibleDelivered when it enqueues the model-visible completion
+    // body into the active loop. A generic display-only / API listener that
+    // returns true does NOT set it, so `handled` alone must never be read as
+    // "the model saw the body".
+    const modelVisibleDelivered = event.modelVisibleDelivered === true;
+    return { handled, modelVisibleDelivered };
   }
 
   function notifyFnForSession(callerSessionId) {
     return (text, meta = {}) => {
-      const handledByRuntimeListener = emitRuntimeNotification(text, meta);
+      const { handled: handledByRuntimeListener, modelVisibleDelivered } = emitRuntimeNotification(text, meta);
       let enqueued = false;
       // TUI sessions consume raw execution notifications for UI/task cards via
       // onNotification, but those raw envelopes are internal-only in pending
-      // drain. Always mirror terminal completions with a model-visible wrapper
-      // while keeping the raw text for UI display.
-      if (callerSessionId && typeof mgr.enqueuePendingMessage === 'function'
-        && shouldPersistModelVisibleToolCompletion(text, meta)) {
+      // drain. The TUI execution-ui path injects the model-visible twin of a
+      // terminal completion into the active loop and acks with
+      // modelVisibleDelivered, so mirroring it into the pending queue would
+      // double-inject the same completion — skip only on that EXPLICIT ack. A
+      // generic display-only / API listener returning true is NOT an ack: the
+      // mirror stays as the sole model-visible delivery.
+      if (shouldMirrorCompletionToPendingQueue({
+        callerSessionId,
+        modelVisibleDelivered,
+        hasEnqueue: typeof mgr.enqueuePendingMessage === 'function',
+        text,
+        meta,
+      })) {
         try {
           const visible = modelVisibleToolCompletionMessage(text, meta);
           // Terminal completion (gated by shouldPersistModelVisibleToolCompletion)
@@ -973,7 +1008,7 @@ export async function createMixdogSessionRuntime({
       const meta = params.meta && typeof params.meta === 'object' ? params.meta : {};
       const content = channelNotificationModelContent(params);
       if (!content) return;
-      const handled = emitRuntimeNotification(content, meta);
+      const { handled } = emitRuntimeNotification(content, meta);
       if (!handled && session?.id && shouldMirrorChannelNotificationToPending(meta)) {
         try { mgr.enqueuePendingMessage(session.id, content); } catch {}
       }

package/src/session-runtime/warmup-schedulers.mjs

@@ -102,7 +102,13 @@ export function createWarmupSchedulers({
         scheduleProviderModelWarmup(backgroundBusyRetryMs);
         return;
       }
-      warmProviderModelCache();
+      if (!isFirstTurnCompleted() && !envFlag('MIXDOG_PROVIDER_WARMUP_BEFORE_FIRST_TURN')) {
+        bootProfile('provider-models:warm-deferred', { reason: 'first-turn-pending' });
+        warmProviderModelCache();
+        scheduleProviderModelWarmup(backgroundBusyRetryMs);
+        return;
+      }
+      warmProviderModelCache({ loadSecrets: true });
     }, delayMs);
     timers.providerModelWarmupTimer.unref?.();
   }

package/src/standalone/explore-tool.mjs

@@ -92,7 +92,7 @@ function escapeXml(str) {
 // reminder. The full no-verdict contract lives at system level
 // (rules/agent/30-explorer.md).
 export function buildExplorerPrompt(query) {
-  return `<query>${escapeXml(query)}</query>\nReminder: RULE ZERO is a binary gate after every tool result: >=1 path:line matching a SPECIFIC query token (product/library/domain name) -> STOP and answer NOW with those exact coordinates, this IS your final turn; zero -> one more batch if budget remains. Turns 2-3 exist SOLELY as zero-hit recovery (the previous turn matched ZERO specific tokens); spending a turn to confirm, refine, or upgrade an anchor you already hold is a defect. A generic-word-only match (schema, handler, config, resolver, index, error...) while the query's specific tokens match nowhere counts as ZERO, not a hit. There is no third branch: "hits exist but I want better ones" IS branch one — answer now. A code_graph symbol hit (find_symbol/symbol_search returning path:line) IS an anchor — emit it directly, never re-locate it with grep. Credibility is mechanical (specific-token match), never judged: "is this the real implementation / final handler / just a wrapper" are caller questions, FORBIDDEN here; mark weak anchors ? and answer anyway. Flow/how/trigger queries: first matching definition/entry anchors ARE the complete answer — never trace the chain, one anchor per concept. You locate WHERE, never WHY. Scope is ALWAYS the session working directory: omit path or pass only a path seen in an earlier result; inventing a directory (/workspace/..., another repo's layout) is a defect — on zero hits change TOKENS, never guess paths. HARD max 3 tool turns; counter line (turn 1/3, turn 2/3, turn 3/3) on every tool message; expected shape is turn 1 -> answer, turns 2-3 are miss-recovery only (previous turn had ZERO matching lines), with changed tokens; after turn 3/3 you MUST answer best-so-far. Each turn = ONE maximal batch: a single grep whose pattern[] packs ALL token variants PLUS code_graph/find/glob in the SAME message; a single-tool turn is a wasted turn. Before emitting EXPLORATION_FAILED re-scan ALL earlier results: any line matching a specific query token -> answer with that anchor (? if weak) — a weak anchor beats a false miss; EXPLORATION_FAILED only when all 3 turns found zero token-matching lines. Output only anchor lines formatted as path:line — symbol/name — short reason, max 3 lines, or EXPLORATION_FAILED. No preamble, bullets, numbering, headings, summary, code quotes, analysis, verdicts, ratings, or recommendations.`;
+  return `<query>${escapeXml(query)}</query>\nReminder: BUDGET = TWO MESSAGES NORMALLY: message 1 = your multi-tool batch, message 2 = your answer text. A 3rd message (ANY extra tool call) is a DEFECT unless message 1 returned ZERO specific-token lines — extra code_graph/grep calls to confirm or upgrade an anchor you already hold are the single biggest source of overspend. TURN 1 IS ONE BATCH, NON-NEGOTIABLE: your FIRST tool message fires, in that single message together, grep (pattern[] packing 3-6 token variants) AND code_graph symbol_search (identifiers) AND find/glob (path/name fragments) — never emit grep alone and wait for its result before adding code_graph/find. Serial one-tool-per-turn is the #1 budget defect and forfeits the turn-1 -> answer path; a first turn that is not this multi-tool batch is malformed. After that batch returns, if ANY line carries a specific query token you MUST emit the ANSWER as your very next message: a further tool call to refine, confirm, or upgrade is the primary overspend defect — a second tool turn is legal ONLY when the batch returned ZERO specific-token lines. Then RULE ZERO is a binary gate after every tool result: >=1 path:line matching a SPECIFIC query token (product/library/domain name) -> STOP and answer NOW with those exact coordinates, this IS your final turn; zero -> one more batch if budget remains. Turns 2-3 exist SOLELY as zero-hit recovery (the previous turn matched ZERO specific tokens); spending a turn to confirm, refine, or upgrade an anchor you already hold is a defect. A generic-word-only match (schema, handler, config, resolver, index, error...) while the query's specific tokens match nowhere counts as ZERO, not a hit. There is no third branch: "hits exist but I want better ones" IS branch one — answer now. A code_graph symbol hit (find_symbol/symbol_search returning path:line) IS an anchor — emit it directly, never re-locate it with grep. Credibility is mechanical (specific-token match), never judged: "is this the real implementation / final handler / just a wrapper" are caller questions, FORBIDDEN here; mark weak anchors ? and answer anyway. Flow/how/trigger queries: first matching definition/entry anchors ARE the complete answer — trace no chains, one anchor per concept; the SOLE exception: a query that EXPLICITLY asks flow/default-resolution whose turn 1 yielded only an entry anchor (not the resolved value) may take ONE turn-2 hop to the resolving site, then stop. You locate WHERE, never WHY. Scope is ALWAYS the session working directory: omit path (project cwd default) or pass only a path seen in an earlier result; an unverified path/name fragment rides the SAME turn-1 find query[] batch (a find-only turn is a defect) and scopes grep/glob only through the exact path find returns; inventing a directory (/workspace/..., another repo's layout) is a defect — on zero hits change TOKENS, never guess paths. HARD max 3 tool turns; counter line (turn 1/3, turn 2/3, turn 3/3) on every tool message; expected shape is turn 1 -> answer, turns 2-3 are miss-recovery only (previous turn had ZERO matching lines), with changed tokens; after turn 3/3 you MUST answer best-so-far. Each turn = ONE maximal batch: a single grep whose pattern[] packs ALL token variants PLUS code_graph/find/glob in the SAME message; a single-tool turn is a wasted turn. Before emitting EXPLORATION_FAILED re-scan ALL earlier results: any line matching a specific query token -> answer with that anchor (? if weak) — a weak anchor beats a false miss; EXPLORATION_FAILED only when all 3 turns found zero token-matching lines. Output only anchor lines formatted as path:line — symbol/name — short reason, max 3 lines, or EXPLORATION_FAILED. For a CODE-location answer every line MUST carry :line (an explicit line number) — a bare filename with no :line is a DEFECT; with no line-anchored code evidence, return EXPLORATION_FAILED rather than a vague file-only or prose answer. EXCEPTION — file/dir-LOCATION queries (where does X store its config/logs/data on disk, which directory or file holds Y): an exact VERIFIED path (the file or directory itself, no :line) IS the valid answer — do not force a line number and do not FAIL. No preamble, bullets, numbering, headings, summary, code quotes, analysis, verdicts, ratings, or recommendations.`;
 }
 
 export function normalizeExploreQueries(rawQuery) {

package/src/tui/dist/index.mjs

@@ -22625,6 +22625,7 @@ function agentArgsWithResultMetadata(args, parsed) {
 
 // src/tui/engine/queue-helpers.mjs
 var QUEUE_PRIORITY = { now: 0, next: 1, later: 2 };
+var STEERING_SUPPRESSED_DISPLAY = "\0mixdog:suppress-steer-display\0";
 function queuePriorityValue(value) {
   return QUEUE_PRIORITY[String(value || "next")] ?? QUEUE_PRIORITY.next;
 }
@@ -23347,8 +23348,13 @@ function createAgentJobFeed({
             // next tool batch; no special pending-resume bypass.
             priority: "next",
             key: notificationKey || void 0,
-            displayText: delivery.displayText || text
+            displayText: delivery.displayText || text,
+            // The immediate Response card was already pushed above
+            // (pushUserOrSyntheticItem). Keep this queued twin model-visible
+            // but suppress its drain-time transcript card to avoid a duplicate.
+            suppressDisplay: true
           });
+          if (event && typeof event === "object") event.modelVisibleDelivered = true;
         }
         return true;
       }
@@ -23771,6 +23777,7 @@ function createSessionFlow(bag) {
       key: options.key || null,
       skipSlashCommands: options.skipSlashCommands === true,
       displayText: mode === "task-notification" ? notificationDisplayText(displayText) : String(displayText || ""),
+      suppressDisplay: options.suppressDisplay === true,
       steeringPersistId: options.steeringPersistId || null,
       steeringPersistRestored: options.steeringPersistRestored === true
     };
@@ -23882,6 +23889,7 @@ function createSessionFlow(bag) {
         const merged = mergePromptContents(batch);
         for (const entry of batch) {
           if (entry.mode === "pending-resume") continue;
+          if (entry.suppressDisplay) continue;
           pushUserOrSyntheticItem(entry.text, entry.id, isQueuedEntryEditable(entry) ? "user" : "injected");
         }
         const nonEditable = batch.filter((entry) => !isQueuedEntryEditable(entry));
@@ -23948,6 +23956,12 @@ function createSessionFlow(bag) {
       if (batch.length === 0) break;
       for (const entry of batch) {
         const content = entry.content;
+        if (entry.suppressDisplay) {
+          if (Array.isArray(content) ? content.length > 0 : String(content ?? "").trim().length > 0) {
+            out.push({ text: STEERING_SUPPRESSED_DISPLAY, content });
+          }
+          continue;
+        }
         const value = typeof content === "string" ? content.trim() : { text: String(entry.text || "").trim(), content };
         if (typeof value === "string") {
           if (value.length > 0) out.push(value);
@@ -24770,6 +24784,7 @@ function createRunTurn(bag) {
         drainSteering: (_sessionId, drainOptions) => isCurrentTurn() ? drainPendingSteering(drainOptions) : [],
         onSteerMessage: (text) => {
           if (!markTurnProgress("steer-message")) return;
+          if (text === STEERING_SUPPRESSED_DISPLAY) return;
           flushStreamBatch();
           if (currentAssistantId) {
             patchItem(currentAssistantId, { text: currentAssistantText || assistantText, streaming: false });

package/src/tui/engine/agent-job-feed.mjs

@@ -152,7 +152,17 @@ export function createAgentJobFeed({
             priority: 'next',
             key: notificationKey || undefined,
             displayText: delivery.displayText || text,
+            // The immediate Response card was already pushed above
+            // (pushUserOrSyntheticItem). Keep this queued twin model-visible
+            // but suppress its drain-time transcript card to avoid a duplicate.
+            suppressDisplay: true,
           });
+          // EXPLICIT ack to the emitting runtime: the model-visible completion
+          // body was injected into the active loop here, so notifyFnForSession
+          // must NOT also mirror it into the pending queue (double injection).
+          // A bare truthy return below is display/status handling only — this
+          // flag is the sole model-visible-delivery signal.
+          if (event && typeof event === 'object') event.modelVisibleDelivered = true;
         }
         return true;
       }

package/src/tui/engine/queue-helpers.mjs

@@ -12,6 +12,14 @@ import {
 
 const QUEUE_PRIORITY = { now: 0, next: 1, later: 2 };
 
+// Sentinel display text for a steering entry that is model-visible only: its
+// immediate transcript ("Response …") card was already pushed at delivery time
+// (live execution completion), so the mid-turn steering drain must NOT render a
+// second card for it. drainPendingSteering emits this as the entry's display
+// text; turn.mjs's onSteerMessage recognizes it and skips the push while the
+// model still receives the entry's content.
+export const STEERING_SUPPRESSED_DISPLAY = '\u0000mixdog:suppress-steer-display\u0000';
+
 export function queuePriorityValue(value) {
   return QUEUE_PRIORITY[String(value || 'next')] ?? QUEUE_PRIORITY.next;
 }

package/src/tui/engine/session-flow.mjs

@@ -3,7 +3,7 @@
  */
 import { presentErrorText } from '../../runtime/shared/err-text.mjs';
 import { createSessionStats } from './session-stats.mjs';
-import { queuePriorityValue, defaultQueuePriority, isQueuedEntryEditable, isQueuedEntryVisible, isSlashQueuedEntry, notificationDisplayText, sessionActivityTimestamp, promptDisplayText, mergePromptContents, mergePastedImages, mergePastedTexts, callCommitCallbacks } from './queue-helpers.mjs';
+import { queuePriorityValue, defaultQueuePriority, isQueuedEntryEditable, isQueuedEntryVisible, isSlashQueuedEntry, notificationDisplayText, sessionActivityTimestamp, promptDisplayText, mergePromptContents, mergePastedImages, mergePastedTexts, callCommitCallbacks, STEERING_SUPPRESSED_DISPLAY } from './queue-helpers.mjs';
 import { appendTuiSteeringPersist, dropTuiSteeringPersist, drainTuiSteeringPersist } from './tui-steering-persist.mjs';
 
 export function createSessionFlow(bag) {
@@ -53,6 +53,7 @@ export function createSessionFlow(bag) {
       key: options.key || null,
       skipSlashCommands: options.skipSlashCommands === true,
       displayText: mode === 'task-notification' ? notificationDisplayText(displayText) : String(displayText || ''),
+      suppressDisplay: options.suppressDisplay === true,
       steeringPersistId: options.steeringPersistId || null,
       steeringPersistRestored: options.steeringPersistRestored === true,
     };
@@ -186,6 +187,10 @@ export function createSessionFlow(bag) {
         const merged = mergePromptContents(batch);
         for (const entry of batch) {
           if (entry.mode === 'pending-resume') continue;
+          // Live execution completions push their own immediate Response card
+          // at delivery time; the queued twin is model-visible only and must
+          // NOT render a second transcript card here (no fall-back to content).
+          if (entry.suppressDisplay) continue;
           pushUserOrSyntheticItem(entry.text, entry.id, isQueuedEntryEditable(entry) ? 'user' : 'injected');
         }
         const nonEditable = batch.filter((entry) => !isQueuedEntryEditable(entry));
@@ -274,6 +279,15 @@ export function createSessionFlow(bag) {
       if (batch.length === 0) break;
       for (const entry of batch) {
         const content = entry.content;
+        if (entry.suppressDisplay) {
+          // Model-visible twin of an already-rendered live completion: deliver
+          // content to the model but flag onSteerMessage to skip the duplicate
+          // transcript card (no fall-back to content-derived display text).
+          if (Array.isArray(content) ? content.length > 0 : String(content ?? '').trim().length > 0) {
+            out.push({ text: STEERING_SUPPRESSED_DISPLAY, content });
+          }
+          continue;
+        }
         const value = typeof content === 'string'
           ? content.trim()
           : { text: String(entry.text || '').trim(), content };

package/src/tui/engine/turn.mjs

@@ -7,7 +7,7 @@ import { pickVerb, pickDoneVerb, compactEventLabel, compactEventDetail } from '.
 import { toolResultText, toolErrorDisplay } from './tool-result-text.mjs';
 import { toolCallId, toolResultCallId, toolCallName, toolCallArgs } from './tool-call-fields.mjs';
 import { toolResultStatus, isErrorToolStatus } from './agent-envelope.mjs';
-import { promptDisplayText } from './queue-helpers.mjs';
+import { promptDisplayText, STEERING_SUPPRESSED_DISPLAY } from './queue-helpers.mjs';
 import { memoryCoreResultErrorText } from '../app/input-parsers.mjs';
 import { yieldToRenderer } from './render-timing.mjs';
 import { aggregateRawResult, aggregateBucketForCategory, aggregateSummaries, assignAggregateSummaryOrder } from './tool-result-status.mjs';
@@ -727,6 +727,11 @@ export function createRunTurn(bag) {
         drainSteering: (_sessionId, drainOptions) => (isCurrentTurn() ? drainPendingSteering(drainOptions) : []),
         onSteerMessage: (text) => {
           if (!markTurnProgress('steer-message')) return;
+          // A suppressed live-completion twin is model-visible only; its
+          // Response card was already pushed at delivery time. Skip the
+          // duplicate transcript item (progress is still marked above since
+          // the content WAS injected into the model turn).
+          if (text === STEERING_SUPPRESSED_DISPLAY) return;
           // Steering can be injected after a terminal no-tool response has
           // already streamed but before runTurn finalizes. Seal the current
           // assistant segment first so the steered user turn and the next