mixdog 0.9.145 → 0.9.147

package/src/runtime/agent/orchestrator/providers/openai-ws-pool.mjs

@@ -25,7 +25,7 @@ import {
 
 // Human-readable transport label for handshake/acquire error messages. Shared
 // with openai-oauth-ws.mjs (stream-side errors use the same labels).
-import { _envOn, _codexUuidIdParity, _codexDashedId, _codexTurnStateGate, _codexDashedIdV7, _codexBetaFeatures, _dumpHandshakeHeaders, _dumpFrame, _formatRedactedHeaders, _cfCookieHeader, _cfCookieCapture } from './openai-ws-headers.mjs';
+import { _envOn, _codexDashedId, _codexDashedIdV7, _codexBetaFeatures, _dumpHandshakeHeaders, _dumpFrame, _formatRedactedHeaders, _cfCookieHeader, _cfCookieCapture } from './openai-ws-headers.mjs';
 export function _wsErrLabel(p) {
     if (p === 'xai') return 'xAI WS';
     if (p === 'openai-direct' || p === 'openai') return 'OpenAI WS';
@@ -76,6 +76,46 @@ const MAX_POOLED_SOCKETS_PER_KEY = 8;
 export const _wsPool = new Map();
 let _releaseSequence = 0;
 
+// The server issues an `x-codex-turn-state` sticky-routing token on the
+// handshake 101 response; it pins the backend node that holds the warm prefix.
+// codex keeps that token in a turn-scoped cell and replays it on the RECONNECT
+// handshake (build_responses_headers -> connect_websocket), so a replacement
+// connection re-pins the same node instead of cold-starting the prefix. Our
+// pool entry dies with its socket, so the token is retained here at poolKey
+// scope and replayed only for a replacement socket. A parallel peer must still
+// open clean: inheriting a sibling's token makes openai-oauth treat the request
+// as a continuation of another in-flight turn ("No tool output found for
+// function call ...").
+const _turnStateByPoolKey = new Map();
+const MAX_RETAINED_TURN_STATE_KEYS = 4096;
+
+function _retainTurnState(poolKey, entry) {
+    if (!poolKey || !entry) return;
+    const turnState = typeof entry.turnState === 'string' ? entry.turnState : '';
+    // A token already retired by the per-turn drop guard must not be revived.
+    if (!turnState) return;
+    // Bounded like the other pool maps so a long-lived process cannot
+    // accumulate one token per dead session.
+    if (!_turnStateByPoolKey.has(poolKey) && _turnStateByPoolKey.size >= MAX_RETAINED_TURN_STATE_KEYS) {
+        const oldest = _turnStateByPoolKey.keys().next().value;
+        if (oldest !== undefined) _turnStateByPoolKey.delete(oldest);
+    }
+    _turnStateByPoolKey.set(poolKey, {
+        turnState,
+        // Carry the turn owner so the per-turn drop guard still retires a
+        // replayed token when turn_id moves on.
+        turnStateTurnId: entry.turnStateTurnId ?? null,
+    });
+}
+
+function _replacementTurnState(poolKey) {
+    if (!poolKey) return null;
+    // A live entry in the bucket means this handshake is a parallel peer, not
+    // a reconnect.
+    if (hasPooledWebSocket(poolKey)) return null;
+    return _turnStateByPoolKey.get(poolKey) || null;
+}
+
 function _poolCompatibility(auth, cacheKey) {
     const type = String(auth?.type || 'openai-oauth');
     // Prefer the stable OAuth account id so an access-token refresh can keep
@@ -139,6 +179,9 @@ function _removeFromPool(poolKey, entry) {
     // idle-close or liveness-ping interval.
     _clearIdle(entry);
     _clearLiveness(entry);
+    // The entry is going away; keep its shard pin so the session's next socket
+    // can reconnect onto the same backend node.
+    _retainTurnState(poolKey, entry);
     if (!poolKey) return;
     const arr = _wsPool.get(poolKey);
     if (!arr) return;
@@ -343,41 +386,24 @@ function _buildHandshakeHeaders({ auth, sessionToken, turnState, cacheKey: _cach
             'x-codex-beta-features': _codexBetaFeatures(),
         };
     const isOpenAiOauth = auth.type !== 'xai' && auth.type !== 'openai-direct';
-    // The reference client sends only the dashed session-id/thread-id pair,
-    // but OUR backend measurements disagree with pure
-    // wire parity here: 2026-04-19 probes showed the OAuth backend dedupes
-    // its in-memory prefix state by the underscore session_id handshake
-    // header, and the only 0.0%-miss full-frame rounds (R7/R8, R15 regressed
-    // to 13% after this header was dropped) all had it present. Send both.
-    // The underscore session_id is the backend prefix-dedupe key (2026-04-19
-    // probes; R15 regressed to 13% miss when it was dropped). Strict wire
-    // parity sends ONLY the dashed pair, but dropping this
-    // header is a KNOWN cache-unsafe change — so the general parity flag no
-    // longer silently drops it. Keep it unless an operator EXPLICITLY opts
-    // into the codex-exact dashed-only wire via
-    // MIXDOG_OAI_CODEX_WIRE_PARITY_SESSION_ID=dashed.
-    // The gate bundle implies the dashed-only wire (drop the underscore
-    // session_id) on top of the standalone opt-in.
-    const gate = _codexTurnStateGate();
-    const dropUnderscoreSessionId = process.env.MIXDOG_OAI_CODEX_WIRE_PARITY_SESSION_ID === 'dashed' || gate;
-    if (sessionToken && !dropUnderscoreSessionId) {
+    // Default mode preserves the measured Mixdog underscore session_id cache
+    // key. Strict wire parity instead follows Codex exactly: dashed
+    // session-id/thread-id only, UUIDv7-shaped ids, and x-client-request-id.
+    const wireParity = process.env.MIXDOG_OAI_CODEX_WIRE_PARITY === '1';
+    if (sessionToken && !wireParity) {
         headers['session_id'] = String(sessionToken);
     }
     if (isOpenAiOauth && (sessionToken || _cacheKey)) {
-        // Gate bundle forces Codex-shaped UUIDv7 ids; the standalone parity flag
-        // keeps its v5-derived shape.
-        const uuidIds = _codexUuidIdParity() || gate;
-        const shapeId = gate ? _codexDashedIdV7 : _codexDashedId;
+        const uuidIds = wireParity;
+        const shapeId = wireParity ? _codexDashedIdV7 : _codexDashedId;
         // Underscore `session_id` above is left as-is (backend prefix-dedupe
         // key); only the dashed codex pair is reshaped under the opt-in.
         const threadId = uuidIds ? shapeId(String(_cacheKey || sessionToken)) : String(_cacheKey || sessionToken);
         const sessionId = uuidIds ? shapeId(String(sessionToken || _cacheKey)) : String(sessionToken || _cacheKey);
         headers['session-id'] = sessionId;
         headers['thread-id'] = threadId;
-        // Default/parity wire duplicates the dashed thread-id here. The gate
-        // hypothesis is that a duplicated x-client-request-id suppresses
-        // turn-state issuance, so omit it entirely under the bundle.
-        if (!gate) headers['x-client-request-id'] = threadId;
+        // The reference client sets x-client-request-id to the dashed thread id.
+        headers['x-client-request-id'] = threadId;
         if (codexHeaders && typeof codexHeaders === 'object') {
             for (const [key, value] of Object.entries(codexHeaders)) {
                 if (typeof key === 'string' && typeof value === 'string' && value) {
@@ -580,6 +606,13 @@ export async function acquireWebSocket({ auth, poolKey, cacheKey, codexHeaders,
             if (!_isOpen(arr[i]) || arr[i].closing || incompatibleIdle) {
                 if (incompatibleIdle) {
                     try { arr[i].socket.close(1000, 'pool_boundary_changed'); } catch {}
+                } else {
+                    // A dead socket pruned here never reaches _removeFromPool,
+                    // so retain its shard pin explicitly — this is the common
+                    // reconnect path and the one the replacement handshake
+                    // below reads. A boundary change deliberately drops the
+                    // pin: it belongs to the old auth/cache identity.
+                    _retainTurnState(poolKey, arr[i]);
                 }
                 _clearIdle(arr[i]);
                 _clearLiveness(arr[i]);
@@ -668,13 +701,17 @@ export async function acquireWebSocket({ auth, poolKey, cacheKey, codexHeaders,
     // Parallel sockets must not inherit sibling turnState or the openai-oauth server
     // treats the new request as a continuation of another in-flight turn and
     // returns "No tool output found for function call …". turnState only
-    // propagates within a single entry across its own iterations.
+    // propagates within a single entry across its own iterations — plus the
+    // codex reconnect case below, where the bucket holds no live entry and the
+    // retained token re-pins the shard the dead socket was using. forceFresh
+    // asks for a deliberately unpinned socket, so it always opens clean.
     const sessionToken = _mintSessionToken(cacheKey, auth);
     const compatibility = _poolCompatibility(auth, cacheKey);
+    const retainedTurnState = forceFresh ? null : _replacementTurnState(poolKey);
     if (process.env.MIXDOG_DEBUG_AGENT) {
         process.stderr.write(`[agent-trace] acquire-new tokenHash=${createHash('sha256').update(String(sessionToken)).digest('hex').slice(0, 8)} elapsed=${Date.now() - _acqStart}ms\n`);
     }
-    const { socket, turnState } = await _openSocketImpl({ auth, sessionToken, turnState: null, externalSignal, cacheKey, codexHeaders });
+    const { socket, turnState } = await _openSocketImpl({ auth, sessionToken, turnState: retainedTurnState?.turnState || null, externalSignal, cacheKey, codexHeaders });
     // Drain may complete while the normal handshake is awaiting 'open'. Never
     // return or insert that late socket into the already-drained process pool.
     if (_drainComplete) {
@@ -693,7 +730,11 @@ export async function acquireWebSocket({ auth, poolKey, cacheKey, codexHeaders,
         lastInputPrefixHash: null,
         releaseSequence: 0,
         ...compatibility,
-        turnState: turnState || null,
+        // A token issued on THIS handshake supersedes the replayed one and is
+        // attributed on first use; a surviving retained token keeps its
+        // original turn owner so the per-turn drop guard still retires it.
+        turnState: turnState || retainedTurnState?.turnState || null,
+        turnStateTurnId: turnState ? null : (retainedTurnState?.turnStateTurnId ?? null),
         closing: false,
         ephemeral: false,
         sessionToken,
@@ -733,10 +774,15 @@ export function releaseWebSocket({ entry, poolKey, keep }) {
 
 export function closeOpenaiWsPoolForSession(poolKey, reason = 'session_closed') {
     if (!poolKey) return;
+    // The session is over, so its shard pin must not survive into a later
+    // session that reuses the key. Clearing each entry's token before the
+    // close() calls also keeps the async 'close' handlers from re-retaining it.
+    _turnStateByPoolKey.delete(poolKey);
     const entries = _wsPool.get(poolKey);
     if (!entries) return;
     _wsPool.delete(poolKey);
     for (const entry of entries) {
+        entry.turnState = null;
         _clearIdle(entry);
         _clearLiveness(entry);
         try { entry.socket.close(1000, reason); } catch {}
@@ -764,12 +810,14 @@ export function _seedWebSocketEntryForTest({ poolKey, auth, cacheKey, entry }) {
 export function _clearWebSocketPoolForTest() {
     for (const arr of _wsPool.values()) {
         for (const entry of arr) {
+            entry.turnState = null;
             _clearIdle(entry);
             _clearLiveness(entry);
             try { entry.socket.close(1000, 'test_cleanup'); } catch {}
         }
     }
     _wsPool.clear();
+    _turnStateByPoolKey.clear();
     _releaseSequence = 0;
 }
 

package/src/runtime/agent/orchestrator/providers/openai-ws-stream.mjs

@@ -180,6 +180,11 @@ function _hasHeaderKey(headers, name) {
 
 export function _captureTurnStateFromEvent(entry, event) {
     if (!entry || entry.turnState || !event || typeof event !== 'object') return;
+    // The token normally arrives on the WebSocket 101 handshake and is held
+    // write-once per entry, which is what keeps sticky routing stable across
+    // previous_response_id calls. This event path is the fallback for
+    // deployments that surface the header on a response event instead; the
+    // write-once guard above means it can never swap a live chain's token.
     const turnState = _headerString(event.headers, X_CODEX_TURN_STATE_HEADER)
         || _headerString(event.response?.headers, X_CODEX_TURN_STATE_HEADER)
         || _headerString(event.response?.metadata?.headers, X_CODEX_TURN_STATE_HEADER)
@@ -354,6 +359,13 @@ export async function _streamResponse({
             id: item.id || '',
             encrypted_content: item.encrypted_content,
             summary: Array.isArray(item.summary) ? item.summary : [],
+            // Emission order is part of the chain proof. A turn can reason,
+            // speak, then reason again before calling a tool; rebuilding it
+            // with every reasoning item in front of the text yields an order
+            // the previous response never produced, and the incremental check
+            // then fails on the message item and drops the chain to a cold
+            // full frame. Record which side of the text this item arrived on.
+            ...(responseItemsAdded.some((added) => added?.type === 'message') ? { afterText: true } : {}),
         });
     };
     const pushResponseItem = (item) => {

package/src/runtime/agent/orchestrator/session/compact/runner.mjs

@@ -37,6 +37,7 @@ import {
     shouldExcludeIngestMessage,
 } from '../../../../memory/lib/session-ingest.mjs';
 import { cleanMemoryText } from '../../../../memory/lib/memory-extraction.mjs';
+import { codexWireSendOpts } from '../manager/session-id.mjs';
 import {
     COMPACTION_SYSTEM_PROMPT,
     fitCompactionPrompt,
@@ -446,6 +447,13 @@ export async function semanticCompactMessages(provider, messages, model, budgetT
     if (opts.providerCacheKey || opts.sendOpts?.providerCacheKey) {
         sendOpts.providerCacheKey = `${opts.providerCacheKey || opts.sendOpts.providerCacheKey}:compact`;
     }
+    // Compaction is a request of the SAME session, not a session of its own:
+    // thread identity and window carry over, only the request kind and the turn
+    // id change. The `:compact` suffixes above stay — they scope the socket
+    // pool bucket so a summary never steals the live turn's socket — while the
+    // wire identity below keeps both on one server-side prefix-cache slot.
+    const codexWire = codexWireSendOpts(sendOpts.session, { requestKind: 'compaction' });
+    if (codexWire) Object.assign(sendOpts, codexWire);
 
     const response = await provider.send([
         { role: 'system', content: COMPACTION_SYSTEM_PROMPT },

package/src/runtime/agent/orchestrator/session/manager/ask-session.mjs

@@ -52,6 +52,7 @@ import {
 } from './runtime-liveness.mjs';
 import { SessionClosedError } from './session-errors.mjs';
 import { acquireSessionLock } from './session-lock.mjs';
+import { codexWireSendOpts, ensureCodexWireSessionId, mintUuidV7 } from './session-id.mjs';
 import { _tryBridgeExplicitPrefetch } from './prefetch-bridge.mjs';
 import {
     filterModelVisibleSessionMessages,
@@ -283,6 +284,7 @@ export async function askSession(sessionId, prompt, context, onToolCall, cwdOver
         if (preSession.closed === true) {
             throw new SessionClosedError(sessionId, 'session already closed');
         }
+        const _codexWireSessionId = ensureCodexWireSessionId(preSession);
         if (!_crashRecoveryChecked) {
             _crashRecoveryChecked = true;
             const recovery = recoverTurnCheckpoint(preSession);
@@ -341,6 +343,7 @@ export async function askSession(sessionId, prompt, context, onToolCall, cwdOver
         const _turnInterruption = createTurnInterruptionTracker();
         const _turnCheckpointToken = randomUUID();
         const _turnCheckpointStartedAt = Date.now();
+        const _codexTurnId = _codexWireSessionId ? mintUuidV7(_turnCheckpointStartedAt) : null;
         const _TURN_CHECKPOINT_THROTTLE_MS = 150;
         let _turnCheckpointTimer = null;
         let _turnCheckpointStopped = false;
@@ -736,6 +739,12 @@ export async function askSession(sessionId, prompt, context, onToolCall, cwdOver
                         try { askOpts?.onSteerMessage?.(text, detail); } catch {}
                     },
                     notifyFn: typeof askOpts?.notifyFn === 'function' ? askOpts.notifyFn : undefined,
+                    // Same projection compaction uses, so a session presents one
+                    // identity on every request it makes.
+                    ...(codexWireSendOpts(session, {
+                        turnId: _codexTurnId,
+                        startedAtMs: _turnCheckpointStartedAt,
+                    }) || {}),
                     promptCacheKey: session.promptCacheKey || sessionId,
                     // Provider-scoped cache key (mixdog-codex, mixdog-claude…).
                     // Distinct from sessionId — providers that pool sockets

package/src/runtime/agent/orchestrator/session/manager/compaction-runner.mjs

@@ -349,6 +349,10 @@ export async function runSessionCompaction(session, opts = {}) {
                             sessionId: resolvedSessionId,
                             cwd: session.cwd,
                             signal: opts.signal || null,
+                            // Carries the session's wire identity so the
+                            // summary request stays on the session's own
+                            // prefix-cache slot instead of opening a second one.
+                            sendOpts: { session },
                             promptCacheKey: session.promptCacheKey || null,
                             providerCacheKey: session.promptCacheKey || null,
                             timeoutMs: semanticCompactTimeoutMs(session, beforeMessageTokens),
@@ -394,6 +398,9 @@ export async function runSessionCompaction(session, opts = {}) {
                     sessionId: resolvedSessionId,
                     cwd: session.cwd,
                     signal: opts.signal || null,
+                    // Same-session wire identity: one prefix-cache slot for
+                    // turns and their summaries alike.
+                    sendOpts: { session },
                     promptCacheKey: session.promptCacheKey || null,
                     providerCacheKey: session.promptCacheKey || null,
                     timeoutMs: semanticCompactTimeoutMs(session, beforeMessageTokens),

package/src/runtime/agent/orchestrator/session/manager/session-id.mjs

@@ -4,6 +4,85 @@
 // clearSessionMessages (clear-fork), matching the original single `nextId`.
 import { randomBytes } from 'crypto';
 let nextId = Date.now();
+const UUID_V7_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+let lastUuidV7Ms = -1;
+let uuidV7Sequence = 0;
+
 export function mintSessionId() {
     return `sess_${process.pid}_${nextId++}_${Date.now()}_${randomBytes(16).toString('hex')}`;
 }
+
+export function isUuidV7(value) {
+    return UUID_V7_RE.test(String(value || '').trim());
+}
+
+export function mintUuidV7(nowMs = Date.now()) {
+    const parsedNow = Number(nowMs);
+    const timestampMs = Math.max(
+        0,
+        Math.min(
+            0xffffffffffff,
+            Math.floor(Number.isFinite(parsedNow) ? parsedNow : Date.now()),
+        ),
+    );
+    if (timestampMs === lastUuidV7Ms) {
+        uuidV7Sequence = (uuidV7Sequence + 1) & 0x0fff;
+    } else {
+        lastUuidV7Ms = timestampMs;
+        uuidV7Sequence = randomBytes(2).readUInt16BE(0) & 0x0fff;
+    }
+    const bytes = randomBytes(16);
+    const timestamp = BigInt(timestampMs);
+    bytes[0] = Number((timestamp >> 40n) & 0xffn);
+    bytes[1] = Number((timestamp >> 32n) & 0xffn);
+    bytes[2] = Number((timestamp >> 24n) & 0xffn);
+    bytes[3] = Number((timestamp >> 16n) & 0xffn);
+    bytes[4] = Number((timestamp >> 8n) & 0xffn);
+    bytes[5] = Number(timestamp & 0xffn);
+    bytes[6] = 0x70 | ((uuidV7Sequence >> 8) & 0x0f);
+    bytes[7] = uuidV7Sequence & 0xff;
+    bytes[8] = (bytes[8] & 0x3f) | 0x80;
+    const hex = bytes.toString('hex');
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
+}
+
+/**
+ * Send-opts projection of a session's Codex wire identity.
+ *
+ * Every request belonging to one session — live turns and compaction summaries
+ * alike — presents the SAME session/thread id, because the backend derives its
+ * prompt-cache slot from that id. Only `turn_id` and `request_kind` change per
+ * request. Splitting compaction onto its own identity would hand the same
+ * session two cache slots and cold-start one of them on every compaction.
+ *
+ * Returns null for providers without a Codex wire identity, so callers can
+ * spread the result unconditionally.
+ */
+export function codexWireSendOpts(session, { requestKind = 'turn', turnId = null, startedAtMs = null } = {}) {
+    const wireSessionId = ensureCodexWireSessionId(session);
+    if (!wireSessionId) return null;
+    const parsedStartedAt = Number(startedAtMs);
+    const startedAt = Number.isFinite(parsedStartedAt) && parsedStartedAt > 0
+        ? Math.floor(parsedStartedAt)
+        : Date.now();
+    return {
+        codexSessionId: wireSessionId,
+        codexThreadId: wireSessionId,
+        turnId: turnId || mintUuidV7(startedAt),
+        windowId: `${wireSessionId}:0`,
+        turnStartedAtUnixMs: startedAt,
+        requestKind,
+    };
+}
+
+export function ensureCodexWireSessionId(session) {
+    if (!session || session.provider !== 'openai-oauth') return null;
+    const current = String(session.codexWireSessionId || '').trim().toLowerCase();
+    if (isUuidV7(current)) {
+        session.codexWireSessionId = current;
+        return current;
+    }
+    const minted = mintUuidV7();
+    session.codexWireSessionId = minted;
+    return minted;
+}

package/src/runtime/agent/orchestrator/session/manager/session-lifecycle.mjs

@@ -29,6 +29,7 @@ import {
 import {
     filterModelEditToolNames,
     filterModelEditTools,
+    unusedModelEditToolName,
 } from '../../../../shared/edit-tool-dialect.mjs';
 import {
     positiveContextWindow,
@@ -36,7 +37,7 @@ import {
     resolveSessionContextMeta,
 } from './context-meta.mjs';
 import { getAgentRuntimeSync, warnAgentRuntimeResolveFailureOnce } from './agent-runtime-singleton.mjs';
-import { mintSessionId } from './session-id.mjs';
+import { ensureCodexWireSessionId, mintSessionId, mintUuidV7 } from './session-id.mjs';
 import { providerCacheKey } from './provider-cache-key.mjs';
 import { clearTurnCheckpoint, recoverTurnCheckpoint } from './turn-checkpoint.mjs';
 import {
@@ -234,7 +235,11 @@ export function createSession(opts) {
         ...(hiddenAgent ? ['Skill'] : []),
         ...(!ownerIsAgent && workflowDisallowsAgentTool(opts.workflow) ? ['agent'] : []),
     ];
-    const injectedRules = skipAgentRules ? '' : _buildSharedRules({ omitTools: sessionDeny });
+    // The edit dialect this model never receives is omitted from the rules as
+    // well, so a session never reads placement guidance for a tool it cannot
+    // call.
+    const ruleOmitTools = [...sessionDeny, unusedModelEditToolName(modelName)];
+    const injectedRules = skipAgentRules ? '' : _buildSharedRules({ omitTools: ruleOmitTools });
     const delegationFree = !ownerIsAgent && workflowDisallowsAgentTool(opts.workflow);
     const roleRules = skipAgentRules
         ? ''
@@ -385,6 +390,7 @@ export function createSession(opts) {
     });
     const session = {
         id,
+        codexWireSessionId: providerName === 'openai-oauth' ? mintUuidV7() : null,
         provider: providerName,
         model: modelName,
         messages,
@@ -495,6 +501,7 @@ export function updateSessionRoute(id, route = {}) {
     if (route.model) session.model = route.model;
     if (Object.prototype.hasOwnProperty.call(route, 'fast')) session.fast = route.fast === true;
     if (Object.prototype.hasOwnProperty.call(route, 'effort')) session.effort = route.effort || null;
+    ensureCodexWireSessionId(session);
     if (Object.prototype.hasOwnProperty.call(route, 'modelParameters')) {
         session.modelParameters = route.modelParameters && typeof route.modelParameters === 'object'
             ? { ...route.modelParameters }
@@ -809,6 +816,7 @@ export async function resumeSession(sessionId, preset, options = {}) {
     // save below would also block the write, but failing fast here is cleaner
     // than silently dropping the tool-refresh side effects.
     if (session.closed === true) return null;
+    ensureCodexWireSessionId(session);
     // Desktop callers pass their selected durable classification as a
     // capability check. Refuse a stale/tampered cross-class resume before any
     // tool refresh or save. CLI/TUI callers omit this option and retain the

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

@@ -14,8 +14,8 @@ const _shellSyntaxCheat =
 // Keep the routing map short and adjacent to the shell's primary description.
 // PowerShell aliases appear only on win32.
 const _shellToolRouting = process.platform === 'win32'
-    ? 'Use read, NOT cat/Get-Content/head/tail; list, NOT ls/dir; find/glob, NOT find; grep, NOT grep/rg/Select-String; edit/apply_patch, NOT sed/awk/echo/Set-Content or a file-writing heredoc.'
-    : 'Use read, NOT cat/head/tail; list, NOT ls; find/glob, NOT find; grep, NOT grep/rg; edit/apply_patch, NOT sed/awk/echo or a file-writing heredoc.';
+    ? 'Use read, NOT cat/Get-Content/head/tail; list, NOT ls/dir; find/glob, NOT find; grep, NOT grep/rg/Select-String; edit/apply_patch, NOT sed/awk/echo/Set-Content or a file-writing heredoc; git, NOT a plain git command; task, NOT Start-Job or a wait loop.'
+    : 'Use read, NOT cat/head/tail; list, NOT ls; find/glob, NOT find; grep, NOT grep/rg; edit/apply_patch, NOT sed/awk/echo or a file-writing heredoc; git, NOT a plain git command; task, NOT & or a wait loop.';
 // Process-stable switch used to describe foreground-only execution accurately.
 const _shellBackgroundDisabled = /^(1|true|yes|on)$/i.test(
     String(process.env.MIXDOG_SHELL_DISABLE_BACKGROUND_TASKS || '').trim(),
@@ -26,7 +26,7 @@ export const BUILTIN_TOOLS = [
         name: 'read',
         title: 'Read',
         annotations: { title: 'Read', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false, compressible: false },
-        description: 'Read-only; safe to batch in parallel. Known-file contents or line ranges, bounded to the narrowest range that answers the question. Spans another tool already returned are source context; read only what they omit. Images render for viewing; not directories. Replaces cat/head/tail.',
+        description: 'Read-only; safe to batch in parallel. Known-file contents or line ranges, bounded to the narrowest range that answers the question. Images render for viewing; not directories. Replaces cat/head/tail.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -52,7 +52,7 @@ export const BUILTIN_TOOLS = [
         name: 'edit',
         title: 'Edit',
         annotations: { title: 'Edit', readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false, compressible: false, compressibleLossless: true },
-        description: 'Replace exact text in one file. Use exact text already in context; never re-open the file to build old_string or to verify a successful edit. old_string must match once unless replace_all is true. Empty old_string creates a missing file or fills an empty file; it never overwrites a non-empty file.',
+        description: 'Replace exact text in one file. Use exact text already in context; never re-open the file to build old_string or to verify a successful edit. old_string must match once unless replace_all is true. Empty old_string creates a missing file or fills an empty file; it never overwrites a non-empty file. Replaces sed/awk and echo redirection.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -81,7 +81,7 @@ export const BUILTIN_TOOLS = [
         name: 'shell',
         title: 'Shell',
         annotations: { title: 'Shell', readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true, compressible: true },
-        description: `Run programs, runtime/state operations, calculations, transformations, file generation, and unsupported-format inspection. ${_shellToolRouting} Avoid file operations covered by dedicated tools unless explicitly instructed or after verifying that a dedicated tool cannot do the job. An already-open shell is never a reason to route work to it. ${_shellBackgroundDisabled ? 'Commands run in the foreground until completion.' : 'Commands use a 10s foreground window by default—not a timeout. Still-running work continues as a tracked task_id. Completion is automatic; do not poll with task read/monitor unless the user explicitly requests polling or periodic progress. Otherwise, use task read only for an immediate decision and task monitor only for explicitly requested periodic progress.'}`,
+        description: `Run programs, runtime/state operations, calculations, transformations, file generation, and unsupported-format inspection. ${_shellToolRouting} ${_shellBackgroundDisabled ? 'Commands run in the foreground until completion.' : 'Commands use a 10s foreground window by default—not a timeout. Still-running work continues as a tracked task_id. Completion is automatic; do not call task read/monitor to wait or check progress. Continue independent work or end the turn. Use task read only when the user explicitly asks for current status, and task monitor only when they explicitly ask for periodic progress.'}`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -102,7 +102,7 @@ export const BUILTIN_TOOLS = [
         name: 'task',
         title: 'Task',
         annotations: { title: 'Task', readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
-        description: 'List shell tasks, read one current snapshot, change periodic monitoring, or cancel by task_id. Completion is automatic; do not poll with read/monitor unless the user explicitly requests polling or periodic progress. Otherwise, use read only for an immediate decision and monitor only for explicitly requested periodic progress.',
+        description: 'List shell tasks, read one current snapshot, change periodic monitoring, or cancel by task_id. Replaces shell job control (jobs/wait/Start-Job). Completion is automatic; do not call read/monitor to wait or check progress. Continue independent work or end the turn. Use read only when the user explicitly asks for current status, and monitor only when they explicitly ask for periodic progress.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -153,7 +153,7 @@ export const BUILTIN_TOOLS = [
         name: 'glob',
         title: 'Glob',
         annotations: { title: 'Glob', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false, compressible: true },
-        description: 'Read-only; safe to batch in parallel. Return wildcard-matching file paths under a known base directory when those paths are needed. Omit path for the current Project; if the base location is unknown, use find first. Directories never match. Newest first by default. Replaces find -name.',
+        description: 'Read-only; safe to batch in parallel. Return wildcard-matching file paths under a known base directory when those paths are needed. Omit path for the current Project; an unknown base directory goes to find first. Directories never match. Newest first by default. Replaces find -name.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -165,7 +165,7 @@ export const BUILTIN_TOOLS = [
                     description: 'Glob or array of globs (max 10).',
                 },
                 path: {
-                    type: 'string',                    description: 'Known existing base directory; omit for the current Project; unknown location → find.',
+                    type: 'string',                    description: 'Known existing base directory; omit for the current Project.',
                 },
                 sort: { type: 'string', enum: ['natural', 'mtime'], description: 'mtime default (newest first); natural = raw walk order, cheaper on huge trees.' },
                 limit: { type: 'integer', minimum: 0, description: 'Max entries; default 100; 0 unlimited.' },
@@ -198,7 +198,7 @@ export const BUILTIN_TOOLS = [
         name: 'list',
         title: 'List Directory',
         annotations: { title: 'List Directory', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false, compressible: true },
-        description: "Read-only; safe to batch in parallel. Return a known directory's immediate entries (path + type) when the entry list itself is needed; never as a prerequisite for another tool on that directory. No wildcard; meta:true adds size/mtime/mode.",
+        description: "Read-only; safe to batch in parallel. Return a known directory's immediate entries (path + type) when the entry list itself is needed; never as a prerequisite for another tool on that directory. No wildcard; meta:true adds size/mtime/mode. Replaces ls/dir.",
         inputSchema: {
             type: 'object',
             properties: {

package/src/runtime/agent/orchestrator/tools/builtin/lib/shell-job-insights.mjs

@@ -13,27 +13,39 @@ function summarizeJobPreviewText(text, maxChars = 160) {
     return summary.length > maxChars ? `${summary.slice(0, maxChars - 1)}…` : summary;
 }
 
+// The reported source must be the stream the summary actually came from: a
+// present-but-blank preview previously mislabeled a stderr summary as stdout.
+function pickJobSummary(candidates) {
+    for (const [source, text] of candidates) {
+        const summary = summarizeJobPreviewText(text);
+        if (summary) return { summary, summarySource: source };
+    }
+    return { summary: '', summarySource: '' };
+}
+
 export function attachJobInsights(detail) {
     if (!detail || typeof detail !== 'object') return detail;
     const result = { ...detail };
     let summary = '';
     let summarySource = '';
+    const stdoutFirst = [['stdout', result.stdoutPreview], ['stderr', result.stderrPreview]];
+    const stderrFirst = [['stderr', result.stderrPreview], ['stdout', result.stdoutPreview]];
     if (result.status === 'completed') {
-        summary = summarizeJobPreviewText(result.stdoutPreview)
-            || summarizeJobPreviewText(result.stderrPreview);
-        summarySource = summary ? (result.stdoutPreview ? 'stdout' : 'stderr') : '';
+        // A non-zero exit means the diagnosis lives in stderr, so lead with it
+        // instead of the last stdout line, which is usually unrelated progress.
+        const failedExit = typeof result.exitCode === 'number' && result.exitCode !== 0;
+        ({ summary, summarySource } = pickJobSummary(failedExit ? stderrFirst : stdoutFirst));
     } else if (result.status === 'failed') {
-        summary = summarizeJobPreviewText(result.stderrPreview)
-            || summarizeJobPreviewText(result.stdoutPreview)
-            || String(result.error || '').trim();
-        summarySource = summary ? (result.stderrPreview ? 'stderr' : (result.stdoutPreview ? 'stdout' : 'status')) : '';
+        ({ summary, summarySource } = pickJobSummary(stderrFirst));
+        if (!summary) {
+            summary = String(result.error || '').trim();
+            summarySource = summary ? 'status' : '';
+        }
     } else if (result.status === 'cancelled') {
         summary = 'cancelled before completion';
         summarySource = 'status';
     } else if (result.status === 'running') {
-        summary = summarizeJobPreviewText(result.stdoutPreview)
-            || summarizeJobPreviewText(result.stderrPreview);
-        summarySource = summary ? (result.stdoutPreview ? 'stdout' : 'stderr') : '';
+        ({ summary, summarySource } = pickJobSummary(stdoutFirst));
     }
     if (summary) {
         result.summary = summary;

package/src/runtime/agent/orchestrator/tools/builtin/shell-lossless-compact.mjs

@@ -76,8 +76,32 @@ function compactStructuredJson(stdout) {
     return `${compacted.join('\n')}${hadTrailingNewline ? '\n' : ''}`;
 }
 
+// A test summary states the RUN's verdict, so it may only replace output whose
+// exit status belongs to the runner itself. A pipeline, chain, or substitution
+// can hand back someone else's status (`node --test … | tail` exits 0 while the
+// suite fails), which would turn a failed run into a success line. Plain
+// redirects keep the runner's own status and stay eligible.
+function statusOwningCommand(command) {
+    const text = String(command ?? '').replace(/\d?>&\d/g, ' ').trim();
+    if (!text) return false;
+    return !/[;&|<>`]|\$\(|\$\{/.test(text);
+}
+
+// Runner-agnostic failure markers. Whichever matcher would otherwise claim the
+// run, an explicit failure line forbids a success summary.
+function hasTestFailureMarker(stdout) {
+    const text = String(stdout ?? '');
+    return /(?:^|\n)\s*not ok\b/i.test(text)
+        || /^#\s*(?:fail|cancelled|todo)\s+[1-9]/m.test(text)
+        || /(?:^|\n)(?:---\s*FAIL|FAIL\b|FAILED\b)/.test(text)
+        || /(?:^|\n)\s*failures:/i.test(text)
+        || /\bpanicked at\b/.test(text)
+        || /[\u2716\u2718]/.test(text);
+}
+
 function testLikeCommand(command) {
     const text = String(command ?? '').trim();
+    if (!statusOwningCommand(text)) return false;
     return simplePytestCommand(text)
         || /^(?:node|bun)(?:\.exe)?\s+--test(?:\s|$)/i.test(text)
         || /^(?:npm|pnpm|yarn|bun)\s+(?:run\s+)?test(?:[:.\w-]*)(?:\s|$)/i.test(text)
@@ -137,10 +161,15 @@ function cargoTestSuccessSummary(stdout) {
     return `Cargo test: ${passed} passed in ${resultLines.length} suites${duration ? ` (${duration.toFixed(2)}s)` : ''}`;
 }
 
+// Go prints `ok  <pkg>  0.02s` or `ok  <pkg>  (cached)`. Anchoring on that
+// trailing duration field keeps TAP's `ok 3 - name` result lines — which are
+// individual assertions, not packages — from being counted as Go packages.
 function goTestSuccessSummary(stdout) {
     const text = String(stdout ?? '');
     if (/(?:^|\n)(?:FAIL\b|--- FAIL:)|\b(?:panic|warning):/im.test(text)) return null;
-    const packages = text.split(/\r?\n/).filter((line) => /^ok\s+\S+/.test(line.trim()));
+    if (/^TAP version \d+/m.test(text) || /^1\.\.\d+\s*$/m.test(text)) return null;
+    const packages = text.split(/\r?\n/)
+        .filter((line) => /^ok\s+\S+\s+(?:\(cached\)|[\d.]+m?s)\b/.test(line.trim()));
     if (!packages.length) return null;
     return `Go test: ${packages.length} packages passed`;
 }

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: 'Read-only; safe to batch in parallel. Source-file structure, symbol relations, and flow. Exact identifiers route directly to find_symbol/references/callers/callees; symbol-name keywords use symbol_search/search. Source text, literals, regex, and conceptual keywords use grep. File modes use files[]; symbol modes use symbols[]. overview and mode:symbols return file summaries. find_symbol returns declaration/body; references returns declaration/usages plus optional body; callers/callees return locations.',
+    description: 'Read-only; safe to batch in parallel. Source-file structure, symbol relations, and flow. Exact identifiers route directly to find_symbol/references/callers/callees; symbol-name keywords use symbol_search/search. Text, literals, and regex belong to grep. File modes use files[]; symbol modes use symbols[]. overview and mode:symbols return file summaries. find_symbol returns declaration/body; references returns declaration/usages plus optional body; callers/callees return locations.',
     inputSchema: {
       type: 'object',
       properties: {