@ngockhoale/ukit 2.3.12 → 2.3.14

package/CHANGELOG.md

@@ -2,6 +2,66 @@
 
 All notable changes to UKit are documented here.
 
+## 2.3.14 - 2026-09-11
+
+Vision-lane root cause, part 3 — the decisive one: the extractor could not see images in REAL
+Claude Code transcripts at all. Found by reproducing the failure against the user's own real
+session transcripts after they insisted the bug lived "right at the image" — grep proved the
+transcripts contained `"type":"image"` while every extraction returned `imageCount: 0`. The
+2.3.12/2.3.13 suites were green because the fixtures modeled an invented transcript shape.
+
+**P1 — real transcript image envelopes were invisible to the extractor.** Verified against
+real transcripts from four projects, Claude Code stores images in THREE shapes:
+
+- flat: `message.content[i] = { type: 'image', source: { type: 'base64', … } }` — the only
+  shape the pre-fix parser handled;
+- pasted: a top-level `attachment` envelope (`type: 'attachment'`,
+  `attachment.prompt[]` = content blocks) — every real pasted image lives here, NOT in
+  `message.content`; the pre-fix parser extracted nothing from any pasted image;
+- tool-returned: `message.content[i] = { type: 'tool_result', content: [ { type: 'image',
+  … } ] }` — screenshots coming back from tools nest one level down; also invisible.
+
+Fix: `extractImageBlocks()` now walks a bounded collector (depth ≤ 3) across
+`message.content[]`, nested `content[]` arrays inside blocks, and the top-level
+`attachment.prompt[]` / `attachment.content` envelopes. Same-base64 payloads across
+envelopes dedupe by sha as before. Real-data validation after the fix: the same four
+transcripts now extract valid images (PNG 2278×2154 from the paste envelope, JPEG 1400×884
+from a tool_result, PNG/JPEG from the flat shape), and a live analyst dispatch read the
+real pasted screenshot.
+
+Tests: `tests/handoff/cycle10/extract-image-contract.test.mjs` gains three cases whose
+fixtures copy the real envelope structures verbatim (RED pre-fix: `imageCount 0`), plus a
+cross-envelope dedupe pin. All cycle10 + cycle4 vision suites green.
+
+## 2.3.13 - 2026-09-11
+
+Vision-lane root cause, part 2: the Codex model catalog could still deny the vision lane on
+every gateway machine, even after the 2.3.12 plumbing sweep. Found by a fresh end-to-end
+repro (install into a clean project → fire the hook → live dispatch) plus a live gateway
+probe on 2026-09-11 that returned `STATUS: OK / MODEL: unic-vision` on a machine whose
+`~/.codex/model-catalog.json` omits the alias.
+
+**P1 — the Codex model catalog could deny the Claude Code vision lane from another tool's
+config.** `unic-gateway.mjs` derived `aliasAvailable` solely from
+`~/.codex/model-catalog.json`: a catalog that omitted `unic-vision` — or was missing
+entirely, the default on any machine that never used Codex CLI — produced
+`aliasAvailable: false`, and both consumers (the vision router hint and route-task's
+`resolveVisionModel`) then force-downgraded the lane to "read natively / do NOT dispatch"
+or a config fallback. The catalog is a different tool's config and says nothing about what
+the gateway resolves server-side for this session — the same principle TASK-007 already
+established for endpoints. Fix: the catalog may now only CONFIRM the alias (new
+`catalogListed` field); silence (absent, malformed, or alias-omitting catalog) leaves the
+lane honored, with an informational advisory instead of a denial. The analyst agent's own
+`WRONG_MODEL` self-check remains the in-band safety net: a genuinely dead alias fails
+loudly and never guesses. `aliasAvailable: false` is reserved for a future source of
+positive unavailability evidence, so the dormant fallback branches in both consumers are
+unchanged and still covered by tests.
+
+Tests: `tests/handoff/cycle4/unic-gateway.test.mjs` and
+`tests/handoff/cycle10/vision-lane-fallback.test.mjs` rewritten for the flip (catalog
+silent → lane honored; catalog missing → lane honored; listing → positive confirmation),
+with the strict `=== false` fallback contract kept as a source-level case.
+
 ## 2.3.12 - 2026-09-11
 
 Vision-lane freeze-sweep (post-2.3.11): the four defects that stranded the vision image lane on

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "2.3.12",
+  "version": "2.3.14",
   "description": "Install/update an index-first AI workspace for Claude Code, OpenAI Codex, OpenCode, and omp (Oh My Pi).",
   "license": "MIT",
   "type": "module",

package/templates/.claude/ukit/index/extract-image.mjs

@@ -381,25 +381,64 @@ function readLines(filePath) {
   return raw.split('\n').filter((line) => line.trim().length > 0);
 }
 
+/**
+ * Deepest content-blocks nesting the collector walks. 1 covers the flat
+ * message.content[] / attachment.prompt[] arrays; 2 covers the real-world
+ * tool_result nesting (message.content[i].content[]); 3 is a cheap safety
+ * bound — deeper structures are not a Claude Code shape and are ignored.
+ */
+const MAX_BLOCK_WALK_DEPTH = 3;
+
+/**
+ * Collects base64 image blocks from one content-blocks array. Real Claude
+ * Code transcripts nest images in more than one place (verified against real
+ * session transcripts 2026-09-11 — the pre-fix parser only saw the flat
+ * shape and extracted NOTHING from real paste/tool-image traffic):
+ *   A. message.content[i] = { type: 'image', source: { type: 'base64', … } }
+ *   C. message.content[i] = { type: 'tool_result', content: [ { type: 'image', … } ] }
+ * Blocks that carry their own `content` array (tool_result etc.) are walked
+ * one level deeper, bounded by MAX_BLOCK_WALK_DEPTH.
+ */
+function collectImageBlocksFromContent(content, lineIndex, blocks, depth) {
+  if (!Array.isArray(content) || depth > MAX_BLOCK_WALK_DEPTH) return;
+  for (const block of content) {
+    if (!block || typeof block !== 'object') continue;
+    if (block.type === 'image') {
+      const source = block.source;
+      if (!source || source.type !== 'base64') continue;
+      const mediaType = source.media_type;
+      const data = source.data;
+      if (typeof mediaType !== 'string' || typeof data !== 'string' || !data) continue;
+      blocks.push({ mediaType, data, lineIndex });
+    } else if (Array.isArray(block.content)) {
+      collectImageBlocksFromContent(block.content, lineIndex, blocks, depth + 1);
+    }
+  }
+}
+
 /**
  * Parses each JSONL line independently. A malformed line is skipped via its
  * own try/catch and never throws out to the caller.
+ *
+ * Envelope shapes collected per line (real-transcript evidence 2026-09-11):
+ *   A/C. the API message envelope — flat image blocks, plus tool_result
+ *        blocks that nest theirs one level down (see the collector above).
+ *   B.   pasted images arrive in a TOP-LEVEL attachment envelope, NOT in
+ *        message.content: attachment.prompt[] is the content-blocks array
+ *        (attachment.content accepted defensively for the same reason).
+ * The same payload appearing in two envelopes (attachment + the later user
+ * message) dedupes by sha in selectImages().
  */
 function extractImageBlocks(lines) {
   const blocks = [];
   for (let i = 0; i < lines.length; i += 1) {
     try {
       const obj = JSON.parse(lines[i]);
-      const content = obj?.message?.content;
-      if (!Array.isArray(content)) continue;
-      for (const block of content) {
-        if (block?.type !== 'image') continue;
-        const source = block.source;
-        if (!source || source.type !== 'base64') continue;
-        const mediaType = source.media_type;
-        const data = source.data;
-        if (typeof mediaType !== 'string' || typeof data !== 'string' || !data) continue;
-        blocks.push({ mediaType, data, lineIndex: i });
+      collectImageBlocksFromContent(obj?.message?.content, i, blocks, 1);
+      const attachment = obj?.attachment;
+      if (attachment && typeof attachment === 'object') {
+        collectImageBlocksFromContent(attachment.prompt, i, blocks, 1);
+        collectImageBlocksFromContent(attachment.content, i, blocks, 1);
       }
     } catch {
       // malformed line: skip and continue

package/templates/.claude/ukit/index/route-task.mjs

@@ -99,8 +99,11 @@ function detectPastedImageViaExtractor({ rootDir = process.cwd() } = {}) {
  * Policy (mirrors the hook side in TASK-007 / ws-g.sh):
  *   - unicMode true AND aliasAvailable true  -> unic-vision (today's behavior).
  *   - unicMode true AND aliasAvailable false -> fall through to config fallback (do NOT force a
- *     failing dispatch to a model the gateway itself says is unavailable); state the
- *     unavailability in visionAdvisory so callers skip the lane and prefer native read.
+ *     failing dispatch to a model positively reported unavailable); state the unavailability in
+ *     visionAdvisory so callers skip the lane and prefer native read. Since the 2026-09-11
+ *     unic-gateway contract flip, the Codex catalog can no longer produce `false` (its silence
+ *     never denies the lane), so this branch only fires on POSITIVE unavailability evidence
+ *     from a future source.
  *   - unicMode true AND aliasAvailable missing/undefined -> keep today's behavior
  *     (return unic-vision). The strict === false check is what preserves the "missing field
  *     doesn't change today's behavior" contract from the task spec.
@@ -124,15 +127,15 @@ async function resolveVisionModel({ rootDir = process.cwd() } = {}) {
     if (typeof fallbackModel === 'string' && fallbackModel.trim()) {
       return {
         visionModel: fallbackModel.trim(),
-        visionAdvisory: 'vision lane detected but unic-vision alias is unavailable in the gateway '
-          + 'catalog; falling back to orchestration.modelTiers.vision.fallbackModel.',
+        visionAdvisory: 'vision lane detected but the unic-vision alias was positively reported '
+          + 'unavailable; falling back to orchestration.modelTiers.vision.fallbackModel.',
       };
     }
     return {
       visionModel: null,
-      visionAdvisory: 'vision lane detected but unic-vision alias is unavailable in the gateway '
-        + 'catalog and orchestration.modelTiers.vision.fallbackModel is not configured; no model '
-        + 'was named to avoid forcing a failing dispatch — caller should prefer native read.',
+      visionAdvisory: 'vision lane detected but the unic-vision alias was positively reported '
+        + 'unavailable and orchestration.modelTiers.vision.fallbackModel is not configured; no '
+        + 'model was named to avoid forcing a failing dispatch — caller should prefer native read.',
     };
   }
 

package/templates/.claude/ukit/index/unic-gateway.mjs

@@ -1,10 +1,12 @@
 #!/usr/bin/env node
 /**
- * unic-gateway.mjs (TASK-003, narrowed by TASK-007)
+ * unic-gateway.mjs (TASK-003, narrowed by TASK-007; alias-availability contract flipped 2026-09-11)
  *
  * Detects whether THIS Claude Code session's own outbound endpoint is pointed at the UNIC gateway
- * — i.e. `ANTHROPIC_BASE_URL` contains "unicjsc.com" — so the vision lane can pin `unic-vision`
- * when it is available in the Codex model catalog, and fall back safely when it is not.
+ * — i.e. `ANTHROPIC_BASE_URL` contains "unicjsc.com" — so the vision lane can pin `unic-vision`.
+ * The Codex model catalog can CONFIRM the alias (listing it) but its silence never denies it:
+ * it is another tool's config and says nothing about what the gateway resolves server-side for
+ * this session (live dispatch STATUS: OK on a machine whose catalog omits the alias, 2026-09-11).
  *
  * Self-contained: reads only env vars and local files. Does NOT read `.ukit/storage/config.json`,
  * so it has no dependency on TASK-001 and stays usable in Wave 1.
@@ -121,25 +123,35 @@ function probeClaudeSettings(filePath) {
 // Narrow anchored regex probe (no YAML parsing) for the omp config file's `baseUrl` key. A
 // missing file, unreadable path, or malformed YAML all degrade to "no hit" -- never throws.
 /**
- * Checks whether the Codex model catalog exists and, if so, whether it lists `unic-vision`.
- * A missing/unreadable/malformed catalog is never an error — it degrades to "unknown" and the
- * caller treats that as aliasAvailable: false with an explanatory advisory.
+ * Checks what the Codex model catalog says about `unic-vision`.
+ *
+ * 2026-09-11 CONTRACT FLIP — the catalog may CONFIRM the alias but must never DENY it.
+ * The catalog belongs to Codex, a different tool, and says nothing about what the UNIC
+ * gateway resolves server-side for a Claude Code subagent dispatch. Live evidence from
+ * 2026-09-11: on a machine whose ~/.codex/model-catalog.json omits the alias, dispatching
+ * the alias through the real gateway returned STATUS: OK with real pixel data. The old
+ * behaviour (missing / malformed / alias-absent catalog => aliasAvailable: false) made the
+ * vision lane dead by default on every gateway machine — the exact "image reading always
+ * errors" field report this flip closes. The analyst agent's own WRONG_MODEL self-check is
+ * the in-band safety net: if the alias ever stops resolving, a dispatch fails loudly and
+ * never guesses. `aliasAvailable: false` is therefore reserved for a future source of
+ * POSITIVE unavailability evidence; no such source exists today.
  */
 function checkCodexVisionAlias(catalogPath) {
   const json = safeReadJson(catalogPath);
   if (json == null) {
-    return { checked: false, aliasAvailable: false };
+    return { checked: false, catalogListed: null, aliasAvailable: true };
   }
   const models = Array.isArray(json?.models)
     ? json.models
     : Array.isArray(json)
       ? json
       : [];
-  const aliasAvailable = models.some((entry) => {
+  const catalogListed = models.some((entry) => {
     const slug = entry && typeof entry === 'object' ? entry.slug ?? entry.id ?? entry.name : null;
     return slug === VISION_MODEL_ALIAS;
   });
-  return { checked: true, aliasAvailable };
+  return { checked: true, catalogListed, aliasAvailable: true };
 }
 
 /**
@@ -187,6 +199,7 @@ export function detectUnicGateway(options = {}) {
     sources,
     visionModel: VISION_MODEL_ALIAS,
     aliasAvailable: catalogInfo.aliasAvailable,
+    catalogListed: catalogInfo.catalogListed,
   };
 
   const advisoryParts = [];
@@ -195,8 +208,15 @@ export function detectUnicGateway(options = {}) {
       'No tool on this machine is pointed at the UNIC gateway (unicjsc.com); UNIC routing stays disabled.',
     );
   }
-  if (catalogInfo.checked && !catalogInfo.aliasAvailable) {
-    advisoryParts.push(`${VISION_MODEL_ALIAS} not listed in the Codex model catalog; vision requests may fall back.`);
+  // Informational only — never a lane denial (see checkCodexVisionAlias above).
+  if (!catalogInfo.checked) {
+    advisoryParts.push(
+      `${VISION_MODEL_ALIAS} availability is unverified locally (Codex model catalog not found); the gateway resolves the alias server-side.`,
+    );
+  } else if (!catalogInfo.catalogListed) {
+    advisoryParts.push(
+      `${VISION_MODEL_ALIAS} not listed in the local Codex model catalog; the gateway resolves the alias server-side, so the lane stays available.`,
+    );
   }
   if (advisoryParts.length > 0) {
     result.advisory = advisoryParts.join(' ');
@@ -223,7 +243,9 @@ function safeFallbackResult() {
     source: null,
     sources: [],
     visionModel: VISION_MODEL_ALIAS,
-    aliasAvailable: false,
+    // Silence is never denial (2026-09-11 flip): an unexpected detection failure carries no
+    // positive unavailability evidence, so it must not deny the vision lane either.
+    aliasAvailable: true,
     advisory: 'unic-gateway detection failed unexpectedly; defaulting to unicMode: false.',
   };
 }