mixdog 0.9.11 → 0.9.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mixdog",
-  "version": "0.9.11",
+  "version": "0.9.13",
   "private": false,
   "type": "module",
   "description": "Standalone mixdog coding-agent CLI/TUI workspace.",

package/scripts/internal-comms-bench.mjs

@@ -29,6 +29,7 @@ const PLUGIN_ROOT = join(REPO_ROOT, 'src');
 const HEADLESS = pathToFileURL(resolve(__dir, '../src/headless-role.mjs')).href;
 
 const RULE_FILES = [
+  'rules/agent/00-core.md',
   'rules/agent/00-common.md',
   'agents/worker/AGENT.md',
   'agents/heavy-worker/AGENT.md',

package/scripts/internal-comms-smoke.mjs

@@ -38,15 +38,19 @@ assert(/authoritative/i.test(flat(leadBrief)), 'lead-brief.md: brief must state
 assert(/lead brief contract/i.test(flat(workflow)), 'WORKFLOW.md: must defer to the lead brief contract');
 assert(!BRIEF_FIELDS.every((field) => workflow.includes(field)), 'WORKFLOW.md: must not duplicate the full brief field list');
 
-// --- Agent handoff contract (00-common.md) ---------------------------------
-const common = readSrc('rules', 'agent', '00-common.md');
-assert(/minimum characters, maximum information/i.test(flat(common)), '00-common: handoff must state token-optimized principle');
-assert(/fragments/i.test(common), '00-common: handoff must require fragments');
-assert(/file:line/i.test(common), '00-common: handoff must anchor evidence to file:line');
-assert(/Banned as pure cost/i.test(flat(common)), '00-common: handoff must list banned cost items');
+// --- Agent handoff contract (00-core.md) -----------------------------------
+const core = readSrc('rules', 'agent', '00-core.md');
+assert(/minimum characters, maximum information/i.test(flat(core)), '00-core: handoff must state token-optimized principle');
+assert(/fragments/i.test(core), '00-core: handoff must require fragments');
+assert(/file:line/i.test(core), '00-core: handoff must anchor evidence to file:line');
+assert(/Banned as pure cost/i.test(flat(core)), '00-core: handoff must list banned cost items');
 for (const banned of ['headings', 'tables', 'narration', 'raw logs', 'next-checks']) {
-  assert(common.toLowerCase().includes(banned), `00-common: banned list missing ${banned}`);
+  assert(core.toLowerCase().includes(banned), `00-core: banned list missing ${banned}`);
 }
+const common = readSrc('rules', 'agent', '00-common.md');
+assert(/Public Agent Constraints/i.test(common), '00-common: must be titled public-only constraints');
+assert(/git operations deferred to Lead/i.test(common), '00-common: must refuse git/Ship');
+assert(/Overflow goes to a file/i.test(common), '00-common: must keep overflow-to-file rule');
 
 // --- Per-role output contracts --------------------------------------------
 const roles = {

package/src/lib/rules-builder.cjs

@@ -24,7 +24,8 @@
  *   - lead/lead-brief.md            — Lead brief contract (agent handoff briefs)
  *   - lead/01-02                     — Lead general / channels
  *   - output-styles/<name>.md        — Lead output style, selected by config outputStyle
- *   - agent/00-common.md             — agent common behavior + universal worker contract (BP2)
+ *   - agent/00-core.md               — universal agent constraints (BP2, all profiles)
+ *   - agent/00-common.md             — public-agent-only extras (BP2 full profile)
  *   - agent/10..50-*.md              — per-hidden-agent bodies (consumed by loadScopedRoleInstructions)
  *
  * Core memory snapshot is injected separately from the memory worker (pgdata)
@@ -361,11 +362,13 @@ function buildAgentInjectionContent({ PLUGIN_ROOT, DATA_DIR }) {
 }
 
 function buildAgentRoleContent({ PLUGIN_ROOT, profile = 'full' }) {
+  const AGENT_DIR = path.join(PLUGIN_ROOT, 'rules', 'agent');
   if (String(profile || 'full') === 'retrieval') {
-    return buildAgentRetrievalInjectionContent();
+    return buildAgentRetrievalInjectionContent({ PLUGIN_ROOT });
   }
-  const AGENT_DIR = path.join(PLUGIN_ROOT, 'rules', 'agent');
-  return readOptional(path.join(AGENT_DIR, '00-common.md'));
+  const core = readOptional(path.join(AGENT_DIR, '00-core.md'));
+  const common = readOptional(path.join(AGENT_DIR, '00-common.md'));
+  return [core, common].filter(Boolean).join('\n\n');
 }
 
 /**
@@ -376,18 +379,19 @@ function buildAgentRoleContent({ PLUGIN_ROOT, profile = 'full' }) {
  *
  * @returns {string}
  */
-function buildAgentRetrievalInjectionContent() {
-  return [
+function buildAgentRetrievalInjectionContent({ PLUGIN_ROOT }) {
+  const AGENT_DIR = path.join(PLUGIN_ROOT, 'rules', 'agent');
+  const core = readOptional(path.join(AGENT_DIR, '00-core.md'));
+  const parts = [
     '# Tool Use',
     '',
     '- Batch independent read-only lookups in the same tool turn.',
     '- Use code_graph for symbols/dependencies, grep for exact text, find/glob/list for files, and read only known paths/windows.',
     '',
-    '# Agent Constraints',
-    '',
-    '- Read-only retrieval role: do not edit files, run shell, or use git.',
-    '- Follow the role output contract exactly; do not add handoff prose.',
-  ].join('\n');
+  ];
+  if (core) parts.push(core.trim());
+  parts.push('', '- Read-only retrieval role: do not edit files, run shell, or use git.');
+  return parts.join('\n');
 }
 
 /**

package/src/mixdog-session-runtime.mjs

@@ -216,6 +216,7 @@ import {
   TOOL_SEARCH_TOOL,
   CWD_TOOL,
   SKILL_TOOL,
+  SESSION_MANAGE_TOOL,
   LEAD_DISALLOWED_TOOLS,
   applyStandaloneToolDefaults,
 } from './session-runtime/tool-defs.mjs';
@@ -480,6 +481,9 @@ export async function createMixdogSessionRuntime({
   let sessionCreatePromise = null;
   let currentCwd = cwd;
   let sessionNeedsCwdRefresh = false;
+  // session_manage tool: reset request scheduled by the model mid-turn,
+  // consumed by the TUI engine at turn end ('clear' | 'compact_clear').
+  let pendingSessionReset = null;
   let closeRequested = false;
   const warmupTimers = {
     providerSetupWarmupTimer: null,
@@ -922,6 +926,7 @@ export async function createMixdogSessionRuntime({
     TOOL_SEARCH_TOOL,
     SKILL_TOOL,
     CWD_TOOL,
+    SESSION_MANAGE_TOOL,
     EXPLORE_TOOL,
     ...(searchToolDefs?.TOOL_DEFS || []).filter((tool) => tool?.name === 'search' || tool?.name === 'web_fetch'),
     ...(memoryToolDefs?.TOOL_DEFS || []).filter((tool) => tool?.name === 'recall' || tool?.name === 'memory'),
@@ -1018,6 +1023,29 @@ export async function createMixdogSessionRuntime({
         }
         return JSON.stringify({ cwd: currentCwd, sessionId: session?.id || null }, null, 2);
       }
+      if (name === 'session_manage') {
+        // Lead/owner sessions only: an agent worker resetting its own
+        // transcript mid-task would corrupt the delegation contract, and it
+        // must never reach the owner conversation either.
+        const callerSessionId = callerCtx?.callerSessionId || null;
+        if (callerSessionId && session?.id && callerSessionId !== session.id) {
+          throw new Error('session_manage: only the lead session may reset the conversation');
+        }
+        if (!session?.id) throw new Error('session_manage: no active session');
+        const action = clean(args?.action).toLowerCase();
+        if (action !== 'clear' && action !== 'compact_clear') {
+          throw new Error(`session_manage: unknown action "${action}" (use clear | compact_clear)`);
+        }
+        // Never clear mid-turn — the loop is still reading the transcript.
+        // Schedule and let the TUI engine consume it at turn end (same
+        // boundary the idle auto-clear uses).
+        // Pin to the current session id so a resume/new-session between
+        // scheduling and consumption can never clear the wrong conversation.
+        pendingSessionReset = { action, sessionId: session.id };
+        return action === 'clear'
+          ? 'Session reset scheduled: full clear will run when this turn ends. All prior context will be gone.'
+          : 'Session reset scheduled: the conversation will be summarized (compact) and cleared when this turn ends; key context carries forward in the summary.';
+      }
       if (name === 'Skill') {
         return skillToolContent(args?.name);
       }
@@ -1498,6 +1526,16 @@ export async function createMixdogSessionRuntime({
   // seat, or to re-pin forwarding onto the current transcript).
   function startRemote() {
     remoteEnabled = true;
+    // Boot the memory daemon eagerly. The channels worker forwards
+    // transcript ingests/entries to the memory HTTP service, whose port is
+    // published to active-instance.json by getMemoryModule().init(). Without
+    // this, memory only starts on the first turn's getMemoryModule() call —
+    // so early channel traffic finds no memory_port and gets buffered (or,
+    // pre-drainer, silently dropped). Fire-and-forget BEFORE channel claim so
+    // the port is (racing to be) live by the time the worker sends its first
+    // ingest.
+    try { void getMemoryModule().catch((error) => bootProfile('channels:memory-eager-init-failed', { error: error?.message || String(error) })); }
+    catch (error) { bootProfile('channels:memory-eager-init-failed', { error: error?.message || String(error) }); }
     // Publish this session's record + transcript file BEFORE the worker's
     // activate-time discovery polls, so output forwarding binds to this
     // terminal session immediately instead of waiting for the first turn.
@@ -2518,6 +2556,16 @@ export async function createMixdogSessionRuntime({
       invalidateContextStatusCache();
       return true;
     },
+    // session_manage tool handoff: the engine polls this at turn end and, if
+    // set, runs the same clear path the idle auto-clear uses. One-shot read.
+    consumePendingSessionReset() {
+      const pending = pendingSessionReset;
+      pendingSessionReset = null;
+      if (!pending) return null;
+      // Session changed since scheduling (resume / new session) — drop it.
+      if (!session?.id || pending.sessionId !== session.id) return null;
+      return pending.action;
+    },
     async compact(options = {}) {
       if (!session?.id) return null;
       if (activeTurnCount > 0) {

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

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

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

@@ -0,0 +1,21 @@
+# Agent Constraints
+
+- Use English for agent task communication.
+- NEVER PREAMBLE: no tool-call preambles, status/progress narration, "I
+  will..." setup, or transition text before tool calls.
+- If tools are needed, call them immediately. Emit text only for the final
+  handoff after tool work is done.
+- Final handoff: minimum characters, maximum information for Lead. Follow the
+  role's stricter output contract if defined; else emit fragments — outcome
+  (1 line), key `file:line`(s), verification result, material risks (only if
+  any).
+- Density over length: never repeat what Lead already knows (the brief, the
+  process, how you searched); state only what changed and where to look.
+  Verification = command + result in one line. Same fact twice = delete one.
+- Handoff cap ~30 lines unless `Deliver:` raises it — a safety ceiling, not
+  a target.
+- Banned as pure cost: report headings, markdown tables (unless requested),
+  prose narration, raw logs/tool traces, speculative next-checks, restated
+  brief, articles/politeness.
+- Exception: a runtime wrap-up directive (exploration budget reached) overrides
+  this — then summarize done/remaining/blocking as instructed.

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

@@ -3,6 +3,13 @@
 - Brief = one-line fragments `Goal:` `Anchors:` `Allow/Forbid:` `Deliver:`
   `Verify:` (+`Stop:` heavy-worker). No role-known rules, background, or
   motivation — minimum characters, maximum information.
+- Density over length: every line must carry information the agent cannot
+  know — never restate role rules, prior context, or the same fact twice.
+  A brief that feels long is a scope problem; split the scope, don't pad.
+- Anchors = `file:line` + one-line conclusion each. Never paste log/code
+  bodies; the agent reads the file itself.
+- Instruct by outcome ("make X behave Y"), not by method (no code snippets,
+  no step-by-step edits) unless the method IS the requirement.
 - `Deliver:` states output size/shape (e.g. "fragments <=15 lines", "verdict
   + top-3 risks", "detail to file, path only"). Never request a long report
   in the handoff itself.

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

@@ -29,11 +29,16 @@ import {
     askSession,
     updateSessionStatus,
     closeSession,
+    getSession,
 } from '../session/manager.mjs';
 import {
+    abortAgentProgressWatchdog,
     agentWatchdogPolicyActive,
     evaluateAgentWatchdogAbort,
     resolveAgentWatchdogPolicy,
+    resolveHandoffMessageStartIndex,
+    watchdogPartialHandoffFromError,
+    AgentStallAbortError,
 } from './agent-progress-watchdog.mjs';
 
 // Cap agent role synthesis to ~3000 tokens (~12 KB at the 4 B/tok
@@ -332,6 +337,7 @@ export function makeAgentDispatch(opts = {}) {
         const _linkSignal = _managerMod?.linkParentSignalToSession;
         const _getProgressSnapshot = _managerMod?.getSessionProgressSnapshot;
         const _getLastProgressAt = _managerMod?.getSessionLastProgressAt;
+        const _getSession = _managerMod?.getSession || getSession;
         if (_linkSignal) {
             if (opts.parentSignal instanceof AbortSignal) {
                 try { _linkSignal(session.id, opts.parentSignal); } catch { /* ignore */ }
@@ -362,6 +368,7 @@ export function makeAgentDispatch(opts = {}) {
         const _watchdogAnchorTs = Date.now();
         const _idleTimer = (_idleController && (typeof _getProgressSnapshot === 'function' || typeof _getLastProgressAt === 'function'))
             ? setInterval(() => {
+                if (_idleController.signal?.aborted) return;
                 const now = Date.now();
                 const snapshot = typeof _getProgressSnapshot === 'function' ? _getProgressSnapshot(session.id) : null;
                 const abortErr = snapshot
@@ -371,12 +378,33 @@ export function makeAgentDispatch(opts = {}) {
                     const reported = typeof _getLastProgressAt === 'function' ? _getLastProgressAt(session.id) : 0;
                     const last = reported || _watchdogAnchorTs;
                     if (_watchdogPolicy.idleStaleMs > 0 && now - last > _watchdogPolicy.idleStaleMs) {
-                        try { _idleController.abort(new Error(`agent task stale (${_watchdogPolicy.idleStaleMs}ms without progress)`)); } catch { /* ignore */ }
+                        const err = new AgentStallAbortError(`agent task stale (${_watchdogPolicy.idleStaleMs}ms without progress)`);
+                        const sess = typeof _getSession === 'function' ? _getSession(session.id) : null;
+                        abortAgentProgressWatchdog(_idleController, {
+                            sessionId: session.id,
+                            agent,
+                            error: err,
+                            policy: _watchdogPolicy,
+                            now,
+                            anchorTs: _watchdogAnchorTs,
+                            lastProgressAt: reported,
+                            iteration: typeof sess?.lastIterationIndex === 'number' ? sess.lastIterationIndex : null,
+                        });
                     }
                     return;
                 }
                 if (abortErr) {
-                    try { _idleController.abort(abortErr); } catch { /* ignore */ }
+                    const sess = typeof _getSession === 'function' ? _getSession(session.id) : null;
+                    abortAgentProgressWatchdog(_idleController, {
+                        sessionId: session.id,
+                        agent,
+                        error: abortErr,
+                        snapshot,
+                        policy: _watchdogPolicy,
+                        now,
+                        anchorTs: _watchdogAnchorTs,
+                        iteration: typeof sess?.lastIterationIndex === 'number' ? sess.lastIterationIndex : null,
+                    });
                 }
             }, 1000)
             : null;
@@ -384,7 +412,9 @@ export function makeAgentDispatch(opts = {}) {
         let terminalStatus = 'idle';
         process.stderr.write(`[agent-dispatch] agent=${agent} preset=${presetName} model=${preset.model} provider=${preset.provider} session=${session.id}\n`);
         const _agentDispatchT0 = Date.now();
+        let _handoffMsgStart = 0;
         try {
+            _handoffMsgStart = resolveHandoffMessageStartIndex(getSession(session.id));
             const result = await askSession(session.id, finalPrompt, null, null, cwd, undefined, {
                 onCompactEvent: (event) => {
                     try {
@@ -413,6 +443,13 @@ export function makeAgentDispatch(opts = {}) {
             try { closeSession(session.id, 'ephemeral-done'); } catch { /* ignore */ }
             return out;
         } catch (err) {
+            const partial = watchdogPartialHandoffFromError(err, getSession(session.id), _handoffMsgStart);
+            if (partial) {
+                terminalStatus = 'idle';
+                try { closeSession(session.id, 'ephemeral-done'); } catch { /* ignore */ }
+                if (opts.brief === false) return partial;
+                return applyBriefCap(partial);
+            }
             terminalStatus = 'error';
             try { closeSession(session.id, 'ephemeral-error'); } catch { /* ignore */ }
             throw err;

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

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

package/src/runtime/agent/orchestrator/agent-runtime/agent-progress-watchdog.mjs

@@ -4,12 +4,129 @@
  * lastProgressAt during long tool work; this module decides when to abort.
  */
 
+import { appendAgentTrace } from '../agent-trace-io.mjs';
 import { getHiddenAgent } from '../internal-agents.mjs';
 import {
     resolveAgentStallThresholds,
     resolveAgentToolThresholdSeconds,
 } from '../stall-policy.mjs';
 
+const WATCHDOG_ABORT_RE = /^agent (?:first response stale|task stale|tool running stale)\s*\(/;
+
+/**
+ * Typed abort error for the agent progress watchdog. Carrying a stable `name`
+ * lets the retry-classifier and the WS/SSE abort handlers distinguish a
+ * watchdog stall from a user cancel: it is classified as `agent_stall` (a
+ * retryable stream failure), NOT a user abort (null classification). The abort
+ * signal reason surfaces as this error's `name`, so both the classifier's
+ * `err.name` check and the provider abort handlers' `reason.name` check match.
+ */
+export class AgentStallAbortError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'AgentStallAbortError';
+    }
+}
+
+export function isAgentProgressWatchdogAbortError(err) {
+    const msg = err?.message;
+    return typeof msg === 'string' && WATCHDOG_ABORT_RE.test(msg);
+}
+
+function assistantMessageText(content) {
+    if (typeof content === 'string') return content;
+    if (!Array.isArray(content)) return '';
+    return content
+        .filter((b) => b && (b.type === 'text' || b.type === 'output_text'))
+        .map((b) => (typeof b.text === 'string' ? b.text : ''))
+        .join('\n');
+}
+
+/** Message index at askSession start — salvage only assistant rows appended this run. */
+export function resolveHandoffMessageStartIndex(session) {
+    const messages = Array.isArray(session?.messages) ? session.messages : [];
+    return messages.length;
+}
+
+export function collectSessionAssistantHandoffText(session, messageStartIndex = 0) {
+    const messages = Array.isArray(session?.messages) ? session.messages : [];
+    const start = Math.max(0, Math.floor(Number(messageStartIndex) || 0));
+    const parts = [];
+    for (let i = start; i < messages.length; i += 1) {
+        const m = messages[i];
+        if (m?.role !== 'assistant') continue;
+        const t = assistantMessageText(m.content).trim();
+        if (t && t !== '.') parts.push(t);
+    }
+    return parts.length ? parts.join('\n\n') : '';
+}
+
+export function watchdogPartialHandoffFromError(error, session, messageStartIndex = 0) {
+    if (!isAgentProgressWatchdogAbortError(error)) return null;
+    const text = collectSessionAssistantHandoffText(session, messageStartIndex);
+    return text.trim() ? text : null;
+}
+
+function resolveWatchdogAbortElapsedMs({ error, snapshot, policy, now, anchorTs, lastProgressAt }) {
+    if (snapshot && policy) {
+        if (snapshot.waitingForFirstActivity) {
+            const startedAt = snapshot.modelRequestStartedAt || snapshot.askStartedAt;
+            if (startedAt) return Math.max(0, now - startedAt);
+        }
+        if (snapshot.stage === 'tool_running' && snapshot.toolStartedAt
+            && typeof error?.message === 'string' && error.message.includes('tool running stale')) {
+            return Math.max(0, now - snapshot.toolStartedAt);
+        }
+        const last = snapshot.lastProgressAt || snapshot.firstActivityAt;
+        if (last) return Math.max(0, now - last);
+    }
+    const last = lastProgressAt || anchorTs;
+    if (last) return Math.max(0, now - last);
+    return null;
+}
+
+export function recordAgentWatchdogAbort({
+    sessionId,
+    agent = null,
+    error,
+    snapshot = null,
+    policy = null,
+    now = Date.now(),
+    anchorTs = 0,
+    lastProgressAt = 0,
+    iteration = null,
+}) {
+    if (!sessionId || !error) return;
+    const elapsed = resolveWatchdogAbortElapsedMs({
+        error,
+        snapshot,
+        policy,
+        now,
+        anchorTs,
+        lastProgressAt,
+    });
+    try {
+        appendAgentTrace({
+            sessionId,
+            iteration: iteration ?? null,
+            kind: 'stall_abort',
+            agent: agent || null,
+            payload: {
+                elapsed_ms: elapsed,
+                message: typeof error.message === 'string' ? error.message : String(error),
+                stage: snapshot?.stage ?? null,
+            },
+        });
+    } catch { /* best-effort */ }
+}
+
+export function abortAgentProgressWatchdog(controller, ctx) {
+    if (!controller || !ctx?.error) return;
+    if (controller.signal?.aborted) return;
+    recordAgentWatchdogAbort(ctx);
+    try { controller.abort(ctx.error); } catch { /* ignore */ }
+}
+
 function envTimeoutMs(name, fallback) {
     const raw = process.env[name];
     if (raw === undefined || raw === '') return fallback;
@@ -76,14 +193,14 @@ export function evaluateAgentWatchdogAbort(snapshot, now, policy) {
     if (snapshot.waitingForFirstActivity) {
         const startedAt = snapshot.modelRequestStartedAt || snapshot.askStartedAt;
         if (policy.firstResponseMs > 0 && startedAt && now - startedAt > policy.firstResponseMs) {
-            return new Error(`agent first response stale (${policy.firstResponseMs}ms)`);
+            return new AgentStallAbortError(`agent first response stale (${policy.firstResponseMs}ms)`);
         }
         return null;
     }
 
     const last = snapshot.lastProgressAt || snapshot.firstActivityAt;
     if (policy.idleStaleMs > 0 && last && now - last > policy.idleStaleMs) {
-        return new Error(`agent task stale (${policy.idleStaleMs}ms without stream/tool progress)`);
+        return new AgentStallAbortError(`agent task stale (${policy.idleStaleMs}ms without stream/tool progress)`);
     }
 
     if (
@@ -92,7 +209,7 @@ export function evaluateAgentWatchdogAbort(snapshot, now, policy) {
         && policy.toolRunningMs > 0
         && now - snapshot.toolStartedAt > policy.toolRunningMs
     ) {
-        return new Error(`agent tool running stale (${policy.toolRunningMs}ms)`);
+        return new AgentStallAbortError(`agent tool running stale (${policy.toolRunningMs}ms)`);
     }
 
     return null;

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

@@ -155,7 +155,42 @@ function extractThinkingTokens(rawUsage) {
     return null;
 }
 
-function traceAgentUsage({ sessionId, iteration, inputTokens, outputTokens, cachedTokens, cacheWriteTokens, promptTokens, model, modelDisplay, responseId, rawUsage, provider, serviceTier, requestKind }) {
+/** xAI Responses cache-chain diagnosis for usage_raw rows (measurement only). */
+function grokCacheChainTraceFields(providerState, requestPrevResponseId, continuationResetReason = null) {
+    const lastReceived = typeof providerState?.xaiResponses?.previousResponseId === 'string'
+        && providerState.xaiResponses.previousResponseId.length > 0
+        ? providerState.xaiResponses.previousResponseId
+        : null;
+    const sent = typeof requestPrevResponseId === 'string' && requestPrevResponseId.length > 0
+        ? requestPrevResponseId
+        : null;
+    const chainContinuous = sent !== null && sent === lastReceived;
+    return {
+        requestPrevResponseId: sent,
+        chainContinuous,
+        continuationResetReason: continuationResetReason || null,
+    };
+}
+
+function traceAgentUsage({
+    sessionId,
+    iteration,
+    inputTokens,
+    outputTokens,
+    cachedTokens,
+    cacheWriteTokens,
+    promptTokens,
+    model,
+    modelDisplay,
+    responseId,
+    rawUsage,
+    provider,
+    serviceTier,
+    requestKind,
+    requestPrevResponseId,
+    chainContinuous,
+    continuationResetReason,
+}) {
     const inclusive = isInclusiveProvider(provider);
     const inTok = inputTokens || 0;
     const cacheRead = cachedTokens || 0;
@@ -186,6 +221,9 @@ function traceAgentUsage({ sessionId, iteration, inputTokens, outputTokens, cach
         response_id: responseId || null,
         request_kind: typeof requestKind === 'string' && requestKind ? requestKind : null,
         service_tier: resolvedServiceTier,
+        ...(requestPrevResponseId !== undefined ? { request_prev_response_id: requestPrevResponseId } : {}),
+        ...(chainContinuous !== undefined ? { chain_continuous: chainContinuous } : {}),
+        ...(continuationResetReason !== undefined ? { continuation_reset_reason: continuationResetReason } : {}),
         payload: {
             provider: provider || null,
             prompt_tokens: promptTotal,
@@ -195,6 +233,9 @@ function traceAgentUsage({ sessionId, iteration, inputTokens, outputTokens, cach
             response_id: responseId || null,
             service_tier: resolvedServiceTier,
             raw_usage: rawUsage || null,
+            ...(requestPrevResponseId !== undefined ? { request_prev_response_id: requestPrevResponseId } : {}),
+            ...(chainContinuous !== undefined ? { chain_continuous: chainContinuous } : {}),
+            ...(continuationResetReason !== undefined ? { continuation_reset_reason: continuationResetReason } : {}),
         },
     });
 }
@@ -213,6 +254,7 @@ export {
     traceAgentToolFailure,
     traceAgentCompact,
     traceAgentUsage,
+    grokCacheChainTraceFields,
     traceAgentCompress,
     traceAgentBatch,
     traceStreamAborted,

package/src/runtime/agent/orchestrator/context/collect.mjs

@@ -511,7 +511,7 @@ function loadHiddenAgentSnippets(pluginRoot) {
         const agentRulesDir = join(pluginRoot, 'rules', 'agent');
         if (!existsSync(agentRulesDir)) return [];
         const files = readdirSync(agentRulesDir)
-            .filter(f => f.endsWith('.md') && f !== '00-common.md')
+            .filter(f => f.endsWith('.md') && f !== '00-common.md' && f !== '00-core.md')
             .sort();
         const pairs = [];
         for (const f of files) {