mixdog 1.0.12 → 1.1.1

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

@@ -30,7 +30,9 @@
  * Non-breakpoint providers:
  *   - OpenAI (public): prompt_cache_key plus model-specific retention when
  *     response storage is enabled (30m cache options or 24h retention).
- *   - OpenAI OAuth: prompt_cache_key only (server in-memory 5-10min)
+ *   - OpenAI OAuth: prompt_cache_key only; the Codex backend keeps the
+ *     prompt cache at least 30 minutes on GPT-5.6+ models, refreshed on use
+ *     (the openai-oauth auto-clear window matches it)
  *   - Gemini: provider-managed explicit cachedContents with 5m default TTL, plus
  *     implicit caching as a fallback when the prefix is below cache minimums.
  *   - xAI: conversation routing for chat; Responses omits prompt_cache_key

package/src/runtime/agent/orchestrator/agent-runtime/session-builder.mjs

@@ -76,6 +76,8 @@ export function prepareAgentSession({
   schemaAllowedTools,
   sessionId,
   mcpScopeId,
+  contextPercent,
+  selectedContextWindow,
 }) {
   const effectivePermission = resolveAgentSessionPermission(agent, permission);
   // Pass cwd through verbatim — null is the fixed agent sentinel meaning
@@ -112,6 +114,8 @@ export function prepareAgentSession({
     compaction: compaction || undefined,
     mcpScopeId: mcpScopeId || null,
   };
+  if (contextPercent) sessionOpts.contextPercent = contextPercent;
+  if (selectedContextWindow) sessionOpts.selectedContextWindow = selectedContextWindow;
   if (agentTag) sessionOpts.agentTag = agentTag;
   if (effectivePermission) sessionOpts.permission = effectivePermission;
   if (permissionMode) sessionOpts.permissionMode = permissionMode;

package/src/runtime/agent/orchestrator/config-presets.d.mts

@@ -0,0 +1 @@
+export function withDefaultPresets(stored: unknown): unknown[];

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

@@ -1,4 +1,6 @@
 // Preset normalization and identity are independent of config storage.
+import { isDeepStrictEqual } from 'node:util';
+
 const ANTHROPIC_FAMILY_MODEL = Object.freeze({
   opus: 'claude-opus-4-8',
   sonnet: 'claude-sonnet-4-6',
@@ -64,6 +66,48 @@ export const DEFAULT_PRESETS = Object.freeze([
   }),
 ]);
 
+const DEFAULT_PRESET_BY_ID = new Map(DEFAULT_PRESETS.map((preset) => [preset.id, preset]));
+
+/** Effective presets: the stored entries in their stored order, then the
+ *  shipped presets missing from storage in shipped order. */
+export function withDefaultPresets(stored) {
+  const list = Array.isArray(stored) ? stored : [];
+  const present = new Set(list.map(presetKey));
+  return [...list, ...DEFAULT_PRESETS.filter((preset) => !present.has(preset.id)).map((preset) => ({ ...preset }))];
+}
+
+/** Stored form of `presets`: only entries that differ from the shipped default of the same id. */
+export function presetsDelta(presets) {
+  return (Array.isArray(presets) ? presets : []).filter((preset) => {
+    const shipped = DEFAULT_PRESET_BY_ID.get(presetKey(preset));
+    return !shipped || !isDeepStrictEqual(normalizePreset(preset), { ...shipped });
+  });
+}
+
+/** Stored form of `maintenance`: only slots that differ from the shipped route. */
+export function maintenanceDelta(maintenance) {
+  const source = maintenance && typeof maintenance === 'object' ? maintenance : {};
+  return Object.fromEntries(
+    Object.entries(source).filter(([slot, route]) => !isDeepStrictEqual(route, DEFAULT_MAINTENANCE[slot]))
+  );
+}
+
+/** Drop shipped presets and maintenance routes that equal their default; loadConfig restores them. */
+export function stripStoredRouteDefaults(agent) {
+  const next = { ...agent };
+  if (Object.hasOwn(next, 'presets')) {
+    const presets = presetsDelta(next.presets);
+    if (presets.length) next.presets = presets;
+    else delete next.presets;
+  }
+  if (Object.hasOwn(next, 'maintenance')) {
+    const maintenance = maintenanceDelta(next.maintenance);
+    if (Object.keys(maintenance).length) next.maintenance = maintenance;
+    else delete next.maintenance;
+  }
+  return next;
+}
+
 const AGENT_PROVIDER_ALIASES = Object.freeze({
   'openai-api': 'openai',
   'gemini-api': 'gemini',

package/src/runtime/agent/orchestrator/config-providers-merge.mjs

@@ -50,9 +50,17 @@ export function mergeStoredProviders({ raw, defaults, includeSecrets }) {
     }
   }
   // Custom providers: the keychain account is the generated custom-<uuid> id.
+  // A keyless (auth 'none') custom provider never carries a key, not even a
+  // hand-edited plaintext one.
+  for (const [name, val] of Object.entries(mergedProviders)) {
+    if (val?.type === 'custom' && val.auth === 'none' && Object.hasOwn(val, 'apiKey')) {
+      const { apiKey: _dropped, ...rest } = val;
+      mergedProviders[name] = rest;
+    }
+  }
   if (includeSecrets) {
     for (const [name, val] of Object.entries(mergedProviders)) {
-      if (val?.type !== 'custom' || !name.startsWith('custom-')) continue;
+      if (val?.type !== 'custom' || !name.startsWith('custom-') || val.auth === 'none') continue;
       const kc = getAgentApiKey(name);
       if (kc) mergedProviders[name] = { ...val, apiKey: kc, enabled: raw.providers?.[name]?.enabled !== false };
     }

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

@@ -2,6 +2,11 @@ import { hasExtensionScopes, normalizeExtensionScopes } from '../../shared/exten
 import { agentRouteStorageNeedsMigration, canonicalizeAgentRouteStorage } from '../../shared/agent-route-config.mjs';
 import profileConfig from '../../shared/profile-config.cjs';
 import { normalizeAgentProviderId, normalizePreset } from './config-presets.mjs';
+import {
+  loadSavedCodexCatalog,
+  migrateCodexRoute,
+  supersededCodexSettingsKey,
+} from './providers/openai-oauth-catalog-store.mjs';
 
 const { normalizeProfileConfig } = profileConfig;
 const RETIRED_LOCAL_PROVIDER_IDS = new Set(['ollama', 'lmstudio']);
@@ -205,7 +210,20 @@ function retiredLocalProviderStoragePresent(value = {}) {
   );
 }
 
+// Saved routes on a model the provider catalog has superseded (see
+// openai-oauth-catalog-store.mjs) — read from the last fetched catalog.
+function supersededRouteStoragePresent(value = {}, catalog = loadSavedCodexCatalog()) {
+  const superseded = (route) => migrateCodexRoute(route, catalog) !== route;
+  return (
+    (Array.isArray(value?.presets) && value.presets.some(superseded)) ||
+    Object.values(configObject(value?.agents)).some(superseded) ||
+    Object.values(configObject(value?.maintenance)).some(superseded) ||
+    Object.keys(configObject(value?.modelSettings)).some((key) => supersededCodexSettingsKey(key, catalog))
+  );
+}
+
 export function canonicalizeAgentStorage(value = {}) {
+  const catalog = loadSavedCodexCatalog();
   const next = canonicalizeAgentRouteStorage(value);
   const removedPresetIds = new Set(
     (Array.isArray(next.presets) ? next.presets : [])
@@ -216,17 +234,26 @@ export function canonicalizeAgentStorage(value = {}) {
   next.providers = configObject(next.providers);
   for (const id of RETIRED_LOCAL_PROVIDER_IDS) delete next.providers[id];
   next.presets = Array.isArray(next.presets)
-    ? next.presets.map((preset) => normalizePreset(preset)).filter((preset) => preset && !isRetiredLocalRoute(preset))
+    ? next.presets
+        .map((preset) => normalizePreset(migrateCodexRoute(preset, catalog)))
+        .filter((preset) => preset && !isRetiredLocalRoute(preset))
     : [];
   if (removedPresetIds.has(String(next.default || '').trim())) next.default = null;
   next.agents = Object.fromEntries(
-    Object.entries(configObject(next.agents)).filter(([, route]) => !isRetiredLocalRoute(route))
+    Object.entries(configObject(next.agents))
+      .filter(([, route]) => !isRetiredLocalRoute(route))
+      .map(([id, route]) => [id, migrateCodexRoute(route, catalog)])
   );
   next.maintenance = Object.fromEntries(
-    Object.entries(configObject(next.maintenance)).filter(([, route]) => !isRetiredLocalRoute(route))
+    Object.entries(configObject(next.maintenance))
+      .filter(([, route]) => !isRetiredLocalRoute(route))
+      .map(([slot, route]) => [slot, migrateCodexRoute(route, catalog)])
   );
+  // A superseded model's own settings have no model left to apply to.
   next.modelSettings = Object.fromEntries(
-    Object.entries(normalizedModelSettings(value)).filter(([key]) => !isRetiredLocalModelKey(key))
+    Object.entries(normalizedModelSettings(value)).filter(
+      ([key]) => !isRetiredLocalModelKey(key) && !supersededCodexSettingsKey(key, catalog)
+    )
   );
   setOrDelete(next, 'autoClear', canonicalizeAutoClearStorage(next.autoClear));
   setOrDelete(next, 'compaction', canonicalizeCompactionStorage(next.compaction));
@@ -266,6 +293,7 @@ export function agentConfigStorageNeedsMigration(value = {}) {
   return (
     agentRouteStorageNeedsMigration(value) ||
     retiredLocalProviderStoragePresent(value) ||
+    supersededRouteStoragePresent(value) ||
     RETIRED_AGENT_FIELDS.some((key) => key !== 'guide' && Object.hasOwn(value || {}, key)) ||
     presets.some((preset) => !normalizePreset(preset)) ||
     (modules && typeof modules === 'object' && Object.hasOwn(modules, 'memory')) ||

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

@@ -4,9 +4,33 @@ import { mergeStoredProviders } from './config-providers-merge.mjs';
 import { normalizeExtensionScopes } from '../../shared/extension-scopes.mjs';
 import { applyConfigPatch, diffConfig } from '../../shared/config-patch.mjs';
 import { normalizeWorkflowSelection } from '../../shared/orchestration.mjs';
-import { DEFAULT_DISABLED_AGENT_IDS, canonicalizeAgentRouteStorage } from '../../shared/agent-route-config.mjs';
+import {
+  DEFAULT_INSTRUCTION_FILES_MODE,
+  normalizeInstructionFilesMode,
+} from '../../shared/instruction-files-mode.mjs';
+import {
+  DEFAULT_DISABLED_AGENT_ROSTER,
+  canonicalizeAgentRouteStorage,
+  disabledAgentDelta,
+  disabledAgentIds,
+  effectiveDisabledAgents,
+  withEffectiveDisabledAgents,
+  withStoredDisabledAgents,
+} from '../../shared/agent-route-config.mjs';
+import {
+  DEFAULTS_VERSION,
+  ensureDefaultsSeparated,
+  storedDefaultsVersion,
+  stripAgentSectionDefaults,
+} from '../../shared/defaults-separation.mjs';
 import profileConfig from '../../shared/profile-config.cjs';
-import { DEFAULT_MAINTENANCE, DEFAULT_PRESETS, normalizePreset } from './config-presets.mjs';
+import {
+  DEFAULT_MAINTENANCE,
+  DEFAULT_PRESETS,
+  normalizePreset,
+  stripStoredRouteDefaults,
+  withDefaultPresets,
+} from './config-presets.mjs';
 import {
   agentConfigStorageNeedsMigration,
   canonicalizeAgentStorage,
@@ -87,9 +111,13 @@ export function buildDefaultConfig(options = {}) {
   // stored in mixdog-config.json — enabled at runtime from the presence of
   // Mixdog-owned credentials.
   providers['grok-oauth'] = oauthEntry('grok-oauth');
+  // Muse Code subscription (Meta Muse Spark), enabled from its stored key.
+  providers['muse-code-oauth'] = oauthEntry('muse-code-oauth');
   // Dev-only providers (Settings → Developer → Providers, one option each):
   // omitted entirely from the default config while their option is off so
   // they never surface in settings.
+  // Experimental MiMo subscription: enabled from a stored platform API key.
+  if (isOAuthProviderAvailable('mimo-oauth')) providers['mimo-oauth'] = oauthEntry('mimo-oauth');
   // Experimental direct Cursor wire provider. It remains disabled unless a
   // Mixdog-owned login or CURSOR_ACCESS_TOKEN is present.
   if (isOAuthProviderAvailable('cursor-oauth')) providers['cursor-oauth'] = oauthEntry('cursor-oauth');
@@ -100,11 +128,10 @@ export function buildDefaultConfig(options = {}) {
   providers['mixdog-local'] = { enabled: false };
   return {
     providers,
-    // The Maintainer also starts off: background upkeep spends model calls, so
-    // it runs only once the user turns it on and picks its model.
-    disabledAgents: [...DEFAULT_DISABLED_AGENT_IDS, 'maintainer'],
+    // Effective roster; the file stores only the user's delta against it.
+    disabledAgents: [...DEFAULT_DISABLED_AGENT_ROSTER],
     workflow: { active: 'default' },
-    orchestrationMode: 'none',
+    orchestrationMode: 'balanced',
   };
 }
 
@@ -168,11 +195,26 @@ function normalizeRecapConfig(rawRecap) {
   return recap;
 }
 
+// `instructionFiles` (instruction-files-mode.mjs): only a valid non-default
+// mode is kept; absent means the default.
+function storedInstructionFiles(agent) {
+  const mode = normalizeInstructionFilesMode(agent?.instructionFiles);
+  return mode === DEFAULT_INSTRUCTION_FILES_MODE ? {} : { instructionFiles: mode };
+}
+
 export function loadConfig(options = {}) {
   const includeSecrets = options.secrets !== false;
+  try {
+    ensureDefaultsSeparated({ stripRouteDefaults: separateStoredAgent });
+  } catch (err) {
+    process.stderr.write(`[config] defaults separation failed: ${err?.message}\n`);
+  }
   const sectionRaw = readSection('agent');
   if (hasKeys(sectionRaw)) {
     try {
+      // A file that could not be separated still holds the legacy form:
+      // before version 1 `disabledAgents` is the full list, not a delta.
+      const legacyDisabledAgents = storedDefaultsVersion() < 1;
       let raw = sectionRaw;
       const storageNeedsMigration = agentConfigStorageNeedsMigration(raw);
       raw = canonicalizeAgentStorage(raw);
@@ -206,7 +248,7 @@ export function loadConfig(options = {}) {
       const loaded = canonicalizeAgentRouteStorage({
         providers: mergedProviders,
         mcpServers,
-        presets: normalizedPresets,
+        presets: withDefaultPresets(normalizedPresets),
         default: raw.default || null,
         maintenance: { ...DEFAULT_MAINTENANCE, ...normalizedMaint },
         workflowRoutes,
@@ -214,9 +256,11 @@ export function loadConfig(options = {}) {
         modelSettings,
         onboarding: raw.onboarding && typeof raw.onboarding === 'object' ? raw.onboarding : {},
         agents: raw.agents && typeof raw.agents === 'object' ? raw.agents : {},
-        // Explicit "off" roster. canonicalizeAgentRouteStorage normalizes
-        // and drops it when empty, so an all-enabled config stays clean.
-        disabledAgents: Array.isArray(raw.disabledAgents) ? raw.disabledAgents : [],
+        // Effective "off" roster = code defaults + the stored user delta.
+        // canonicalizeAgentRouteStorage drops it when empty.
+        disabledAgents: legacyDisabledAgents ? disabledAgentIds(raw) : effectiveDisabledAgents(raw),
+        ...(raw.memoryTools && typeof raw.memoryTools === 'object' ? { memoryTools: { ...raw.memoryTools } } : {}),
+        ...storedInstructionFiles(raw),
         ...normalizeWorkflowSelection(raw),
         profile: normalizeProfileConfig(raw.profile),
         skills: normalizeSkillsConfig(raw.skills),
@@ -241,7 +285,7 @@ export function loadConfig(options = {}) {
           // Retired cross-section fields are no longer migrated by
           // the shared config layer. Normalize only the locked
           // current section; stale reads must not undo deletions.
-          persistAgentConfig(canonicalizeAgentStorage);
+          persistAgentConfig((current) => storedAgentForm(canonicalizeAgentStorage(current)));
         } catch (err) {
           process.stderr.write(`[config] persist canonical agent config failed: ${err?.message}\n`);
         }
@@ -263,7 +307,7 @@ export function loadConfig(options = {}) {
     onboarding: {},
     agents: {},
     workflow: { active: 'default' },
-    orchestrationMode: 'none',
+    orchestrationMode: 'balanced',
     profile: normalizeProfileConfig(null),
     skills: normalizeSkillsConfig(null),
     extensionScopes: normalizeExtensionScopes(null),
@@ -383,28 +427,83 @@ function buildAgentSaveBuilder(config) {
     // Developer options (developer-options.mjs); an empty set stays absent.
     if (Object.keys(developer).length) next.developer = developer;
     else if (Object.hasOwn(config, 'developer')) delete next.developer;
-    if (canonicalRoutes.disabledAgents) {
-      next.disabledAgents = canonicalRoutes.disabledAgents;
-    } else {
-      delete next.disabledAgents;
-    }
+    // Only the user's delta against the default roster is stored.
+    delete next.disabledAgents;
+    delete next.enabledAgents;
+    // An unseparated file keeps the legacy full list until the pass succeeds.
+    if (storedDefaultsVersion() < 1) {
+      if (canonicalRoutes.disabledAgents?.length) next.disabledAgents = canonicalRoutes.disabledAgents;
+    } else Object.assign(next, disabledAgentDelta(canonicalRoutes.disabledAgents));
+    if (config.memoryTools && typeof config.memoryTools === 'object') next.memoryTools = { ...config.memoryTools };
+    else delete next.memoryTools;
+    delete next.instructionFiles;
+    Object.assign(next, storedInstructionFiles(config));
     delete next.workflowRoutes;
-    return removeRetiredAgentFields(next);
+    // Defaults live in code: values equal to the current default are not stored.
+    return storedAgentForm(removeRetiredAgentFields(next));
   };
 }
+
+/** A numeric `default` is a preset index; store the preset id it points at (index into the effective list). */
+function resolveNumericDefault(agent) {
+  const value = agent?.default;
+  // The loader reads a falsy default (including 0) as "none".
+  if (!value || !(typeof value === 'number' || /^\d+$/.test(String(value)))) return agent;
+  const stored = (Array.isArray(agent.presets) ? agent.presets : [])
+    .map((preset) => normalizePreset(preset))
+    .filter(Boolean)
+    .filter((preset) => preset.id !== 'workflow-search');
+  const { presets } = canonicalizeAgentRouteStorage({ presets: withDefaultPresets(stored) });
+  const preset = presets[Number(value)];
+  return preset ? { ...agent, default: preset.id } : agent;
+}
+
+/** The agent section as stored: defaults dropped. Route defaults go only once the file is separated. */
+function storedAgentForm(agent) {
+  const stripped = stripAgentSectionDefaults(resolveNumericDefault(agent));
+  return storedDefaultsVersion() >= DEFAULTS_VERSION ? stripStoredRouteDefaults(stripped) : stripped;
+}
+
+/** Separation pass: normalize the compared sections first, then drop every default. */
+function separateStoredAgent(agent) {
+  const full = canonicalizeAgentStorage(agent);
+  const next = { ...agent };
+  for (const key of ['autoClear', 'compaction', 'modules']) {
+    if (!Object.hasOwn(agent, key)) continue;
+    if (full[key] === undefined) delete next[key];
+    else next[key] = full[key];
+  }
+  return stripStoredRouteDefaults(stripAgentSectionDefaults(resolveNumericDefault(next)));
+}
+
+/** Patch the stored section; unseparated data keeps its form, a numeric default becomes an id first. */
+function applyStoredPatch(current, changes) {
+  const base = resolveNumericDefault(current);
+  if (storedDefaultsVersion() >= 1) return applyConfigPatch(base, changes);
+  const delta = withStoredDisabledAgents({ ...base, disabledAgents: disabledAgentIds(base) });
+  return withEffectiveDisabledAgents(applyConfigPatch(delta, changes));
+}
 // Diff the persisted schema, not runtime defaults, aliases, or secret overlays.
+// Patches always speak the delta domain; an unseparated file's full list is
+// converted here and back in applyStoredPatch.
+function patchForm(agent) {
+  if (storedDefaultsVersion() >= 1) return agent;
+  const { disabledAgents, ...rest } = agent;
+  return { ...rest, ...disabledAgentDelta(disabledAgents || []) };
+}
+
 export function createConfigPatch(before, after) {
-  return diffConfig(buildAgentSaveBuilder(before)({}), buildAgentSaveBuilder(after)({}));
+  return diffConfig(patchForm(buildAgentSaveBuilder(before)({})), patchForm(buildAgentSaveBuilder(after)({})));
 }
 
 export function saveConfigPatch(changes) {
   if (!changes.length) return;
-  persistAgentConfig((current) => applyConfigPatch(current, changes));
+  persistAgentConfig((current) => applyStoredPatch(current, changes));
 }
 
 export async function saveConfigPatchAsync(changes) {
   if (!changes.length) return;
-  await persistAgentConfigAsync((current) => applyConfigPatch(current, changes));
+  await persistAgentConfigAsync((current) => applyStoredPatch(current, changes));
 }
 
 // Whole-section replacement is reserved for explicit full saves. Read/edit/save

package/src/runtime/agent/orchestrator/context/instruction-files.mjs

@@ -0,0 +1,130 @@
+// The user's instruction files (AGENTS.md / CLAUDE.md), global then project,
+// rendered as one `# Instruction Files` block for a new session's BP3 core.
+import { closeSync, constants, fstatSync, openSync, readSync, realpathSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { isAbsolute, join, relative, resolve } from 'node:path';
+import { readSection } from '../../../shared/config.mjs';
+import { normalizeInstructionFilesMode } from '../../../shared/instruction-files-mode.mjs';
+import { featureEnvOverride } from '../runtime-core/config-helpers.mjs';
+
+// Per-file budget in UTF-8 bytes (same byte-based cap as core memory).
+const INSTRUCTION_FILE_MAX_BYTES = 32 * 1024;
+const TRUNCATED_MARK = '\n\n[... truncated]';
+const KINDS_BY_MODE = { all: ['agents', 'claude'], agents: ['agents'], claude: ['claude'], off: [] };
+const GLOBAL_DIR = { agents: '.codex', claude: '.claude' };
+const FILE_NAME = { agents: 'AGENTS.md', claude: 'CLAUDE.md' };
+
+/** The configured mode, forced off by MIXDOG_BOOT_INSTRUCTION_FILES=0. */
+export function effectiveInstructionFilesMode(mode) {
+  if (featureEnvOverride('MIXDOG_BOOT_INSTRUCTION_FILES') === false) return 'off';
+  return normalizeInstructionFilesMode(mode);
+}
+
+/** The stored agent-config value; an unreadable config reads as the default. */
+export function configuredInstructionFilesMode() {
+  try {
+    return normalizeInstructionFilesMode(readSection('agent')?.instructionFiles);
+  } catch {
+    return normalizeInstructionFilesMode(undefined);
+  }
+}
+
+const UTF8_BOM = Buffer.from([0xef, 0xbb, 0xbf]);
+
+/** Candidate files in load order: global files first, then the project root's.
+ *  Project files are confined to the real directory of their `root`; global
+ *  files carry no root and may resolve anywhere. */
+function instructionFileCandidates({ mode, cwd, homeDir = homedir() } = {}) {
+  const kinds = KINDS_BY_MODE[effectiveInstructionFilesMode(mode)];
+  const candidates = [];
+  if (homeDir) {
+    const root = resolve(homeDir);
+    // Global files may be symlinks into a dotfiles repo: no containment root.
+    for (const kind of kinds) candidates.push({ path: join(root, GLOBAL_DIR[kind], FILE_NAME[kind]) });
+  }
+  if (cwd) {
+    const root = resolve(cwd);
+    for (const kind of kinds) candidates.push({ path: join(root, FILE_NAME[kind]), root });
+  }
+  return candidates;
+}
+
+function isInside(root, path) {
+  const rel = relative(root, path);
+  return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
+}
+
+function skipNote(path, reason) {
+  process.stderr.write(`[instruction-files] skipped ${path}: ${reason}\n`);
+}
+
+/** At most the file's first cap bytes (plus a BOM allowance and one probe byte)
+ *  from an open fd, so a huge or endless file is never read whole. */
+function readHead(fd) {
+  const buffer = Buffer.allocUnsafe(INSTRUCTION_FILE_MAX_BYTES + UTF8_BOM.length + 1);
+  let length = 0;
+  while (length < buffer.length) {
+    const count = readSync(fd, buffer, length, buffer.length - length, null);
+    if (count === 0) break;
+    length += count;
+  }
+  return buffer.subarray(0, length);
+}
+
+/** Decode a head that may end mid-character: the incomplete tail is dropped. */
+function decodeHead(bytes) {
+  return new TextDecoder('utf-8').decode(bytes, { stream: true });
+}
+
+/** The bounded, trimmed text of one instruction file; over the budget it is cut
+ *  at a word boundary and ends with the truncation notice. */
+function boundedText(head) {
+  const bytes = head.subarray(0, UTF8_BOM.length).equals(UTF8_BOM) ? head.subarray(UTF8_BOM.length) : head;
+  if (bytes.length <= INSTRUCTION_FILE_MAX_BYTES) return decodeHead(bytes).trim();
+  const budget = INSTRUCTION_FILE_MAX_BYTES - Buffer.byteLength(TRUNCATED_MARK, 'utf8');
+  const text = decodeHead(bytes.subarray(0, budget)).trim();
+  return `${text.replace(/\s+\S*$/, '')}${TRUNCATED_MARK}`;
+}
+
+/** The file's bounded content, or '' when it is absent, unreadable, not a
+ *  regular file, or resolves (symlink/junction) outside `root` when one is set. */
+function readInstructionFile({ path, root }) {
+  let fd;
+  try {
+    const realPath = realpathSync.native(path);
+    if (root && !isInside(realpathSync.native(root), realPath)) {
+      skipNote(path, 'resolves outside its root');
+      return '';
+    }
+    if (!statSync(realPath).isFile()) return '';
+    fd = openSync(realPath, constants.O_RDONLY | (constants.O_NONBLOCK ?? 0));
+    if (!fstatSync(fd).isFile()) return '';
+    return boundedText(readHead(fd));
+  } catch (error) {
+    if (error?.code !== 'ENOENT' && error?.code !== 'ENOTDIR' && error?.code !== 'EISDIR') {
+      skipNote(path, error?.code || error?.message || 'unreadable');
+    }
+    return '';
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+  }
+}
+
+/** The `# Instruction Files` block, or '' when no file has content. Files
+ *  whose bounded content repeats an included one (symlinks, copies) are dropped. */
+export function loadInstructionFilesContext({ mode, cwd, homeDir = homedir() } = {}) {
+  const seen = new Set();
+  const sections = [];
+  for (const candidate of instructionFileCandidates({ mode, cwd, homeDir })) {
+    const content = readInstructionFile(candidate);
+    if (!content || seen.has(content)) continue;
+    seen.add(content);
+    sections.push(`## ${candidate.path}\n\n${content}`);
+  }
+  if (!sections.length) return '';
+  return [
+    '# Instruction Files',
+    "The user's instruction files. Project files take precedence over global ones when they conflict.",
+    ...sections,
+  ].join('\n\n');
+}

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

@@ -268,12 +268,16 @@ export function composeSystemPrompt(opts) {
   // Keep the active workflow first within BP3 so it leads the role and
   // environment material that varies with the session.
   const coreMemory = skip.memory ? '' : trimmedPromptSlice(opts.coreMemoryContext);
+  // User AGENTS.md / CLAUDE.md block (context/instruction-files.mjs), already
+  // headed `# Instruction Files`; rides right after core memory.
+  const instructionFiles = skip.claudemd ? '' : trimmedPromptSlice(opts.instructionFilesContext);
   const sessionMarkerCore = joinPromptSlices([
     trimmedPromptSlice(opts.workflowContext),
     opts.roleRules || '',
     opts.userPrompt || '',
     roleInstructionContext,
     coreMemory ? `# Core Memory\n${coreMemory}` : '',
+    instructionFiles,
   ]);
   // Response language is the LAST system text before the conversation. It
   // rides the environment block (not the tier3 core) because the `# Session`