mixdog 1.4.1 → 1.4.3

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,115 @@ 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 +248,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 +271,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) {
@@ -246,9 +357,9 @@ export function resolveAgentWatchdogPolicy(agent, overrides = {}) {
     // 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) — 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. Anthropic pings extend it only up to
+    // 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

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

@@ -255,15 +255,6 @@ export function cacheCapabilityForProvider(provider) {
   return PROVIDER_CACHE_CAPABILITY[provider] || 'none';
 }
 
-export function shouldMarkWarmForProvider(provider) {
-  const capability = cacheCapabilityForProvider(provider);
-  return capability === 'explicit-breakpoint' || capability === 'key-prefix' || capability === 'managed-explicit';
-}
-
-export function shouldRecordObservedForProvider(provider) {
-  return cacheCapabilityForProvider(provider) === 'implicit-observed';
-}
-
 // Stable provider namespaces, not final wire cache keys. The request builders
 // add session identity by default; explicit overrides can enable shared routing.
 // Anthropic/Gemini use content-keyed breakpoints / explicit cache objects instead.
@@ -563,6 +554,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/heartbeat-completion.mjs

@@ -12,8 +12,8 @@ const TIMEOUT_MS = 30_000;
 // Every digest is new and asked once: a cache write would cost more than any
 // read it could earn, so no layer is marked.
 const NO_PROMPT_CACHE = Object.freeze({ tools: 'none', system: 'none', tier3: 'none', messages: 'none' });
-export const HEARTBEAT_NOTHING = 'NOTHING';
-export const HEARTBEAT_WAKE = 'WAKE';
+const HEARTBEAT_NOTHING = 'NOTHING';
+const HEARTBEAT_WAKE = 'WAKE';
 const MAX_ITEMS = 5;
 const ITEM_LIMIT = 300;
 

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/agent-runtime/session-builder.mjs

@@ -22,6 +22,16 @@ import { traceAgentPreset } from '../agent-trace.mjs';
 import { resolveAgentSessionPermission } from '../internal-agents.mjs';
 import { loadConfig } from '../config.mjs';
 import { RETIRED_COMPACTION_FIELDS } from '../config-storage.mjs';
+import {
+  liveFeatureDisallowedTools,
+  stageConnectorAvailability,
+  stageToolAvailability,
+} from '../runtime-core/tool-availability.mjs';
+import { COMPACTION_CONFIG_KEYS } from '../runtime-core/compaction-config-keys.mjs';
+import { stagePromptSettingsNotice } from '../session/manager/prompt-settings.mjs';
+import { loadInstructionFilesContext } from '../context/instruction-files.mjs';
+import { normalizeInstructionFilesMode } from '../../../shared/instruction-files-mode.mjs';
+import { finalizeSessionToolList, previewSessionTools } from '../session/manager/tool-resolution.mjs';
 
 function normalizeAgentCompactionConfig(value = {}) {
   const raw = value && typeof value === 'object' ? value : {};
@@ -89,8 +99,12 @@ export function prepareAgentSession({
   const effectiveOwnerSessionId =
     ownerSessionId === undefined ? process.env.MIXDOG_OWNER_SESSION_ID || null : ownerSessionId;
   let compaction = null;
+  // The settings gates as they stand: a disabled feature (git and github
+  // included) never reaches the agent's schema or dispatch.
+  let featureDenied = [];
   try {
     const cfg = loadConfig({ secrets: false });
+    featureDenied = liveFeatureDisallowedTools(cfg);
     if (cfg?.compaction && typeof cfg.compaction === 'object') {
       compaction = normalizeAgentCompactionConfig(cfg.compaction);
     }
@@ -114,6 +128,8 @@ export function prepareAgentSession({
     clientHostPid: clientHostPid || null,
     compaction: compaction || undefined,
     mcpScopeId: mcpScopeId || null,
+    callerDisallowedTools: [],
+    disallowedTools: featureDenied,
   };
   if (contextPercent) sessionOpts.contextPercent = contextPercent;
   if (contextTokens) sessionOpts.contextTokens = contextTokens;
@@ -142,3 +158,54 @@ export function prepareAgentSession({
   }
   return { session, effectiveCwd };
 }
+
+/**
+ * An in-process agent session reused for another turn (no session runtime
+ * turn start reconciles it): bring it to the settings as they stand without
+ * touching its request prefix — its settings-gated tools
+ * (stageToolAvailability), its connectors (stageConnectorAvailability) and
+ * its compaction settings. Returns the tool change, or null.
+ */
+export function reconcileAgentSession(session) {
+  if (!session?.id) return null;
+  let cfg;
+  try {
+    cfg = loadConfig({ secrets: false });
+  } catch {
+    return null;
+  }
+  if (cfg?.compaction && typeof cfg.compaction === 'object') {
+    // Config-owned keys follow the settings; the session's own state stays.
+    const own = { ...(session.compaction || {}) };
+    for (const key of COMPACTION_CONFIG_KEYS) delete own[key];
+    session.compaction = { ...own, ...normalizeAgentCompactionConfig(cfg.compaction) };
+  }
+  const connectors = stageConnectorAvailability(session);
+  // The prompt settings a delegated worker's prompt carries: its instruction
+  // files (the rest are a Lead's). Told once, like a session runtime's turn start.
+  if (session.promptSettings && session.skipInstructionFiles !== true && session.cwd) {
+    const toolFree = Array.isArray(session.schemaAllowedTools) && session.schemaAllowedTools.length === 0;
+    const skip = toolFree || session.promptIdentity?.profileSkip?.claudemd;
+    stagePromptSettingsNotice(session, {
+      only: ['instructionFiles'],
+      instructionFiles: skip ? '' : loadInstructionFilesContext({ mode: cfg?.instructionFiles, cwd: session.cwd }),
+      instructionFilesMode: normalizeInstructionFilesMode(cfg?.instructionFiles),
+    });
+  }
+  const tools = stageToolAvailability(session, liveFeatureDisallowedTools(cfg), (names) =>
+    finalizeSessionToolList(
+      previewSessionTools('full', [], {
+        ownerIsAgentSession: true,
+        mcpScopeId: session.mcpScopeId || null,
+        modelName: session.model,
+        cwd: session.cwd || null,
+      }).filter((tool) => names.includes(tool?.name)),
+      { ownerIsAgent: true }
+    )
+  );
+  if (!tools && !connectors) return null;
+  return {
+    added: [...(tools?.added || []), ...(connectors?.added || [])],
+    removed: [...(tools?.removed || []), ...(connectors?.removed || [])],
+  };
+}

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

@@ -422,6 +422,7 @@ function classifyToolFailure(resultText, toolName) {
   if (isUserControlCancellation(leading)) return 'expected-cancellation';
   if (
     /^The arguments provided to `[^`]+` are invalid JSON and could not be parsed:/i.test(leading) ||
+    // Retired Goal task errors: still in stored failure logs that get reclassified.
     /^new Goal tasks must omit ids; use updates for existing tasks$/i.test(leading) ||
     /^goal task exceeds \d+ characters$/i.test(leading) ||
     /^goal (?:tasks|updates) support at most \d+ entries(?:$|;)/i.test(leading) ||

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

@@ -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,
     });
@@ -274,13 +253,13 @@ export const PERSONA_MAX_CHARS = 4000;
 export const PERSONA_TRUNCATION_MARKER = '\n\n[persona truncated]';
 const PERSONA_AGENT_ID = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
 
-export function truncatePersona(text, max = PERSONA_MAX_CHARS) {
+function truncatePersona(text, max = PERSONA_MAX_CHARS) {
   const value = typeof text === 'string' ? text.trim() : '';
   if (value.length <= max) return value;
   return value.slice(0, max).trimEnd() + PERSONA_TRUNCATION_MARKER;
 }
 
-export function loadAgentPersonaSection(agent) {
+function loadAgentPersonaSection(agent) {
   if (typeof agent !== 'string' || !PERSONA_AGENT_ID.test(agent) || agent.includes('..')) return '';
   const isLead = agent === 'lead';
   // Mixy's persona is in its own folder; a store bot's in its bots/ folder.
@@ -325,7 +304,7 @@ function personaSection(persona) {
 // The user-editable 일하는 방식 of Mixy, framed like any agent's role section.
 // Agent mode only; empty or missing means no section. Re-read per
 // composition, so an edit applies to the next prompt build.
-export function loadMixyRoleSection() {
+function loadMixyRoleSection() {
   let raw = '';
   try {
     const dir = mixyDir();
@@ -402,7 +381,7 @@ export function agentModeIdentityLine(agent) {
 // invalid id. A coding Lead (`lead` outside Mixy's own thread) embeds no
 // profile file at all, so its stamp is a constant: editing Mixy never
 // rebuilds a coding session's prompt.
-export const CODING_LEAD_PROFILE_REVISION = 'coding-lead';
+const CODING_LEAD_PROFILE_REVISION = 'coding-lead';
 export function agentProfileRevision(agent, { mixy = true } = {}) {
   if (typeof agent !== 'string' || !PERSONA_AGENT_ID.test(agent) || agent.includes('..')) return '';
   if (agent === 'lead' && !mixy) return CODING_LEAD_PROFILE_REVISION;

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);
-}