mixdog 1.3.1 → 1.3.2

package/src/runtime/agent/orchestrator/session/manager/session-lifecycle.mjs

@@ -15,10 +15,11 @@ import { loadConfig } from '../../config.mjs';
 import {
   buildProviderCacheOpts,
   cacheCapabilityForProvider,
+  isLeadCacheClass,
   roleProviderCacheOpts,
 } from '../../agent-runtime/cache-strategy.mjs';
 import { normalizeAutoClearConfig, resolveAutoClearIdleMs } from '../../runtime-core/config-helpers.mjs';
-import { _buildBaseRules } from './rules-cache.mjs';
+import { _buildBaseRules, promptRulesRevision } from './rules-cache.mjs';
 import { stripProviderReplayMessages } from './provider-replay.mjs';
 import { composeSessionSystem, seedSessionMessages } from './session-prompt-composition.mjs';
 import { agentProfileRevision, leadRosterRevision } from '../../context/role-instructions.mjs';
@@ -41,6 +42,7 @@ import { ensureCodexWireSessionId, mintSessionId } from './session-id.mjs';
 import { providerCacheKey } from './provider-cache-key.mjs';
 import { buildSessionRecord, normalizeDesktopSessionMetadata, sessionOriginFields } from './session-record.mjs';
 import { normalizeWorkflowRoute } from '../../runtime-core/workflow.mjs';
+import { ownerRouteFallbacks } from './owner-route-fallbacks.mjs';
 import { applyPendingWorkspaceReroot, refreshSessionBp3Environment } from './prompt-utils.mjs';
 import { isWorktreeBound } from '../../../../shared/worktrees/contract.mjs';
 import { applyAgentToolExposure } from '../loop/tool-exposure-migration.mjs';
@@ -53,17 +55,20 @@ export { recoverSessionAfterProcessRestart } from './turn-checkpoint-recovery.mj
 // re-exported so prior importers of this module stay unchanged.
 export { prefetchSession, prepareSessionProjection } from './prepared-resume-cache.mjs';
 
-function buildSessionProviderCacheOpts(providerName, sessionId, agent = null, config = null) {
+// `session` is the record or create options; it classifies agent-mode Leads
+// (bot home threads, routine runs) into the Lead cache class.
+function buildSessionProviderCacheOpts(providerName, sessionId, agent = null, config = null, session = null) {
   // Keep this in sync with createSession's provider-cache policy: only
-  // explicit-breakpoint providers get BP cache opts here; OpenAI/key-prefix
-  // providers use promptCacheKey and request-time strategy instead, plus the
-  // shared prompt-cache scope of a one-shot role.
+  // explicit-breakpoint providers get BP cache opts here; key-prefix
+  // providers use promptCacheKey and request-time strategy instead (plus the
+  // OpenAI API's Lead-class 12h prefix TTL and a one-shot role's shared
+  // prompt-cache scope).
   if (cacheCapabilityForProvider(providerName) !== 'explicit-breakpoint') {
-    return roleProviderCacheOpts(providerName, agent);
+    return roleProviderCacheOpts(providerName, agent, { session });
   }
   try {
     let autoClear = null;
-    if (!agent || agent === 'lead') {
+    if (isLeadCacheClass(agent, session)) {
       const loadedConfig = config || loadConfig({ secrets: false });
       const normalizedAutoClear = normalizeAutoClearConfig(loadedConfig?.autoClear);
       autoClear = {
@@ -71,20 +76,23 @@ function buildSessionProviderCacheOpts(providerName, sessionId, agent = null, co
         idleMs: resolveAutoClearIdleMs(loadedConfig, providerName),
       };
     }
-    return buildProviderCacheOpts(providerName, sessionId, agent, { autoClear });
+    return buildProviderCacheOpts(providerName, sessionId, agent, { autoClear, session });
   } catch {
     return null;
   }
 }
 
-// Re-derive a Lead session's builder-made cache policy (messages TTL follows
-// the auto-clear idle window). Explicit caller/profile policies, non-Lead
-// sessions and non-explicit-breakpoint providers are left untouched.
+// Re-derive a Lead-class session's builder-made cache policy (Anthropic
+// messages TTL follows the auto-clear idle window; the OpenAI API prefix TTL
+// follows the cache class). Explicit caller/profile policies, sub-agents and
+// other providers are left untouched.
 export function refreshSessionProviderCacheOpts(session, config = null) {
   if (!session || session.providerCacheOptsOverride === true) return false;
-  if (session.agent && session.agent !== 'lead') return false;
-  if (cacheCapabilityForProvider(session.provider) !== 'explicit-breakpoint') return false;
-  const next = buildSessionProviderCacheOpts(session.provider, session.id, session.agent, config);
+  if (!isLeadCacheClass(session.agent, session)) return false;
+  if (cacheCapabilityForProvider(session.provider) !== 'explicit-breakpoint' && session.provider !== 'openai') {
+    return false;
+  }
+  const next = buildSessionProviderCacheOpts(session.provider, session.id, session.agent, config, session);
   if (!next) return false;
   session.providerCacheOpts = next;
   return true;
@@ -225,26 +233,35 @@ export function createSession(createOpts) {
     sessionMode === AGENT_MODE && !createOpts.agent && actingAgent
       ? { ...createOpts, agent: actingAgent, sessionMode }
       : { ...createOpts, sessionMode };
-  const routeFallbacks = normalizeWorkflowRoute({
-    provider: providerName,
-    model: modelName,
-    fallbacks: Object.hasOwn(opts, 'routeFallbacks') ? opts.routeFallbacks : presetObj?.fallbacks,
-  })?.fallbacks;
+  // A Lead-class session (actingAgent set) takes its owner's chain while it
+  // runs on the owner's primary model; an agent keeps its preset's.
+  const routeFallbacks = actingAgent
+    ? Object.hasOwn(opts, 'routeFallbacks')
+      ? opts.routeFallbacks
+      : ownerRouteFallbacks({ sessionMode, agentId: actingAgent, provider: providerName, model: modelName })
+    : normalizeWorkflowRoute({
+        provider: providerName,
+        model: modelName,
+        fallbacks: Object.hasOwn(opts, 'routeFallbacks') ? opts.routeFallbacks : presetObj?.fallbacks,
+      })?.fallbacks;
   // Provider cache strategy — agentRuntime.resolveSync() above is a
   // best-effort injection point (setAgentRuntime() has no live caller
   // today, so that branch never fires); build it directly here so every
-  // session still gets a cache strategy. Lead sessions (opts.agent ===
-  // 'lead', or no agent at all — raw/CLI callers) get their BP4 message
-  // tail TTL linked to the user's autoClear idle-sweep config; hidden and
-  // public agents keep the flat 5m default (see cache-strategy.mjs docs).
-  // Scoped to explicit-breakpoint (Anthropic-family) providers only.
-  const providerCacheOpts = resolved.providerCacheOpts || buildSessionProviderCacheOpts(providerName, id, opts.agent);
+  // session still gets a cache strategy. Lead-class sessions (the Lead, raw
+  // callers, bot home threads and other agent-mode Leads) get their BP4
+  // message tail TTL linked to the user's autoClear idle-sweep config and,
+  // on the OpenAI API, the 12h stable-prefix TTL; sub-agents and hidden roles
+  // keep the agent defaults (see cache-strategy.mjs docs).
+  const providerCacheOpts =
+    resolved.providerCacheOpts || buildSessionProviderCacheOpts(providerName, id, opts.agent, null, { ...opts, id });
   const surface = resolveSessionToolSurface(opts, { profile, toolPreset, modelName });
   // The agent profile the prompt is composed from, read first: an edit landing
   // during composition leaves the stamp behind, never ahead (refreshAgentProfile).
   const agentProfile = surface.ownerIsAgent
     ? ''
     : agentProfileRevision(surface.resolvedAgent, { mixy: sessionMode === AGENT_MODE });
+  // A bot thread lives on across releases: the rules it was built from.
+  const rulesRevision = agentProfile && sessionMode === AGENT_MODE ? promptRulesRevision() : '';
   const prompt = composeSessionSystem(opts, { profile, providerName, modelName, surface, sessionMode });
   const messages = seedSessionMessages(prompt, opts.files);
   logSessionSurface(surface);
@@ -268,6 +285,7 @@ export function createSession(createOpts) {
     session.agentProfileRevision = agentProfile;
     // The bot roster its prompt lists (a Lead's catalog slices).
     session.agentRosterRevision = leadRosterRevision(opts.leadWorkflowParts);
+    if (rulesRevision) session.rulesRevision = rulesRevision;
   }
   if (routeFallbacks?.length) session.routeFallbacks = routeFallbacks;
   // A non-native agent sends core + bridge, built from its filtered tools.
@@ -340,6 +358,13 @@ function applyRouteFields(session, route) {
     else delete session.autoEffort;
   }
   if (Object.hasOwn(route, 'effort')) session.effort = route.effort || null;
+  // A deliberate route choice restarts the chain (a fallback hop never passes this).
+  if (Object.hasOwn(route, 'routeFallbacks')) {
+    if (route.routeFallbacks?.length) session.routeFallbacks = route.routeFallbacks;
+    else delete session.routeFallbacks;
+    delete session.routeFallbackIndex;
+    delete session.routeFallbackFailures;
+  }
   ensureCodexWireSessionId(session);
   if (Object.hasOwn(route, 'modelParameters')) {
     session.modelParameters =
@@ -387,7 +412,8 @@ function applyRouteContextWindow(session, routeChanged, selectedContextWindowPro
 // surface: the previous route's readings and prepared tools no longer apply.
 function resetSessionForRouteChange(id, session, previousModel, previousProvider) {
   session.promptCacheKey = providerCacheKey(session.provider);
-  session.providerCacheOpts = buildSessionProviderCacheOpts(session.provider, session.id, session.agent) || null;
+  session.providerCacheOpts =
+    buildSessionProviderCacheOpts(session.provider, session.id, session.agent, null, session) || null;
   session.providerCacheOptsOverride = false;
   session.lastInputTokens = 0;
   session.lastOutputTokens = 0;
@@ -437,7 +463,9 @@ function stripProviderReplay(session) {
 // auto-compacts) against the new model's window.
 export function updateSessionRoute(id, route = {}, options = {}) {
   if (!id) return null;
-  const session = loadSession(id);
+  // options.session: the live object of a running turn, changed in place; the id's
+  // stored copy (a disk reload after another process took the generation) is not.
+  const session = options.session?.id === id ? options.session : loadSession(id);
   if (!session || session.closed === true) return null;
   const previousProvider = session.provider || null;
   const previousModel = session.model || null;

package/src/runtime/agent/orchestrator/session/manager/session-prompt-composition.mjs

@@ -5,7 +5,7 @@
 import { buildSkillManifest, composeSystemPrompt } from '../../context/collect.mjs';
 import { configuredInstructionFilesMode, loadInstructionFilesContext } from '../../context/instruction-files.mjs';
 import { agentModeIdentityLine } from '../../context/role-instructions.mjs';
-import { AGENT_MODE, isRoutineSource, sessionModeOf } from '../agent-mode.mjs';
+import { AGENT_MODE, sessionModeOf } from '../agent-mode.mjs';
 import { MIXY_AGENT_ID } from '../agent-home.mjs';
 import {
   _buildBaseRules,
@@ -98,12 +98,9 @@ export function buildWorkspacePromptContext(session, cwd) {
 // A Lead's BP3 rule slices, ordered for prefix sharing (composeSystemPrompt):
 // LEAD.md's common lines first; then the mode block (coding: LEAD.md's two
 // passages; agent mode: their conversational variants and AGENT_MODE.md);
-// then Mixy's MIXY.md; last the per-session tail — routine line, identity.
+// then Mixy's MIXY.md; last the per-session tail — identity.
 // Agent mode is a Lead created as an agent (agent-mode.mjs).
-export function sessionRolePromptFields(
-  identity,
-  { ownerIsAgent, toolFreeRole, delegationFree, sessionMode, routine = false }
-) {
+export function sessionRolePromptFields(identity, { ownerIsAgent, toolFreeRole, delegationFree, sessionMode }) {
   const skipRules = identity.skipAgentRules || toolFreeRole;
   const lead = !ownerIsAgent && !skipRules;
   const agentMode = lead && sessionMode === AGENT_MODE;
@@ -131,7 +128,6 @@ export function sessionRolePromptFields(
       ? {
           agentModeRules: _buildAgentModeRules({ part: 'conduct' }),
           ...(mixy ? { mixyRules: _buildAgentModeRules({ part: 'mixy' }) } : {}),
-          ...(routine ? { routineRules: _buildAgentModeRules({ part: 'routine' }) } : {}),
         }
       : {}),
     userPrompt: identity.systemPrompt,
@@ -176,7 +172,6 @@ export function composeSessionSystem(opts, { profile, providerName, modelName, s
     toolFreeRole,
     delegationFree,
     sessionMode,
-    routine: isRoutineSource(opts.sourceType),
   });
   const leadOnly = !skipAgentRules && !ownerIsAgent;
   const metaContext = leadOnly ? _buildLeadMetaContext({ includeOutputStyle: !agentMode }) : '';

package/src/runtime/agent/orchestrator/session/manager/session-record.mjs

@@ -2,8 +2,10 @@
 // What a persisted session row contains and where each field comes from: the
 // compaction budget, the origin/permission/cache metadata analytics slice on,
 // the desktop classification, and the record assembled from them. Everything
-// here is field derivation — no I/O, no ownership, no prompt text.
+// here is field derivation — no ownership, no prompt text; the only read is the
+// parent's record a delegated session takes its root from.
 import { toSessionWorkflowMeta } from '../../runtime-core/workflow.mjs';
+import { delegationForNewSession } from '../human-gate/delegation.mjs';
 import { sessionOrchestrationMode } from '../../../../shared/orchestration.mjs';
 import { preserveBufferConfigFields } from './context-meta.mjs';
 import { positiveInt } from '../../../../shared/numbers.mjs';
@@ -101,9 +103,18 @@ export function sessionOriginFields(opts, { profile, presetObj, providerCacheOpt
     ownerSessionId: opts.ownerSessionId || null,
     visibility: opts.visibility || null,
     clientHostPid: opts.clientHostPid || null,
+    // A sub-agent's or a bot-created task session's root (who it works for, and
+    // how that root was acting), derived from the parent's record — the one
+    // read here — never taken from the options (human-gate/delegation.mjs).
+    ...delegationFields(opts),
   };
 }
 
+function delegationFields(opts) {
+  const delegation = delegationForNewSession(opts);
+  return delegation ? { delegation } : {};
+}
+
 // The persisted session record.
 export function buildSessionRecord({ opts, route, presetObj, surface, prompt, messages, contextMeta, origin }) {
   const {

package/src/runtime/agent/orchestrator/session/manager/turn-checkpoint-journal.mjs

@@ -35,10 +35,9 @@
 // keeps the durable prefix.
 import { appendFileSync, existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
 import { appendFile, unlink, writeFile } from 'node:fs/promises';
-import { randomBytes } from 'node:crypto';
 import { join } from 'node:path';
 import { getPluginData } from '../../config.mjs';
-import { renameWithRetrySync } from '../../../../shared/atomic-file.mjs';
+import { writeFileAtomicSync } from '../../../../shared/atomic-file.mjs';
 import { sanitizeContentForStoredHistory } from '../../providers/media-normalization.mjs';
 import { promptContentText } from './prompt-utils.mjs';
 
@@ -145,19 +144,11 @@ export function writeCheckpointHeader(checkpoint) {
     contextState: checkpoint.contextState ?? null,
     updatedAt: Date.now(),
   };
-  const temp = `${target}.${randomBytes(6).toString('hex')}.tmp`;
-  try {
-    writeFileSync(temp, JSON.stringify(payload), 'utf8');
-    renameWithRetrySync(temp, target);
-    return true;
-  } catch (error) {
-    try {
-      unlinkSync(temp);
-    } catch {
-      /* best-effort */
-    }
-    throw error;
-  }
+  // Durable (fsynced through its handle, then renamed): a crash must not
+  // publish a header whose bytes never landed. A damaged header already reads
+  // as "no checkpoint" (parseTurnCheckpointHeader) and the next turn rewrites it.
+  writeFileAtomicSync(target, JSON.stringify(payload));
+  return true;
 }
 
 export function readTurnCheckpointHeader(sessionId) {

package/src/runtime/agent/orchestrator/session/manager/turn-interruption.mjs

@@ -20,7 +20,15 @@ const INTERRUPTED_TOOL_RESULT = 'Cancelled';
 // PRESERVE the just-sent user turn: nothing restores the prompt there, and
 // rewinding erases the user's message from the persisted transcript (the
 // exact loss seen when the desktop app quits mid-turn).
-const USER_CANCEL_ABORT_REASONS = new Set(['cli-abort', 'user-cancel', 'turn-abort']);
+//
+// A user cancel the host will NOT answer with the prompt back in the input box
+// (the desktop Stop button, a prompt carrying attachments cancelled from
+// another device) names `USER_CANCEL_KEEP_PROMPT_REASON`: it is still a user
+// cancel, but the unanswered prompt stays in the stored transcript. Rewinding
+// it left a first message with zero stored messages — a session every catalog
+// hides — and its text nowhere.
+export const USER_CANCEL_KEEP_PROMPT_REASON = 'user-cancel-keep-prompt';
+const USER_CANCEL_ABORT_REASONS = new Set(['cli-abort', 'user-cancel', 'turn-abort', USER_CANCEL_KEEP_PROMPT_REASON]);
 
 function provisionalUserTurnIndex(messages, currentUserContent) {
   const currentText = promptContentText(currentUserContent);
@@ -78,7 +86,17 @@ function finalizeInterruptedTurn({
   // turn and its side effects from history.
   const preserveResponse = responseStarted && (producedOutput || !userCancelled);
   if (!preserveResponse) {
-    if (!userCancelled) {
+    if (!userCancelled || abortReason === USER_CANCEL_KEEP_PROMPT_REASON) {
+      // A kept prompt gets the generic interruption row (rendered as the
+      // Cancelled status, unlike the hidden by-user control row): without it a
+      // rebuilt transcript shows the stopped prompt as if it were still
+      // awaiting an answer, directly above the next one.
+      if (
+        abortReason === USER_CANCEL_KEEP_PROMPT_REASON &&
+        provisionalUserTurnIndex(messages, currentUserContent) >= 0
+      ) {
+        messages.push({ role: 'user', content: SESSION_INTERRUPT_MESSAGE });
+      }
       return {
         messages,
         responsePreserved: false,
@@ -145,18 +163,16 @@ function appendObservedTurnOutput(
     if (!result?.toolCallId || representedToolResultIds.has(result.toolCallId)) continue;
     messages.push({
       role: 'tool',
-      content: result.content == null ? '' : result.content,
+      content: result.content ?? '',
       toolCallId: result.toolCallId,
       ...(result.toolKind ? { toolKind: result.toolKind } : {}),
     });
     representedToolResultIds.add(result.toolCallId);
   }
 
-  const allToolCallIds = [];
+  const allToolCallIds = new Set();
   for (const message of messages) {
-    for (const id of assistantToolCallIds(message)) {
-      if (!allToolCallIds.includes(id)) allToolCallIds.push(id);
-    }
+    for (const id of assistantToolCallIds(message)) allToolCallIds.add(id);
   }
   for (const callId of allToolCallIds) {
     if (representedToolResultIds.has(callId)) continue;
@@ -283,7 +299,7 @@ export function createTurnInterruptionTracker() {
       if (message.__earlyNotify === true) {
         state.observedToolResults.set(callId, {
           role: 'tool',
-          content: message.content == null ? '' : message.content,
+          content: message.content ?? '',
           toolCallId: callId,
           toolKind: message.toolKind || (message.isError ? 'error' : null),
         });

package/src/runtime/agent/orchestrator/session/manager/workflow-switch-notice.mjs

@@ -1,20 +1,97 @@
 // manager/workflow-switch-notice.mjs
 // A mid-conversation workflow switch (session-runtime/tool-policy-refresh.mjs
-// switchSessionWorkflow) rebuilds the session's prompt and tool surface and
-// stages `session.workflowSwitch`, the one-time notice the next user turn
-// carries in its reminder block. Lifecycle mirrors the working-folder notice
-// (prompt-utils snapshotPendingWorkspaceNotice): snapshot when the turn is
-// built, acknowledge once the provider accepted it, so a failed turn re-sends
-// it. The state object is replaced, never mutated:
-//   from — the workflow the model was last told about (kept across switches
-//          made before a notice reached it);
-//   to   — the workflow the prompt carries now.
+// switchSessionWorkflow) leaves the request prefix — system blocks and tool
+// schemas — byte-identical, so the provider cache survives. The switch lives
+// in two pieces of session state:
+//   session.workflowOverlay — while the session's workflow differs from the
+//     one its system prompt carries: the prompt's workflow (`prompt`, and the
+//     orchestration mode its tool surface was built with), the new workflow,
+//     its tools that are refused at call time (`deniedTools`), the tools it
+//     allows that this session cannot reach (`unavailableTools`) and the
+//     self-contained reminder (`content`) with the new workflow's rules,
+//     orchestration and agents. It is folded into the prompt (and dropped) at
+//     the next point where the cache is cold anyway (tool-policy-refresh.mjs).
+//   session.workflowSwitch — the notice the next user turn carries in its
+//     reminder block. Lifecycle mirrors the working-folder notice
+//     (prompt-utils snapshotPendingWorkspaceNotice): snapshot when the turn is
+//     built, acknowledge once the provider accepted it, so a failed turn
+//     re-sends it. Delivered, it stays in the conversation. Replaced, never
+//     mutated:
+//       from — the workflow the model was last told about (kept across
+//              switches made before a notice reached it);
+//       to   — the session's workflow now.
+// Every notice says it replaces the earlier ones, so the latest one wins.
 
 function workflowRef(workflow) {
   const id = String(workflow?.id || '').trim();
   return id ? { id, name: String(workflow?.name || id).trim() } : null;
 }
 
+/** The workflow the session's system prompt and tool surface were built with. */
+export function promptWorkflowOf(session) {
+  return session?.workflowOverlay?.prompt || session?.workflow || null;
+}
+
+const lower = (name) => String(name || '').toLowerCase();
+
+/** The refusal of a call to a tool the session's current workflow denies
+ *  while its schema (built for the prompt's workflow) still carries it; null
+ *  for any other call. */
+export function workflowOverlayDenial(session, name) {
+  const overlay = session?.workflowOverlay;
+  if (!overlay?.deniedTools?.some((denied) => lower(denied) === lower(name))) return null;
+  return `Error: tool "${name}" is not available in workflow ${overlay.workflow.name}: this conversation switched to it. Do the work without it.`;
+}
+
+const listed = (names) => names.map((name) => `\`${name}\``).join(', ');
+
+/** The reminder that makes the Lead follow `workflow` while its system prompt
+ *  still carries `promptName`'s: self-contained (rules, orchestration, agents,
+ *  tool changes) and superseding every earlier one. */
+export function workflowOverlayContent({
+  promptName,
+  workflow,
+  instructions,
+  deniedTools = [],
+  loadableTools = [],
+  unavailableTools = [],
+}) {
+  const name = workflow.name;
+  return [
+    '<system-reminder>',
+    '# Workflow Changed',
+    `This conversation now runs the ${name} workflow. The system prompt's Active Workflow, orchestration mode and available agents are still ${promptName}'s: they no longer apply; follow ${name}'s below instead. This replaces every earlier Workflow Changed reminder in this conversation.`,
+    ...(deniedTools.length ? [`Not available in ${name} (calls are refused): ${listed(deniedTools)}.`] : []),
+    ...(loadableTools.length
+      ? [
+          `${name} adds ${listed(loadableTools)}: not among your directly defined tools yet; load ${loadableTools.length === 1 ? 'it' : 'them'} with \`load_tool\` before the first call.`,
+        ]
+      : []),
+    ...(unavailableTools.length
+      ? [`${name} allows ${listed(unavailableTools)}, but this session cannot use them; a new session can.`]
+      : []),
+    `Agents already started under ${promptName} keep running with their own instructions; new delegation follows ${name}.`,
+    '',
+    instructions,
+    '</system-reminder>',
+  ].join('\n');
+}
+
+function messageText(message) {
+  if (typeof message?.content === 'string') return message.content;
+  if (!Array.isArray(message?.content)) return '';
+  return message.content.map((part) => (typeof part === 'string' ? part : part?.text || '')).join('');
+}
+
+/** The conversation still holds `content` (a delivered reminder); false once
+ *  a compaction or a clear dropped it. */
+export function conversationHolds(session, content) {
+  if (!content) return false;
+  return (Array.isArray(session?.messages) ? session.messages : []).some(
+    (message) => message?.role !== 'system' && messageText(message).includes(content)
+  );
+}
+
 /** Stage the notice of a switch from `from` to `to`; a switch back to what the
  *  model was last told drops it. Returns the staged state or null. */
 export function stageWorkflowSwitchNotice(session, from, to) {
@@ -29,13 +106,14 @@ export function stageWorkflowSwitchNotice(session, from, to) {
   return session.workflowSwitch;
 }
 
-function workflowNoticeContent({ from, to }) {
+// The prompt itself carries `to` (a switch back to it, or the overlay folded in).
+function promptWorkflowNoticeContent({ from, to }) {
   const before = from?.name || 'the previous workflow';
   return [
     '<system-reminder>',
     '# Workflow Changed',
-    `The workflow changed from ${before} to ${to.name}. Earlier turns of this conversation ran under ${before}; the system prompt was updated in place, so its Active Workflow rules, delegation instructions, available agents and tools are now those of ${to.name}. Follow them from this turn on.`,
-    `Agents already started under ${before} keep running with their own instructions; new delegation uses the current tools and agents.`,
+    `This conversation now runs the ${to.name} workflow, the one the system prompt carries: its Active Workflow, orchestration mode, available agents and tools apply. This replaces every earlier Workflow Changed reminder in this conversation.`,
+    `Agents already started under ${before} keep running with their own instructions; new delegation follows ${to.name}.`,
     '</system-reminder>',
   ].join('\n');
 }
@@ -47,7 +125,10 @@ function workflowNoticeContent({ from, to }) {
 export function snapshotPendingWorkflowNotice(session) {
   const pending = session?.workflowSwitch;
   if (!pending?.to?.id) return null;
-  return { revision: pending.revision, content: workflowNoticeContent(pending) };
+  const overlay = session.workflowOverlay;
+  const content =
+    overlay?.workflow?.id === pending.to.id && overlay.content ? overlay.content : promptWorkflowNoticeContent(pending);
+  return { revision: pending.revision, content };
 }
 
 /** The notice of `revision` reached the model: nothing is due any more. */

package/src/runtime/agent/orchestrator/session/pre-send-compact.mjs

@@ -19,6 +19,7 @@ import {
 import { previewFreshContextCompaction, runFreshContextCompact } from './loop/fresh-context.mjs';
 import { estimateMessagesTokensSafe } from './loop/compact-debug.mjs';
 import { textPdfAllowanceDiscount } from './context-utils.mjs';
+import { referenceOversizedAttachments } from './attachment-preflight.mjs';
 import { providerNativePdf } from '../providers/registry.mjs';
 import { messagesArrayChanged } from './loop/tool-helpers.mjs';
 import { normalizeUsage, addUsage } from './loop/usage.mjs';
@@ -274,6 +275,9 @@ async function compactTranscript(ctx, run) {
     goalReminderText: run.inlineGoalReminder?.content || '',
     activeTurn: true,
     requireReduction: decision.requireReduction,
+    // The provider refused this request as too long: whatever the estimate
+    // said, the latest request's attachments now travel by reference.
+    referenceLatestAttachments: decision.compactTrigger === 'reactive',
   });
   const freshMessages = Array.isArray(run.freshContextResult?.messages) ? run.freshContextResult.messages : null;
   if (!freshMessages) throw new Error('fresh-context compact produced no messages');
@@ -290,6 +294,9 @@ function acknowledgeGoalReminder(sessionRef, run) {
   }
 }
 
+// Detection is narrow on purpose — signal.aborted or a true AbortError — so
+// the recall pipeline's SYNTHETIC "…aborted: memory … ; head preserved"
+// failure (a real compact failure, message text aside) still escalates.
 function isCompactAbort(signal, err) {
   return signal?.aborted === true || err?.name === 'AbortError' || err?.code === 'ABORT_ERR' || err?.code === 'ABORT';
 }
@@ -326,16 +333,6 @@ function reportCompactFailure(ctx, run, compactErr) {
   });
 }
 
-// A failed compact pass ends the send. A genuine cancellation/abort surfaced
-// from the compact pipeline is NOT a context overflow: the fresh-context
-// pipeline deliberately rethrows the original abort error unchanged so the
-// session records a clean cancellation — and the manual/auto-clear runner
-// (manager/compaction-runner.mjs) likewise never fabricates an
-// AGENT_CONTEXT_OVERFLOW for an aborted compact. Mirror that here: preserve
-// the real error (code/name/cause intact) instead of masking it as overflow.
-// Detection is narrow on purpose — signal.aborted or a true AbortError — so
-// the recall pipeline's SYNTHETIC "…aborted: memory … ; head preserved"
-// failure (a real compact failure, message text aside) still escalates.
 function isGenuineCompactOverflow(compactErr) {
   return (
     compactErr?.code === 'AGENT_CONTEXT_OVERFLOW' ||
@@ -362,6 +359,13 @@ function retryCompactQuietly(ctx, run, compactErr) {
   return true;
 }
 
+// A failed compact pass ends the send. A genuine cancellation/abort surfaced
+// from the compact pipeline is NOT a context overflow: the fresh-context
+// pipeline deliberately rethrows the original abort error unchanged so the
+// session records a clean cancellation — and the manual/auto-clear runner
+// (manager/compaction-runner.mjs) likewise never fabricates an
+// AGENT_CONTEXT_OVERFLOW for an aborted compact. Mirror that here: preserve
+// the real error (code/name/cause intact) instead of masking it as overflow.
 function throwCompactFailure(ctx, run, compactErr) {
   const { state, compactPolicy, decision } = ctx;
   const { sessionRef, sessionId, signal, model } = state;
@@ -555,6 +559,33 @@ async function compactBeforeSend(ctx) {
   await runCompactHook(ctx, 'postCompactHook');
 }
 
+// Attachments that would crowd the window travel by reference from this send
+// on (session/attachment-preflight.mjs). Runs whether or not auto-compaction
+// is on: it is what keeps an oversized attachment message from ever reaching
+// the provider. A rewrite changes the transcript the provider chain was built
+// on, so the continuation is dropped and the send is tagged exactly like an
+// automatic compaction: the prefix guard accepts that boundary, whereas a
+// transcript-repair tag would refuse the rewritten earlier message.
+function preflightAttachments(ctx, compactPolicy) {
+  const { state } = ctx;
+  const contextWindow = compactPolicy?.contextWindow || state.sessionRef?.contextWindow;
+  const outcome = referenceOversizedAttachments(state.messages, {
+    contextWindow,
+    nativePdf: providerNativePdf(state.sessionRef?.provider),
+  });
+  if (!outcome.changed) return;
+  ctx.providerState = undefined;
+  ctx.providerStateCleared = true;
+  ctx.compactChanged = true;
+  if (state.opts && !String(state.opts.cacheBreakIntent || '').endsWith('_compaction')) {
+    state.opts.cacheBreakIntent = 'automatic_compaction';
+  }
+  writeStderrBestEffort(
+    `[loop] attachments sent by reference (sess=${state.sessionId || 'unknown'}): ` +
+      `${outcome.referencedMessages} message(s), inline estimate ${outcome.inlineTokensBefore} > budget ${outcome.budgetTokens}\n`
+  );
+}
+
 export async function runPreSendCompactPass(state) {
   const ctx = {
     state,
@@ -567,6 +598,7 @@ export async function runPreSendCompactPass(state) {
     compactChanged: false,
   };
   const compactPolicy = resolveWorkerCompactPolicy(state.sessionRef, state.requestTools);
+  preflightAttachments(ctx, compactPolicy);
   if (compactPolicy?.auto) {
     ctx.compactPolicy = compactPolicy;
     ctx.decision = preSendCompactDecision(state, compactPolicy);

package/src/runtime/agent/orchestrator/session/provider-prefix-guard.mjs

@@ -1,5 +1,6 @@
 import { createHash } from 'node:crypto';
 import { hasPlainPrototype } from '../../../shared/object.mjs';
+import { withoutMessageIdsReplacer } from './message-ids.mjs';
 
 const COMPACTION_INTENTS = new Set([
   'automatic_compaction',
@@ -8,8 +9,8 @@ const COMPACTION_INTENTS = new Set([
   'post_turn_compaction',
 ]);
 
-function digest(value) {
-  const encoded = JSON.stringify(value);
+function digest(value, replacer) {
+  const encoded = JSON.stringify(value, replacer);
   if (typeof encoded !== 'string') {
     throw new TypeError('provider prefix value is not serializable');
   }
@@ -82,11 +83,28 @@ function matchShape(value, tokens, cursor) {
   return count === tokens[cursor + 1] ? next : -1;
 }
 
+// A message's digest covers what the provider can see of it. The stable
+// message id (`meta.transcript.messageId`, message-ids.mjs) is display
+// bookkeeping that is stamped onto live messages in place — a compaction pass
+// stamps every unstamped message before it runs, whatever it then decides —
+// and no provider request builder reads or sends it (the rest of `meta` is
+// not bookkeeping: `meta.source` and `meta.effortConfiguration` steer the
+// wire and stay in the digest). Hashing it would make a pass that changes
+// nothing look like a rewritten prefix on the next send.
+//
+// Only the message root's own `meta` is projected: a `meta` nested in content
+// (e.g. a structured tool result) is provider-visible and stays in the digest.
+function rootMessageIdsReplacer(message) {
+  return function replacer(key, value) {
+    return this === message ? withoutMessageIdsReplacer(key, value) : value;
+  };
+}
+
 function messageDigest(message) {
   if (message === null || typeof message !== 'object') return digest(message);
   const memo = messageDigestMemo.get(message);
   if (memo && matchShape(message, memo.tokens, 0) === memo.tokens.length) return memo.hash;
-  const hash = digest(message);
+  const hash = digest(message, rootMessageIdsReplacer(message));
   const tokens = [];
   if (recordShape(message, tokens)) messageDigestMemo.set(message, { hash, tokens });
   else messageDigestMemo.delete(message);