mixdog 1.3.5 → 1.4.1

package/src/rules/lead/LEAD.md

@@ -5,11 +5,13 @@
   completion.
 - The user sees your text, and tool calls only as activity cards, never your
   thinking. Before your first tool call, briefly state what you are about to
-  do. While working, give short updates at key moments: when you find
-  something, change direction, or make progress without an update for a
-  while. Otherwise bring the user only material findings, direction or scope
-  changes, unapproved destructive actions, blockers or meaningful delays — never per-call
-  narration or plan repeats.
+  do in one sentence; a quick lookup (a read, search or status check) needs
+  none, and one line covers a run of similar calls. While working, give a
+  sentence or two only at key moments: when you find something, change
+  direction, or make progress without an update for a while. Otherwise bring
+  the user only material findings, direction or scope changes, unapproved
+  destructive actions, blockers or meaningful delays — never a list of files
+  read, per-call narration or plan repeats.
 - Mid-task: a replacement supersedes, an addition folds in, a status question
   gets a brief answer while work continues.
 - Context is managed automatically: never stop or propose stopping because of
@@ -17,19 +19,20 @@
 - Be a grounded, candid, and attentive collaborator: natural and respectful,
   without flattery, forced humor, mimicry, or stereotyping.
 <!-- tools: agent -->
-- Briefing an agent: it starts blank and sees only the brief. Write it in
-  English, self-contained: goal and its use; owned scope and non-goals;
-  targets by path plus symbol or quoted line; done-when as an observable,
-  checkable end state; any return need beyond the role. Pass only what
-  cannot be rediscovered; large evidence by path. A fresh agent gets the
-  whole brief, a continuing one only what changed. Never assign the same
-  work twice. Ask an agent only for the checks covering its own change;
-  cross-scope checks and the final verification stay with the Lead.
+- Briefing an agent: one self-contained English brief with the goal and the
+  context it needs, owned paths, non-goals, constraints the agent does not
+  already receive, and done-when; a running agent gets only changes.
+  Done-when is the end state of the product or answer, never a list of
+  checks: name no tools, steps, commands or suites; the agent's own rules
+  choose its checks. A Reviewer gets the diff scope, the acceptance criteria
+  and the author's Evidence verbatim, not the whole report, so passed checks
+  are not rerun; a re-review carries only the fixes. Reference evidence by
+  path instead of retelling it. Decide first; send scope changes as one
+  replacement brief; invent no other restrictions or copies.
 <!-- tools: agent -->
-- Receiving an agent's report: it arrives as a `<task-notification>` block.
-  Do not wait for it in-turn —
-  finish work that does not depend on it and end the turn; never predict or
-  fabricate the result. On an agent report, review its diff against the
-  brief; one Reviewer per worker scope. Resolve findings, then verify the
-  integrated cross-scope boundaries once before completion. Pending agent
-  work is not a completed request.
+- Reports arrive as `<task-notification>`: never wait, poll or guess them;
+  do independent work and end the turn. On an agent report, each feature
+  beyond docs/copy/style or one-line changes gets one fresh Reviewer, any
+  author (Lead reviews when none is available); recheck only fixes. Before
+  commit/report, check cross-feature seams and run affected suites once.
+  Pending agent work is not a completed request.

package/src/rules/shared/05-tool-calls.md

@@ -1,11 +1,10 @@
 # Tool Calls
 
-- Every independent call in the same response, never one per round. Sequence
-  only on a real dependency.
-- A tool that takes an array (`read`, `grep`, `glob`, `git`, `code_graph`) gets
-  one call with the array whenever there are several targets; separate calls of
-  the same tool only when the targets need different options or one depends on
-  another's result.
+- Group calls already known to be needed in one response. Sequence only when
+  an earlier operation or result is needed to choose or safely run a later call.
+- For `read`, `grep`, `glob`, `git`, and `code_graph`, combine compatible targets
+  in one array call; split only for dependencies, differing options or scope,
+  or schema limits.
 - Order on files: enumerate only when the scope is unknown → locate every
   site (known locations skip straight to the read) → one read stage over every
   located site → every edit in one response → one verification. A search after

package/src/rules/shared/10-tool-workflow.md

@@ -7,6 +7,10 @@
   patch from it with no surveys or history. Stop once every requested item
   has its evidence; never widen past what was asked, and never ask
   permission for work the request already covers.
+- When blocked, first look for a workaround you can carry out yourself with
+  the available tools.
+<!-- tools: lead -->
+  Ask the user only when none exists.
 - Do not add work whose need depends on a pending result. Reuse content
   already delivered; changed sources and omitted ranges are new evidence.
   Trust documented guarantees; no availability checks or defensive branches —

package/src/rules/shared/45-destructive.md

@@ -7,8 +7,6 @@
   files you did not create: it may hold other agents' or the user's
   uncommitted work. Use a copy or managed snapshot for before/after
   comparisons.
-- Worktrees live only in the app-managed store; never create one through
-  shell or in a temp folder.
 <!-- tools: git -->
 - Separate-branch work goes into a managed worktree through `git`.
 - Back up only when changes risk irreversible loss, not for routine code edits;

package/src/rules/shared/50-execution.md

@@ -4,4 +4,6 @@
   data transformation, generated output, unsupported-format decoding. An open
   shell is never a routing reason.
 - Structured service operations go through the service's MCP tool or CLI.
+- Open no window, dialog or elevation prompt unless showing or operating
+  that UI is the task.
 

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

@@ -3,11 +3,13 @@
 - 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.
-- Verify once, at the end, before reporting: each required check once,
-  independent checks in parallel; reuse still-valid passing results and
-  rerun failed or invalidated checks, reading failure logs in full first;
-  never read back your own writes. If repeated fixes leave the same failure unchanged,
-  test the underlying assumptions before another fix.
+- 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.
+- 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.

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,11 @@
   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,
+  plans; comparisons or research tables go in a visualize page. Keep the chat
+  to a short summary.
 
 <!-- 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-progress-watchdog.mjs

@@ -243,11 +243,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) — 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
+    // 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 +272,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 +304,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 +320,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

@@ -195,9 +195,8 @@ export function resolveCacheStrategy(agent, { autoClear, session = null } = {})
 // ttl "30m"; Lead-class sessions pin their stable prefix with one "12h"
 // breakpoint (header: break-even). Earlier models' typical retention is
 // ~30 min as well.
-export const OPENAI_TAIL_CACHE_TTL = '30m';
-export const OPENAI_LEAD_PREFIX_CACHE_TTL = '12h';
-const ANTHROPIC_TAIL_LIFETIME_MS = Object.freeze({ '5m': 5 * 60_000, '1h': 60 * 60_000 });
+const OPENAI_LEAD_PREFIX_CACHE_TTL = '12h';
+export const ANTHROPIC_TAIL_LIFETIME_MS = Object.freeze({ '5m': 5 * 60_000, '1h': 60 * 60_000 });
 const OPENAI_TAIL_LIFETIME_MS = 30 * 60_000;
 
 /** The OpenAI (API key) stable-prefix TTL for a session: '12h' for the Lead

package/src/runtime/agent/orchestrator/agent-runtime/title-completion.mjs

@@ -14,7 +14,9 @@ function titleSystemPrompt(locale = '') {
     : TITLE_SYSTEM_PROMPT;
 }
 
-function createTitleCompletion(deps = {}) {
+/** The title generator over injectable `deps` (tests); generateSessionTitle
+ *  is it over the real config and provider registry. */
+export function createTitleCompletion(deps = {}) {
   const load = deps.loadConfig || loadConfig;
   const resolveRoute = deps.resolveMaintenanceRoute || resolveMaintenanceRoute;
   const initialize = deps.initProviders || initProviders;

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

@@ -137,7 +137,7 @@ const TOOL_ARG_KEYS = {
   recall: ['query', 'limit', 'session_id', 'cwd'],
   search: ['query', 'limit', 'cwd'],
   code_graph: ['mode', 'file', 'files', 'symbol', 'symbols', 'body', 'language', 'limit', 'depth', 'page', 'cwd'],
-  shell: ['command', 'timeout_ms'],
+  shell: ['command', 'cwd', 'timeout_ms'],
   task: ['action', 'task_id'],
   edit: ['file_path', 'replace_all'],
   edit_many: ['edits'],
@@ -631,6 +631,8 @@ function traceAgentTool({
       ...(toolBatchId ? { batch: { batch_id: toolBatchId, tool_call_id: toolCallId } } : {}),
       ...(Array.isArray(executionIntervals) ? { execution_intervals: executionIntervals } : {}),
       ...(resultTelemetry?.integrity ? { integrity: { ...resultTelemetry.integrity } } : {}),
+      // Shell-tool misuse the guards saw on this call (misuse-guard.mjs).
+      ...(Array.isArray(resultTelemetry?.shellMisuse) ? { shell_misuse: resultTelemetry.shellMisuse } : {}),
     },
     cwd: cwd || null,
   });

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

@@ -41,6 +41,10 @@ import {
   removeRetiredAgentFields,
 } from './config-storage.mjs';
 import { oauthCredentialProbeState, isOAuthProviderAvailable } from './providers/oauth-credential-probes.mjs';
+import {
+  DEFAULT_HEARTBEAT_INTERVAL_MINUTES,
+  normalizeHeartbeatIntervalMinutes,
+} from '../../shared/heartbeat-interval.mjs';
 import { normalizeDeveloperConfig } from '../../shared/developer-options.mjs';
 import { normalizeWorktreeSettings } from '../../shared/worktrees/settings.mjs';
 import { normalizePluginMcpIntents } from './runtime-core/plugin-mcp.mjs';
@@ -295,8 +299,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 2-hourly heartbeat check (session-runtime/mixy-heartbeat.mjs); default on.
+        // Mixy's heartbeat check (session-runtime/mixy-heartbeat.mjs); default on.
         heartbeat: raw.heartbeat !== false,
+        // 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,
         // 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
@@ -351,6 +360,7 @@ export function loadConfig(options = {}) {
     shell: {},
     update: {},
     recap: { enabled: true },
+    promptCacheWarming: true,
     worktree: normalizeWorktreeSettings(null),
     developer: {},
     modules: {},
@@ -482,8 +492,14 @@ function buildAgentSaveBuilder(config) {
     else delete next.aiSessionTitles;
     if (config.heartbeat === false) next.heartbeat = false;
     else delete next.heartbeat;
+    // Only a non-default choice is stored.
+    const heartbeatMinutes = normalizeHeartbeatIntervalMinutes(config.heartbeatIntervalMinutes);
+    if (heartbeatMinutes !== DEFAULT_HEARTBEAT_INTERVAL_MINUTES) next.heartbeatIntervalMinutes = heartbeatMinutes;
+    else delete next.heartbeatIntervalMinutes;
     if (config.reactions === false) next.reactions = false;
     else delete next.reactions;
+    if (config.promptCacheWarming === false) next.promptCacheWarming = false;
+    else delete next.promptCacheWarming;
     if (Array.isArray(config.botOrder) && config.botOrder.length) next.botOrder = [...config.botOrder];
     else delete next.botOrder;
     if (config.leadAvatar && typeof config.leadAvatar === 'object') next.leadAvatar = { ...config.leadAvatar };

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

@@ -1,6 +1,7 @@
 export {
   applyInitialDeferredToolManifestToBp2,
   buildDeferredToolManifest,
+  resetBp2StableContext,
   stripDeferredToolManifestBlock,
 } from './deferred-tools.mjs';
 export {
@@ -11,11 +12,13 @@ export {
   collectPromptSkillsCached,
   collectSkills,
   collectSkillsCached,
+  currentSkillDelivery,
   filterSkillsExcludingDisabled,
   invalidateSkillsCache,
   isSkillDisabled,
   loadSkillResource,
   skillBodyPresentInSession,
+  skillLoadRefusal,
   skillMissingFeature,
   skillOutsideScope,
   skillEnabledFlags,

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

@@ -1,7 +1,11 @@
-// Deferred-pool and MCP-instruction manifests injected into BP2.
-import { accountOfInstructions } from '../../../shared/connector-accounts.mjs';
+// Deferred-pool manifest injected into BP2. MCP server instruction bodies are
+// not injected: a server's one-line entry is its when-to-use trigger (accounts
+// one line per server), and its instructions arrive with its tools
+// on load_tool. The <mcp-instructions> block is still recognized so older
+// prompts can shed it.
 import { connectorTrigger } from '../../../shared/connector-triggers.mjs';
 import { parseMcpToolName, titleCaseMcpServer } from '../../../shared/tool-primitives.mjs';
+import { SKILL_TRIGGER_LISTING_MAX } from '../../../shared/skill-document.mjs';
 import { isToolBridgeEnabled, TOOL_BRIDGE_GUIDANCE } from '../runtime-core/tool-exposure.mjs';
 
 export function compactPromptManifestText(value, max = 250) {
@@ -24,13 +28,24 @@ const MCP_INSTRUCTIONS_BLOCK_RE = /(\n\n---\n*)?<mcp-instructions>[\s\S]*?<\/mcp
 // Tool and MCP server names enter the manifests only as plain identifiers
 // (no markup can be smuggled into the prompt through a name).
 const MANIFEST_NAME_SAFE_RE = /^[A-Za-z0-9_.:-]+$/;
-const MCP_INSTRUCTION_MAX_CHARS = 600;
 
 function sanitizeManifestName(name) {
   const text = String(name || '').trim();
   return MANIFEST_NAME_SAFE_RE.test(text) ? text : '';
 }
 
+const MCP_INSTRUCTION_MAX_CHARS = 600;
+
+/** A server's instruction text without markup, capped at MCP_INSTRUCTION_MAX_CHARS. */
+export function sanitizeMcpInstructionText(text, max = MCP_INSTRUCTION_MAX_CHARS) {
+  const stripped = String(text || '')
+    .replace(/[<>]/g, '')
+    .trim();
+  if (!stripped) return '';
+  const cap = Math.max(1, Number(max) || MCP_INSTRUCTION_MAX_CHARS);
+  return stripped.length > cap ? `${stripped.slice(0, Math.max(1, cap - 3))}...` : stripped;
+}
+
 function skillRoutedToolNames(messages) {
   const names = new Set();
   for (const message of Array.isArray(messages) ? messages : []) {
@@ -63,7 +78,8 @@ function hasDeferredToolManifestBlock(text) {
  * wire tools). Each entry is either a bare name string or `{ name, description }`;
  * output lines are `- name: description` (description omitted when absent),
  * mirroring the available-skills manifest so the model calls deferred tools
- * directly. Descriptions are compacted and stripped of `<`/`>`.
+ * directly. Descriptions are compacted to the skill listing's trigger cap
+ * (skill-document.mjs SKILL_TRIGGER_LISTING_MAX) and stripped of `<`/`>`.
  * Empty pool → '' (caller omits the block).
  */
 export function buildDeferredToolManifest(entries) {
@@ -77,62 +93,19 @@ export function buildDeferredToolManifest(entries) {
     const description =
       typeof entry === 'string'
         ? ''
-        : compactPromptManifestText(String(entry?.description || '').replace(/[<>]/g, ''), 100);
+        : compactPromptManifestText(String(entry?.description || '').replace(/[<>]/g, ''), SKILL_TRIGGER_LISTING_MAX);
     list.push({ name, description });
   }
   if (!list.length) return '';
   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');
 }
 
-function sanitizeMcpInstructionText(text, max = MCP_INSTRUCTION_MAX_CHARS) {
-  const stripped = String(text || '')
-    .replace(/[<>]/g, '')
-    .trim();
-  if (!stripped) return '';
-  const cap = Math.max(1, Number(max) || MCP_INSTRUCTION_MAX_CHARS);
-  return stripped.length > cap ? `${stripped.slice(0, Math.max(1, cap - 3))}...` : stripped;
-}
-
-/**
- * Per-server MCP initialize instructions for deferred-pool tools only.
- * Empty when no instructions or no matching deferred MCP tools → omit block.
- * Emits ONLY the server heading + instruction body: tool names are never
- * listed — <available-deferred-tools> names each server once (mcp__<server>).
- */
-function buildMcpInstructionsManifest(mcpServerInstructions, poolNames, catalog = []) {
-  const map = mcpServerInstructions && typeof mcpServerInstructions === 'object' ? mcpServerInstructions : {};
-  const pool = [
-    ...new Set((Array.isArray(poolNames) ? poolNames : []).map((name) => sanitizeManifestName(name)).filter(Boolean)),
-  ];
-  // Tool definitions carry their server (shortened names cannot be parsed).
-  const byName = new Map();
-  for (const tool of Array.isArray(catalog) ? catalog : []) {
-    const name = String(tool?.name || '').trim();
-    if (name && !byName.has(name)) byName.set(name, tool);
-  }
-  const deferredServers = new Set();
-  for (const name of pool) {
-    const server = parseMcpToolName(byName.get(name) || name)?.server;
-    if (server) deferredServers.add(server);
-  }
-  const servers = [...deferredServers]
-    .filter((server) => sanitizeManifestName(server) && sanitizeMcpInstructionText(map[server]))
-    .sort((a, b) => a.localeCompare(b));
-  if (!servers.length) return '';
-  const lines = ['<mcp-instructions>'];
-  for (const server of servers) {
-    lines.push(`## ${sanitizeManifestName(server)}`, sanitizeMcpInstructionText(map[server]));
-  }
-  lines.push('</mcp-instructions>');
-  return lines.join('\n');
-}
-
 export function stripDeferredToolManifestBlock(text) {
   return String(text || '')
     .replace(DEFERRED_TOOLS_BLOCK_RE, '')
@@ -144,9 +117,8 @@ export function stripDeferredToolManifestBlock(text) {
 // Rebuild path: replace the FIRST previously-injected <available-deferred-tools>
 // block (with its leading `---` separator) with the fresh manifest IN PLACE, so
 // the block keeps its original position and no sibling BP2 block (skills
-// manifest, agent rules, …) is reordered or dropped. The fresh manifest already
-// carries the mcp-instructions companion, so any pre-existing standalone one is
-// removed first to avoid duplication.
+// manifest, agent rules, …) is reordered or dropped. A legacy <mcp-instructions>
+// block left by older sessions is removed first.
 function rebuildDeferredToolManifestBlock(text, manifest) {
   let out = String(text || '').replace(MCP_INSTRUCTIONS_BLOCK_RE, '');
   let replaced = false;
@@ -183,24 +155,50 @@ const firstSentence = (text) => {
   return (flat.split(/(?<=[.!?])\s/, 1)[0] || flat).replace(/[.!?]+$/, '');
 };
 
-// A catalog connector's curated trigger; else the server's MCP instructions;
-// else its tools' leading descriptions (name order); else its name. Derived
-// lines are compacted to at most 100 characters, ellipsis included.
+// 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
+// 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) {
-  // A multi-account connector's server names its account (connector-accounts.mjs).
-  const account = accountOfInstructions(instructions?.[server]);
   const curated = connectorTrigger(server);
-  if (curated) return account ? `${curated} Account: ${account}` : curated;
-  const instruction = String(instructions?.[server] || '').replace(/[<>]/g, '');
+  if (curated) return curated;
+  // The account sentence ("Account: <address>. …", connector-accounts.mjs) is
+  // not a use line; it reaches the model with the loaded server's 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 derived = instruction.trim() ? instruction : described;
+  const derived = firstSentence(instruction) || described;
   return derived ? compactPromptManifestText(derived, 98) : `${titleCaseMcpServer(server)} MCP server tools.`;
 }
 
+// `mcp__<server>` as the manifest names it, or '' for an unsafe server name.
+export const mcpServerManifestLabel = (server) => sanitizeManifestName(mcpServerLineName(server));
+
+/**
+ * One `{ label: 'mcp__<server>', trigger }` line per server of `servers` (Map
+ * server → its tools). The BP2 manifest and the deferred-tool delta both
+ * render these; a server with an unsafe name gets none.
+ */
+export function mcpServerLines(servers, instructions) {
+  const lines = [];
+  for (const [server, tools] of servers) {
+    const label = mcpServerManifestLabel(server);
+    if (!label) continue;
+    const trigger = compactPromptManifestText(
+      String(mcpServerTrigger(server, tools, instructions)).replace(/[<>]/g, ''),
+      SKILL_TRIGGER_LISTING_MAX
+    );
+    lines.push({ label, trigger });
+  }
+  return lines;
+}
+
 function deferredManifestEntries(session, pool) {
   const byName = catalogByName(session);
   const skillRoutedNames = skillRoutedToolNames(session.messages);
@@ -221,11 +219,8 @@ function deferredManifestEntries(session, pool) {
       description: skillRoutedNames.has(key) ? '' : String(tool?.trigger || tool?.description || ''),
     });
   }
-  for (const [server, tools] of servers) {
-    entries.push({
-      name: mcpServerLineName(server),
-      description: mcpServerTrigger(server, tools, session.mcpServerInstructions),
-    });
+  for (const line of mcpServerLines(servers, session.mcpServerInstructions)) {
+    entries.push({ name: line.label, description: line.trigger });
   }
   return entries;
 }
@@ -241,7 +236,7 @@ export function listedDeferredToolNames(session, poolNames, rendered) {
 }
 
 function composeDeferredBp2Manifest(session, pool) {
-  // Bridge exposure gets the native roster and MCP instructions (the pool is
+  // Bridge exposure gets the native roster (the pool is
   // already limited to what the session's policy lets it run), followed by
   // the static bridge guidance. A tool-free bridge session gets nothing.
   const bridge = isToolBridgeEnabled(session);
@@ -249,8 +244,6 @@ function composeDeferredBp2Manifest(session, pool) {
   const parts = [];
   const deferredManifest = buildDeferredToolManifest(deferredManifestEntries(session, pool));
   if (deferredManifest) parts.push(deferredManifest);
-  const mcpManifest = buildMcpInstructionsManifest(session.mcpServerInstructions, pool, session.deferredToolCatalog);
-  if (mcpManifest) parts.push(mcpManifest);
   if (bridge) parts.push(TOOL_BRIDGE_GUIDANCE);
   return parts.join('\n\n');
 }
@@ -292,6 +285,18 @@ function resolveDeferredBp2Index(session) {
   return idx;
 }
 
+/**
+ * Give BP2 `stableContext` (profile meta + skill manifest) and no deferred
+ * manifest. The caller re-applies that manifest
+ * (applyInitialDeferredToolManifestToBp2 with `rebuild`), which appends it
+ * after the stable part exactly as session creation laid it out.
+ */
+export function resetBp2StableContext(session, stableContext) {
+  if (!Array.isArray(session?.messages)) return;
+  const idx = resolveDeferredBp2Index(session);
+  if (idx >= 0) setSystemContent(session, idx, String(stableContext || ''));
+}
+
 function writeDeferredManifestAt(session, idx, manifest, rebuild) {
   for (let i = 0; i < session.messages.length; i++) {
     if (i === idx || session.messages[i]?.role !== 'system' || typeof session.messages[i].content !== 'string')