fix(vision): bounded wait for in-flight VDS description on first message (#970 stage 1)

[joelteply]

Summary

• Text-only personas no longer hallucinate "absence of images" on the first message after a fresh start. PersonaResponseGenerator now waits up to 8s for an in-flight VDS description, instead of skipping the wait entirely when the cache is cold.
• VDS already deduplicates in-flight requests, so the wait piggybacks on the pre-warm started at chat-send time — no extra inference cost on the happy path.
• Stage 1 of vision: [Attached image: <desc>] marker missing on user-role msg for text-only personas #970 (TS-side). Stage 2 (Rust-side marker for the description=None case) still tracked in vision: [Attached image: <desc>] marker missing on user-role msg for text-only personas #970.

Background — empirical hit (Anvil, PR #950 / 2026-04-25)

CodeReview AI #e50f39 HALLUCINATED "absence of images or attachments" when image IS attached. VDS [Attached image: ] marker missing on user-role msg (your separate bug). non-vision personas can't see + no fail-loud marker either.

Root cause (TS-side)

PersonaResponseGenerator.ts:380-391 only attached the VDS description when descriptionStatus(base64) === 'cached'. On the first message with a fresh image, pre-warm started at chat-send time is still 'inflight' when the persona reaches this code — so description stays undefined, the Rust IPC signal carries { ..., description: undefined }, and the text-only persona's user-role message has no image marker.

Fix

Wait when status is 'cached' OR 'inflight':

if (m.type === 'image') {
  try {
    const visionSvc = VisionDescriptionService.getInstance();
    const status = visionSvc.descriptionStatus(base64);
    if (status === 'cached' || status === 'inflight') {
      const VDS_WAIT_MS = 8000;
      const desc = await Promise.race([
        visionSvc.describeBase64(base64, m.mimeType ?? 'image/png', { maxLength: 200 }),
        new Promise<null>((resolve) => setTimeout(() => resolve(null), VDS_WAIT_MS)),
      ]);
      description = desc?.description;
    }
  } catch { /* ... */ }
}

8s ceiling protects against a stuck pre-warm. LLaVA on CPU at 60-70s would still time out and leave description undefined — that's where Stage 2 (Rust marker injection) takes over.

Test plan

• npm run build:ts — clean.
• Empirical: send an image to a text-only persona on the first message after a fresh start. Persona MUST receive a valid description in its user-role context.
• Cache-hit path unchanged: subsequent messages with the same image still take ~0ms (VDS cache returns immediately).

Refs

• vision: [Attached image: <desc>] marker missing on user-role msg for text-only personas #970 (parent issue, both stages)
• Stage 2 (Rust marker injection when description=None) is the next chunk.

[Copilot]

Pull request overview

Adjusts PersonaResponseGenerator to avoid dropping image descriptions on the first message after a fresh start by waiting (bounded) for an in-flight VisionDescriptionService (VDS) description instead of only accepting already-cached results.

Changes:

• Wait up to 8s for VDS when image description status is 'inflight' (in addition to 'cached').
• Use a Promise.race timeout to bound the wait and keep description fetch best-effort.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The comment mentions status error, but VisionDescriptionService.descriptionStatus() currently only returns 'cached' | 'inflight' | 'none' (no error state). Please update the comment to match the actual status values so future readers don’t assume there’s an error state to handle here.

Suggested change

	// Status `none` / `error` → don't trigger a blocking describe
	// here; the chat-send path is responsible for prewarming. Stage
	// 2 (Rust-side) is responsible for emitting an [Attached image:
	// Status `none` → don't trigger a blocking describe here; the
	// chat-send path is responsible for prewarming. Stage 2
	// (Rust-side) is responsible for emitting an [Attached image:

[Copilot]

Promise.race([... setTimeout(...)]) creates a timer that is never cleared/unref’d; even when the description resolves immediately (especially for status === 'cached'), the pending 8s timer still keeps the event loop alive and can accumulate under load. Consider: (1) only using the timeout path for 'inflight' (skip creating a timer for 'cached'), and (2) clearing the timeout (or using unref() where available) once the describe promise resolves first.

Suggested change

	if (status === 'cached' || status === 'inflight') {
	const VDS_WAIT_MS = 8000;
	const desc = await Promise.race([
	visionSvc.describeBase64(base64, m.mimeType ?? 'image/png', { maxLength: 200 }),
	new Promise<null>((resolve) => setTimeout(() => resolve(null), VDS_WAIT_MS)),
	]);
	description = desc?.description;
	if (status === 'cached') {
	const desc = await visionSvc.describeBase64(base64, m.mimeType ?? 'image/png', { maxLength: 200 });
	description = desc?.description;
	} else if (status === 'inflight') {
	const VDS_WAIT_MS = 8000;
	let timeoutHandle: ReturnType<typeof setTimeout> | undefined;
	try {
	const timeoutPromise = new Promise<null>((resolve) => {
	timeoutHandle = setTimeout(() => resolve(null), VDS_WAIT_MS);
	if (typeof timeoutHandle.unref === 'function') {
	timeoutHandle.unref();
	}
	});
	const desc = await Promise.race([
	visionSvc.describeBase64(base64, m.mimeType ?? 'image/png', { maxLength: 200 }),
	timeoutPromise,
	]);
	description = desc?.description;
	} finally {
	if (timeoutHandle) {
	clearTimeout(timeoutHandle);
	}
	}

[Copilot]

Gating on descriptionStatus(base64) risks missing fast cache hits: descriptionStatus() only reflects the TS L1 + in-flight map, and does not consult Rust L1.5 or the on-disk sidecar cache that describeBase64() can return from quickly. This means a TS-cold start (or a race where prewarm hasn’t registered inflight yet) can still produce status === 'none' even when describeBase64() would return immediately without inference. Consider adding a cached-only accessor that checks Rust/sidecar (no inference), or broadening this path to attempt a bounded describeBase64() when status is none but a cache hit is likely.