mixdog 0.9.12 → 0.9.14

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

@@ -4,7 +4,7 @@ import { takeApplyPatchUiDiff } from '../tools/patch.mjs';
 import { executeInternalTool, isInternalTool } from '../internal-tools.mjs';
 import { normalizeToolEnvelope } from './tool-envelope.mjs';
 import { traceAgentLoop, traceAgentTool, traceAgentToolFailure, traceAgentCompact, estimateProviderPayloadBytes, messagePrefixHash, appendAgentTrace } from '../agent-trace.mjs';
-import { resolveSessionMaxLoopIterations, WORKER_SOFT_CAP_ITERATIONS, isWorkerSoftCapSession } from '../agent-runtime/agent-loop-policy.mjs';
+import { resolveSessionMaxLoopIterations } from '../agent-runtime/agent-loop-policy.mjs';
 import { isAgentOwner } from '../agent-owner.mjs';
 import { markSessionToolCall, updateSessionStage, SessionClosedError, bumpUsageMetricsEpoch } from './manager.mjs';
 import {
@@ -48,8 +48,7 @@ import { mergeSteeringEntries, steeringContentText } from './loop/steering.mjs';
 import {
     crossTurnSignature,
     crossTurnDedupStub,
-    SOFT_CAP_WRAPUP_MESSAGE,
-    SOFT_CAP_REFUSAL_STUB,
+    ITERATION_CAP_REFUSAL_STUB,
 } from './loop/completion-guards.mjs';
 import { isEditProgressTool } from './loop/completion-guards.mjs';
 import { agentContextOverflowError } from './loop/context-overflow.mjs';
@@ -137,7 +136,6 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
     let lastUsage;
     let firstTurnUsage;
     let response;
-    let contractNudges = 0;
     let contextOverflowRetryUsed = false;
     // Set when the hard iteration-cap break below fires. Consumed at the final
     // return to tag terminationReason='iteration_cap' so a worker that exhausts
@@ -240,14 +238,11 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
     const _crossTurnCalls = new Map();
     const _CROSS_TURN_CAP = 500;
     let _dedupStubTotal = 0;
-    // Step 3: worker soft-cap wrap-up state.
-    const _softCapEnabled = isWorkerSoftCapSession(sessionRef);
-    let _softCapActive = false;      // tools disabled + wrap-up injected
-    let _softCapGraceTurns = 0;      // text-only grace turns consumed (max 2)
-    let _terminatedBySoftCap = false;
     // Hard-cap final-answer turn: one tool-less wrap-up turn granted when the
     // hard iteration cap fires, so the session ends with text, not empty.
     let _capFinalTurnUsed = false;
+    // True while the granted hard-cap final turn is active (no tool defs).
+    let _capFinalToolsDisabled = false;
     // Completion-first steering ladder controller. Owns the (cumulative) level-1
     // fire count, the all-read-only / serial-single / same-file-grep streaks,
     // and the level-2 latch. Threaded via live getters so it reads the loop's
@@ -257,7 +252,6 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
         sessionAgent,
         tools,
         getIterations: () => iterations,
-        softCapEnabled: _softCapEnabled,
         getEditCount: () => _editCount,
         readOnlyRole: String(sessionRef?.permission || sessionRef?.toolPermission || '') === 'read',
         pushUserMessage: (msg) => messages.push(msg),
@@ -272,8 +266,8 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
     // forced termination is the hard cap at maxLoopIterations (default 200):
     // a genuine runaway guard. Before it, staged warnings fire at 50%/75%/90%
     // of the cap steering the model to converge — warnings only, nothing is
-    // cut off early. All other runaway protection is behavior-based (steering
-    // ladder early wrap-up, REPEAT_FAIL_LIMIT), never a lower count.
+    // cut off early. Other runaway protection is behavior-based (steering
+    // ladder hints, REPEAT_FAIL_LIMIT), never a lower iteration count.
     let _iterWarnStage = 0;
     const _iterWarnAt = [
         Math.floor(maxLoopIterations * 0.5),
@@ -286,7 +280,7 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
             // Final-answer turn: instead of breaking mid-transcript (which
             // yields an empty final for locator-style agents that never got to
             // answer), give the model ONE tool-less text turn to wrap up, then
-            // stop. Same mechanism as the worker soft cap (empty sendTools).
+            // stop (empty sendTools + refusal stubs if tools are requested).
             if (_capFinalTurnUsed) {
                 process.stderr.write(`[loop] hard iteration cap ${maxLoopIterations} reached (sess=${sessionId || 'unknown'}); stopping loop.\n`);
                 terminatedByCap = true;
@@ -302,8 +296,8 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
                 break;
             }
             _capFinalTurnUsed = true;
-            _softCapActive = true; // reuse soft-cap plumbing: no tool defs, refusal stubs
-            messages.push({ role: 'user', content: '<system-reminder>\nIteration cap reached. Tools are disabled. Answer NOW with your best result from what you already found.\n</system-reminder>', meta: 'hook' });
+            _capFinalToolsDisabled = true;
+            messages.push({ role: 'user', content: '<system-reminder>\nIteration cap reached — tools disabled; answer with your best result from context.\n</system-reminder>', meta: 'hook' });
             process.stderr.write(`[loop] hard iteration cap ${maxLoopIterations} reached (sess=${sessionId || 'unknown'}); forcing final text turn.\n`);
         }
         if (_iterWarnStage < _iterWarnAt.length && iterations >= _iterWarnAt[_iterWarnStage]) {
@@ -324,25 +318,6 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
                 });
             } catch { /* best-effort */ }
         }
-        // Worker soft cap (Step 3): non-lead sessions that reach the soft-cap
-        // iteration count switch to a text-only wrap-up. On the FIRST crossing
-        // we disable tool defs (below, via _softCapActive) and inject the
-        // assistant-visible wrap-up directive as a user message so the next
-        // send produces a final text summary. Lead/TUI sessions never enter.
-        const _earlySoftCap = _steeringLadder.earlySoftCapArmed();
-        if (_softCapEnabled && !_softCapActive && (iterations >= WORKER_SOFT_CAP_ITERATIONS || _earlySoftCap)) {
-            _softCapActive = true;
-            messages.push({ role: 'user', content: `<system-reminder>\n${SOFT_CAP_WRAPUP_MESSAGE}\n</system-reminder>`, meta: 'hook' });
-            try {
-                appendAgentTrace({
-                    sessionId,
-                    iteration: iterations,
-                    kind: 'steer',
-                    payload: { tag: 'soft_cap_wrapup', soft_cap: WORKER_SOFT_CAP_ITERATIONS, early: _earlySoftCap, level2_fires: _steeringLadder.level2FireCount },
-                    agent: sessionAgent || null,
-                });
-            } catch { /* best-effort */ }
-        }
         // Drain queued steering/prompts BEFORE the
         // pre-send compact check. The compact decision must see the exact
         // message set that the next provider.send would receive, including
@@ -757,9 +732,9 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
         } else {
             delete opts.toolChoice;
         }
-        // Soft-cap wrap-up (Step 3a): once active, send NO tool definitions so
-        // the provider can only emit text. Overrides the forced-first-tool path.
-        const sendTools = _softCapActive
+        // Hard-cap final turn: send NO tool definitions so the provider can
+        // only emit text. Overrides the forced-first-tool path.
+        const sendTools = _capFinalToolsDisabled
             ? []
             : (forcedFirstToolDef && toolCallsTotal === 0 ? [forcedFirstToolDef] : tools);
         // Eager-dispatch queue: when the provider streams a tool-call event,
@@ -934,7 +909,11 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
             if (
                 sendErr?.streamStalled === true
                 && sendErr.pendingToolUse !== true
-                && sendErr.unsafeToRetry !== true
+                // NOT gated on unsafeToRetry: live-text stalls stamp
+                // unsafeToRetry=true (replay would double-render), but
+                // ACCEPTING the already-streamed partial is exactly the safe
+                // move (CC rule). Only an emitted tool call blocks acceptance.
+                && sendErr.emittedToolCall !== true
                 && typeof sendErr.partialContent === 'string'
                 && sendErr.partialContent.trim().length > 0
                 && !(Array.isArray(sendErr.partialToolCalls) && sendErr.partialToolCalls.length > 0)
@@ -1138,14 +1117,14 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
             } catch { /* best-effort — never break the loop */ }
         }
         // No tool calls. For PUBLIC agents, the agent contract
-        // (rules/agent/00-common.md) requires either a tool call or a
-        // `<final-answer>` wrapped reply.
+        // (rules/agent/00-core.md) requires either a tool call or a final
+        // handoff text (fragments).
         // A text-only turn without those tags violates the contract (e.g.
         // Opus 4.6 emits 'Now I'll polish…' preamble before its first tool
         // call) and used to leave the session idle until the idle sweep
-        // collected it. Re-prompt the worker with a contract reminder; cap
-        // at 2 nudges so a model that never complies still terminates the
-        // loop. Hidden roles (cycle1-agent / cycle2-agent / explorer /
+        // collected it. Re-prompt the worker with a contract reminder on each
+        // empty turn (hard iteration cap bounds total turns). Hidden roles
+        // (cycle1-agent / cycle2-agent / explorer /
         // scheduler-task / webhook-handler) are exempt:
         // their own role rules define a different output contract (pipe-
         // separated chunker output, structured pipe-format, etc.) and a
@@ -1162,9 +1141,7 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
             //   - has content + non-hidden role → valid final, break.
             //   - empty content + hidden role → contract allows text-only
             //     terminal turn, break.
-            //   - empty content + non-hidden role → one soft nudge. Repeated
-            //     reminders waste turns and fragment the working context, so
-            //     the second empty turn is accepted as terminal.
+            //   - empty content + non-hidden role → contract nudge, continue.
             const hasContent = typeof response.content === 'string' && response.content.trim().length > 0;
             const isHidden = HIDDEN_AGENT_NAMES.has(sessionAgent);
             const stopReason = response.stopReason ?? response.stop_reason ?? null;
@@ -1181,13 +1158,11 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
                 continue;
             }
             if (!hasContent && !isHidden) {
-                if (contractNudges >= 1) break;
-                contractNudges += 1;
                 let nudgeMsg;
                 if (isIncompleteStop) {
-                    nudgeMsg = `[mixdog-runtime] Previous turn ended mid-synthesis (stopReason=${stopReason}) with empty content. Continue — emit <final-answer>...</final-answer> with your synthesis so far, or call more tools to finish.`;
+                    nudgeMsg = `[mixdog-runtime] Previous turn ended mid-synthesis (stopReason=${stopReason}) with empty content. Continue — emit your final handoff (fragments, file:line) with your synthesis so far, or call more tools to finish.`;
                 } else {
-                    nudgeMsg = '[mixdog-runtime] Your previous response was empty (no <final-answer> tag and no tool call). Either emit your final answer wrapped in <final-answer>...</final-answer> tags, or continue with tool calls. Do not return an empty turn.';
+                    nudgeMsg = '[mixdog-runtime] Your previous response was empty (no handoff text and no tool call). Either emit your final handoff text now, or continue with tool calls. Do not return an empty turn.';
                 }
                 messages.push({ role: 'user', content: nudgeMsg });
                 continue;
@@ -1232,34 +1207,17 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
                 : {}),
         };
         messages.push(_assistantTurnMsg);
-        // Soft-cap wrap-up (Step 3b): tools are disabled but the model still
-        // emitted tool calls. Do NOT execute them — push a refusal stub for
-        // each (after the assistant turn is appended so tool_use/tool_result
-        // pairing stays valid) and consume a grace turn. After 2 grace turns,
-        // terminate via the soft-cap path so a model that never complies stops.
-        if (_softCapActive) {
+        // Hard-cap final turn: tools are disabled but the model still emitted
+        // tool calls. Do NOT execute them — push a refusal stub for each.
+        if (_capFinalToolsDisabled) {
             for (const _c of calls) {
                 pushToolResultMessage({
                     role: 'tool',
-                    content: SOFT_CAP_REFUSAL_STUB,
+                    content: ITERATION_CAP_REFUSAL_STUB,
                     toolCallId: _c.id,
                     toolKind: 'error',
                 });
             }
-            _softCapGraceTurns += 1;
-            try {
-                appendAgentTrace({
-                    sessionId,
-                    iteration: iterations,
-                    kind: 'steer',
-                    payload: { tag: 'soft_cap_wrapup', grace_turn: _softCapGraceTurns },
-                    agent: sessionAgent || null,
-                });
-            } catch { /* best-effort */ }
-            if (_softCapGraceTurns >= 2) {
-                _terminatedBySoftCap = true;
-                break;
-            }
             if (sessionId) updateSessionStage(sessionId, 'connecting');
             continue;
         }
@@ -1851,10 +1809,9 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
             }
         }
         // Completion-first steering hints (missed-parallelism / all-read-only /
-        // serial-rewording). At most ONE hint per turn (priority: soft-cap >
-        // level-2 > same-file grep > level-1); soft-cap active suppresses all.
-        // The ladder controller owns the cumulative counters and streaks.
-        _steeringLadder.emitPostBatchSteering(calls, _softCapActive);
+        // serial-rewording). At most ONE hint per turn. The ladder controller
+        // owns the cumulative counters and streaks.
+        _steeringLadder.emitPostBatchSteering(calls, false);
         // Mid-turn steering is drained at the next loop's pre-send point,
         // AFTER any auto-compact pass. Draining here would put the steering
         // user turn after the fresh tool results before compaction runs; then
@@ -1868,8 +1825,6 @@ export async function agentLoop(provider, messages, model, tools, onToolCall, cw
     // "completed" (see classifyTerminationReason in ./loop/termination.mjs).
     const terminationReason = classifyTerminationReason(response, {
         terminatedByCap,
-        terminatedBySoftCap: _terminatedBySoftCap,
-        softCapActive: _softCapActive,
         sessionAgent,
     });
     return {

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

@@ -12,10 +12,10 @@ import {
     effectiveBudget as compactEffectiveBudget,
     compactTypeIsRecallFastTrack,
     compactTypeIsSemantic,
-    drainSessionCycle1,
 } from '../compact.mjs';
 import { estimateMessagesTokens, estimateRequestReserveTokens, estimateTranscriptContextUsage, resolveCompactBufferRatio } from '../context-utils.mjs';
 import { executeInternalTool } from '../../internal-tools.mjs';
+import { truncateToKb, DIGEST_DEFAULT_MAX_KB } from '../loop/recall-fasttrack.mjs';
 import {
     positiveContextWindow,
     compactTriggerForSession,
@@ -81,52 +81,40 @@ async function runRecallFastTrackForSession(session, messages, opts = {}) {
     } catch (err) {
         try { process.stderr.write(`[session] recall-fasttrack ingest skipped (sess=${sessionId}): ${err?.message || err}\n`); } catch {}
     }
-    const dumpArgs = {
-        action: 'dump_session_roots',
-        sessionId,
-        includeRaw: true,
-        limit: positiveContextWindow(session?.compaction?.recallChunkLimit ?? session?.compaction?.recallLimit) || hydrateLimit,
-    };
-    const runTool = (name, args) => executeInternalTool(name, args, callerCtx);
-    let recallText = await executeInternalTool('memory', dumpArgs, callerCtx);
-    let cycle1Text = '';
+    // Digest injection (mirrors loop/recall-fasttrack.mjs): no dump + cycle1
+    // drain — that ran memory-pipeline LLM chunking inside the compaction.
+    // ingest_session above stored the full transcript; background cycle1
+    // chunks it on its own schedule and recall serves anything beyond the
+    // digest.
+    let recallText = '';
     let cycle1Error = null;
-    const hasRawRows = /(?:^|\n)# raw_pending\s+\d+\s+id=/i.test(String(recallText || ''));
-    if (hasRawRows) {
-        try {
-            // Drain this session's cycle1 in window×concurrency units until no
-            // raw rows remain, so the injected root is fully chunked rather than
-            // carrying the unprocessed transcript tail (single-pass left raw in).
-            const drained = await drainSessionCycle1(runTool, {
-                sessionId,
-                dumpArgs,
-                deadlineMs: positiveContextWindow(session?.compaction?.recallCycle1DeadlineMs) || 120_000,
-                maxPasses: positiveContextWindow(session?.compaction?.recallCycle1MaxPasses) || 0,
-                cycleArgs: {
-                    min_batch: 1,
-                    session_cap: 1,
-                    batch_size: positiveContextWindow(session?.compaction?.recallCycle1BatchSize) || 100,
-                    rows_per_session: positiveContextWindow(session?.compaction?.recallRowsPerSession) || 100,
-                    window_size: positiveContextWindow(session?.compaction?.recallWindowSize) || 20,
-                    concurrency: positiveContextWindow(session?.compaction?.recallConcurrency) || 5,
-                },
-            });
-            recallText = drained.recallText;
-            cycle1Text = drained.cycle1Text;
-            if (drained.error) {
-                cycle1Error = drained.error;
-                try { process.stderr.write(`[session] recall-fasttrack cycle1 error (sess=${sessionId}): ${drained.error}\n`); } catch {}
-            }
-            if (drained.rawRemaining > 0) {
-                try { process.stderr.write(`[session] recall-fasttrack drained passes=${drained.passes} rawRemaining=${drained.rawRemaining} (sess=${sessionId})\n`); } catch {}
-            }
-        } catch (err) {
-            try { process.stderr.write(`[session] recall-fasttrack cycle1 skipped (sess=${sessionId}): ${err?.message || err}\n`); } catch {}
-        }
-    } else {
-        cycle1Text = 'cycle1: skipped (session chunks already hydrated)';
+    try {
+        const browsed = await executeInternalTool('memory', {
+            action: 'search',
+            sessionId,
+            limit: positiveContextWindow(session?.compaction?.recallDigestLimit) || 30,
+            includeMembers: true,
+            includeRaw: true,
+        }, callerCtx);
+        recallText = typeof browsed === 'string' ? browsed : String(browsed?.text ?? browsed ?? '');
+    } catch (err) {
+        cycle1Error = err?.message || String(err);
+        try { process.stderr.write(`[session] recall-digest browse failed (sess=${sessionId}): ${err?.message || err}\n`); } catch {}
     }
-    return { query, querySha, cycle1Error, recallText: [`session_id=${sessionId}`, cycle1Text, recallText].map(v => String(v || '').trim()).filter(Boolean).join('\n\n') };
+    return {
+        query,
+        querySha,
+        cycle1Error,
+        recallText: [
+            `session_id=${sessionId}`,
+            `Full history is in memory — use the recall tool for details beyond this digest.`,
+            // Same byte cap as the loop digest path (recallDigestMaxKb,
+            // default = shared tool-output limit) — without it the memory
+            // renderer bounds the browse at ~200 rows × 1000 chars, letting a
+            // manual//clear compact process a far larger digest than loop's.
+            truncateToKb(recallText, positiveContextWindow(session?.compaction?.recallDigestMaxKb) || DIGEST_DEFAULT_MAX_KB),
+        ].map(v => String(v || '').trim()).filter(Boolean).join('\n\n'),
+    };
 }
 // Element-identity change detection (same approach as loop.mjs messagesArrayChanged): two
 // arrays are "unchanged" only when same length AND every slot is the same object

package/src/runtime/agent/orchestrator/session/manager/pending-messages.mjs

@@ -4,10 +4,13 @@ import { join } from 'path';
 import { resolvePluginData } from '../../../../shared/plugin-paths.mjs';
 import { updateJsonAtomicSync } from '../../../../shared/atomic-file.mjs';
 import { promptContentText, isInternalRuntimeNotificationText } from './prompt-utils.mjs';
+import { loadSession } from '../store.mjs';
 
 const _sessionPendingMessages = new Map();
 const PENDING_MESSAGES_FILE = 'session-pending-messages.json';
 const PENDING_MESSAGES_MODE = 0o600;
+const PENDING_ORPHAN_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+const PENDING_ORPHAN_GRACE_MS = 60 * 60 * 1000;
 const _pendingPersistBuffers = new Map();
 let _pendingPersistImmediate = null;
 
@@ -19,25 +22,58 @@ function isValidPendingSessionId(sessionId) {
     return typeof sessionId === 'string' && /^[A-Za-z0-9_-]+$/.test(sessionId);
 }
 
+function isTuiSteeringPendingKey(sessionId) {
+    return typeof sessionId === 'string' && sessionId.startsWith('tui_');
+}
+
+function normalizeTuiSteeringQueueEntry(entry) {
+    if (typeof entry === 'string') {
+        const text = entry.trim();
+        return text || null;
+    }
+    if (!entry || typeof entry !== 'object') return null;
+    if (typeof entry.text === 'string' && entry.text.trim()) {
+        const text = entry.text.trim();
+        const id = typeof entry.id === 'string' && entry.id.trim() ? entry.id.trim() : null;
+        return id ? { id, text } : text;
+    }
+    return null;
+}
+
 function normalizePendingStore(raw) {
     const sessions = raw && typeof raw === 'object' && raw.sessions && typeof raw.sessions === 'object'
         ? raw.sessions
         : {};
-    const out = { version: 1, updatedAt: Date.now(), sessions: {} };
+    const storeUpdatedAt = Number(raw?.updatedAt) || Date.now();
+    const touchedRaw = raw && typeof raw === 'object' && raw.sessionTouchedAt && typeof raw.sessionTouchedAt === 'object'
+        ? raw.sessionTouchedAt
+        : {};
+    const out = { version: 1, updatedAt: storeUpdatedAt, sessions: {}, sessionTouchedAt: {} };
     for (const [sid, value] of Object.entries(sessions)) {
         if (!isValidPendingSessionId(sid) || !Array.isArray(value)) continue;
-        const q = value
-            .map((entry) => {
-                if (typeof entry === 'string') return entry;
-                if (entry && typeof entry === 'object' && typeof entry.message === 'string') return entry.message;
-                return '';
-            })
-            .filter(Boolean);
-        if (q.length > 0) out.sessions[sid] = q;
+        const q = isTuiSteeringPendingKey(sid)
+            ? value.map(normalizeTuiSteeringQueueEntry).filter(Boolean)
+            : value
+                .map((entry) => {
+                    if (typeof entry === 'string') return entry;
+                    if (entry && typeof entry === 'object' && typeof entry.message === 'string') return entry.message;
+                    return '';
+                })
+                .filter(Boolean);
+        if (q.length > 0) {
+            out.sessions[sid] = q;
+            const touched = Number(touchedRaw[sid]);
+            out.sessionTouchedAt[sid] = Number.isFinite(touched) && touched > 0 ? touched : storeUpdatedAt;
+        }
     }
     return out;
 }
 
+function touchPendingSessionEntry(next, sessionId, now = Date.now()) {
+    if (!next.sessionTouchedAt || typeof next.sessionTouchedAt !== 'object') next.sessionTouchedAt = {};
+    next.sessionTouchedAt[sessionId] = now;
+}
+
 function normalizePendingMessageEntry(entry) {
     if (typeof entry === 'string') {
         const text = entry.trim();
@@ -86,7 +122,9 @@ function persistPendingMessages(sessionId, messages) {
             const q = Array.isArray(next.sessions[sessionId]) ? next.sessions[sessionId] : [];
             q.push(...persistedMessages);
             next.sessions[sessionId] = q;
-            next.updatedAt = Date.now();
+            const now = Date.now();
+            next.updatedAt = now;
+            touchPendingSessionEntry(next, sessionId, now);
             depth = q.length;
             return next;
         }, { compact: true, lock: true, mode: PENDING_MESSAGES_MODE, fsync: false });
@@ -143,6 +181,7 @@ function drainPersistedPendingMessages(sessionId) {
             drained = q.filter((m) => typeof m === 'string' && m.length > 0);
             if (drained.length === 0) return undefined;
             delete next.sessions[sessionId];
+            if (next.sessionTouchedAt) delete next.sessionTouchedAt[sessionId];
             next.updatedAt = Date.now();
             return next;
         }, { compact: true, lock: true, mode: PENDING_MESSAGES_MODE, fsync: false });
@@ -152,6 +191,75 @@ function drainPersistedPendingMessages(sessionId) {
     return drained;
 }
 
+function clearPersistedPendingMessages(sessionId) {
+    if (!isValidPendingSessionId(sessionId)) return;
+    try {
+        updateJsonAtomicSync(pendingMessagesPath(), (raw) => {
+            const next = normalizePendingStore(raw);
+            if (!Object.prototype.hasOwnProperty.call(next.sessions, sessionId)) return undefined;
+            delete next.sessions[sessionId];
+            if (next.sessionTouchedAt) delete next.sessionTouchedAt[sessionId];
+            next.updatedAt = Date.now();
+            return next;
+        }, { compact: true, lock: true, mode: PENDING_MESSAGES_MODE, fsync: false });
+    } catch (err) {
+        try { process.stderr.write(`[session] pending-message clear failed sessionId=${sessionId}: ${err?.message || err}\n`); } catch {}
+    }
+}
+
+function shouldEvictPendingSession(sessionId, ttlMs, entryTouchedAt, now = Date.now()) {
+    if (isTuiSteeringPendingKey(sessionId)) {
+        const entryTouch = Number(entryTouchedAt) || 0;
+        if (entryTouch <= 0) return false;
+        return (now - entryTouch) > ttlMs;
+    }
+    const session = loadSession(sessionId);
+    if (session) {
+        const touched = Math.max(
+            Number(session.updatedAt) || 0,
+            Number(session.lastHeartbeatAt) || 0,
+            Number(session.createdAt) || 0,
+        );
+        return touched > 0 && (now - touched) > ttlMs;
+    }
+    const entryTouch = Number(entryTouchedAt) || 0;
+    return entryTouch > 0 && (now - entryTouch) > PENDING_ORPHAN_GRACE_MS;
+}
+
+export function sweepOrphanedPendingMessages({ ttlMs = PENDING_ORPHAN_TTL_MS } = {}) {
+    const now = Date.now();
+    const removed = [];
+    try {
+        updateJsonAtomicSync(pendingMessagesPath(), (raw) => {
+            const next = normalizePendingStore(raw);
+            const ids = Object.keys(next.sessions);
+            if (ids.length === 0) return undefined;
+            for (const sid of ids) {
+                const entryTouchedAt = next.sessionTouchedAt?.[sid];
+                if (shouldEvictPendingSession(sid, ttlMs, entryTouchedAt, now)) {
+                    delete next.sessions[sid];
+                    if (next.sessionTouchedAt) delete next.sessionTouchedAt[sid];
+                    removed.push(sid);
+                }
+            }
+            if (removed.length === 0) return undefined;
+            next.updatedAt = now;
+            return next;
+        }, { compact: true, lock: true, mode: PENDING_MESSAGES_MODE, fsync: false });
+    } catch (err) {
+        try { process.stderr.write(`[session] pending-message sweep failed: ${err?.message || err}\n`); } catch {}
+        return 0;
+    }
+    if (removed.length > 0) {
+        try {
+            process.stderr.write(
+                `[session] pending-message sweep: removed ${removed.length} stale/orphan queue(s) (ttl=${Math.round(ttlMs / 86400000)}d) (${removed.slice(0, 5).join(', ')}${removed.length > 5 ? `, +${removed.length - 5} more` : ''})\n`,
+            );
+        } catch { /* ignore */ }
+    }
+    return removed.length;
+}
+
 function modelVisiblePendingMessages(messages) {
     return (Array.isArray(messages) ? messages : [])
         .map(pendingMessageQueueEntry)
@@ -229,7 +337,20 @@ export function drainPendingMessages(sessionId) {
 
 // Cleanup hook for closeSession — drop the in-memory queue and buffered-persist
 // entry so both Maps do not accumulate one entry per closed session.
-export function _dropPendingMessageState(id) {
+export function _dropPendingMessageState(id, { clearPersisted = true } = {}) {
+    if (!clearPersisted) {
+        const buffered = _pendingPersistBuffers.get(id);
+        if (buffered?.length) {
+            try { persistPendingMessages(id, buffered); } catch { /* ignore */ }
+        }
+    }
     try { _sessionPendingMessages.delete(id); } catch { /* ignore */ }
     try { _pendingPersistBuffers.delete(id); } catch { /* ignore */ }
+    if (clearPersisted) {
+        try { clearPersistedPendingMessages(id); } catch { /* ignore */ }
+    }
 }
+
+setImmediate(() => {
+    try { sweepOrphanedPendingMessages(); } catch { /* ignore */ }
+});

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

@@ -95,6 +95,7 @@ const AGENT_STRING_PERMISSION_READ_WRITE_ALLOW = Object.freeze([
     'grep',
     'read',
     'apply_patch',
+    'shell',
     'explore',
     'search',
     'web_fetch',
@@ -131,7 +132,7 @@ export function applyToolPermissionNarrowing(tools, toolPermission, warnRole = n
     return tools;
 }
 
-function recursiveWrapperToolNameForPublicAgent(agent) {
+export function recursiveWrapperToolNameForPublicAgent(agent) {
     if (!agent) return null;
     const key = String(agent).trim();
     if (key === 'explore') return 'explore';
@@ -161,11 +162,11 @@ export function finalizeSessionToolList(tools, {
         const denySet = new Set(callerDeny.map(n => n.toLowerCase()));
         out = out.filter(t => !denySet.has(String(t?.name || '').toLowerCase()));
     }
-    const recursiveDeny = ownerIsAgent ? recursiveWrapperToolNameForPublicAgent(resolvedAgent) : null;
-    if (recursiveDeny) {
-        const deny = recursiveDeny.toLowerCase();
-        out = out.filter(t => String(t?.name || '').toLowerCase() !== deny);
-    }
+    // NOTE: the self-wrapper anti-recursion deny is intentionally NOT applied
+    // here. Stripping a role's own wrapper tool (e.g. explore) from the schema
+    // would fork the read-only cache group into one shard per wrapper role.
+    // The bundle stays bit-identical; recursion is broken at call time in
+    // pre-dispatch-deny.mjs (recursiveWrapperToolNameForPublicAgent) instead.
     if (ownerIsAgent) {
         out = out.filter(t => !t?.annotations?.agentHidden);
         out = orderSessionTools(out);

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

@@ -72,6 +72,7 @@ import {
     enqueuePendingMessage,
     drainPendingMessages,
     _dropPendingMessageState,
+    sweepOrphanedPendingMessages,
 } from './manager/pending-messages.mjs';
 import {
     bumpUsageMetricsTurnId,
@@ -649,24 +650,37 @@ export function createSession(opts) {
     const roleRules = skipAgentRules ? '' : (ownerIsAgent ? _buildAgentRules(agentRulesProfile) : _buildLeadRules());
     const metaContext = skipAgentRules ? '' : (ownerIsAgent ? '' : _buildLeadMetaContext());
     const roleSpecific = ownerIsAgent && !skipAgentRules ? _buildAgentSpecific(agentRulesAgent) : '';
-    // Agent sessions must not inherit role/profile/preset tool narrowing: Pool
-    // B and Pool C share one bit-identical tool schema to maximize provider
-    // prefix reuse, and permission differences are enforced only at call time. Raw
-    // non-agent callers keep the historical profile.tools / preset.tools
-    // behaviour.
-    const toolSpec = ownerIsAgent
-        ? 'full'
-        : (Array.isArray(profile?.tools) ? profile.tools : toolPreset);
-
-    // Prompt permission is metadata only. Preset tool restrictions must NOT
-    // enter the prompt, or they split the shared agent cache tail; they map
-    // to toolPermission below and are enforced only at call time.
-    const permission = opts.permission
-        || null;
+    // Prompt permission is metadata for the write bundle, but a read-only role
+    // is stamped BEFORE the toolSpec decision so its schema ships the narrowed
+    // bundle. Resolve toolPermission (with profile/preset fallbacks) first, and
+    // let the stored/logged `permission` reflect that resolved value — not just
+    // opts.permission — so diagnostics show the effective read/write class.
     const toolPermission = opts.permission
         || profile?.permission
         || permissionFromToolSpec(toolPreset)
         || null;
+    const permission = toolPermission;
+
+    // Agent sessions do not inherit arbitrary role/profile/preset tool
+    // narrowing — that would shatter provider prefix reuse into one shard per
+    // role. Instead they collapse onto exactly TWO stable, bit-identical
+    // bundles, one cache group each:
+    //   - read-only roles (reviewer / debugger / hidden retrieval, i.e. any
+    //     session resolving to permission 'read') -> 'readonly' bundle:
+    //     read builtins (code_graph/find/glob/list/grep/read) + retrieval
+    //     (explore/search/web_fetch/Skill), no apply_patch/shell/task, no
+    //     MCP-write. applyToolPermissionNarrowing('read') below trims the
+    //     bundle to AGENT_STRING_PERMISSION_READ_ALLOW so the final surface is
+    //     bit-identical across these roles regardless of MCP registry state.
+    //   - write roles (worker / heavy-worker / maintainer / …) -> 'full'
+    //     bundle: the historical full schema.
+    // Call-time permission enforcement below is UNCHANGED (defense in depth):
+    // applyToolPermissionNarrowing still runs so the bundle choice never
+    // widens effective access.
+    const isReadOnlyAgentBundle = ownerIsAgent && toolPermission === 'read';
+    const toolSpec = ownerIsAgent
+        ? (isReadOnlyAgentBundle ? 'readonly' : 'full')
+        : (Array.isArray(profile?.tools) ? profile.tools : toolPreset);
     let toolsForRouting = resolveSessionTools(toolSpec, skills, { ownerIsAgentSession: ownerIsAgent });
     // Fail-closed permission intersection: when a session declares an explicit
     // object-form permission, intersect the
@@ -2069,7 +2083,7 @@ export function closeSession(id, reason = 'manual', opts = {}) {
     // Drop the in-memory pending-message queue and any buffered-persist entry
     // for this session — otherwise both Maps accumulate one entry per closed
     // session for the life of the mcp-server.
-    _dropPendingMessageState(id);
+    _dropPendingMessageState(id, { clearPersisted: tombstone });
     // 4. Defer runtime map clear to next tick so any settling askSession can
     //    observe `closed=true` / bumped generation before we yank the entry.
     //    Disk tombstone remains — that's what blocks resurrection.
@@ -2209,6 +2223,7 @@ function hasActiveRuntimeWork() {
 
 function _runCleanupCycle() {
     if (hasActiveRuntimeWork()) return;
+    sweepOrphanedPendingMessages();
     sweepIdleSessions({ includeTombstones: true });
 }