mixdog 0.9.97 → 0.9.100

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mixdog",
-  "version": "0.9.97",
+  "version": "0.9.100",
   "private": false,
   "type": "module",
   "description": "Standalone mixdog coding-agent CLI/TUI workspace.",
@@ -88,13 +88,18 @@
     "test:embedding-runtime": "node --test scripts/embedding-runtime-prune-test.mjs scripts/memory-pg-recovery-test.mjs && node scripts/verify-embedding-runtime.mjs",
     "test:embedding-runtime:core": "node --test scripts/embedding-runtime-prune-test.mjs scripts/memory-pg-recovery-test.mjs && node scripts/verify-embedding-runtime.mjs --core",
     "test:embedding-runtime:warmup": "node scripts/verify-embedding-runtime.mjs --warmup",
+    "prepare:code-graph-test": "node scripts/prepare-code-graph-test.mjs",
     "test:code-graph-dispatch": "node --test scripts/code-graph-dispatch-test.mjs",
     "test:tui-queue": "node --test scripts/submit-commandbusy-race-test.mjs scripts/steering-drain-buckets-test.mjs scripts/abort-recovery-test.mjs scripts/message-rewind-test.mjs scripts/execution-pending-resume-kick-test.mjs scripts/execution-resume-esc-integration-test.mjs scripts/pending-stale-injection-test.mjs",
     "test:tui-input-render": "node --test scripts/prompt-immediate-render-test.mjs scripts/prompt-key-parity-test.mjs",
     "test:tui-streaming-window": "node --test scripts/streaming-tail-window-test.mjs scripts/tui-store-frame-batch-test.mjs && node scripts/tui-transcript-jitter-harness.mjs",
     "test:tui-ambiguous-width": "node --test scripts/tui-ambiguous-width-test.mjs",
     "test:release-assets": "node --check scripts/verify-release-assets.mjs && node --check scripts/verify-release-assets-test.mjs && node --check scripts/deploy-workflow-test.mjs && node --check scripts/release-version-discipline-test.mjs && node --test scripts/verify-release-assets-test.mjs scripts/deploy-workflow-test.mjs scripts/release-version-discipline-test.mjs",
-    "test:release-focused": "npm run test:release-assets && npm run test:tool-contracts && npm run test:tool-batching && npm run test:placeholder && npm run smoke:patch && npm run test:patch-binary-cache && npm run test:providers && npm run test:deferred-tools && npm run smoke:compact && npm run test:compact && npm run test:context && node --test scripts/code-graph-root-federation-test.mjs scripts/code-graph-aggregate-cwd-test.mjs && npm run test:code-graph-dispatch && node --test scripts/code-graph-disk-hit-test.mjs && npm run test:shellhardening && npm run test:project-registry && npm run test:session && npm run test:workflow-editor && npm run test:embedding-runtime && node --test scripts/tui-transcript-perf-test.mjs",
+    "test:release-focused": "npm run test:release-focused:contracts && npm run test:release-focused:providers && npm run test:release-focused:compact && npm run test:release-focused:session",
+    "test:release-focused:contracts": "npm run test:release-assets && npm run test:tool-contracts && npm run test:tool-batching && npm run test:placeholder && npm run smoke:patch && npm run test:patch-binary-cache",
+    "test:release-focused:providers": "npm run test:providers && npm run test:deferred-tools && npm run test:compact && npm run test:context && npm run prepare:code-graph-test && node --test scripts/code-graph-root-federation-test.mjs scripts/code-graph-aggregate-cwd-test.mjs && npm run test:code-graph-dispatch && node --test scripts/code-graph-disk-hit-test.mjs",
+    "test:release-focused:compact": "npm run smoke:compact && npm run test:shellhardening",
+    "test:release-focused:session": "npm run test:project-registry && npm run test:session && npm run test:workflow-editor && npm run test:embedding-runtime && node --test scripts/tui-transcript-perf-test.mjs",
     "test:native-edit-wire": "node --test scripts/native-edit-wire-test.mjs",
     "test:patch-binary-cache": "node --test scripts/patch-binary-cache-test.mjs",
     "test:patch-parity": "node --test scripts/v4a-parity-test.mjs",
@@ -155,9 +160,11 @@
     "pg": "^8.22.0",
     "puppeteer-core": "^25.2.0",
     "react": "^19.2.7",
+    "sharp": "^0.35.3",
     "string-width": "^8.2.1",
     "strip-ansi": "^7.2.0",
     "tiktoken": "^1.0.22",
+    "unpdf": "^1.8.0",
     "undici": "^8.5.0",
     "wrap-ansi": "^10.0.0",
     "ws": "^8.21.0",

package/scripts/dependency-lock-cache-key.mjs

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+
+import { createHash } from 'node:crypto'
+import { readFile } from 'node:fs/promises'
+import { resolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+import { normalizeRuntimeLockfile } from './runtime-dependency-cache-key.mjs'
+
+export const DEPENDENCY_LOCK_CACHE_SCHEMA = 1
+
+export function dependencyLockCacheKey(lockfile) {
+  const normalized = normalizeRuntimeLockfile(lockfile)
+  const fingerprint = createHash('sha256')
+    .update(JSON.stringify(normalized))
+    .digest('hex')
+  return `dependency-lock-v${DEPENDENCY_LOCK_CACHE_SCHEMA}-${fingerprint}`
+}
+
+const invokedPath = process.argv[1] ? pathToFileURL(resolve(process.argv[1])).href : ''
+if (invokedPath === import.meta.url) {
+  const lockfilePath = process.argv[2]
+  if (!lockfilePath) throw new Error('Usage: dependency-lock-cache-key.mjs <package-lock.json>')
+  readFile(resolve(lockfilePath))
+    .then((lockfile) => process.stdout.write(`${dependencyLockCacheKey(lockfile)}\n`))
+    .catch((error) => {
+      process.stderr.write(`Dependency lock cache key failed: ${error?.message || error}\n`)
+      process.exitCode = 1
+    })
+}

package/src/rules/agent/30-explorer.md

@@ -9,19 +9,19 @@ kind: retrieval
 Return only WHERE (`path:line`), never WHY. You ARE `explore`; never call it.
 Use only grep/find/glob/code_graph; `read` and `list` are forbidden.
 
-Turn 1 (`turn 1/3`) is the whole search and should already mint anchors. Split
-broad/uncertain input into every known facet and send one batch under the
-shared one-route contract. Route each facet to the cheapest anchor source:
-`code_graph` `symbol_search` whenever the facet names a plausible
-symbol/identifier; grep `content_with_context` with `pattern[]` of 4–8
-code-token variants for concept facets — its hits carry `path:line`, cite them
-directly instead of re-mining; `find` `query[]` ONLY when the target is itself
-a file/dir name or an unverified path fragment, never as a default extra
-facet. For a symptom/behavior query, add the upstream producer/derivation
-layer of the reported surface as extra facets in the SAME batch, never as a
-later turn. Follow-up turns batch every unresolved facet in parallel; a
-single-tool turn is allowed only when exactly one pre-anchor/zero-hit facet
-remains.
+Turn 1 (`turn 1/3`) is the whole search and should already mint anchors.
+Extract every concrete locator facet implied by the query, deduplicate
+overlap, and send the maximum independent fan-out in one batch under the
+shared one-route contract; never cap query or facet count. Route each facet to
+exactly one cheapest anchor source: `code_graph` `symbol_search` when it names
+a plausible symbol/identifier; grep `content_with_context` with `pattern[]` of
+4–8 code-token variants for a concept or quoted error; `find` `query[]` only
+when the target itself is a file/dir name or unverified path fragment. For a
+symptom/behavior query, include the reported surface and its immediate
+producer as sibling facets in the same batch when both are needed to locate
+the behavior. Never add generic repository metadata, tests, docs, or adjacent
+subsystems unless the query asks for them, and never send the same facet to
+multiple tools merely for confidence.
 
 Grep defaults to `output_mode:"content_with_context"` with `context:0`
 (matches only — the match line already carries its citable `path:line`) and a
@@ -35,33 +35,44 @@ queries to English identifiers.
 Scope is every `<roots><root>…</root></roots>` entry when supplied, otherwise
 session cwd. Search every supplied root in the turn-1 batch: grep/glob batch
 `path[]`, while find uses one sibling call per root. Never silently fall back to
-cwd or omit a supplied root. A find result is relative to its exact root; prefix
-that root when returning a path outside cwd. For unverified `src` paths, use
-`find` first; never guess or invent directories or pair `path:"."` with guessed
-`src/**`. Scoped grep/glob may use only a supplied root or an exact find-returned
-path. After zero hits, change tokens or scope, never wording or guessed paths.
+cwd or omit a supplied root. A tool-returned path is immutable evidence: copy
+it exactly and never join, prefix, normalize, repair, or reconstruct it from a
+root. A relative find result is a pre-anchor for code-location queries and may
+only scope a later grep; for file/dir-location queries it may be returned
+verbatim. For unverified `src` paths, use `find` first; never guess or invent
+directories or pair `path:"."` with guessed `src/**`. Scoped grep/glob may use
+only a supplied root or an exact find-returned path. After zero hits, change
+tokens or scope, never wording or guessed paths.
 
 An anchor is a `path:line` containing a query token or synonym, including a
 code_graph hit. Generic terms without query specificity are zero. Never
-re-locate, reconfirm, or upgrade an anchor. A path without `:line` is a
-pre-anchor and counts as zero. After every result, stop and answer on any
-specific-token anchor; mark a weak anchor `?`.
+re-locate, reconfirm, upgrade, or weaken an anchor. A path without `:line` is a
+pre-anchor and counts as zero for code locations. After every result, stop and
+answer as soon as the query's locator objective has specific-token anchors;
+never return a weak or merely plausible anchor.
 
-For a code-location query left only with pre-anchors, the sole anchor-minting
-follow-up is one scoped `content_with_context` grep with `head_limit` on those
-paths. If it returns zero, recovery may continue within budget with changed
-tokens or scope. Never make a second minting hop or fabricate/estimate a line.
+Turn 2 is allowed only when turn 1 has zero valid anchors for the locator
+objective. Batch every unresolved facet at once with changed concrete tokens
+or scope; never repeat the same tokens and scope. Exact pre-anchors may use
+one batched scoped `content_with_context` grep with `head_limit` to mint
+coordinates.
 
-Use at most 3 turns and label every tool message `turn N/3`; normally use one
-batch and one answer. Turns 2–3 are allowed only when turn 1 has zero anchors.
-The first matching entry/definition anchors a concept, value, or default; never
-trace its chain. Only an explicit flow or default-resolution query with an
-entry anchor but no resolved value may use turn 2 for one resolving hop.
+Turn 3 is allowed only when turn 2 produced new exact pre-anchors, or an
+explicit flow/default-resolution query has entry anchors but still needs one
+dependent hop. Batch every final scoped grep or resolving hop at once. Never
+start a broad search, add a facet, or merely reword the query on turn 3; if
+these conditions are absent, return `EXPLORATION_FAILED` after turn 2.
+
+Use at most 3 tool turns and label every tool message `turn N/3`; normally use
+one batch and one answer. An allowed turn is not a target: fail as soon as the
+next turn lacks a concrete evidence-producing move. The first matching
+entry/definition anchors a concept, value, or default; never trace its chain
+unless the query explicitly asks for flow/default resolution.
 
 Answer in at most 3 lines, most specific first:
 `path:line — symbol — short reason`. Copy every cited `path:line` verbatim from
 a tool result in this session; never estimate, adjust, or recall it. Every
 code-location line requires `:line`; never return a bare filename or vague
 prose. A file/dir-location query may return an exact verified path without
-`:line`. Return `EXPLORATION_FAILED` only after spending the budget with zero
-anchors; first prefer a weak anchor to a false miss.
+`:line`. Return `EXPLORATION_FAILED` when the bounded recovery rules above
+cannot produce a verified anchor; never fabricate, estimate, or soften one.

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

@@ -1,5 +1,5 @@
-import { createHash } from 'crypto';
 import { isInclusiveProvider } from '../../shared/llm/cost.mjs';
+import { estimateJsonBytes, hashStructuredValue } from '../../shared/json-metrics.mjs';
 import {
     appendAgentTrace,
     drainAgentTrace,
@@ -17,7 +17,23 @@ import {
 
 function estimateProviderPayloadBytes(messages, model, tools) {
     try {
-        return Buffer.byteLength(JSON.stringify({ model, messages, tools: tools || [] }), 'utf8');
+        let referencedBytes = 0;
+        const seen = new Set();
+        const walk = (value) => {
+            if (!value || typeof value !== 'object' || seen.has(value)) return;
+            seen.add(value);
+            if (typeof value.attachmentRef === 'string') {
+                const bytes = Number(value.sizeBytes) || 0;
+                referencedBytes += value.type === 'image' || value.type === 'file'
+                    ? Math.ceil(bytes / 3) * 4
+                    : bytes;
+                return;
+            }
+            if (Array.isArray(value)) value.forEach(walk);
+            else Object.values(value).forEach(walk);
+        };
+        walk(messages);
+        return estimateJsonBytes({ model, messages, tools: tools || [] }) + referencedBytes;
     }
     catch {
         return null;
@@ -60,9 +76,7 @@ function extractCacheWriteTokens(usage) {
 // hashing megabytes per turn. Truncated SHA1 keeps the trace row compact.
 function messagePrefixHash(messages) {
     try {
-        const json = JSON.stringify(messages || []);
-        const slice = json.length > 4096 ? json.slice(0, 4096) : json;
-        return createHash('sha1').update(slice).digest('hex').slice(0, 12);
+        return hashStructuredValue(messages || [], { maxStringChars: 4096 }).slice(0, 12);
     } catch {
         return null;
     }

package/src/runtime/agent/orchestrator/providers/grok-oauth.mjs

@@ -112,6 +112,13 @@ function _sanitizeGrokModels(models) {
         const display = _displayGrokModel(m);
         const family = _normalizeGrokFamily(m?.id);
         const reasoningLevels = _grokModelSupportsEffort(m?.id) ? ['none', 'low', 'medium', 'high'] : [];
+        // api.x.ai /models does not expose a max-output field. Historical
+        // enrichment could persist contextWindow as outputTokens (for example
+        // 500k/500k); clear it rather than advertise an invented request cap.
+        if (out?.outputTokens != null) {
+            changed = true;
+            out = { ...out, outputTokens: null };
+        }
         if (display && display !== out?.display) {
             changed = true;
             out = { ...out, display, name: out?.name || out?.id };

package/src/runtime/agent/orchestrator/providers/media-normalization.mjs

@@ -1,4 +1,9 @@
 import { createHash } from 'node:crypto';
+import {
+    attachmentTextForPart,
+    isAttachmentReference,
+    readAttachmentBase64,
+} from '../../../attachments/store.mjs';
 
 const DEFAULT_IMAGE_MIME = 'image/png';
 
@@ -9,6 +14,9 @@ function cleanMimeType(value) {
 
 function imageInfo(block) {
     if (!block || typeof block !== 'object' || block.type !== 'image') return null;
+    if (isAttachmentReference(block)) {
+        return { data: readAttachmentBase64(block), mimeType: cleanMimeType(block.mimeType || block.mediaType) };
+    }
     if (typeof block.data === 'string' && block.data) {
         return { data: block.data, mimeType: cleanMimeType(block.mimeType || block.mediaType) };
     }
@@ -32,10 +40,13 @@ function geminiInlineInfo(block) {
 // as their native document shape; estimators must never serialize its base64.
 function fileInfo(block) {
     if (!block || typeof block !== 'object' || block.type !== 'file') return null;
-    if (typeof block.data !== 'string' || !block.data) return null;
+    const data = isAttachmentReference(block)
+        ? readAttachmentBase64(block)
+        : (typeof block.data === 'string' ? block.data : '');
+    if (!data) return null;
     const mimeType = String(block.mimeType || block.mediaType || 'application/pdf').trim().toLowerCase() || 'application/pdf';
     const filename = typeof block.filename === 'string' && block.filename ? block.filename : '';
-    return { data: block.data, mimeType, filename };
+    return { data, mimeType, filename };
 }
 
 function imageUrlFromPart(block) {
@@ -95,6 +106,7 @@ function imageMimeFromDataUrl(url) {
 function textFromPart(block) {
     if (typeof block === 'string') return block;
     if (!block || typeof block !== 'object') return '';
+    if (block.type === 'text' && isAttachmentReference(block)) return attachmentTextForPart(block);
     if (typeof block.text === 'string') return block.text;
     if (typeof block.content === 'string') return block.content;
     return '';
@@ -112,7 +124,7 @@ function contentParts(content) {
     if (content && typeof content === 'object'
         && (imageUrlFromPart(content) || imageFileIdFromPart(content)
             || imageFileUriFromPart(content) || geminiInlineInfo(content)
-            || fileInfo(content))) return [content];
+            || fileInfo(content) || isAttachmentReference(content))) return [content];
     return null;
 }
 
@@ -149,6 +161,14 @@ function imageIdentity(kind, value, mimeType = '') {
 
 function imageDescriptor(part) {
     if (!part || typeof part !== 'object') return null;
+    if (part.type === 'image' && isAttachmentReference(part)) {
+        return {
+            identity: imageIdentity('attachment-ref', part.attachmentRef, part.mimeType || part.mediaType),
+            width: positiveDimension(part.width, part.dimensions?.width),
+            height: positiveDimension(part.height, part.dimensions?.height),
+            detail: String(part.detail || 'auto').toLowerCase(),
+        };
+    }
     const info = imageInfo(part);
     const inline = geminiInlineInfo(part);
     const url = imageUrlFromPart(part);
@@ -187,6 +207,9 @@ export function contentFileDescriptors(content) {
     const parts = contentParts(content);
     if (!parts) return [];
     return parts.flatMap((part) => {
+        if (part?.type === 'file' && isAttachmentReference(part)) {
+            return [{ mimeType: String(part.mimeType || part.mediaType || 'application/pdf'), sizeBytes: Number(part.sizeBytes) || 0 }];
+        }
         const file = fileInfo(part);
         if (!file) return [];
         return [{ mimeType: file.mimeType, sizeBytes: Math.floor((file.data.length * 3) / 4) }];
@@ -215,6 +238,7 @@ function storedHistoryImagePlaceholder(part) {
 function sanitizePartForStoredHistory(part) {
     if (typeof part === 'string') return part;
     if (!part || typeof part !== 'object') return part;
+    if (isAttachmentReference(part)) return part;
     if (part.type === 'image' || part.type === 'image_url' || part.type === 'input_image' || imageUrlFromPart(part) || imageFileIdFromPart(part) || imageFileUriFromPart(part) || geminiInlineInfo(part)) {
         return { type: 'text', text: storedHistoryImagePlaceholder(part) };
     }
@@ -307,6 +331,9 @@ export function normalizeContentForAnthropic(content) {
         if (part?.type === 'input_text' || part?.type === 'output_text') {
             return { type: 'text', text: part.text || '' };
         }
+        if (part?.type === 'text' && isAttachmentReference(part)) {
+            return { type: 'text', text: attachmentTextForPart(part) };
+        }
         return part;
     });
 }

package/src/runtime/agent/orchestrator/providers/model-catalog.mjs

@@ -360,7 +360,7 @@ function _modelsDevMetadataSync(id, provider) {
     if (!pid) return null;
     if (!_mdCache) {
         warmModelsDevFromDiskSync();
-        if (!_mdCache) { void loadModelsDevCatalog(); return null; }
+        if (!_mdCache) return null;
     }
     const row = _mdCache?.[pid]?.models?.[id];
     if (!row || !row.cost) return null;
@@ -372,10 +372,12 @@ function _modelsDevMetadataSync(id, provider) {
 // require a `cost` field (staleness only needs family/release_date) and
 // returns the raw row untouched. Warms from disk one-shot if memory is cold;
 // returns null when the catalog is unavailable so callers can skip filtering.
+// Sync reads never start network work: session warmup owns remote catalog I/O,
+// and injected/provider-local transports must remain request-hermetic.
 // `_test` (tests only) injects a fake catalog map without touching disk.
 export function getModelsDevRowSync(id, provider, _test) {
     const cat = _test || _mdCache || (warmModelsDevFromDiskSync(), _mdCache);
-    if (!cat) { void loadModelsDevCatalog(); return null; }
+    if (!cat) return null;
     const pid = _modelsDevProviderId(provider);
     if (!pid) return null;
     const row = cat?.[pid]?.models?.[id];
@@ -387,7 +389,7 @@ export function getModelsDevRowSync(id, provider, _test) {
 // provider's whole catalog. Returns null when the catalog is cold/unavailable.
 export function getModelsDevProviderModelsSync(provider, _test) {
     const cat = _test || _mdCache || (warmModelsDevFromDiskSync(), _mdCache);
-    if (!cat) { void loadModelsDevCatalog(); return null; }
+    if (!cat) return null;
     const pid = _modelsDevProviderId(provider);
     if (!pid) return null;
     const models = cat?.[pid]?.models;

package/src/runtime/agent/orchestrator/providers/provider-catalog-cache.mjs

@@ -31,6 +31,22 @@ function readModelsFromCacheFile(fileName) {
   }
 }
 
+export function providerCachedModelsSync(provider) {
+  const p = String(provider || '').toLowerCase();
+  const files = PROVIDER_CACHE_FILES[p] || [];
+  const rows = [];
+  const seen = new Set();
+  for (const fileName of files) {
+    for (const row of readModelsFromCacheFile(fileName)) {
+      const id = rowId(row);
+      if (!id || seen.has(id)) continue;
+      seen.add(id);
+      rows.push({ ...row, id });
+    }
+  }
+  return rows;
+}
+
 function modelAliases(id) {
   const text = String(id || '').trim();
   if (!text) return [];
@@ -60,11 +76,17 @@ function getProviderCachedModelSync(provider, model) {
 }
 
 export function providerCachedModelMetadataSync(provider, model) {
+  const p = String(provider || '').toLowerCase();
   const row = getProviderCachedModelSync(provider, model);
   if (!row) return null;
   return {
     contextWindow: num(row.contextWindow ?? row.context_window ?? row.maxContextWindow ?? row.max_context_window ?? row.max_input_tokens),
-    outputTokens: num(row.outputTokens ?? row.maxOutputTokens ?? row.max_output_tokens ?? row.output_token_limit),
+    // Grok's /models response currently publishes a context window but no
+    // output ceiling. Older enriched cache rows copied contextWindow into
+    // outputTokens; never feed that derived value back as provider-native.
+    outputTokens: p === 'grok-oauth'
+      ? null
+      : num(row.outputTokens ?? row.maxOutputTokens ?? row.max_output_tokens ?? row.output_token_limit),
     supportsVision: row.supportsVision === true,
     supportsFunctionCalling: row.supportsFunctionCalling === true,
     supportsWebSearch: row.supportsWebSearch === true,

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

@@ -9,6 +9,7 @@ import { readStreamOutcome } from '../../providers/lib/stream-outcome.mjs';
 import { normalizeCompactType, DEFAULT_COMPACT_TYPE } from '../compact.mjs';
 import { loadSession, saveSession, saveSessionAsync, saveSessionAsyncDeferred, readSessionLifecycleFromDisk } from '../store.mjs';
 import { createAbortController } from '../../../../shared/abort-controller.mjs';
+import { estimateJsonBytes } from '../../../../shared/json-metrics.mjs';
 import { logLlmCall } from '../../../../shared/llm/usage-log.mjs';
 import { appendAgentTrace } from '../../agent-trace.mjs';
 import { recordStandaloneStatusTelemetry } from './status-telemetry.mjs';
@@ -568,7 +569,7 @@ export async function askSession(sessionId, prompt, context, onToolCall, cwdOver
                 const _prefetchBytes = Buffer.byteLength(explicitPrefetchResult || '', 'utf8');
                 const _promptBytes = promptContentBytes(prompt);
                 const _userTurnBytes = promptContentBytes(_userTurnContent);
-                const _messagesBytes = Buffer.byteLength(JSON.stringify(historyMessages || []), 'utf8');
+                const _messagesBytes = estimateJsonBytes(historyMessages || []);
                 const _totalBytes = _userTurnBytes + _messagesBytes;
                 appendAgentTrace({
                     kind: 'context',

package/src/runtime/agent/orchestrator/session/manager/pending-messages.mjs

@@ -355,6 +355,9 @@ function normalizePendingMessageEntry(entry) {
         id: pendingMessageId(entry),
         enqueuedAt: Number(entry.enqueuedAt) || Date.now(),
     };
+    const entryOptions = entry.options && typeof entry.options === 'object'
+        ? { options: entry.options }
+        : {};
     const marker = entry.notificationKind === COMPLETION_NOTIFICATION_KIND
         ? { notificationKind: COMPLETION_NOTIFICATION_KIND, enqueuedAt: Number(entry.enqueuedAt) || Date.now() }
         : null;
@@ -366,13 +369,13 @@ function normalizePendingMessageEntry(entry) {
     if (content == null) return null;
     const text = typeof entry.text === 'string' ? entry.text.trim() : promptContentText(content).trim();
     let out = null;
-    if (Array.isArray(content)) out = content.length > 0 ? { content, text } : null;
+    if (Array.isArray(content)) out = content.length > 0 ? { content, text, ...entryOptions } : null;
     else if (typeof content === 'string') {
         const value = content.trim();
-        out = value ? { content: value, text: text || value } : null;
+        out = value ? { content: value, text: text || value, ...entryOptions } : null;
     } else {
         const fallback = promptContentText(content).trim();
-        out = fallback ? { content: fallback, text: text || fallback } : null;
+        out = fallback ? { content: fallback, text: text || fallback, ...entryOptions } : null;
     }
     if (!out) return null;
     // The lifecycle token rides along every derived copy (see carryLifecycleToken).
@@ -394,7 +397,12 @@ function pendingMessageQueueEntry(entry) {
     const marker = isCompletionNotificationEntry(normalized)
         ? { notificationKind: COMPLETION_NOTIFICATION_KIND, enqueuedAt: normalized.enqueuedAt }
         : null;
-    const base = { ...identity, content: normalized.content, text: normalized.text || promptContentText(normalized.content).trim() };
+    const base = {
+        ...identity,
+        content: normalized.content,
+        text: normalized.text || promptContentText(normalized.content).trim(),
+        ...(normalized.options ? { options: normalized.options } : {}),
+    };
     return carryLifecycleToken(marker ? { ...base, ...marker } : base, entry);
 }
 
@@ -427,6 +435,20 @@ function normalizePersistedEntry(entry, options = {}) {
         const message = entry.message.trim();
         return message ? { id, message, enqueuedAt } : null;
     }
+    if (Object.prototype.hasOwnProperty.call(entry, 'content')) {
+        const normalized = normalizePendingMessageEntry(entry);
+        if (!normalized) return null;
+        if (typeof normalized.content === 'string' && !normalized.options) {
+            return { id, message: normalized.text || normalized.content, enqueuedAt };
+        }
+        return {
+            id,
+            content: normalized.content,
+            text: normalized.text,
+            ...(normalized.options ? { options: normalized.options } : {}),
+            enqueuedAt,
+        };
+    }
     const t = pendingMessageText(entry);
     return t ? { id, message: t, enqueuedAt } : null;
 }
@@ -1195,10 +1217,26 @@ async function _flushForeignDrainBatch() {
                         && !isCompletionNotificationEntry(entry)
                         && !isLegacyUnmarkedCompletionNotification(text)
                         && text && !isInternalRuntimeNotificationText(text);
+                    const normalized = normalizePendingMessageEntry(entry);
+                    const structured = Array.isArray(normalized?.content) || Boolean(normalized?.options);
                     if (foreignUser && isStaleUserInjection(entry)) {
-                        taken.push({ text: lateDeliveryText(text, entry), id });
+                        const lateText = lateDeliveryText(text, entry);
+                        const content = Array.isArray(normalized?.content)
+                            ? [{ type: 'text', text: `${lateText.slice(0, lateText.length - text.length)}` }, ...normalized.content]
+                            : lateText;
+                        taken.push({
+                            ...(structured ? { content } : {}),
+                            text: lateText,
+                            id,
+                            ...(normalized?.options ? { options: normalized.options } : {}),
+                        });
                     } else if (foreignUser) {
-                        taken.push({ text, id });
+                        taken.push({
+                            ...(structured ? { content: normalized?.content ?? text } : {}),
+                            text,
+                            id,
+                            ...(normalized?.options ? { options: normalized.options } : {}),
+                        });
                     } else {
                         kept.push(entry);
                     }

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

@@ -4,13 +4,14 @@ import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { isInternalRuntimeNotificationText as contractIsInternalRuntimeNotificationText } from '../../../../shared/tool-execution-contract.mjs';
 import { SUMMARY_PREFIX } from '../compact.mjs';
+import { attachmentTextForPart, isAttachmentReference } from '../../../../attachments/store.mjs';
 
 export function promptContentText(content) {
     if (typeof content === 'string') return content;
     if (Array.isArray(content)) {
         return content.map((part) => {
             if (typeof part === 'string') return part;
-            if (part?.type === 'text') return part.text || '';
+            if (part?.type === 'text') return isAttachmentReference(part) ? attachmentTextForPart(part) : (part.text || '');
             if (part?.type === 'image') return '[Image]';
             return part?.text || '';
         }).filter(Boolean).join('\n');

package/src/runtime/agent/orchestrator/session/store/serialize.mjs

@@ -4,12 +4,9 @@ import { renameWithRetrySync } from '../../../../shared/atomic-file.mjs';
 import { sanitizeContentForStoredHistory } from '../../providers/media-normalization.mjs';
 import { readTopLevelLifecycleRecord, isLifecycleUnreadable } from '../lifecycle-scan.mjs';
 
-// The live in-memory session (and every model request)
-// retains attached image bytes across turns so multi-turn recognition works.
-// The persisted session JSON, however, replaces image content with a short
-// text placeholder at serialization time — keeping session files small without
-// starving the model of the image mid-conversation. Returns the same object
-// reference when nothing changed (no-image sessions pay only a shallow scan).
+// Inline legacy media is replaced with placeholders on disk. New prompt media
+// already arrives as durable content-addressed refs, so session JSON stays small
+// while provider lowering can still resolve it across turns.
 // Per-message disk projection shared by _sessionForDisk and the save-worker
 // delta path (tail-only projection). Returns the SAME array reference when no
 // message changed. Idempotent: already-sanitized content passes through