mixdog 0.8.1 → 0.9.1

package/src/runtime/agent/orchestrator/{smart-bridge/bridge-llm.mjs → agent-runtime/agent-dispatch.mjs}

@@ -1,19 +1,19 @@
 /**
- * Smart Bridge — Internal LLM Helper (session-based).
+ * Agent Runtime — Internal LLM Helper (session-based).
  *
  * Every one-shot LLM dispatch from internal callers (memory-cycle,
  * scheduler, webhook) now flows through the SAME session pipeline as the
- * MCP `bridge` tool. No more parallel `provider.send()` helper — one code
- * path = one message shape = one usage log = "bridge single path".
+ * MCP `agent` tool. No more parallel `provider.send()` helper — one code
+ * path = one message shape = one usage log = "agent single path".
  *
  * The returned function uses the existing caller signature, so call sites
  * do not need changes:
  *
- *   const llm = makeBridgeLlm({ role: 'maintenance', preset: 'haiku' });
+ *   const llm = makeAgentDispatch({ role: 'maintenance', preset: 'haiku' });
  *   const text = await llm({ prompt });
  *
  * Internally it:
- *   1. Resolves the preset (explicit arg > opts.preset > user-workflow.json[role])
+ *   1. Resolves the preset (explicit arg > opts.preset > hidden-role config)
  *   2. Creates or reuses a session via the session manager
  *   3. Applies stateless-reset for stateless profiles so the prefix handle
  *      stays warm while per-dispatch transcripts never leak
@@ -21,33 +21,27 @@
  *      `session/manager.mjs` (mode='active')
  */
 
-import { readFileSync } from 'fs';
-import { join } from 'path';
 import { loadConfig } from '../config.mjs';
 import { resolveRuntimeSpec } from '../config.mjs';
-import { getHiddenRole, resolveBridgeSessionPermission } from '../internal-roles.mjs';
-import { prepareBridgeSession } from './session-builder.mjs';
-import { resolvePluginData } from '../../../shared/plugin-paths.mjs';
+import { getHiddenRole, resolveAgentSessionPermission } from '../internal-roles.mjs';
+import { prepareAgentSession } from './session-builder.mjs';
 import {
     askSession,
     updateSessionStatus,
     closeSession,
 } from '../session/manager.mjs';
+import {
+    agentWatchdogPolicyActive,
+    evaluateAgentWatchdogAbort,
+    resolveAgentWatchdogPolicy,
+} from './agent-progress-watchdog.mjs';
 
-// Cap bridge role synthesis to ~3000 tokens (~12 KB at the 4 B/tok
+// Cap agent role synthesis to ~3000 tokens (~12 KB at the 4 B/tok
 // working average). Pool B explore/recall/search answers occasionally land
 // 8-10k-token walls that then ride in the Lead context for the rest of the
 // turn; the cap keeps those outliers bounded without touching the 95%+ of
 // answers already under the threshold.
 const BRIEF_CAP_BYTES = 12 * 1024;
-function envTimeoutMs(name, fallback) {
-    const raw = process.env[name];
-    if (raw === undefined || raw === '') return fallback;
-    const n = Number(raw);
-    return Number.isFinite(n) && n >= 0 ? Math.floor(n) : fallback;
-}
-const DEFAULT_FIRST_RESPONSE_TIMEOUT_MS = envTimeoutMs('MIXDOG_BRIDGE_FIRST_RESPONSE_TIMEOUT_MS', 120_000);
-const DEFAULT_STALE_TIMEOUT_MS = envTimeoutMs('MIXDOG_BRIDGE_STALE_TIMEOUT_MS', 30 * 60_000);
 function applyBriefCap(text) {
     if (typeof text !== 'string') return text;
     if (text.length <= BRIEF_CAP_BYTES) return text;
@@ -56,25 +50,35 @@ function applyBriefCap(text) {
     return `${head}\n\n... [TRUNCATED — full answer was ~${approxTokens} tokens / ${Math.round(text.length / 1024)} KB. Re-run with brief:false for the complete synthesis]`;
 }
 
-// Unified-shard policy — most bridge sessions (Pool B + Pool C) share the
+// Unified-shard policy — most agent sessions (Pool B + Pool C) share the
 // same tool schema so BP_1 is bit-identical across roles and one provider-side
 // cache shard serves every caller. Per-role behaviour is steered by:
-//   1. rules/bridge/*.md concatenated into BP2 roleCatalog (via
-//      loadScopedRoleCatalog — every bridge session carries the full
-//      hidden-role catalog so the shard stays bit-identical across roles)
+//   1. role-scoped BP2 instructions from agents/<role>.md and
+//      rules/agent/<role>.md
 //   2. call-time guards (loop.mjs write-block + ai-wrapped-dispatch
 //      recursion break)
 // Hidden-role exceptions are declarative: defaults/hidden-roles.json may set
 // toolSchemaProfile when first-turn routing quality is worth a separate tool
-// prefix. Keep "unified" as the default; new profiles must justify the cache
-// shard split.
+// prefix. Standard profiles are none/read/full; legacy names stay as aliases.
 // See manager.mjs resolveSessionTools for the single source of truth;
-// bridge visibility is declared via annotations.bridgeHidden on each tool def.
+// agent visibility is declared via annotations.agentHidden on each tool def.
 const HIDDEN_ROLE_TOOL_SCHEMA_PROFILES = Object.freeze({
+    full: null,
+    none: Object.freeze([]),
+    read: Object.freeze([
+        'code_graph',
+        'find',
+        'glob',
+        'list',
+        'grep',
+        'read',
+    ]),
+    // Backward-compatible aliases for older hidden-role definitions.
     unified: null,
     'llm-only': Object.freeze([]),
     'filesystem-read': Object.freeze([
         'code_graph',
+        'find',
         'glob',
         'list',
         'grep',
@@ -87,99 +91,127 @@ export function resolveHiddenRoleSchemaAllowedTools(hidden) {
     if (Array.isArray(hidden.schemaAllowedTools)) {
         return hidden.schemaAllowedTools.map((name) => String(name || '').trim()).filter(Boolean);
     }
-    const profile = String(hidden.toolSchemaProfile || 'unified').trim() || 'unified';
+    const profile = String(hidden.toolSchemaProfile || 'full').trim() || 'full';
     if (Object.prototype.hasOwnProperty.call(HIDDEN_ROLE_TOOL_SCHEMA_PROFILES, profile)) {
         return HIDDEN_ROLE_TOOL_SCHEMA_PROFILES[profile];
     }
-    process.stderr.write(`[bridge-llm] unknown hidden-role toolSchemaProfile="${profile}" role="${hidden.name || 'unknown'}"; using unified schema\n`);
+    process.stderr.write(`[agent-dispatch] unknown hidden-role toolSchemaProfile="${profile}" role="${hidden.name || 'unknown'}"; using full schema\n`);
     return null;
 }
 
 /**
- * Resolve a preset name from (preset arg | opts.preset | hidden-role | user-workflow).
+ * Resolve the maintenance ROUTE (or legacy preset name) for a dispatch.
  *
- * Hidden roles (explorer, cycle1/cycle2, scheduler-task, etc.) are
- * Mixdog-managed and take precedence over user-workflow.json — users cannot
- * override them by redefining the same name.
+ * Returns one of:
+ *   - a route object `{ provider, model, effort?, fast? }` — the preferred
+ *     shape: a maintenance slot now stores its model directly (parity with
+ *     `agents.<role>`), so no preset-array name lookup is needed.
+ *   - a string — a legacy preset NAME still stored in a maintenance slot, or an
+ *     explicit `preset`/`opts.preset` override. The caller resolves the name
+ *     against config.presets for backward compatibility.
+ *   - null — unresolved.
+ *
+ * Hidden roles read their slot from `maint[maintKey || slot]`; the cycle1/2/3
+ * agents share one knob via the `maintKey: 'memory'` override.
  */
-export function resolvePresetName({ preset, optsPreset, role, config: cfgIn = null }) {
+export function resolveMaintenanceRoute({ preset, optsPreset, role, config: cfgIn = null }) {
     if (preset) return preset;
     if (optsPreset) return optsPreset;
     if (!role) return null;
-    // Hidden roles resolve their maintenance preset by SLOT. Every slot carries
-    // a concrete default in DEFAULT_MAINTENANCE, so `maint[slot]` resolves
-    // directly; the Setup panel can still tune each slot independently.
-    // (explorer.slot = 'explore', cycle1-agent.slot = 'cycle1', …). A hidden
-    // role may override which maintenance key it reads via `maintKey`
-    // (e.g. the cycle1/2/3 agents all read `maint.memory` instead of their
-    // own slot) so several agents can share one model knob while keeping
-    // distinct slots/identity.
     const hidden = getHiddenRole(role);
     if (hidden) {
         try {
-            const config = cfgIn || loadConfig();
+            const config = cfgIn || loadConfig({ secrets: false });
             const maint = config?.maintenance || {};
-            return maint[hidden.maintKey || hidden.slot] || null;
+            return maint[hidden.maintKey || hidden.slot] ?? null;
         } catch { return null; }
     }
-    try {
-        const pluginData = resolvePluginData();
-        if (!pluginData) return null;
-        const wf = JSON.parse(readFileSync(join(pluginData, 'user-workflow.json'), 'utf8'));
-        if (!Array.isArray(wf.roles)) return null;
-        const entry = wf.roles.find((r) => r.name === role);
-        return entry ? entry.preset : null;
-    } catch {
-        return null;
-    }
+    return null;
+}
+
+// Back-compat alias: older callers/tests import resolvePresetName. It now
+// returns whatever resolveMaintenanceRoute does (route object OR name string).
+export const resolvePresetName = resolveMaintenanceRoute;
+
+// A maintenance slot value is a direct route when it carries provider+model.
+function maintenanceRouteToPreset(routeOrName, role) {
+    if (!routeOrName || typeof routeOrName !== 'object') return null;
+    const provider = String(routeOrName.provider || '').trim();
+    const model = String(routeOrName.model || '').trim();
+    if (!provider || !model) return null;
+    const out = {
+        id: `maint-${role}`,
+        name: `MAINT ${String(role || '').toUpperCase()}`,
+        type: 'agent',
+        provider,
+        model,
+        tools: 'full',
+    };
+    const effort = String(routeOrName.effort || '').trim();
+    if (effort) out.effort = effort;
+    if (routeOrName.fast === true) out.fast = true;
+    return out;
 }
 
 /**
- * Build a bridge-backed LLM callback.
+ * Build an agent-backed dispatch callback.
  *
  * @param {object} opts
  * @param {string} opts.role        — REQUIRED; canonical role name (worker, cycle1-agent, scheduler-task, ...)
  * @param {string} [opts.taskType]  — optional internal classification stamped on the session
  * @param {string} [opts.preset]    — explicit preset override (bypasses role → preset lookup)
- * @param {string} [opts.parentSessionId] — parent bridge session for trace aggregation
+ * @param {string} [opts.parentSessionId] — parent agent session for trace aggregation
  * @param {string|null} [opts.ownerSessionId] — owning Mixdog session for statusline isolation
  * @param {AbortSignal} [opts.parentSignal] — optional AbortSignal from the fan-out coordinator;
- *   when aborted the bridge role session's own controller is also aborted so the
+ *   when aborted the agent role session's own controller is also aborted so the
  *   provider call tears down promptly (parent→child cascade).
  * @returns {(args: { prompt, preset?, sourceName? }) => Promise<string>}
  */
-export function makeBridgeLlm(opts = {}) {
+export function makeAgentDispatch(opts = {}) {
     if (!opts.role || typeof opts.role !== 'string') {
-        throw new Error('[bridge-llm] opts.role is required');
+        throw new Error('[agent-dispatch] opts.role is required');
     }
     const role = opts.role;
 
-    return async function bridgeLlm({ prompt, preset: presetArg, sourceName: sourceNameArg, parentSignal: callParentSignal, idleTimeoutMs: callIdleTimeoutMs }) {
+    return async function agentDispatch({ prompt, preset: presetArg, sourceName: sourceNameArg, parentSignal: callParentSignal, idleTimeoutMs: callIdleTimeoutMs }) {
         if (typeof prompt !== 'string' || !prompt) {
-            throw new Error(`[bridge-llm] prompt required for role "${role}"`);
+            throw new Error(`[agent-dispatch] prompt required for role "${role}"`);
         }
 
-        const config = opts.config || loadConfig();
-        const presetName = resolvePresetName({
+        const config = opts.config || loadConfig({ secrets: false });
+        const routeOrName = resolveMaintenanceRoute({
             preset: presetArg,
             optsPreset: opts.preset,
             role,
             config,
         });
-        if (!presetName) {
+        if (!routeOrName) {
             throw new Error(
-                `[bridge-llm] preset unresolved for role "${role}" `
+                `[agent-dispatch] maintenance route unresolved for role "${role}" `
                 + `(preset="${presetArg || opts.preset || ''}")`,
             );
         }
-
-        const preset = config.presets?.find((p) => p.id === presetName || p.name === presetName);
+        // Preferred path: a maintenance slot that stores its model directly
+        // (route object). Legacy path: a slot still holding a preset NAME —
+        // resolve it against config.presets for backward compatibility.
+        let preset = maintenanceRouteToPreset(routeOrName, role);
         if (!preset) {
-            throw new Error(`[bridge-llm] preset "${presetName}" not found in mixdog-config.json`);
+            const legacyName = String(routeOrName || '').trim();
+            preset = config.presets?.find((p) => p.id === legacyName || p.name === legacyName) || null;
+            if (!preset) {
+                throw new Error(
+                    `[agent-dispatch] maintenance route for role "${role}" is neither a `
+                    + `{provider,model} route nor a known preset name ("${legacyName}")`,
+                );
+            }
         }
+        // Stable label for traces / session metadata, derived from the resolved
+        // preset object regardless of whether it came from a direct route or a
+        // legacy preset name.
+        const presetName = preset.id || preset.name || `maint-${role}`;
 
         const runtimeSpec = resolveRuntimeSpec(preset, {
-            lane: 'bridge',
+            lane: 'agent',
             agentId: role,
         });
 
@@ -189,38 +221,37 @@ export function makeBridgeLlm(opts = {}) {
         // we pass `null` through instead of falling back to `process.cwd()`
         // — the MCP server's launch dir is not deterministic across callers,
         // and the downstream skill-discovery path tolerates null. Combined
-        // with the frozen bridge skill meta-tools (collect.mjs) this keeps
+        // with the frozen agent skill meta-tools (collect.mjs) this keeps
         // every caller on the same provider cache shard.
         const cwd = (typeof opts.cwd === 'string' && opts.cwd) ? opts.cwd : null;
 
         // Unified dispatch: Pool B/C share bit-identical tools + system prompt
         // unless a hidden role declares a narrow toolSchemaProfile. Per-role
-        // differentiation rides in the user-message header (permission + role
-        // line) plus an optional short Pool C snippet. The read-only contract
-        // is still enforced at call time via loop.mjs's READ_BLOCKED_TOOLS
-        // guard; schema profiles are a routing-efficiency layer, not safety.
+        // differentiation lives in scoped role rules / stable session context;
+        // raw role and permission labels are not repeated in the prompt.
+        // Runtime permission enforcement was removed (every tool call is
+        // trusted); schema profiles remain a routing-efficiency layer that
+        // narrows the advertised tool list, not a runtime safety gate.
         const hidden = getHiddenRole(role);
         const isPoolC = Boolean(hidden);
         // Permission: read-declared hidden roles are locked in
-        // resolveBridgeSessionPermission (prepareBridgeSession applies the same).
-        const permission = resolveBridgeSessionPermission(
+        // resolveAgentSessionPermission (prepareAgentSession applies the same).
+        const permission = resolveAgentSessionPermission(
             role,
             opts.permission ?? (isPoolC ? (hidden?.permission || 'read') : null),
         );
-        // Pool C hidden-role instructions live in BP2 roleCatalog (loaded
-        // by loadScopedRoleCatalog from rules/bridge/*.md) — the Tier 3
-        // reminder is suppressed so the shard stays bit-identical across
-        // every bridge role.
+        // Pool C hidden-role instructions live in BP2 role-scoped context
+        // (loaded by loadScopedRoleInstructions from rules/agent/*.md).
         //
-        // User message = pure query. Permission / role ride in BP3
-        // sessionMarker (composeSystemPrompt) — only the query varies per
-        // call, so provider cache reuses the shared prefix.
+        // User message = pure query. Stable role rules ride in BP2; stable
+        // memory/meta rides in BP3; only the query varies per call, so
+        // provider cache reuses the shared prefix.
         //
         // Stateless ephemeral session — created fresh per call, never
         // pooled or resumed. Cache prefix matching happens at the provider
         // layer (account-level), not the session level.
         const finalPrompt = prompt;
-        const { session } = prepareBridgeSession({
+        const { session } = prepareAgentSession({
             role,
             presetName,
             preset,
@@ -242,7 +273,7 @@ export function makeBridgeLlm(opts = {}) {
         // count-only "tools=N" line.
         try {
             const _toolNames = (session.tools || []).map((t) => t?.name).filter(Boolean);
-            process.stderr.write(`[bridge-llm] role=${role} tool-list (${_toolNames.length}): ${_toolNames.join(',')}\n`);
+            process.stderr.write(`[agent-dispatch] role=${role} tool-list (${_toolNames.length}): ${_toolNames.join(',')}\n`);
         } catch { /* best-effort diagnostic */ }
 
         await updateSessionStatus(session.id, 'running');
@@ -265,15 +296,16 @@ export function makeBridgeLlm(opts = {}) {
         // Watchdog policy is split:
         // - firstResponseTimeoutMs cuts quickly only when the model produces no
         //   first stream/tool activity at all.
-        // - idleTimeoutMs is a stale watchdog after work has started.
-        //   0 disables that stale abort; default is 30 minutes.
-        const _staleMs = Number.isFinite(callIdleTimeoutMs)
-            ? callIdleTimeoutMs
-            : (Number.isFinite(opts.idleTimeoutMs) ? opts.idleTimeoutMs : DEFAULT_STALE_TIMEOUT_MS);
-        const _firstMs = Number.isFinite(opts.firstResponseTimeoutMs)
-            ? opts.firstResponseTimeoutMs
-            : DEFAULT_FIRST_RESPONSE_TIMEOUT_MS;
-        const _idleController = ((_staleMs > 0 || _firstMs > 0) && _linkSignal) ? new AbortController() : null;
+        // - idle/tool-running caps come from role stallCap (hidden roles) or env defaults.
+        const _watchdogPolicy = resolveAgentWatchdogPolicy(role, {
+            idleTimeoutMs: Number.isFinite(callIdleTimeoutMs)
+                ? callIdleTimeoutMs
+                : opts.idleTimeoutMs,
+            firstResponseTimeoutMs: opts.firstResponseTimeoutMs,
+        });
+        const _idleController = (agentWatchdogPolicyActive(_watchdogPolicy) && _linkSignal)
+            ? new AbortController()
+            : null;
         if (_idleController) {
             try { _linkSignal(session.id, _idleController.signal); } catch { /* ignore */ }
         }
@@ -281,35 +313,30 @@ export function makeBridgeLlm(opts = {}) {
             ? setInterval(() => {
                 const now = Date.now();
                 const snapshot = typeof _getProgressSnapshot === 'function' ? _getProgressSnapshot(session.id) : null;
-                if (snapshot) {
-                    if (snapshot.waitingForFirstActivity) {
-                        const startedAt = snapshot.modelRequestStartedAt || snapshot.askStartedAt;
-                        if (_firstMs > 0 && startedAt && now - startedAt > _firstMs) {
-                            try { _idleController.abort(new Error(`first response stale (${_firstMs}ms)`)); } catch { /* ignore */ }
-                        }
-                        return;
-                    }
-                    const last = snapshot.lastProgressAt || snapshot.firstActivityAt;
-                    if (_staleMs > 0 && last && now - last > _staleMs) {
-                        try { _idleController.abort(new Error(`bridge task stale (${_staleMs}ms without stream/tool progress)`)); } catch { /* ignore */ }
+                const abortErr = snapshot
+                    ? evaluateAgentWatchdogAbort(snapshot, now, _watchdogPolicy)
+                    : null;
+                if (!abortErr && !snapshot && typeof _getLastProgressAt === 'function') {
+                    const last = _getLastProgressAt(session.id);
+                    if (_watchdogPolicy.idleStaleMs > 0 && last && now - last > _watchdogPolicy.idleStaleMs) {
+                        try { _idleController.abort(new Error(`agent task stale (${_watchdogPolicy.idleStaleMs}ms without progress)`)); } catch { /* ignore */ }
                     }
                     return;
                 }
-                const last = _getLastProgressAt?.(session.id);
-                if (_staleMs > 0 && last && now - last > _staleMs) {
-                    try { _idleController.abort(new Error(`bridge task stale (${_staleMs}ms without progress)`)); } catch { /* ignore */ }
+                if (abortErr) {
+                    try { _idleController.abort(abortErr); } catch { /* ignore */ }
                 }
             }, 1000)
             : null;
         if (_idleTimer && typeof _idleTimer.unref === 'function') _idleTimer.unref();
         let terminalStatus = 'idle';
-        process.stderr.write(`[bridge-llm] role=${role} preset=${presetName} model=${preset.model} provider=${preset.provider} session=${session.id}\n`);
-        const _bridgeT0 = Date.now();
+        process.stderr.write(`[agent-dispatch] role=${role} preset=${presetName} model=${preset.model} provider=${preset.provider} session=${session.id}\n`);
+        const _agentDispatchT0 = Date.now();
         try {
             const result = await askSession(session.id, finalPrompt, null, null, cwd);
-            process.stderr.write(`[bridge-llm] role=${role} session=${session.id} elapsed=${Date.now() - _bridgeT0}ms\n`);
+            process.stderr.write(`[agent-dispatch] role=${role} session=${session.id} elapsed=${Date.now() - _agentDispatchT0}ms\n`);
             const raw = result?.content || '';
-            // Brief cap. Bridge role answers (explore/recall/search)
+            // Brief cap. Agent role answers (explore/recall/search)
             // occasionally balloon to 8-10k token walls that then ride in the
             // parent Lead's context for the rest of the turn. A 3000-token
             // (~12 KB) ceiling trims the long tail while leaving the vast

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

@@ -0,0 +1,94 @@
+/**
+ * Unified agent progress / stale watchdog policy for agent-tool spawns and
+ * agent-dispatch internal roles. Activity heartbeats (session manager) refresh
+ * lastProgressAt during long tool work; this module decides when to abort.
+ */
+
+import { getHiddenRole } from '../internal-roles.mjs';
+import {
+    resolveAgentStallThresholds,
+    resolveAgentToolThresholdSeconds,
+} from '../stall-policy.mjs';
+
+function envTimeoutMs(name, fallback) {
+    const raw = process.env[name];
+    if (raw === undefined || raw === '') return fallback;
+    const n = Number(raw);
+    return Number.isFinite(n) && n >= 0 ? Math.floor(n) : fallback;
+}
+
+export const DEFAULT_FIRST_RESPONSE_TIMEOUT_MS = envTimeoutMs(
+    'MIXDOG_AGENT_FIRST_RESPONSE_TIMEOUT_MS',
+    120_000,
+);
+export const DEFAULT_STALE_TIMEOUT_MS = envTimeoutMs(
+    'MIXDOG_AGENT_STALE_TIMEOUT_MS',
+    30 * 60_000,
+);
+
+function resolveExplicitMs(value, fallback) {
+    if (Number.isFinite(value) && value >= 0) return Math.floor(value);
+    return fallback;
+}
+
+export function resolveAgentWatchdogPolicy(role, overrides = {}) {
+    const firstResponseMs = resolveExplicitMs(
+        overrides.firstResponseTimeoutMs,
+        DEFAULT_FIRST_RESPONSE_TIMEOUT_MS,
+    );
+
+    let idleStaleMs;
+    if (Number.isFinite(overrides.idleTimeoutMs) && overrides.idleTimeoutMs >= 0) {
+        idleStaleMs = Math.floor(overrides.idleTimeoutMs);
+    } else if (getHiddenRole(role)) {
+        const { abort } = resolveAgentStallThresholds(role);
+        idleStaleMs = abort * 1000;
+    } else {
+        idleStaleMs = DEFAULT_STALE_TIMEOUT_MS;
+    }
+
+    const idleSec = idleStaleMs / 1000;
+    const toolRunningSec = resolveAgentToolThresholdSeconds(role, idleSec);
+    const toolRunningMs = Math.max(0, Math.floor(toolRunningSec * 1000));
+
+    return {
+        firstResponseMs,
+        idleStaleMs,
+        toolRunningMs,
+    };
+}
+
+export function evaluateAgentWatchdogAbort(snapshot, now, policy) {
+    if (!snapshot || !policy) return null;
+
+    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 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)`);
+    }
+
+    if (
+        snapshot.stage === 'tool_running'
+        && snapshot.toolStartedAt
+        && policy.toolRunningMs > 0
+        && now - snapshot.toolStartedAt > policy.toolRunningMs
+    ) {
+        return new Error(`agent tool running stale (${policy.toolRunningMs}ms)`);
+    }
+
+    return null;
+}
+
+export function agentWatchdogPolicyActive(policy) {
+    if (!policy) return false;
+    return (policy.firstResponseMs > 0)
+        || (policy.idleStaleMs > 0)
+        || (policy.toolRunningMs > 0);
+}

package/src/runtime/agent/orchestrator/{smart-bridge → agent-runtime}/cache-strategy.mjs

@@ -1,25 +1,31 @@
 /**
- * Smart Bridge — Cache Strategy
+ * Agent Runtime — Cache Strategy
  *
  * Provider-level cache policy. Anthropic supports explicit cache_control
- * breakpoints (up to 4 per request) — we use all 4 slots. Non-breakpoint
- * providers rely on server-side automatic prefix matching or observation.
+ * breakpoints (up to 4 per request) — we spend them on the stable system /
+ * session prefix plus the reusable message tail. Non-breakpoint providers
+ * rely on provider-managed prefix routing or provider-local cache objects.
  *
- * Anthropic 4-BP layout (public/CLI):
- *   BP_1  tools      (1h)  — tool schemas, stable per schema profile
- *   BP_2  system     (1h)  — Tier 2 shared rules
- *   BP_3  tier3      (1h)  — role/permission meta (messages[1] system-reminder)
- *   BP_4  messages   (1h)  — last message only; sliding extends prefix loss-free
+ * Anthropic 4-BP layout:
+ *   BP_1  system#1  (1h)  — shared tool policy + compact skill manifest
+ *   BP_2  system#2  (1h)  — role/system rules (Lead / agent / hidden role)
+ *   BP_3  system#3  (1h)  — stable memory/meta marker (sessionMarker system block; tier3)
+ *   BP_4  messages  (1h/5m) — sliding tool_result / prior user-text tail
  *
- * Tier 3 gets its own BP because role meta is stable per dispatch, so a
- * dedicated slot gives a reliable hit across the entire tool loop while
- * the sliding messages BP handles volatile tool_result accumulation.
+ * Tool schemas still sit before system in the provider prompt prefix. We do
+ * not spend a separate cache_control slot on tools; the first system BP covers
+ * the preceding tool prefix via Anthropic prefix caching semantics. Keeping
+ * agent worker tool schemas byte-stable is therefore still load-bearing.
+ *
+ * Tier 3 gets its own BP because memory/meta context is stable within the
+ * session. The sliding messages BP handles tool_result accumulation and
+ * per-call task/event data without pinning volatile text into the 1h tier.
  *
  * Non-breakpoint providers:
  *   - OpenAI (public): prompt_cache_key + prompt_cache_retention=24h
- *   - OpenAI OAuth (Codex): prompt_cache_key only (server in-memory 5-10min)
- *   - Gemini: implicit caching does NOT report cachedContentTokenCount on
- *     3.5+. Explicit cachedContents API required for measurable cache hits.
+ *   - OpenAI OAuth: prompt_cache_key only (server in-memory 5-10min)
+ *   - Gemini: provider-managed explicit cachedContents with 1h TTL, plus
+ *     implicit caching as a fallback when the prefix is below cache minimums.
  *   - xAI: x-grok-conv-id (server routing pin) + prompt_cache_key on
  *     Responses API. Treat as key-prefix, not implicit.
  *   - DeepSeek / OpenCode Go: automatic KV/prefix cache; observe provider
@@ -34,7 +40,7 @@ import { getHiddenRole } from '../internal-roles.mjs';
 /**
  * One-shot, LLM-only maintenance hidden roles (cycle1/cycle2/cycle3-agent):
  * a fresh stateless session is created per call, asked exactly once, and
- * closed (bridge-llm.mjs) — the per-batch user prompt can NEVER be reused.
+ * closed (agent-dispatch.mjs) — the per-batch user prompt can NEVER be reused.
  * Writing a message-tail cache breakpoint on it just pays the 1.25x write
  * premium for content read back 0 times. Identified by the declarative
  * (kind:'maintenance' + toolSchemaProfile:'llm-only') pair rather than
@@ -60,7 +66,7 @@ function isOneShotMaintenanceRole(role) {
  *   '5m'   → ephemeral 5m TTL  (1.25x write premium, 0.1x read)
  *   'none' → no breakpoint written on this layer
  *
- * Public bridge agents stay resumable for up to 1h (the terminal-reap window)
+ * Public agents stay resumable for up to 1h (the terminal-reap window)
  * for same-task reuse, so their message tail uses 1h too. Hidden multi-turn
  * roles (explorer / scheduler / webhook) run a single fan-out or entry-driven
  * session that is not resumed for same-task reuse, so their volatile tail stays
@@ -80,10 +86,10 @@ export function resolveCacheStrategy(role) {
         return { tools: 'none', system: 'none', tier3: 'none', messages: 'none' };
     }
     if (getHiddenRole(role)) {
-        return { tools: '1h', system: '1h', tier3: '1h', messages: '5m' };
+        return { tools: 'none', system: '1h', tier3: '1h', messages: '5m' };
     }
-    // Public bridge agents: resumable up to 1h for same-task reuse → 1h tail.
-    return { tools: '1h', system: '1h', tier3: '1h', messages: '1h' };
+    // Public agents: resumable up to 1h for same-task reuse -> 1h tail.
+    return { tools: 'none', system: '1h', tier3: '1h', messages: '1h' };
 }
 
 /**
@@ -98,6 +104,7 @@ export function resolveCacheStrategy(role) {
 // Provider cache capability kinds:
 //   'explicit-breakpoint' — explicit provider-side cache_control writes
 //   'key-prefix'          — provider-managed shard keyed by cache key/session
+//   'managed-explicit'    — provider object creates/attaches explicit caches
 //   'implicit-observed'   — cache hits are observable but not guaranteed warm
 //   'none'                — no API-level cache knob/metric
 const PROVIDER_CACHE_CAPABILITY = Object.freeze({
@@ -107,7 +114,7 @@ const PROVIDER_CACHE_CAPABILITY = Object.freeze({
     'openai-oauth':    'key-prefix',
     'xai':             'key-prefix',
     'grok-oauth':      'key-prefix',
-    'gemini':          'implicit-observed',
+    'gemini':          'managed-explicit',
     'deepseek':        'implicit-observed',
     'opencode-go':     'implicit-observed',
 });
@@ -118,7 +125,9 @@ export function cacheCapabilityForProvider(provider) {
 
 export function shouldMarkWarmForProvider(provider) {
     const capability = cacheCapabilityForProvider(provider);
-    return capability === 'explicit-breakpoint' || capability === 'key-prefix';
+    return capability === 'explicit-breakpoint'
+        || capability === 'key-prefix'
+        || capability === 'managed-explicit';
 }
 
 export function shouldRecordObservedForProvider(provider) {
@@ -183,7 +192,7 @@ function cleanString(value) {
 
 function normalizePromptCacheNamespace(value) {
     const s = String(value || '').trim() || 'mixdog-shared';
-    // Keep the key boring for OpenAI/Codex's 64-char prompt_cache_key cap while
+    // Keep the key boring for OpenAI OAuth's 64-char prompt_cache_key cap while
     // preserving user overrides as much as possible.
     return s.replace(/[^A-Za-z0-9_-]+/g, '-').replace(/^-+|-+$/g, '') || 'mixdog-shared';
 }
@@ -358,7 +367,7 @@ export function buildProviderCacheOpts(provider, sessionId, role) {
     }
     if (provider === 'openai') {
         // Public OpenAI API: prompt_cache_retention extends prefix retention.
-        // openai-oauth (Codex) rejects the header — falls through to default.
+        // openai-oauth rejects the header — falls through to default.
         return { cacheRetention: '24h' };
     }
     return {};