mixdog 1.4.0 → 1.4.2

package/src/rules/shared/60-verification.md

@@ -3,18 +3,19 @@
 - Check required behavior, exact outputs and essential integrity, security,
   compatibility and buildability. Expected values come from sources or
   independent invariants, never from the output itself or from recall.
-- No builds/lint/tests/formatters mid-flight. Finish planned scope edits,
-  then run required checks once in parallel. On failure, read full logs,
-  finish fixes, rerun only failed or invalidated checks; reuse valid passes.
-  Never reread your writes.
-- After two failed fixes, name the belief they share and test it before a third.
+- Match checks to the change: inspection for nonbehavioral edits, focused
+  tests for local behavior, broader lanes only for shared contracts. Run them
+  once after planned edits, heavy ones in sequence; never reread your writes.
+- Read full logs; rerun only after a relevant fix, never masking a failure
+  with retries, timeout bumps or skips; reuse valid passes.
+  After two failed fixes, report and stop. Stop processes you started.
 - Unexpected result: confirm the check sees the live artifact, not a cache or
   stale copy, before blaming the system.
-- Use supplied commands unchanged except inputs, else documented defaults
-  scoped to the change; no stricter flags or unrequested suites; gates belong
-  to release.
+- Use supplied commands unchanged except inputs; no stricter flags or
+  unrequested suites.
 - Warnings or blocked checks never justify editing passing code. Fix obsolete
-  expectations, not valid requirements; new tests assert behavior, not code shape.
+  expectations, not valid requirements. A bug fix gets one regression test;
+  tests assert behavior, never removals, constants or copied code.
 - Missing dependencies block verification; use only evidenced recovery routes.
   Report verified results and blockers.
 

package/src/rules/shared/70-delivery.md

@@ -1,8 +1,9 @@
 # Delivery
 
 - Unless the user explicitly requests them, do not author separate record-keeping
-  artifacts (reports, progress logs, notes, or checklists). Report progress and
-  results in the conversation instead.
+  artifacts (reports, progress logs, notes, or checklists).
+<!-- tools: lead -->
+  Report progress and results in the conversation instead.
 - Reference files and folders in inline code by a Project-root-relative or
   absolute path, optionally `:line[:column]` (`deliverables/report.docx`,
   `src/app.ts:42`); files outside the Project always by absolute path; never a
@@ -11,14 +12,12 @@
   and give their path; never open them in the system browser or paste their
   source unless the user asks.
 <!-- tools: visualize -->
-- Open each finished artifact beside the chat with `visualize open` when available.
-  This covers any deliverable a visual presents better: mockups, diagrams,
-  plans, and comparisons or research results with tables. Present these as
-  a visualize page and keep the chat to a short summary.
+- Show every finished visual artifact with `visualize open`, loading its schema
+  first if deferred: images, video, HTML, documents, decks, mockups, diagrams.
+  A summary, plan or report of your own work stays in the chat, never a
+  visualize page. `open` shows the user a deliverable; to check your own
+  work (`check`, `inspect`, `capture`, `export`), open with `verify: true`.
 
 <!-- tools: git -->
 - A commit request includes selecting and staging its changes; a stage-only
   request stops before commit. Do not stage changes without either request.
-<!-- tools: git -->
-- Stage selected diff changes with `git` using `action:"stage"`. Keep this
-  internal step within the requested commit workflow, not a separate approval.

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

@@ -3,13 +3,17 @@
 // cancellation sources, so collapse them before installing that one link.
 // The first already-aborted source wins (in declaration order), retaining its
 // original reason instead of replacing it with a generic AbortError.
-export function composeAgentDispatchAbortSignal(signals) {
+// `onWinner(signal)` runs once, with the source that won, before the composite
+// aborts: the owner of a timeout source arms its own bookkeeping there, and a
+// source that fires after another already won is never reported.
+export function composeAgentDispatchAbortSignal(signals, onWinner = null) {
   const sources = (Array.isArray(signals) ? signals : []).filter((signal) => signal instanceof AbortSignal);
   if (sources.length === 0) return { signal: null, dispose: () => {} };
   const controller = new AbortController();
   const listeners = [];
   const abortFrom = (signal) => {
     if (controller.signal.aborted) return;
+    onWinner?.(signal);
     try {
       controller.abort(signal.reason);
     } catch {

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

@@ -34,6 +34,7 @@ import {
   getSession,
   linkParentSignalToSession,
 } from '../session/manager.mjs';
+import { armTurnTimeout } from '../session/manager/turn-reap.mjs';
 import { resolveAgentWatchdogPolicy } from './agent-progress-watchdog.mjs';
 import { resourceAdmission } from '../../../shared/resource-admission.mjs';
 import { composeAgentDispatchAbortSignal } from './agent-dispatch/abort-link.mjs';
@@ -160,7 +161,15 @@ async function dispatchAdmitted(agent, opts, callArgs, { prepare, ask, updateSta
   // each link replaces the previous listener in runtime-liveness. One
   // composite survives askSession's controller swap and makes every source
   // reach the provider call.
-  const abortLink = composeAgentDispatchAbortSignal([opts.parentSignal, callParentSignal, watchdog.signal]);
+  // The watchdog arms this session's own timeout reap only when it is the
+  // source that stops the turn; an inherited parent abort that won first is a
+  // cancel for this child and never arms it.
+  const abortLink = composeAgentDispatchAbortSignal(
+    [opts.parentSignal, callParentSignal, watchdog.signal],
+    (source) => {
+      if (source === watchdog.signal) armTurnTimeout(session.id);
+    }
+  );
   if (abortLink.signal) {
     try {
       linkParentSignalToSession(session.id, abortLink.signal);

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

@@ -8,8 +8,9 @@
  * and never while the turn waits on the user's approval (`awaitingUser`).
  */
 
-import { appendAgentTrace } from '../agent-trace-io.mjs';
+import { appendAgentTrace, normalizeSessionId, _appendToolFailureRow } from '../agent-trace-io.mjs';
 import { getHiddenAgent } from '../internal-agents.mjs';
+import { PACKAGE_VERSION } from '../../../web-search/lib/package-version.mjs';
 import { envNonNegativeInt, envPresent } from '../../../shared/env.mjs';
 import {
   PROVIDER_FIRST_BYTE_TIMEOUT_MS,
@@ -126,22 +127,113 @@ export function partialHandoffTextFromSession(session, messageStartIndex = 0) {
 /** Owner-facing handoff for a watchdog-stopped agent: the stop and its reason
  *  come first, so the owner never mistakes the partial text for a finished
  *  result or a user cancel. */
-export function watchdogStoppedHandoff(error, partial) {
-  return `[Agent stopped by the progress watchdog: ${error.message}. The output below is partial.]\n\n${partial}`;
+export function watchdogStoppedHandoff(error, partial, shellJobs) {
+  const note = stoppedShellJobsNote(shellJobs);
+  return `[Agent stopped by the progress watchdog: ${error.message}. The output below is partial.]${note ? `\n${note}` : ''}\n\n${partial}`;
 }
 
-function resolveWatchdogAbortElapsedMs({ snapshot, policy, now, anchorTs, lastProgressAt }) {
+// Jobs confirmed gone are "stopped"; the others were killed but their
+// processes are not yet confirmed gone, so they are "still stopping".
+function stoppedShellJobsNote({ stopped = [], stopping = [] } = {}) {
+  return [
+    stopped.length > 0 && `[Stopped its background shell jobs: ${stopped.join(', ')}.]`,
+    stopping.length > 0 && `[Still stopping its background shell jobs: ${stopping.join(', ')}.]`,
+  ]
+    .filter(Boolean)
+    .join(' ');
+}
+
+/** A stall with no partial output is rethrown as the error: name the stopped
+ *  jobs in its text so the caller still learns them. */
+export function noteStoppedShellJobsOnError(error, shellJobs) {
+  const note = stoppedShellJobsNote(shellJobs);
+  if (note && error && typeof error === 'object') error.message = `${error.message} ${note}`;
+}
+
+// The timestamp the stop was measured from, and which clock it is.
+function resolveWatchdogAbortClock({ snapshot, policy, anchorTs, lastProgressAt }) {
   if (snapshot && policy) {
     if (snapshot.waitingForFirstSemantic) {
-      const startedAt = snapshot.modelRequestStartedAt || snapshot.askStartedAt;
-      if (startedAt) return Math.max(0, now - startedAt);
+      if (snapshot.modelRequestStartedAt) return { at: snapshot.modelRequestStartedAt, field: 'model_request_started_at' };
+      if (snapshot.askStartedAt) return { at: snapshot.askStartedAt, field: 'ask_started_at' };
     }
-    const last = snapshot.lastProgressAt || snapshot.firstActivityAt;
-    if (last) return Math.max(0, now - last);
+    if (snapshot.lastProgressAt) return { at: snapshot.lastProgressAt, field: 'last_progress_at' };
+    if (snapshot.firstActivityAt) return { at: snapshot.firstActivityAt, field: 'first_activity_at' };
   }
-  const last = lastProgressAt || anchorTs;
-  if (last) return Math.max(0, now - last);
-  return null;
+  if (lastProgressAt) return { at: lastProgressAt, field: 'reported_progress_at' };
+  if (anchorTs) return { at: anchorTs, field: 'anchor_ts' };
+  return { at: null, field: null };
+}
+
+// Which deadline fired, read from the abort message. `idle_bare` is the form
+// the registry/dispatch fallback throws when no progress snapshot existed.
+function watchdogAbortKind(message) {
+  const limit = Number(/\((\d+)ms/.exec(message)?.[1]) || null;
+  if (/^agent first transport stale/.test(message)) return { window: 'first_response', form: 'first_transport', limit };
+  if (/^agent first semantic response stale/.test(message)) return { window: 'first_output', form: 'first_semantic', limit };
+  if (/^agent task stale \(\d+ms without stream\/tool progress\)/.test(message)) {
+    return { window: 'idle', form: 'idle_progress', limit };
+  }
+  if (/^agent task stale/.test(message)) return { window: 'idle', form: 'idle_bare', limit };
+  if (/^agent progress checks failed/.test(message)) return { window: 'idle', form: 'checks_failed', limit: null };
+  return { window: null, form: 'other', limit: null };
+}
+
+// Shipped builds keep no agent trace, so a stop could not be audited after the
+// fact (was the agent really silent?). The tool-failure log stays on in ship
+// mode; the row holds clocks and names only, never prompt or output text.
+// `observation` says how the snapshot was obtained: a wire-safe runtime is
+// sampled asynchronously and the watchdog may judge a cached read, so
+// `snapshot_present` alone does not prove the clocks are current. Only an error
+// name/code is kept from a failed read, never its message.
+function recordAgentWatchdogAbortRow({
+  sessionId,
+  agent,
+  error,
+  snapshot,
+  policy,
+  clock,
+  elapsed,
+  anchorTs,
+  lastProgressAt,
+  iteration,
+  observation,
+  registrationId,
+}) {
+  if (process.env.MIXDOG_AGENT_TRACE_DISABLE === '1') return;
+  const message = typeof error.message === 'string' ? error.message : '';
+  const { window, form, limit } = watchdogAbortKind(message);
+  _appendToolFailureRow({
+    ts: Date.now(),
+    kind: 'stall_abort',
+    category: 'agent-stall',
+    build_version: PACKAGE_VERSION,
+    registration_id: registrationId || null,
+    session_id: normalizeSessionId(sessionId),
+    iteration: iteration ?? null,
+    agent: agent || null,
+    stage: snapshot?.stage ?? null,
+    window,
+    limit_ms: limit ?? policy?.idleStaleMs ?? null,
+    form,
+    compared_field: clock.field,
+    compared_at: clock.at,
+    elapsed_ms: elapsed,
+    snapshot_present: Boolean(snapshot),
+    snapshot_source: snapshot ? observation?.source || 'direct' : null,
+    last_read_ok_at: observation?.lastReadOkAt || null,
+    read_pending_since: observation?.readPendingSince || null,
+    last_read_error: observation?.lastReadError || null,
+    ask_started_at: snapshot?.askStartedAt || null,
+    model_request_started_at: snapshot?.modelRequestStartedAt || null,
+    waiting_for_transport: snapshot ? Boolean(snapshot.waitingForTransport) : null,
+    waiting_for_first_semantic: snapshot ? Boolean(snapshot.waitingForFirstSemantic) : null,
+    awaiting_user: snapshot?.awaitingUser || null,
+    last_progress_at: snapshot?.lastProgressAt || lastProgressAt || null,
+    last_keepalive_at: snapshot?.lastKeepaliveAt || null,
+    anchor_ts: anchorTs || null,
+    current_tool: snapshot?.currentTool || null,
+  });
 }
 
 function recordAgentWatchdogAbort({
@@ -154,15 +246,14 @@ function recordAgentWatchdogAbort({
   anchorTs = 0,
   lastProgressAt = 0,
   iteration = null,
+  observation = null,
+  registrationId = null,
+  comparedClock = null,
 }) {
   if (!sessionId || !error) return;
-  const elapsed = resolveWatchdogAbortElapsedMs({
-    snapshot,
-    policy,
-    now,
-    anchorTs,
-    lastProgressAt,
-  });
+  // A caller that decided on its own clock (the failed-checks stop) names it.
+  const clock = comparedClock || resolveWatchdogAbortClock({ snapshot, policy, anchorTs, lastProgressAt });
+  const elapsed = clock.at ? Math.max(0, now - clock.at) : null;
   try {
     appendAgentTrace({
       sessionId,
@@ -178,6 +269,24 @@ function recordAgentWatchdogAbort({
   } catch {
     /* best-effort */
   }
+  try {
+    recordAgentWatchdogAbortRow({
+      sessionId,
+      agent,
+      error,
+      snapshot,
+      policy,
+      clock,
+      elapsed,
+      anchorTs,
+      lastProgressAt,
+      iteration,
+      observation,
+      registrationId,
+    });
+  } catch {
+    /* best-effort */
+  }
 }
 
 export function abortAgentProgressWatchdog(controller, ctx) {
@@ -243,11 +352,13 @@ export function resolveAgentWatchdogPolicy(agent, overrides = {}) {
     // Role budget, floored so the provider recovery window always wins.
     idleStaleMs = Math.max(abort * 1000, PROVIDER_RECOVERY_FLOOR_MS);
   } else {
-    // Part B: the primary mid-stream stall catch is now the provider-level
-    // SEMANTIC idle abort (~120s, ping-immune). This public-agent idle is a
-    // BACKSTOP only, so it must not exceed the stall abort (600s default) —
-    // the old 30-min value meant a ping-only wedge that slipped past the
-    // provider layer would still hang the owner for half an hour. Cap it at
+    // Part B: the provider-level idle abort is the first mid-stream catch, but
+    // it is transport-based for Anthropic (pings reset it; other providers
+    // judge semantic idle). This public-agent idle is a BACKSTOP only, so it
+    // must not exceed the stall abort (600s default): a ping-only wedge that
+    // slipped past the provider layer would otherwise hang the owner for half
+    // an hour. Anthropic pings extend it only up to
+    // KEEPALIVE_MAX_IDLE_MULTIPLIER times (evaluateAgentWatchdogAbort). Cap it at
     // the stall abort while keeping 30 min as an absolute ceiling. Long tool
     // calls refresh progress through the activity heartbeat, so they never
     // trip this backstop.
@@ -270,6 +381,23 @@ export function resolveAgentWatchdogPolicy(agent, overrides = {}) {
   };
 }
 
+// How far keepalives may extend liveness past the last real progress, as a
+// multiple of the idle budget. Anthropic pings across legitimate generation
+// gaps (adaptive thinking, a buffered tool input), but a wedged stream that
+// pings forever must still die.
+export const KEEPALIVE_MAX_IDLE_MULTIPLIER = 3;
+
+// A keepalive newer than the last real progress holds the idle abort while it
+// is itself fresh and the silence is within the cap. The runtime records one
+// only after the request's first semantic event, so a ping before it never
+// reaches here (the first-output window owns that phase).
+function keepaliveHoldsIdle(snapshot, last, now, idleStaleMs) {
+  const keepaliveAt = snapshot.lastKeepaliveAt || 0;
+  return (
+    keepaliveAt > last && now - keepaliveAt <= idleStaleMs && now - last <= idleStaleMs * KEEPALIVE_MAX_IDLE_MULTIPLIER
+  );
+}
+
 export function evaluateAgentWatchdogAbort(snapshot, now, policy) {
   if (!snapshot || !policy) return null;
   // A turn blocked on the user's tool approval (its own, or a sub-agent's that
@@ -285,7 +413,10 @@ export function evaluateAgentWatchdogAbort(snapshot, now, policy) {
   const firstSemanticMs = policy.firstSemanticMs ?? policy.firstVisibleCeilingMs ?? 0;
   // Independent fixed deadlines from request start. Transport can satisfy
   // only the transport deadline; it never switches, extends, or resets the
-  // semantic-response deadline.
+  // semantic-response deadline. Both are judged per logical model request
+  // (runtime-liveness): the request that carries tool results gets the same
+  // first-output allowance as the turn's first request, while a retry of a
+  // request keeps that request's clock and marks.
   if (snapshot.waitingForTransport && firstTransportMs > 0 && startedAt && now - startedAt > firstTransportMs) {
     return new AgentStallAbortError(`agent first transport stale (${firstTransportMs}ms)`);
   }
@@ -298,6 +429,7 @@ export function evaluateAgentWatchdogAbort(snapshot, now, policy) {
 
   const last = snapshot.lastProgressAt || snapshot.firstActivityAt;
   if (policy.idleStaleMs > 0 && last && now - last > policy.idleStaleMs) {
+    if (keepaliveHoldsIdle(snapshot, last, now, policy.idleStaleMs)) return null;
     return new AgentStallAbortError(`agent task stale (${policy.idleStaleMs}ms without stream/tool progress)`);
   }
 

package/src/runtime/agent/orchestrator/agent-runtime/cache-strategy.mjs

@@ -563,6 +563,19 @@ function oneShotPromptCacheOpts(agent) {
   return isOneShotMaintenanceAgent(agent) ? { promptCacheScope: 'shared' } : null;
 }
 
+/**
+ * Cache send options for a session-less loop whose system prompt and tool
+ * schemas are the same bytes on every call (the explore tool's explorers):
+ * keyed on that prefix, never per call, on the default 5m tier. The parallel
+ * explorers of a fan-out and the next calls minutes later are its only
+ * readers, so the Lead's 1h / 12h tiers would only raise the write price.
+ */
+export function sharedPrefixProviderCacheOpts(provider) {
+  const shared = { promptCacheScope: 'shared' };
+  if (cacheCapabilityForProvider(provider) !== 'explicit-breakpoint') return shared;
+  return { ...shared, cacheStrategy: { tools: 'none', system: '5m', tier3: 'none', messages: '5m' } };
+}
+
 /**
  * Cache send options for a role's requests on `provider`: the breakpoint
  * strategy on explicit-breakpoint providers, the Lead-class 12h prefix TTL on

package/src/runtime/agent/orchestrator/agent-runtime/maintenance-route.mjs

@@ -3,6 +3,9 @@ import { normalizeContextTokens } from '../../../shared/llm/default-context-wind
 import { loadConfig } from '../config.mjs';
 import { getHiddenAgent } from '../internal-agents.mjs';
 
+// The settings agent whose route a hidden role runs on.
+const ROLE_BY_MAINT_KEY = Object.freeze({ memory: 'maintainer', explore: 'explore' });
+
 function normalizeMaintenanceCandidate(candidate) {
   if (!candidate || typeof candidate !== 'object' || Array.isArray(candidate)) return candidate || null;
   const provider = String(candidate.provider || '').trim();
@@ -38,7 +41,7 @@ export function resolveMaintenanceRoute({ preset, optsPreset, agent, config: cfg
     try {
       const config = cfgIn || loadConfig({ secrets: false });
       const key = hidden.maintKey || hidden.slot;
-      const role = key === 'memory' ? 'maintainer' : '';
+      const role = ROLE_BY_MAINT_KEY[key] || '';
       if (!role) return config?.maintenance?.[key] ?? null;
       // A disabled agent must not silently fall back to the Main model:
       // "off" means the maintenance role does not run at all.

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

@@ -53,6 +53,7 @@ export function buildCacheBreakPayload(record = {}) {
     input_prefix_mismatch_actual_hash: cleanHash(record.inputPrefixMismatchActualHash),
     changed_blocks: cleanText(record.changedBlocks),
     system_markers_changed: typeof record.markersChanged === 'boolean' ? record.markersChanged : null,
+    lost_message_breakpoints: cleanText(record.lostMessageBreakpoints),
   };
   return Object.fromEntries(Object.entries(payload).filter(([, value]) => value !== null));
 }
@@ -81,6 +82,7 @@ function formatCacheBreakLine(record = {}) {
     ['noGuardBaseline', payload.missing_prefix_guard_baseline],
     ['changedBlocks', payload.changed_blocks],
     ['systemMarkersChanged', payload.system_markers_changed],
+    ['lostMessageBreakpoints', payload.lost_message_breakpoints],
   ].filter(([, value]) => value !== null && value !== undefined);
   return `[cache-break] ${fields.map(([key, value]) => (typeof value === 'string' ? `${key}=${JSON.stringify(value)}` : `${key}=${value}`)).join(' ')}`;
 }

package/src/runtime/agent/orchestrator/config.mjs

@@ -78,6 +78,10 @@ export function buildDefaultConfig(options = {}) {
       apiKey: apiKey || undefined,
     };
   }
+  // authMode: 'service-account' (the stored key), 'adc' (the gcloud login or a
+  // metadata server, nothing stored) or 'api-key' (an express-mode key). No
+  // location: unset follows the environment's region, then global.
+  providers['vertex-ai'] = { enabled: false, authMode: 'service-account' };
   // OAuth provider detection uses lightweight credential probes so config
   // load does not import provider runtimes or SDKs.
   //
@@ -299,13 +303,13 @@ export function loadConfig(options = {}) {
         recap: recapConfig,
         // The model may title the session (session tool, action=rename); default on.
         aiSessionTitles: raw.aiSessionTitles !== false,
-        // Mixy's heartbeat check (session-runtime/mixy-heartbeat.mjs); default on.
-        heartbeat: raw.heartbeat !== false,
+        // Mixy's heartbeat check (session-runtime/mixy-heartbeat.mjs); default off.
+        heartbeat: raw.heartbeat === true,
         // Minutes between its checks, one of a fixed set (shared/heartbeat-interval.mjs);
         // anything else reads as the default.
         heartbeatIntervalMinutes: normalizeHeartbeatIntervalMinutes(raw.heartbeatIntervalMinutes),
-        // Prompt-cache warming (session/cache-warm.mjs); default on.
-        promptCacheWarming: raw?.promptCacheWarming !== false,
+        // Prompt-cache warming (session/cache-warm.mjs); default off.
+        promptCacheWarming: raw?.promptCacheWarming === true,
         // Bots may leave an emoji reaction on the user's message (react tool); default on.
         reactions: raw.reactions !== false,
         // Bots page layout (order, hidden groups, pins, retention) and the shared
@@ -360,7 +364,7 @@ export function loadConfig(options = {}) {
     shell: {},
     update: {},
     recap: { enabled: true },
-    promptCacheWarming: true,
+    promptCacheWarming: false,
     worktree: normalizeWorktreeSettings(null),
     developer: {},
     modules: {},
@@ -490,7 +494,8 @@ function buildAgentSaveBuilder(config) {
     // Default true lives in code: only the opt-out is stored.
     if (config.aiSessionTitles === false) next.aiSessionTitles = false;
     else delete next.aiSessionTitles;
-    if (config.heartbeat === false) next.heartbeat = false;
+    // Default off lives in code: only the opt-in is stored.
+    if (config.heartbeat === true) next.heartbeat = true;
     else delete next.heartbeat;
     // Only a non-default choice is stored.
     const heartbeatMinutes = normalizeHeartbeatIntervalMinutes(config.heartbeatIntervalMinutes);
@@ -498,7 +503,7 @@ function buildAgentSaveBuilder(config) {
     else delete next.heartbeatIntervalMinutes;
     if (config.reactions === false) next.reactions = false;
     else delete next.reactions;
-    if (config.promptCacheWarming === false) next.promptCacheWarming = false;
+    if (config.promptCacheWarming === true) next.promptCacheWarming = true;
     else delete next.promptCacheWarming;
     if (Array.isArray(config.botOrder) && config.botOrder.length) next.botOrder = [...config.botOrder];
     else delete next.botOrder;

package/src/runtime/agent/orchestrator/context/deferred-tools.mjs

@@ -100,7 +100,7 @@ export function buildDeferredToolManifest(entries) {
   list.sort((a, b) => a.name.localeCompare(b.name));
   return [
     '<available-deferred-tools>',
-    'Deferred tool names and selection triggers; schemas load on demand.',
+    'Deferred tools; load_tool loads their schemas.',
     ...list.map((entry) => (entry.description ? `- ${entry.name}: ${entry.description}` : `- ${entry.name}`)),
     '</available-deferred-tools>',
   ].join('\n');
@@ -156,8 +156,8 @@ const firstSentence = (text) => {
 };
 
 // A catalog connector's curated when-to-use trigger; else the first sentence
-// of the server's MCP instructions; else its tools' leading descriptions (name
-// order); else its name. Never the account: that is part of the instruction
+// of the server's MCP instructions; else the leading description of its first
+// described tool (name order); else its name. Never the account: that is part of the instruction
 // text delivered when the server's tools are loaded. Derived lines are
 // compacted to at most 98 characters, ellipsis included.
 function mcpServerTrigger(server, tools, instructions) {
@@ -168,11 +168,11 @@ function mcpServerTrigger(server, tools, instructions) {
   const instruction = String(instructions?.[server] || '')
     .replace(/[<>]/g, '')
     .replace(/^\s*Account: \S+?\.\s+/, '');
-  const described = [...tools]
-    .sort((a, b) => String(a?.name || '').localeCompare(String(b?.name || '')))
-    .map((tool) => firstSentence(String(tool?.description || '').replace(/[<>]/g, '')))
-    .filter(Boolean)
-    .join('; ');
+  const described =
+    [...tools]
+      .sort((a, b) => String(a?.name || '').localeCompare(String(b?.name || '')))
+      .map((tool) => firstSentence(String(tool?.description || '').replace(/[<>]/g, '')))
+      .find(Boolean) || '';
   const derived = firstSentence(instruction) || described;
   return derived ? compactPromptManifestText(derived, 98) : `${titleCaseMcpServer(server)} MCP server tools.`;
 }

package/src/runtime/agent/orchestrator/context/role-instructions.mjs

@@ -7,7 +7,7 @@ import { compareCodePoints } from '../../../shared/code-point-order.mjs';
 import { BOTS_DIR, MIXY_BOT_ID, botStoreActive, isStoreBot, mixyIdentityDir } from '../../../shared/agent-store.mjs';
 import { mixdogRoot } from '../../../shared/plugin-paths.mjs';
 import { readMarkdownDocument } from '../../../shared/markdown-frontmatter.mjs';
-import { listHiddenAgentsByKind, getAgentCatalogShareAgents } from '../internal-agents.mjs';
+import { listHiddenAgentsByKind } from '../internal-agents.mjs';
 import { mixdogGlobalDir, mtimeWithTtl, readSafe } from './skill-catalog.mjs';
 import { mixyDisplayName } from '../session/mixy-name.mjs';
 
@@ -15,14 +15,14 @@ import { mixyDisplayName } from '../session/mixy-name.mjs';
 // Emits a BP2 agent/system block scoped to the calling agent:
 //   - Public/custom agents: their own agents/<agent>.md when present,
 //     plus the public agent-worker contract.
-//   - Hidden agents: their own rules/agent/<agent>.md section only.
+//   - Hidden maintenance agents: their own rules/agent/<agent>.md section only.
 //   - Null agent: falls back to the full all-in-one block
 //     (explicit-cache unified-shard path).
 //
 // Agent-specific markdown intentionally rides BP2, behind the shared BP1 tool
 // and skill manifest prefix, so agent changes do not disturb the common layer.
 //
-// Classification is dynamic — hidden retrieval/maintenance sets come from the
+// Classification is dynamic — the hidden maintenance set comes from the
 // `kind` field in internal-agents.mjs. Any other non-null agent is public/custom.
 
 // One catalog/rules section; selectRoleInstructionSections matches sections
@@ -36,10 +36,7 @@ function loadAgentClassification() {
   // listHiddenAgentsByKind now reads from the mtime-aware cache inside
   // internal-agents.mjs so the classification always reflects the current
   // agents.json on disk.
-  return {
-    retrieval: new Set(listHiddenAgentsByKind('retrieval')),
-    maintenance: new Set(listHiddenAgentsByKind('maintenance')),
-  };
+  return { maintenance: new Set(listHiddenAgentsByKind('maintenance')) };
 }
 
 const _scopedRoleInstructionsCache = new Map();
@@ -167,28 +164,13 @@ function selfHiddenRuleSection(hiddenPairs, agent) {
   return self ? [roleSection(self.name, self.body)] : [];
 }
 
-function selectRoleInstructionSections({
-  useUnified,
-  agent,
-  classification,
-  agentSharesCatalog,
-  agentSections,
-  hiddenPairs,
-}) {
+function selectRoleInstructionSections({ useUnified, agent, classification, agentSections, hiddenPairs }) {
   if (useUnified || !agent) {
     return {
       agentRuleSectionsToEmit: hiddenRuleSections(hiddenPairs),
       agentSectionsToEmit: agentSections,
     };
   }
-  if (classification.retrieval.has(agent)) {
-    return {
-      agentRuleSectionsToEmit: selfHiddenRuleSection(hiddenPairs, agent),
-      agentSectionsToEmit: agentSections.filter((s) =>
-        [...agentSharesCatalog].some((name) => s.startsWith(`## ${name}\n`))
-      ),
-    };
-  }
   if (classification.maintenance.has(agent)) {
     const selfRules = selfHiddenRuleSection(hiddenPairs, agent);
     const fromAgent = agentSections.find((s) => s.startsWith(`## ${agent}\n`));
@@ -233,8 +215,6 @@ export function loadScopedRoleInstructions(agent, provider = null) {
   // failures (malformed/missing agents.json) must propagate, not be
   // silently swallowed by the file-IO catch below.
   const classification = loadAgentClassification();
-  const agentSharesCatalog =
-    agent && classification.retrieval.has(agent) ? new Set(getAgentCatalogShareAgents(agent)) : new Set();
   try {
     const agentSections = loadAgentSections(pluginRoot);
     const hiddenPairs = loadHiddenAgentSnippets(pluginRoot);
@@ -243,7 +223,6 @@ export function loadScopedRoleInstructions(agent, provider = null) {
       useUnified,
       agent,
       classification,
-      agentSharesCatalog,
       agentSections,
       hiddenPairs,
     });

package/src/runtime/agent/orchestrator/context/skill-catalog.mjs

@@ -669,7 +669,9 @@ export function buildSkillManifest(skills, { limit = 80, charBudget = SKILL_MANI
   for (const skill of visible) skill.trigger = compactPromptManifestText(skill.trigger, triggerCap);
   const lines = [
     '# available-skills',
-    'Selection triggers and linked tools for Skill({"name":"<skill-name>"}). mcp:<server> denotes that server’s tools.',
+    visible.some((skill) => skill.linkedTools.some((tool) => tool.startsWith('mcp:')))
+      ? 'Selection triggers and linked tools. mcp:<server> denotes that server’s tools.'
+      : 'Selection triggers and linked tools.',
     '<available_skills>',
     ...visible.map(
       (skill) => (skill.trigger ? `- ${skill.name}: ${skill.trigger}` : `- ${skill.name}`) + toolSuffix(skill)

package/src/runtime/agent/orchestrator/internal-agents.mjs

@@ -20,9 +20,10 @@
  * found" error rather than silently mis-dispatching.
  *
  * Kind classification:
- *   - 'retrieval'   : short-lived hidden retrieval agents.
  *   - 'maintenance' : background-trigger hidden agents (memory cycle and
  *                     title generation). Receive only their own self section.
+ *   An entry without a kind only names a route (the explore tool's
+ *   `explore-agent`, which runs no session).
  *
  * Permission classification:
  *   - 'read'       : read-only — apply_patch/shell blocked at loop.mjs runtime
@@ -185,7 +186,7 @@ export function listHiddenAgentNames() {
 }
 
 /**
- * List hidden agent names matching a given kind ('retrieval' | 'maintenance').
+ * List hidden agent names matching a given kind ('maintenance').
  * Consumed by collect.mjs to drive BP2 agent classification dynamically
  * instead of hard-coding agent-name sets.
  */
@@ -196,15 +197,3 @@ export function listHiddenAgentsByKind(kind) {
   }
   return out;
 }
-
-/**
- * Return the agents/<name>.md sections a hidden agent shares in its BP2 catalog
- * (in addition to its own self section). Drives hidden-role cache
- * alignment declaratively instead of a hard-coded agent-name branch in
- * collect.mjs. Returns [] when the agent declares none.
- */
-export function getAgentCatalogShareAgents(name) {
-  const hidden = getHiddenAgent(name);
-  if (!hidden || !Array.isArray(hidden.catalogShareAgents)) return [];
-  return hidden.catalogShareAgents.map((n) => String(n || '').trim()).filter(Boolean);
-}