mixdog 0.9.45 → 0.9.47

package/src/runtime/memory/lib/query-handlers.mjs

@@ -49,7 +49,7 @@ export function createQueryHandlers({
   // Raw-row priority lookup for narrow-window queries. Raw rows (is_root=0,
   // chunk_root IS NULL) are inserted immediately by ingestTranscriptFile before
   // cycle1 runs, so they always carry the freshest turns in the DB.
-  async function readRawRowsInWindow(db, tsFromMs, tsToMs, hardLimit = 10, { projectScope, sessionId, terms } = {}) {
+  async function readRawRowsInWindow(db, tsFromMs, tsToMs, hardLimit = 10, { projectScope, sessionId, terms, minHits: minHitsOverride } = {}) {
     try {
       // Composable WHERE assembly (mirrors retrieveEntries' filter semantics so
       // raw and chunked legs stay in filter parity: projectScope AND sessionId
@@ -78,7 +78,9 @@ export function createQueryHandlers({
         // into the page. 1-2 term queries keep single-hit contains semantics —
         // short Korean queries are often exactly two meaningful tokens and a
         // 2-of-2 requirement silently emptied the raw leg for them.
-        const minHits = terms.length >= 3 ? 2 : 1
+        const minHits = Number.isFinite(Number(minHitsOverride))
+          ? Math.max(1, Math.floor(Number(minHitsOverride)))
+          : (terms.length >= 3 ? 2 : 1)
         where.push(`(${clauses.join(' + ')}) >= ${minHits}`)
       }
       params.push(hardLimit)
@@ -722,7 +724,7 @@ export function createQueryHandlers({
       // Deterministic tie-breaker: equal MAX(ts) across sessions would let the
       // LIMIT/OFFSET window skip or duplicate a session between offset pages
       // without a stable secondary sort.
-      const sessSql = `SELECT session_id, MAX(ts) AS last_ts
+      const sessSql = `SELECT session_id, MIN(ts) AS first_ts, MAX(ts) AS last_ts
                        FROM entries
                        WHERE ${selWhere.join(' AND ')}
                        GROUP BY session_id
@@ -732,6 +734,7 @@ export function createQueryHandlers({
       // 2) per selected session, fetch its newest rows (roots+members, sort by
       //    date) plus the fresh raw window, capped at PER_SESSION_ROW_CAP.
       const allRows = []
+      const sessionMeta = new Map()
       for (const s of sessRows) {
         const sid = String(s?.session_id || '').trim()
         if (!sid) continue
@@ -743,7 +746,24 @@ export function createQueryHandlers({
         const sRows = await retrieveEntries(db, sf)
         let merged = sRows
         if (includeRaw) {
-          const rawRows = await readRawRowsInWindow(db, null, Date.now(), perSessionFetchCap, { projectScope, sessionId: sid, terms: queryTerms })
+          let rawRows
+          if (queryTerms.length > 0) {
+            // Keep a full unfiltered recency window for the newest-row floor,
+            // while separately retaining the deeper term-matched raw window.
+            const [recentRawRows, matchedRawRows] = await Promise.all([
+              readRawRowsInWindow(db, null, Date.now(), perSessionFetchCap, { projectScope, sessionId: sid, terms: [] }),
+              readRawRowsInWindow(db, null, Date.now(), perSessionFetchCap, { projectScope, sessionId: sid, terms: queryTerms, minHits: 1 }),
+            ])
+            const rawIds = new Set()
+            rawRows = [...recentRawRows, ...matchedRawRows].filter((r) => {
+              const id = Number(r.id)
+              if (rawIds.has(id)) return false
+              rawIds.add(id)
+              return true
+            })
+          } else {
+            rawRows = await readRawRowsInWindow(db, null, Date.now(), perSessionFetchCap, { projectScope, sessionId: sid, terms: [] })
+          }
           const seenIds = new Set(sRows.map((r) => Number(r.id)))
           for (const r of sRows) if (Array.isArray(r.members)) for (const m of r.members) seenIds.add(Number(m.id))
           // readRawRowsInWindow carries no category filter, so a category-
@@ -768,14 +788,37 @@ export function createQueryHandlers({
             merged.sort((a, b) => (Number(b.ts) || 0) - (Number(a.ts) || 0) || (Number(b.id) || 0) - (Number(a.id) || 0))
           }
         }
+        const fetchedCount = merged.length
+        let queryFiltered = false
         if (queryTerms.length > 0) {
-          merged = merged.filter(matchesQueryTerms)
+          const newestRows = merged.slice(0, 3)
+          const newestIds = new Set(newestRows.map((r) => r.id))
+          const matchedRows = merged.filter(matchesQueryTerms)
+          // A topic query must not obscure a session's latest activity: keep
+          // its three newest rows, then use term matches for the remaining
+          // display slots without duplicating rows already kept for recency.
+          merged = [...newestRows, ...matchedRows.filter((r) => !newestIds.has(r.id))]
+          // Only mark query filtering when its floor+match union actually
+          // excludes fetched rows. The later display cap is independent.
+          queryFiltered = merged.length < fetchedCount
         }
         merged = merged.slice(0, PER_SESSION_ROW_CAP)
+        sessionMeta.set(sid, {
+          minTs: Number(s.first_ts),
+          maxTs: Number(s.last_ts),
+          fetchedCount,
+          shownCount: merged.length,
+          queryFiltered,
+        })
         for (const r of merged) allRows.push(r)
       }
       const _currentSessionHint = String(args?.currentSessionId || '').trim()
-      return { text: recallCapPrefix + renderSessionGroupedLines(allRows, { currentSessionId: _currentSessionHint, recencyOrder: true, spanHeaders: true }) }
+      return { text: recallCapPrefix + renderSessionGroupedLines(allRows, {
+        currentSessionId: _currentSessionHint,
+        recencyOrder: true,
+        spanHeaders: true,
+        sessionMeta,
+      }) }
     }
 
     const filters = { limit: limit + offset }

package/src/runtime/memory/lib/recall-format.mjs

@@ -336,10 +336,16 @@ function spanHeaderSuffix(minTs, maxTs, n) {
 // group's lines are globally ts-desc: without it a chunk root's members (stored
 // ts-ASC) interleave with raw rows and invert the visible timeline within a
 // session (e.g. 04:33 rendered above 04:41).
-export function renderSessionGroupedLines(rows, { currentSessionId, recencyOrder = false, spanHeaders = false } = {}) {
-  if (!rows || rows.length === 0) return '(no results)'
+export function renderSessionGroupedLines(rows, { currentSessionId, recencyOrder = false, spanHeaders = false, sessionMeta } = {}) {
+  const hasSessionMeta = spanHeaders && Number(sessionMeta?.size) > 0
+  if ((!rows || rows.length === 0) && !hasSessionMeta) return '(no results)'
   const groups = new Map()
-  for (const r of rows) {
+  // Seed selected sessions so an entirely query-filtered session still
+  // reports its real activity span and filtering status.
+  if (hasSessionMeta) {
+    for (const sid of sessionMeta.keys()) groups.set(sid, [])
+  }
+  for (const r of rows || []) {
     const sid = String(r?.session_id || '').trim()
     const key = sid || '(no session)'
     if (!groups.has(key)) groups.set(key, [])
@@ -356,11 +362,20 @@ export function renderSessionGroupedLines(rows, { currentSessionId, recencyOrder
     for (const [sid, groupRows] of groups) {
       const mark = current && sid === current ? ' (current)' : ''
       const label = sid === '(no session)' ? sid : `session ${shortSessionLabel(sid)}`
+      const meta = sessionMeta?.get?.(sid)
       const tsAll = collectGroupTs(groupRows)
-      const suffix = tsAll.length
-        ? ` ${spanHeaderSuffix(Math.min(...tsAll), Math.max(...tsAll), groupRows.length)}`
+      const minTs = Number(meta?.minTs)
+      const maxTs = Number(meta?.maxTs)
+      const hasActivitySpan = Number.isFinite(minTs) && Number.isFinite(maxTs)
+      const suffix = hasActivitySpan
+        ? ` ${spanHeaderSuffix(minTs, maxTs, groupRows.length)}`
+        : tsAll.length
+          ? ` ${spanHeaderSuffix(Math.min(...tsAll), Math.max(...tsAll), groupRows.length)}`
         : ` (${groupRows.length} entries)`
-      parts.push(`## ${label}${mark}${suffix}`)
+      const filterNote = meta?.queryFiltered
+        ? ` · query-filtered ${meta.shownCount}/${meta.fetchedCount} rows`
+        : ''
+      parts.push(`## ${label}${mark}${suffix}${filterNote}`)
       const bodyStr = renderEntryLines(groupRows, { recencyOrder })
       const bodyLines = bodyStr === '(no results)'
         ? []

package/src/runtime/memory/tool-defs.mjs

@@ -8,20 +8,20 @@ export const TOOL_DEFS = [
     name: 'memory',
     title: 'Memory Cycle',
     annotations: { title: 'Memory Cycle', readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
-    description: 'Core-memory mutation and status. Use recall for retrieval. Persist with action:"core" op:"add" when: user corrects/confirms your approach, states a durable preference, or says "remember". Core add/edit requires project_id + category + element + summary. Only what code/git/docs cannot derive; include the why. Never transient task state. No prior recall dedup needed — the cycle dedups.',
+    description: 'Core-memory mutation and status; use recall for retrieval. Store durable rules/preferences/facts, one compact ENGLISH clause each — never transient task state. add requires project_id+category+summary; edit works by id alone.',
     inputSchema: {
       type: 'object',
       properties: {
         action: { type: 'string', enum: ['core','status'], description: 'Operation.' },
         op: { type: 'string', enum: ['add','edit','delete','list','candidates','promote','dismiss'], description: 'Mutation op. candidates/promote/dismiss drive core-memory proposal approval.' },
         id: { type: 'number', description: 'Exact memory id.' },
-        element: { type: 'string', maxLength: 40, description: 'Memory key/title. Max 40 chars.' },
-        summary: { type: 'string', maxLength: 100, description: 'Memory content: 1 fact, 1-2 sentences, max 100 chars.' },
+        element: { type: 'string', maxLength: 40, description: 'Memory key/title. Defaults to the first 40 chars of summary. Max 40 chars.' },
+        summary: { type: 'string', maxLength: 100, description: 'Memory content: one short English clause, max 100 chars.' },
         category: { type: 'string', enum: ['rule','constraint','decision','fact','goal','preference','task','issue'], description: 'Category.' },
         status: { type: 'string', enum: ['pending','active','archived'], description: 'Lifecycle status.' },
         limit: { type: 'number', description: 'Max rows/items.' },
         confirm: { type: 'string', description: 'Exact confirmation phrase for destructive actions.' },
-        project_id: { type: 'string', description: 'Core pool: common, slug, or *. Required for core add/edit; there is no default pool.' },
+        project_id: { type: 'string', description: 'Core pool: explicit common or slug. Required for core add only (edit uses the id\'s stored pool); there is no default pool.' },
       },
       additionalProperties: false,
       required: ['action'],
@@ -31,7 +31,7 @@ export const TOOL_DEFS = [
     name: 'recall',
     title: 'Recall',
     annotations: { title: 'Recall', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
-    description: 'Retrieve stored memory/session history. Call when a task ties to prior work — resumes, continuations, or references to earlier decisions/messages. Do not call as a reflexive pre-step, to verify a just-made decision, or before storing memory. Query is topic/semantic search, not regex. Patterns: period:"last" browses recent sessions; +query narrows topic; sessionId without query for current session; period:"3h"/"30m"/"24h" for recent; YYYY-MM-DD, date ranges, or HH:MM~HH:MM for time windows; id for exact follow-up.',
+    description: 'Retrieve stored memory/session history for prior-work context (resumes, earlier decisions); not a reflexive pre-step. Query is topic/semantic, not regex; period selects the time window; id for exact follow-up.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -44,7 +44,6 @@ export const TOOL_DEFS = [
         category: { anyOf: [{ type: 'string', enum: ['rule','constraint','decision','fact','goal','preference','task','issue'] }, { type: 'array', items: { type: 'string', enum: ['rule','constraint','decision','fact','goal','preference','task','issue'] }, minItems: 1 }], description: 'Category filter.' },
         includeArchived: { type: 'boolean', description: 'Include archived entries.' },
         sessionId: { type: 'string', description: 'Scoped session id.' },
-        session_id: { type: 'string', description: 'Alias for sessionId.' },
         includeMembers: { type: 'boolean', description: 'Include chunk members in output; does not widen the search pool.' },
         includeRaw: { type: 'boolean', description: 'Include unchunked raw/episode rows.' },
         sessionOnly: { type: 'boolean', description: 'Search this session only.' },

package/src/runtime/shared/config.mjs

@@ -14,6 +14,17 @@ import {
   loadLatestMixdogConfigFromBackup,
   hasUserDataInitMarker,
 } from './user-data-guard.mjs'
+import {
+  AGENT_PROVIDER_ENV,
+  AGENT_PROVIDER_ENV_ALIASES,
+  getAgentApiKey,
+} from './provider-api-key.mjs'
+
+export {
+  AGENT_PROVIDER_ENV,
+  AGENT_PROVIDER_ENV_ALIASES,
+  getAgentApiKey,
+}
 
 const _require = createRequire(import.meta.url)
 const { getSecret: _getSecret, setSecret: _setSecret, deleteSecret: _deleteSecret, hasSecret: _hasSecret } = _require('../../lib/keychain-cjs.cjs')
@@ -453,40 +464,6 @@ export function getWebhookAuthtoken() {
   return _readSecret(SECRET_ACCOUNTS.webhookAuth)
 }
 
-// Standard provider env names take precedence so existing OPENAI_API_KEY-style
-// exports keep working, then MIXDOG_AGENT_<P>_APIKEY, then the OS keychain.
-// SSOT for agent API-key providers: setup-server.mjs and config-merge.mjs import
-// this so UI key-presence detection uses the exact same predicate the runtime
-// loads from. Add a provider here and every path picks it up.
-export const AGENT_PROVIDER_ENV = Object.freeze({
-  openai: 'OPENAI_API_KEY', anthropic: 'ANTHROPIC_API_KEY', gemini: 'GEMINI_API_KEY',
-  deepseek: 'DEEPSEEK_API_KEY', xai: 'XAI_API_KEY', 'opencode-go': 'OPENCODE_API_KEY',
-})
-
-// Last-resort env aliases honored AFTER the standard env / MIXDOG_AGENT_* /
-// keychain sources. GROK_API_KEY is the established xAI alias elsewhere in the
-// repo (search discovery, xai-api/grok-oauth backends), so honoring it here
-// keeps provider discovery and dispatch resolving the same credential.
-export const AGENT_PROVIDER_ENV_ALIASES = Object.freeze({
-  xai: ['GROK_API_KEY'],
-})
-
-/**
- * Returns the API key for an agent provider.
- * Priority: <PROVIDER>_API_KEY env -> MIXDOG_AGENT_<PROVIDER>_APIKEY -> keychain('agent.<provider>.apiKey') -> alias env (e.g. GROK_API_KEY for xai) -> null.
- * Never reads mixdog-config.json — provider keys are keychain-only.
- */
-export function getAgentApiKey(provider) {
-  const std = AGENT_PROVIDER_ENV[provider]
-  if (std && process.env[std]) return process.env[std]
-  const fromStore = _readSecret(SECRET_ACCOUNTS.agentApiKey(provider))
-  if (fromStore) return fromStore
-  for (const alias of AGENT_PROVIDER_ENV_ALIASES[provider] || []) {
-    if (process.env[alias]) return process.env[alias]
-  }
-  return null
-}
-
 export function getOpenAIUsageSessionKey() {
   return process.env.OPENAI_USAGE_SESSION_KEY
     || process.env.OPENAI_DASHBOARD_SESSION_KEY

package/src/runtime/shared/pristine-execution-contract.json

@@ -0,0 +1,75 @@
+{
+  "schemaVersion": 1,
+  "configFileName": "mixdog-config.json",
+  "guardEnv": {
+    "MIXDOG_DISABLE_MCP": "1",
+    "MIXDOG_DISABLE_SKILLS": "1",
+    "MIXDOG_BOOT_CORE_MEMORY": "0",
+    "MIXDOG_DISABLE_CHANNEL_START": "1",
+    "MIXDOG_SKIP_USER_DATA_BACKUP": "1",
+    "MIXDOG_DISABLE_STAGED_INSTALL": "1",
+    "MIXDOG_DISABLE_STAGED_SWAP": "1"
+  },
+  "approvedExecutionEnv": [
+    "MIXDOG_AGENT_TRACE_PATH",
+    "MIXDOG_ANTHROPIC_OAUTH_REFRESH_DISABLED",
+    "MIXDOG_DRIVER_DEADLINE_MS",
+    "MIXDOG_DISABLE_PROVIDER_WARMUP",
+    "MIXDOG_DISABLE_MODEL_PREFETCH",
+    "MIXDOG_DISABLE_MODEL_CATALOG_WARMUP",
+    "MIXDOG_PROVIDER_FIRST_BYTE_TIMEOUT_MS",
+    "MIXDOG_STALL_FIRST_BYTE_ABORT_S"
+  ],
+  "benchmarkRouteEnv": [
+    "MIXDOG_PROMPT",
+    "MIXDOG_PROVIDER",
+    "MIXDOG_MODEL",
+    "MIXDOG_EFFORT",
+    "MIXDOG_FAST",
+    "MIXDOG_WORKFLOW"
+  ],
+  "oauthProviders": {
+    "anthropic-oauth": {
+      "credentialFile": "anthropic-oauth-credentials.json",
+      "credentialPathEnv": "ANTHROPIC_OAUTH_CREDENTIALS_PATH",
+      "modelCatalogFile": "anthropic-oauth-models.json"
+    },
+    "openai-oauth": {
+      "credentialFile": "openai-oauth.json",
+      "credentialPathEnv": "OPENAI_OAUTH_CREDENTIALS_PATH",
+      "modelCatalogFile": "openai-oauth-models.json"
+    },
+    "grok-oauth": {
+      "credentialFile": "grok-oauth.json",
+      "credentialPathEnv": "GROK_OAUTH_CREDENTIALS_PATH",
+      "modelCatalogFile": "grok-oauth-models.json"
+    }
+  },
+  "apiKeyProviders": {
+    "openai": "OPENAI_API_KEY",
+    "anthropic": "ANTHROPIC_API_KEY",
+    "gemini": "GEMINI_API_KEY",
+    "deepseek": "DEEPSEEK_API_KEY",
+    "xai": "XAI_API_KEY",
+    "opencode-go": "OPENCODE_API_KEY"
+  },
+  "personalStateCounters": [
+    "behavioralStateFilesCopied",
+    "memoryFilesCopied",
+    "sessionFilesCopied",
+    "userProfileFilesCopied",
+    "pluginStateFilesCopied",
+    "channelStateFilesCopied",
+    "otherPersonalStateFilesCopied"
+  ],
+  "disabledFeatures": [
+    "mcpSources",
+    "skills",
+    "bundledSkillSeeding",
+    "coreMemoryBoot",
+    "channelStart",
+    "plugins",
+    "userProfiles",
+    "priorSessions"
+  ]
+}

package/src/runtime/shared/pristine-execution.mjs

@@ -0,0 +1,356 @@
+import { createHash } from 'node:crypto';
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { replaceProviderAuthBindings } from './provider-auth-binding.mjs';
+import {
+  AGENT_PROVIDER_ENV_ALIASES,
+  getAgentApiKey,
+} from './provider-api-key.mjs';
+
+const contractPath = fileURLToPath(
+  new URL('./pristine-execution-contract.json', import.meta.url),
+);
+const patchManifestPath = fileURLToPath(
+  new URL('../agent/orchestrator/tools/patch-manifest.json', import.meta.url),
+);
+
+export const PRISTINE_EXECUTION_CONTRACT = Object.freeze(
+  JSON.parse(readFileSync(contractPath, 'utf8')),
+);
+
+const EFFORTS = new Set(['low', 'medium', 'high', 'xhigh', 'max']);
+
+function clean(value) {
+  return String(value ?? '').trim();
+}
+
+export function validateExplicitPristineRoute({ provider, model, effort, fast } = {}) {
+  const selectedProvider = clean(provider);
+  const selectedModel = clean(model);
+  if (!selectedProvider || !selectedModel) {
+    return 'headless role commands require both --provider <name> and --model <name>; host route fallback is disabled';
+  }
+  const selectedEffort = clean(effort).toLowerCase();
+  if (selectedEffort && !EFFORTS.has(selectedEffort)) {
+    return `invalid --effort ${JSON.stringify(clean(effort))}; expected low, medium, high, xhigh, or max`;
+  }
+  if (fast !== undefined && typeof fast !== 'boolean') {
+    return '--fast must be an explicit boolean flag';
+  }
+  return null;
+}
+
+export function buildMinimalPristineConfig({ provider, model, effort, fast } = {}) {
+  const routeError = validateExplicitPristineRoute({ provider, model, effort, fast });
+  if (routeError) throw new Error(routeError);
+  const selectedProvider = clean(provider);
+  const selectedModel = clean(model);
+  const selectedEffort = clean(effort).toLowerCase();
+  const route = {
+    provider: selectedProvider,
+    model: selectedModel,
+    ...(selectedEffort ? { effort: selectedEffort } : {}),
+    ...(fast === true ? { fast: true } : {}),
+  };
+  const providerConfig = {
+    enabled: true,
+    ...(selectedProvider === 'openai-oauth' ? { websocket: true } : {}),
+  };
+  const modelSettings = {};
+  if (selectedEffort || fast === true) {
+    modelSettings[`${selectedProvider}/${selectedModel}`] = {
+      ...(selectedEffort ? { effort: selectedEffort } : {}),
+      ...(fast === true ? { fast: true } : {}),
+    };
+  }
+  return {
+    agent: {
+      providers: { [selectedProvider]: providerConfig },
+      presets: [{
+        id: 'headless-explicit-route',
+        name: 'HEADLESS EXPLICIT ROUTE',
+        type: 'agent',
+        tools: 'full',
+        ...route,
+      }],
+      default: 'headless-explicit-route',
+      workflow: { active: 'default' },
+      workflowRoutes: {},
+      agents: {},
+      modelSettings,
+      mcpServers: {},
+    },
+  };
+}
+
+function cloneJson(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+
+export function createSelectedProviderPristineLoader({
+  config,
+  provider,
+  apiKey = null,
+} = {}) {
+  const selectedProvider = clean(provider);
+  const runtimeConfig = cloneJson(config?.agent || {});
+  const selectedConfig = {
+    ...(runtimeConfig.providers?.[selectedProvider] || {}),
+    enabled: true,
+    ...(apiKey ? { apiKey } : {}),
+  };
+  runtimeConfig.providers = { [selectedProvider]: selectedConfig };
+  return () => cloneJson(runtimeConfig);
+}
+
+function hostDataDir(env) {
+  if (clean(env.MIXDOG_DATA_DIR)) return resolve(env.MIXDOG_DATA_DIR);
+  const home = clean(env.MIXDOG_HOME)
+    ? resolve(env.MIXDOG_HOME)
+    : join(homedir(), '.mixdog');
+  return join(home, 'data');
+}
+
+function patchPlatformKey() {
+  const os = process.platform === 'win32' ? 'win32' : process.platform;
+  return `${os}-${process.arch}`;
+}
+
+export function seedVerifiedPatchBinaryCache(
+  sourceDataDir,
+  dataDir,
+  { manifestPath = patchManifestPath } = {},
+) {
+  try {
+    const sourcePatchDir = join(sourceDataDir, 'patch-bin');
+    const manifestBytes = readFileSync(manifestPath);
+    const manifest = JSON.parse(manifestBytes.toString('utf8'));
+    const asset = manifest?.assets?.[patchPlatformKey()];
+    const version = String(manifest?.version || '');
+    const expectedSha256 = clean(asset?.sha256).toLowerCase();
+    if (!/^[A-Za-z0-9._-]+$/.test(version) || !/^[a-f0-9]{64}$/.test(expectedSha256)) return false;
+
+    const binaryName = `mixdog-patch-${version}${process.platform === 'win32' ? '.exe' : ''}`;
+    const sourceBinary = join(sourcePatchDir, binaryName);
+    if (!existsSync(sourceBinary)) return false;
+    const binaryBytes = readFileSync(sourceBinary);
+    const actualSha256 = createHash('sha256').update(binaryBytes).digest('hex');
+    if (actualSha256 !== expectedSha256) return false;
+
+    const targetPatchDir = join(dataDir, 'patch-bin');
+    mkdirSync(targetPatchDir, { recursive: true, mode: 0o700 });
+    writeFileSync(join(targetPatchDir, binaryName), binaryBytes, { mode: 0o700 });
+    writeFileSync(join(targetPatchDir, 'manifest.json'), manifestBytes, { mode: 0o600 });
+    return true;
+  } catch {
+    // A missing, stale, or malformed host cache is optional acceleration only.
+    // Leave the pristine runtime empty so the normal fetch path handles it.
+    return false;
+  }
+}
+
+function auditDocument({
+  provider,
+  model,
+  effort,
+  fast,
+  configBytes,
+  authMode,
+  catalogCount,
+}) {
+  const contract = PRISTINE_EXECUTION_CONTRACT;
+  return {
+    schemaVersion: contract.schemaVersion,
+    mode: 'headless-role-pristine',
+    provider: clean(provider),
+    model: clean(model),
+    effort: clean(effort).toLowerCase() || null,
+    fast: fast === true,
+    configSha256: createHash('sha256').update(configBytes).digest('hex'),
+    authMode,
+    authArtifactFilesCopied: 0,
+    injectedModelCatalogFileCount: catalogCount,
+    personalState: {
+      hostConfigRead: false,
+      ...Object.fromEntries(contract.personalStateCounters.map((name) => [name, 0])),
+    },
+    featuresEnabled: Object.fromEntries(
+      contract.disabledFeatures.map((name) => [name, false]),
+    ),
+  };
+}
+
+export function formatPristineExecutionAudit(audit) {
+  return [
+    `pristine-execution-audit v${audit.schemaVersion}`,
+    'mode=headless-role',
+    'personal-files=0',
+    'host-config=0',
+    'mcp=0',
+    'skills=0',
+    'core-memory=0',
+    'channels=0',
+    'plugins=0',
+    'profiles=0',
+    'prior-sessions=0',
+    `provider=${audit.provider}`,
+    `model=${audit.model}`,
+    `effort=${audit.effort || 'provider-default'}`,
+    `fast=${String(audit.fast)}`,
+    `auth=${audit.authMode}`,
+    `catalogs=${audit.injectedModelCatalogFileCount}`,
+  ].join(' ');
+}
+
+export function createPristineExecutionBoundary({
+  provider,
+  model,
+  effort,
+  fast,
+  env = process.env,
+  approvedExecutionEnv = {},
+  apiKeyResolver = getAgentApiKey,
+} = {}) {
+  const routeError = validateExplicitPristineRoute({ provider, model, effort, fast });
+  if (routeError) throw new Error(routeError);
+
+  const contract = PRISTINE_EXECUTION_CONTRACT;
+  const hostEnv = { ...env };
+  const originalEnv = new Map();
+  const touchedKeys = new Set();
+  const setEnv = (name, value) => {
+    if (!touchedKeys.has(name)) {
+      originalEnv.set(name, Object.prototype.hasOwnProperty.call(env, name) ? env[name] : undefined);
+      touchedKeys.add(name);
+    }
+    env[name] = String(value);
+  };
+  const unsetEnv = (name) => {
+    if (!touchedKeys.has(name)) {
+      originalEnv.set(name, Object.prototype.hasOwnProperty.call(env, name) ? env[name] : undefined);
+      touchedKeys.add(name);
+    }
+    delete env[name];
+  };
+  const rootDir = mkdtempSync(join(tmpdir(), 'mixdog-headless-pristine-'));
+  const dataDir = join(rootDir, 'data');
+  mkdirSync(dataDir, { recursive: true, mode: 0o700 });
+  let cleaned = false;
+  let restoreAuthBindings = () => {};
+  const cleanup = () => {
+    if (cleaned) return;
+    cleaned = true;
+    for (const [name, value] of originalEnv) {
+      if (value === undefined) delete env[name];
+      else env[name] = value;
+    }
+    restoreAuthBindings();
+    rmSync(rootDir, { recursive: true, force: true });
+  };
+
+  try {
+    const sourceDataDir = hostDataDir(hostEnv);
+    seedVerifiedPatchBinaryCache(sourceDataDir, dataDir);
+    const approvedNames = new Set(contract.approvedExecutionEnv || []);
+    for (const name of Object.keys(approvedExecutionEnv || {})) {
+      if (!approvedNames.has(name)) {
+        throw new Error(`unapproved pristine execution environment override: ${name}`);
+      }
+    }
+    const inheritedExecutionEnv = Object.fromEntries(
+      [...approvedNames]
+        .filter((name) => hostEnv[name] !== undefined)
+        .map((name) => [name, hostEnv[name]]),
+    );
+    const selectedProvider = clean(provider);
+    const oauth = contract.oauthProviders[selectedProvider];
+    const apiKeyEnv = contract.apiKeyProviders[selectedProvider];
+    let selectedApiKey = null;
+    if (apiKeyEnv) {
+      // Resolve before scrubbing so the selected provider may use its standard,
+      // MIXDOG_AGENT_*, alias, or one provider-scoped keychain account. No
+      // general config loader or all-provider credential scan is involved.
+      selectedApiKey = clean(apiKeyResolver(selectedProvider));
+    }
+    // Fail closed: no inherited Mixdog behavior reaches the child runtime.
+    // Only contract-listed operational controls are reintroduced below.
+    for (const name of Object.keys(env)) {
+      if (name.startsWith('MIXDOG_')) unsetEnv(name);
+    }
+    for (const entry of Object.values(contract.oauthProviders)) {
+      unsetEnv(entry.credentialPathEnv);
+    }
+    for (const name of Object.values(contract.apiKeyProviders)) unsetEnv(name);
+    for (const aliases of Object.values(AGENT_PROVIDER_ENV_ALIASES)) {
+      for (const name of aliases) unsetEnv(name);
+    }
+    setEnv('MIXDOG_HOME', rootDir);
+    setEnv('MIXDOG_DATA_DIR', dataDir);
+    for (const [name, value] of Object.entries({
+      ...inheritedExecutionEnv,
+      ...approvedExecutionEnv,
+    })) {
+      setEnv(name, value);
+    }
+    for (const [name, value] of Object.entries(contract.guardEnv)) setEnv(name, value);
+
+    let authMode = 'provider-managed';
+    let catalogCount = 0;
+    if (oauth) {
+      const sourceCredential = clean(hostEnv[oauth.credentialPathEnv])
+        ? resolve(hostEnv[oauth.credentialPathEnv])
+        : join(sourceDataDir, oauth.credentialFile);
+      if (!existsSync(sourceCredential)) {
+        throw new Error(`required ${clean(provider)} credentials are unavailable; sign in before using the headless role command`);
+      }
+      // Authentication is the sole host-state exception. Bind in-process (not
+      // via child-visible environment) so tools cannot discover the auth path.
+      restoreAuthBindings = replaceProviderAuthBindings({
+        [selectedProvider]: sourceCredential,
+      });
+      authMode = 'in-process-host-oauth-binding';
+      const sourceCatalog = join(sourceDataDir, oauth.modelCatalogFile);
+      if (existsSync(sourceCatalog)) {
+        copyFileSync(sourceCatalog, join(dataDir, oauth.modelCatalogFile));
+        catalogCount = 1;
+      }
+    } else if (apiKeyEnv) {
+      if (!selectedApiKey) {
+        throw new Error(`required ${selectedProvider} authentication is unavailable; set ${apiKeyEnv}`);
+      }
+      authMode = 'in-process-api-key';
+    }
+
+    const config = buildMinimalPristineConfig({ provider, model, effort, fast });
+    const loadConfig = createSelectedProviderPristineLoader({
+      config,
+      provider,
+      apiKey: selectedApiKey,
+    });
+    const configBytes = `${JSON.stringify(config, null, 2)}\n`;
+    writeFileSync(join(dataDir, contract.configFileName), configBytes, { mode: 0o600 });
+    const audit = auditDocument({
+      provider,
+      model,
+      effort,
+      fast,
+      configBytes,
+      authMode,
+      catalogCount,
+    });
+    return { rootDir, dataDir, config, audit, loadConfig, cleanup };
+  } catch (error) {
+    cleanup();
+    throw error;
+  }
+}