@ngockhoale/ukit 2.3.11 → 2.3.13

package/CHANGELOG.md

@@ -2,6 +2,90 @@
 
 All notable changes to UKit are documented here.
 
+## 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
+nearly every image are fixed, the second consumer of the same advisory now honors the fallback,
+and the installed vision-agent file mode is corrected. The cycle10 + cycle4 scripts prove the
+plumbing; a real UNIC round-trip dispatch is not covered by the suite (see `docs/STATUS.md`).
+
+**P1 — `--detect` could not resolve absolute image paths outside the project, or paths wrapped
+in quotes or trailing punctuation.** `extract-image.mjs`'s `--detect` arm accepted relative
+paths and in-project absolutes, but the path-capture regex in `vision-router.sh` then refused an
+out-of-project image ("did not resolve from the project root … Nothing was armed"), and
+trailing punctuation / wrapping quotes (`'<abs>/x.png'.`, `"<abs>/x.png"`) broke the existence
+check. Fix: `stripPathNoise()` in the extractor tries raw / soft-trailing-stripped /
+wrapping-pair-stripped / both shapes against `fs.existsSync`; the hook-side regex now uses the
+same tolerance. The interior of the path is never touched, and relative handling is unchanged.
+
+**P1 — marker receipts were leaked into `images[]`, so the dispatch hint could carry a
+`pending-*.json` path to the analyst.** `--mark-pending --json` returned each marker receipt
+(`{ path: 'pending-<sha>.json', bytes: 0 }`) inside the same `images[]` array that was supposed
+to carry materialized images; downstream code that filtered "bytes > 0" still sometimes passed
+the marker through, and the dispatch hint could carry a `pending-*.json` path the analyst would
+not have materialized. Fix: `images[]` is now the materialized-only invariant (empty in
+`--detect` / `--mark-pending` mode; every entry has bytes > 0 and a non-`.json` extension
+otherwise); receipts live in a new top-level `pendingMarkers[]` carrying
+`{ path, sha, bytes: 0, … }` per detection. On-disk marker format (`pending-<sha>.json`,
+`bytes: 0`) is untouched — only JSON presentation changed.
+
+**P1 — the hook never forwarded the parent transcript, and default session discovery could
+pick a newer-but-empty subagent transcript over the parent's image-bearing one.** When a
+subagent spawn raced the paste, the subagent's empty transcript was the newest file in the
+sessions root, so `discoverSessionFile()` returned it and the analyst got `imageCount: 0`. The
+dispatch hint also lacked any `--session` argument, so the analyst could not materialize from
+the parent transcript even when one was named in the payload. Fix: `discoverSessionFile()`
+honors `CLAUDE_CONFIG_DIR` when set, calls `fs.realpathSync` so the macOS `/var` ↔ `/private/var`
+symlinks do not drift the slug, and runs a bounded newest-first scan (`DISCOVERY_SCAN_BOUND = 5`)
+with a cheap 64 KiB `transcriptHasImageHead()` peek — never an unbounded walk or full-content
+parse. When nothing image-bearing is found, the script emits an explicit `STATUS: NO_IMAGE
+scanned=<names>` (and a JSON line first under `--json`) instead of a fake success. The hook
+hint now always carries `--session <payload.transcript_path>` whenever the payload provides one;
+explicit `--session` still bypasses discovery and the NO_IMAGE branch entirely.
+
+**P1 — when the vision lane was unavailable, both consumers forced a failing dispatch instead
+of degrading to native read.** `unic-gateway.mjs`'s `aliasAvailable: false` advisory was
+ignored by `resolveVisionModel` in `route-task.mjs` and by the hook's hint builder, so a
+gateway without vision routed the analyst task with `[model: unic-vision]` and the agent model
+itself had to read the image, only to fail mid-dispatch. Fix: both consumers now honor
+`aliasAvailable === false` — `resolveVisionModel` returns a non-`unic-vision` (native/main-
+model) lane and states the unavailability in the routed output; the hook hint omits
+`[model: unic-vision]`, says `vision lane unavailable`, and instructs a native read instead of
+dispatching the analyst. The missing-field case preserves today's default; the
+`unicMode === false` short-circuit is unchanged. Also: installed
+`.claude/agents/ukit-vision-analyst.md` is now mode 0644 (template stays `100644` in git) — a
+stale 755 from a prior install that was never regenerated by `ukit install` because
+`copyFileSafe` preserves template mode.
+
 ## 2.3.11 - 2026-09-11
 
 Freeze-sweep wave 11 (post-2.3.10): the two deferred liveness candidates fixed via TDD, plus

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "2.3.11",
+  "version": "2.3.13",
   "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/hooks/vision-router.sh

@@ -79,7 +79,68 @@ const { pathToFileURL } = require('url');
   // URL images are checked first and stripped out so the local-path regex never
   // re-matches the tail of a URL (case c is a hint-only lane — no download here).
   const URL_IMAGE_RE = /https?:\/\/\S+\.(?:png|jpe?g|gif|webp)\b/gi;
-  const LOCAL_PATH_RE = /\S+\.(?:png|jpe?g|gif|webp|bmp)\b/gi;
+  // Local path regex deliberately tolerates a trailing run of punctuation /
+  // brackets / quotes after the extension. A bare \b would stop at the first
+  // closing quote and drop `'.` from `'/tmp/x.png'.`, leaving an unpairable
+  // leading quote for stripPathNoise to fail on. The char class [PUNCT] is
+  // hand-picked: it never matches a word char, so it still refuses to consume
+  // `image.pngbar` (false image) — the class doesn't include letters/digits.
+  // The negative lookahead `(?![A-Za-z0-9])` between the extension and the
+  // punct class is what actually enforces "extension terminates at a
+  // non-alphanumeric boundary": without it, `\S+` would backtrack past
+  // `image.png` inside `image.pngbar` and emit a false positive match (which
+  // then trips the unresolved-path advisory on every prompt of every
+  // installed project). The lookahead keeps the trailing-punctuation
+  // tolerance unchanged for real paths.
+  const LOCAL_PATH_RE = /\S+\.(?:png|jpe?g|gif|webp|bmp)(?![A-Za-z0-9])[()\[\]{}.,;:!?'"`]*/gi;
+
+  // Mirror of extract-image.mjs's stripPathNoise() — the regex above greedily
+  // captures trailing punctuation/quotes an LLM sometimes leaves on a named
+  // path (`/tmp/x.png'.`, `(/tmp/x.png).`, `"/tmp/x.png"`). Without this
+  // pre-clean the extractor receives `'/tmp/x.png` (leading quote, no close
+  // pair) and silently skips it. Kept here as a small inline copy rather than
+  // a cross-file import — the contract is a few lines, the cost of drift is
+  // small, and the hook must stay self-contained (no module resolution).
+  function stripPathNoise(raw) {
+    const value = String(raw ?? '').trim();
+    if (!value) return value;
+    const pairs = { '(': ')', '[': ']', '{': '}', '"': '"', "'": "'" };
+    const trailingSoftPunctRe = /[.,;:]+$/;
+    const trailingAnyPunctRe = /[.,;:)\]}"']+$/;
+    const candidates = [];
+    candidates.push(value);
+    const noSoft = value.replace(trailingSoftPunctRe, '');
+    if (noSoft !== value) candidates.push(noSoft);
+    if (value.length >= 2) {
+      const o = value[0];
+      const c = value[value.length - 1];
+      if (pairs[o] === c) candidates.push(value.slice(1, -1));
+    }
+    if (value.length >= 2) {
+      const o = value[0];
+      const c = value[value.length - 1];
+      if (pairs[o] === c) {
+        const inner = value.slice(1, -1);
+        const innerTrim = inner.replace(trailingAnyPunctRe, '');
+        if (innerTrim !== inner) candidates.push(innerTrim);
+        if (innerTrim !== value.slice(1, -1)) candidates.push(innerTrim);
+      }
+    }
+    if (noSoft.length >= 2) {
+      const o = noSoft[0];
+      const c = noSoft[noSoft.length - 1];
+      if (pairs[o] === c) candidates.push(noSoft.slice(1, -1));
+    }
+    for (const c of candidates) {
+      if (!c) continue;
+      try {
+        if (fs.existsSync(path.resolve(c))) return c;
+      } catch {
+        // ignore
+      }
+    }
+    return noSoft !== value ? noSoft : value;
+  }
 
   const urlMatches = promptText.match(URL_IMAGE_RE) || [];
   const textWithoutUrls = promptText.replace(URL_IMAGE_RE, ' ');
@@ -100,7 +161,10 @@ const { pathToFileURL } = require('url');
       args.push('--session-id', payload.session_id.trim());
     }
     for (const ref of [...localMatches, ...urlMatches]) {
-      args.push('--ref', ref);
+      // Mirror extractor's resolveRefs input contract: the LLM sometimes leaves
+      // trailing punctuation/quotes on a path named in a prompt. Clean before
+      // handing off so the hook and the extractor agree on the ref string.
+      args.push('--ref', stripPathNoise(ref));
     }
     try {
       const out = execFileSync('node', args, {
@@ -114,24 +178,31 @@ const { pathToFileURL } = require('url');
     }
   }
 
-  // Decide from what the EXTRACTOR did, not from prompt-text regex hits: `written`
-  // markers are genuinely new work; `alreadyAnalyzed` entries are closed cases that
-  // must stay silent. Regex mentions alone no longer trigger the full hint.
-  const images = Array.isArray(extractorJson?.images) ? extractorJson.images : [];
+  // TASK-006 contract: in --mark-pending --json mode `images[]` is the
+  // MATERIALIZED-ONLY shape and stays empty; armed markers live in
+  // `pendingMarkers[]` with `{path, sha, bytes: 0, source, ref}`. The hook
+  // keys its armed/not-armed decision off `pendingMarkers[]`, never off
+  // `images[]` — the latter would silently report zero armed for the
+  // mark-pending path that is the entire point of this hook.
+  const pendingMarkers = Array.isArray(extractorJson?.pendingMarkers)
+    ? extractorJson.pendingMarkers
+    : [];
   const analyzed = Array.isArray(extractorJson?.alreadyAnalyzed) ? extractorJson.alreadyAnalyzed : [];
   const sessionId = typeof extractorJson?.sessionId === 'string' && extractorJson.sessionId
     ? extractorJson.sessionId
     : '';
-  const armedCount = images.length;
-  const armedRefs = new Set(images.filter((img) => typeof img?.ref === 'string').map((img) => img.ref));
+  const armedCount = pendingMarkers.length;
+  const armedRefs = new Set(
+    pendingMarkers.filter((m) => typeof m?.ref === 'string').map((m) => m.ref)
+  );
   const analyzedRefs = new Set(analyzed.filter((a) => typeof a?.ref === 'string').map((a) => a.ref));
   const unresolvedLocal = localMatches.filter(
     (m) => !armedRefs.has(m.trim()) && !analyzedRefs.has(m.trim())
   );
   const cases = [];
-  if (images.some((img) => !img?.source)) cases.push('pasted image');
-  if (images.some((img) => img?.source === 'path')) cases.push('local file path');
-  if (images.some((img) => img?.source === 'url')) cases.push('image URL');
+  if (pendingMarkers.some((m) => !m?.source)) cases.push('pasted image');
+  if (pendingMarkers.some((m) => m?.source === 'path')) cases.push('local file path');
+  if (pendingMarkers.some((m) => m?.source === 'url')) cases.push('image URL');
 
   if (armedCount === 0) {
     // No NEW markers. Only speak up when a named path never resolved at all —
@@ -148,27 +219,77 @@ const { pathToFileURL } = require('url');
     return;
   }
 
-  // Only unicMode true or null reach here; off-gateway already exited. There is no
-  // fallback-model branch to advertise. There must never be one: the analyst
-  // self-reports the model it really ran on, so telling it to claim some other ID is
-  // asking it to falsify the receipt.
-  let unicNote = '';
+  // Forward the parent transcript path so step 1 below targets the parent
+  // transcript, NOT whatever transcript happens to live in the parent's
+  // session dir after a subagent spawn (which is empty and silently zero).
+  // No path here ever came from `pendingMarkers[].path` — that field is a
+  // pending-<sha>.json marker receipt and must never reach the hint.
+  const transcriptPath = typeof payload?.transcript_path === 'string' && payload.transcript_path.trim()
+    ? payload.transcript_path.trim()
+    : '';
+  const materializeArgv = ['node', '.claude/ukit/index/extract-image.mjs', '--json'];
+  if (transcriptPath) {
+    materializeArgv.push('--session', transcriptPath);
+  }
+  const materializeCmd = materializeArgv
+    .map((tok) => (/[\s'"\\$`]/.test(tok) ? `'${tok.replace(/'/g, `'\\''`)}'` : tok))
+    .join(' ');
+
+  // Only unicMode true or null reach here. Resolve the gateway advisory ONCE
+  // here so the hint can pick a lane-aware shape. Missing `aliasAvailable`
+  // (older gateway) keeps today's behavior; strict `aliasAvailable === false`
+  // forces the native-read fallback rather than dispatching a specialist that
+  // the gateway itself says is unavailable.
+  let gatewayResult = null;
   if (unicMode === true) {
     try {
       const gatewayPath = path.join(projectRoot, '.claude', 'ukit', 'index', 'unic-gateway.mjs');
       const mod = await import(pathToFileURL(gatewayPath).href);
-      const result = mod.detectUnicGateway({ rootDir: projectRoot });
-      if (result?.visionModel) {
-        unicNote = `  (UNIC gateway active — ${result.visionModel} routes through it.)`;
+      if (typeof mod.detectUnicGateway === 'function') {
+        gatewayResult = mod.detectUnicGateway({ rootDir: projectRoot });
       }
     } catch {
-      unicNote = '';
+      gatewayResult = null;
     }
   }
+  const aliasAvailable = gatewayResult?.aliasAvailable;
+  const laneUnavailable = aliasAvailable === false;
+
+  if (laneUnavailable) {
+    // Lane cannot be honored — say so, prefer native read, do NOT instruct
+    // dispatching the analyst (a forced dispatch to a model the gateway
+    // itself reports as unavailable is the failure mode that closed the
+    // vision lane in the field).
+    const lines = [
+      `UKIT VISION ROUTE — new image input detected (${cases.join(', ')}).`,
+      'Vision lane unavailable (unic-vision alias is not in the gateway catalog).',
+      'Read the image directly with your VERIFIED native vision — do NOT dispatch',
+      `ukit-vision-analyst: the gateway reports the alias as unavailable, and a`,
+      'forced dispatch would fail at the provider.',
+      '',
+      `Materialize with: ${materializeCmd}`,
+      'Then Read each ABSOLUTE path in images[].path as text (subagents do NOT',
+      `inherit image blocks; they can only Read files). For pasted images the`,
+      `--session arg above is required — without it the extractor picks the`,
+      'newest transcript in the session dir, which after a subagent spawn is',
+      'the empty subagent transcript.',
+    ];
+    if (sessionId) {
+      lines.push(`Markers armed under sessionId: ${sessionId}; receipts land as analyzed-<sha>.json.`);
+    }
+    process.stdout.write(`${lines.join('\n')}\n`);
+    process.exit(0);
+    return;
+  }
+
+  // Lane honored (or unverified — missing aliasAvailable defaults to today's
+  // unic-vision dispatch). Capability-framed, never provider identity: the
+  // remedy is "don't guess — use a verified reader", which holds whether the
+  // active model reads images natively or hands off to the specialist.
+  const unicNote = (unicMode === true && gatewayResult?.visionModel)
+    ? `  (UNIC gateway active — ${gatewayResult.visionModel} routes through it.)`
+    : '';
 
-  // Capability-framed, never provider identity: the remedy is "don't guess — use a
-  // verified reader", which holds whether the active model reads images natively or
-  // must hand off to the specialist.
   const reasonLines = [
     'Advisory: never guess at image contents. If the active model has VERIFIED native',
     'vision for these images it may read them directly; otherwise dispatch the specialist',
@@ -178,7 +299,9 @@ const { pathToFileURL } = require('url');
   const lines = [
     `UKIT VISION ROUTE — new image input detected (${cases.join(', ')}).`,
     ...reasonLines,
-    '  1. node .claude/ukit/index/extract-image.mjs --json',
+    `  1. ${materializeCmd}`,
+    '     Materialize the images to disk. With --session the extractor targets the',
+    '     PARENT transcript explicitly, so a subagent spawn cannot drop the image.',
     '  2. Agent(subagent_type: "ukit-vision-analyst")  [model: unic-vision]',
     '     Send the ABSOLUTE paths from images[].path as TEXT (subagents do NOT inherit',
     '     image blocks; they can only Read files). Include the task envelope: the ORIGINAL',
@@ -189,7 +312,7 @@ const { pathToFileURL } = require('url');
   if (sessionId) {
     lines.push(`  Markers armed under sessionId: ${sessionId} (receipts: analyzed-<sha>.json).`);
   }
-  if (images.some((img) => img?.source === 'url')) {
+  if (pendingMarkers.some((m) => m?.source === 'url')) {
     lines.push('  Image URL detected: ukit-vision-analyst downloads it with Bash into');
     lines.push('  .ukit/storage/cache/vision/, then Reads the downloaded file.');
   }

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

@@ -67,6 +67,76 @@ const EXT_MEDIA = {
   bmp: 'image/bmp',
 };
 
+/**
+ * Strips wrapping quotes / matching parens / trailing punctuation that an LLM
+ * sometimes leaves on a path named in a prompt (e.g. `/tmp/x.png'.`,
+ * `(/tmp/x.png).`, `"/tmp/x.png"`). The interior of the path is left alone.
+ *
+ * Strategy: try the original and several cleaned shapes; return the first one
+ * that `fs.existsSync`s. Order is chosen to cover the common artefacts
+ * without consuming a wrapping pair's close-bracket as "trailing punctuation":
+ *   1. the raw value (a clean absolute path needs no stripping)
+ *   2. strip a single trailing run of `.` `,` `;` `:` (cheap; covers `path.`)
+ *   3. strip a matching wrapping pair (covers `"path"` and `'path'`)
+ *   4. strip the wrapping pair AND any leftover trailing punct
+ *      (covers `"/tmp/x.png".` and `'/tmp/x.png',`)
+ *   5. strip a single trailing `)` `]` `}` (the open was a wrap; the close
+ *      got left over after a stray final char) then strip the matching pair
+ *      (covers `(/tmp/x.png).` where the `.` already ate the `)`)
+ */
+function stripPathNoise(raw) {
+  const value = String(raw ?? '').trim();
+  if (!value) return value;
+  const pairs = { '(': ')', '[': ']', '{': '}', '"': '"', "'": "'" };
+  const trailingSoftPunctRe = /[.,;:]+$/; // won't eat a wrapping pair's close
+  const trailingAnyPunctRe = /[.,;:)\]}"']+$/;
+  const candidates = [];
+
+  candidates.push(value);
+  // (2) drop a soft trailing punct run only — won't consume a wrap-close.
+  const noSoft = value.replace(trailingSoftPunctRe, '');
+  if (noSoft !== value) candidates.push(noSoft);
+  // (3) drop a matching wrapping pair if both ends match.
+  if (value.length >= 2) {
+    const o = value[0];
+    const c = value[value.length - 1];
+    if (pairs[o] === c) candidates.push(value.slice(1, -1));
+  }
+  // (4) drop a wrapping pair, THEN any leftover trailing punct.
+  if (value.length >= 2) {
+    const o = value[0];
+    const c = value[value.length - 1];
+    if (pairs[o] === c) {
+      const inner = value.slice(1, -1);
+      const innerTrim = inner.replace(trailingAnyPunctRe, '');
+      if (innerTrim !== inner) candidates.push(innerTrim);
+      if (innerTrim !== value.slice(1, -1)) candidates.push(innerTrim);
+    }
+  }
+  // (5) drop a soft trailing punct, THEN a matching wrapping pair (covers
+  // `(/tmp/x.png).` — soft strip eats `.` then pair strip takes `()`).
+  if (noSoft.length >= 2) {
+    const o = noSoft[0];
+    const c = noSoft[noSoft.length - 1];
+    if (pairs[o] === c) candidates.push(noSoft.slice(1, -1));
+  }
+
+  const seen = new Set();
+  for (const c of candidates) {
+    if (!c || seen.has(c)) continue;
+    seen.add(c);
+    try {
+      if (fs.existsSync(path.resolve(c))) return c;
+    } catch {
+      // ignore
+    }
+  }
+  // No candidate resolved to a real file. Return the soft-stripped shape so
+  // the caller at least gets a deterministic string and the existing "file
+  // not found" branch reports the failure on the cleaned shape.
+  return noSoft !== value ? noSoft : value;
+}
+
 /**
  * Turns --ref values (local paths and URLs named in the prompt) into markers.
  *
@@ -76,24 +146,30 @@ const EXT_MEDIA = {
  * analyzed-<sha> by filename and never recomputes it. Still routed through
  * crypto.createHash here so this file remains the single owner of the hash.
  *
+ * Tolerates absolute paths OUTSIDE the project root (a vision repro sometimes
+ * points at a file outside `process.cwd()`), and strips wrapping quotes / trailing
+ * punctuation that an LLM may leave on a path named in a prompt — see
+ * stripPathNoise() above.
+ *
  * Silently drops anything that is not an image ref or cannot be read: this feeds a
  * hook that must never wedge a prompt.
  */
 export function resolveRefs(values) {
   const out = [];
   const seen = new Set();
-  for (const value of values ?? []) {
-    const match = REF_EXT_RE.exec(value);
+  for (const raw of values ?? []) {
+    const cleaned = stripPathNoise(raw);
+    const match = REF_EXT_RE.exec(cleaned);
     if (!match) continue;
     const mediaType = EXT_MEDIA[match[1].toLowerCase()] ?? 'application/octet-stream';
-    const isUrl = /^https?:\/\//i.test(value);
+    const isUrl = /^https?:\/\//i.test(cleaned);
     let sha;
     if (isUrl) {
-      sha = crypto.createHash('sha256').update(value, 'utf8').digest('hex');
+      sha = crypto.createHash('sha256').update(cleaned, 'utf8').digest('hex');
     } else {
       let bytes;
       try {
-        bytes = fs.readFileSync(path.resolve(value));
+        bytes = fs.readFileSync(path.resolve(cleaned));
       } catch {
         continue; // path named in the prompt but not present on disk: nothing to analyse
       }
@@ -102,7 +178,7 @@ export function resolveRefs(values) {
     }
     if (seen.has(sha)) continue;
     seen.add(sha);
-    out.push({ sha, mediaType, source: isUrl ? 'url' : 'path', value });
+    out.push({ sha, mediaType, source: isUrl ? 'url' : 'path', value: cleaned });
   }
   return out;
 }
@@ -149,21 +225,116 @@ function parseArgs(argv) {
 }
 
 function slugifyCwd(cwd) {
-  return cwd.replace(/[^a-zA-Z0-9]/g, '-');
+  // realpathSync collapses `/var` ↔ `/private/var` symlinks (and any other
+  // platform-specific canonicalisation) so the slug we compute here is the
+  // same string the Claude Code daemon uses to name the same sessions dir.
+  // Without this, on macOS process.cwd() can be `/private/var/folders/...`
+  // while the on-disk dir the daemon queries is `/var/folders/...`, and the
+  // slugs drift apart — silent miss.
+  let canonical = cwd;
+  try {
+    canonical = fs.realpathSync(cwd);
+  } catch {
+    // cwd may not exist (rare, e.g. a deleted-then-recreated cwd); fall back
+    // to the raw path so the script still produces a deterministic slug.
+  }
+  return canonical.replace(/[^a-zA-Z0-9]/g, '-');
+}
+
+/**
+ * How many newest candidates to scan before giving up on default discovery.
+ *
+ * The vision failure we're fixing here had the parent Claude Code spawning a
+ * subagent whose own transcript is the newest file in the sessions dir — but
+ * the subagent's transcript has zero images, while the parent's (older) one
+ * has the pasted image. Picking the *very* newest mtime alone returns the
+ * subagent's empty transcript and silently drops the image.
+ *
+ * The fix is a bounded newest-first walk: scan at most the N newest .jsonl
+ * candidates and pick the first one that actually contains an image block. N
+ * is kept small on purpose: this hook fires on every UserPromptSubmit, so we
+ * refuse to do an unbounded directory walk or a full-content parse of every
+ * candidate. Pinned via DISCOVERY_SCAN_BOUND so the test suite can verify
+ * the bound is enforced (TASK-006 case 7).
+ */
+const DISCOVERY_SCAN_BOUND = 5;
+
+/** Cheap "does this transcript look like it has any image blocks?" check.
+ *
+ * Reads at most 64 KiB from the head of the file (peeks via fs.read with a
+ * bounded length — no full-content parse, no JSON.parse) and looks for the
+ * `"type":"image"` JSON property the extractor uses to recognise pasted
+ * image blocks. False negatives are tolerated: the caller treats a miss as
+ * "not image-bearing" and moves on to the next candidate. False positives
+ * are NOT tolerated silently: the caller MUST confirm with a full parse
+ * (extractImageBlocks), because a transcript's text or sibling keys can
+ * legitimately contain the literal substring `"type":"image"` without any
+ * real image block — see the fall-through in discoverSessionFile().
+ */
+function transcriptHasImageHead(filePath) {
+  let fd = null;
+  try {
+    fd = fs.openSync(filePath, 'r');
+    const stats = fs.fstatSync(fd);
+    const bytesToRead = Math.min(stats.size, 64 * 1024);
+    if (bytesToRead <= 0) return false;
+    const buf = Buffer.alloc(bytesToRead);
+    fs.readSync(fd, buf, 0, bytesToRead, 0);
+    // The extractor emits JSONL with each line as one JSON object; the
+    // pasted-image property is `"type":"image"` (no spaces — same shape
+    // Claude Code writes today). Match both `"type":"image"` and the
+    // canonical-with-spaces shape for resilience.
+    return buf.includes(Buffer.from('"type":"image"'))
+      || buf.includes(Buffer.from('"type": "image"'));
+  } catch {
+    return false;
+  } finally {
+    if (fd !== null) {
+      try { fs.closeSync(fd); } catch { /* ignore */ }
+    }
+  }
 }
 
+/**
+ * Pick a transcript .jsonl to scan for images.
+ *
+ * Returns `{ path, scanned }` where `scanned` is the ordered list of
+ * candidates the bounded walk actually inspected (newest-first, capped at
+ * DISCOVERY_SCAN_BOUND). On success `path` is the first candidate whose
+ * full JSONL parse yielded at least one image block. On failure `path` is
+ * `null` and `scanned` still carries the candidates that were checked so
+ * the caller can emit an explicit `STATUS: NO_IMAGE` message that names
+ * them.
+ *
+ * The head-peek is a cheap prefilter, not a promise. A transcript can pass
+ * the head-peek (its raw bytes contain the literal substring `"type":"image"`)
+ * and still parse to ZERO real image blocks — e.g., a log line that quotes
+ * the JSON shape, or a sibling top-level key/value pair where `"type":"image"`
+ * appears as structural bytes. In that case we fall through to the next
+ * bounded candidate instead of early-stopping. Without this, main() prints
+ * a silent imageCount: 0 and never reaches the explicit NO_IMAGE branch the
+ * vision router relies on to tell "tried, no images" from a real failure.
+ *
+ * The sessions root honours `CLAUDE_CONFIG_DIR` when set (the standard
+ * Claude Code env var) so contributors / tests can redirect the lookup
+ * without touching `~/.claude`. Default stays `os.homedir()/.claude` so
+ * production behaviour is unchanged.
+ */
 function discoverSessionFile(cwd) {
   const slug = slugifyCwd(cwd);
-  const dir = path.join(os.homedir(), '.claude', 'projects', slug);
+  const configRoot = process.env.CLAUDE_CONFIG_DIR
+    ? path.resolve(process.env.CLAUDE_CONFIG_DIR)
+    : path.join(os.homedir(), '.claude');
+  const dir = path.join(configRoot, 'projects', slug);
+
   let entries;
   try {
     entries = fs.readdirSync(dir, { withFileTypes: true });
   } catch {
-    return null;
+    return { path: null, scanned: [] };
   }
 
-  let newestPath = null;
-  let newestMtimeMs = -Infinity;
+  const candidates = [];
   for (const entry of entries) {
     if (!entry.isFile() || !entry.name.endsWith('.jsonl')) continue;
     const full = path.join(dir, entry.name);
@@ -173,12 +344,31 @@ function discoverSessionFile(cwd) {
     } catch {
       continue;
     }
-    if (stat.mtimeMs > newestMtimeMs) {
-      newestMtimeMs = stat.mtimeMs;
-      newestPath = full;
+    candidates.push({ full, mtimeMs: stat.mtimeMs });
+  }
+  // Newest first, bounded.
+  candidates.sort((a, b) => b.mtimeMs - a.mtimeMs);
+  const bounded = candidates.slice(0, DISCOVERY_SCAN_BOUND);
+  const scanned = bounded.map((c) => path.basename(c.full));
+
+  for (const candidate of bounded) {
+    if (!transcriptHasImageHead(candidate.full)) continue;
+    // The head-peek is a cheap prefilter, not a promise: a transcript can
+    // contain the literal substring `"type":"image"` in prose (e.g., a log
+    // line that quotes the JSON shape, or a sibling top-level key/value pair
+    // where `"type":"image"` appears as structural bytes) yet parse to ZERO
+    // real image blocks. The full JSONL parse is the gate — a zero-block
+    // result must fall through to the next bounded candidate instead of
+    // early-stopping. Otherwise main() prints a silent imageCount: 0 and
+    // never reaches the explicit NO_IMAGE branch the vision router relies
+    // on to tell "tried, no images" from a real failure.
+    const lines = readLines(candidate.full);
+    const blocks = extractImageBlocks(lines);
+    if (blocks.length > 0) {
+      return { path: candidate.full, scanned };
     }
   }
-  return newestPath;
+  return { path: null, scanned };
 }
 
 function readLines(filePath) {
@@ -302,11 +492,35 @@ function printResult(opts, result) {
   }
 }
 
+/**
+ * Surface a non-silent refusal when default discovery couldn't find an
+ * image-bearing transcript. The caller (vision-router.sh) relies on this to
+ * distinguish "nothing to analyse" from a real failure, so we always print
+ * the message — both in `--json` (via a STATUS: NO_IMAGE marker line that
+ * the contract layer can read) and in human-readable mode.
+ */
+function emitNoImage(scanned, sessionId, opts) {
+  const names = scanned.length > 0 ? scanned.join(', ') : '(empty)';
+  if (opts.json) {
+    // Two-line shape: the first is machine-parseable (imageCount: 0, images: []),
+    // the second is the explicit refusal marker so callers/tests can assert on it
+    // without parsing the array contents.
+    console.log(JSON.stringify({ imageCount: 0, sessionId, images: [] }));
+    console.log(`STATUS: NO_IMAGE scanned=${names}`);
+    return;
+  }
+  console.log(`STATUS: NO_IMAGE scanned=${names}`);
+}
+
 function main() {
   const opts = parseArgs(process.argv.slice(2));
   const cwd = process.cwd();
 
-  const sessionPath = opts.session ? path.resolve(opts.session) : discoverSessionFile(cwd);
+  const discovery = opts.session
+    ? { path: path.resolve(opts.session), scanned: [] }
+    : discoverSessionFile(cwd);
+  const sessionPath = discovery.path;
+  const scannedNames = discovery.scanned;
   const outDir = opts.out
     ? path.resolve(opts.out)
     : path.join(cwd, '.ukit', 'storage', 'cache', 'vision');
@@ -314,7 +528,23 @@ function main() {
   const sessionId = opts.sessionId
     || (sessionPath ? path.basename(sessionPath, path.extname(sessionPath)) : 'default');
 
-  const lines = sessionPath ? readLines(sessionPath) : [];
+  // Default discovery could not find an image-bearing transcript within the
+  // bounded scan — surface an explicit refusal instead of a silent zero so
+  // the caller can tell "tried, no images" from a real failure. Explicit
+  // --session still bypasses this: the caller knows what they asked for.
+  if (!sessionPath) {
+    if (scannedNames.length > 0) {
+      emitNoImage(scannedNames, sessionId, opts);
+    } else {
+      // No candidates at all (sessions dir missing or empty). Preserve the
+      // original zero-output behaviour so existing callers don't see a new
+      // refusal shape for a pre-existing "no home / no projects" case.
+      printResult(opts, { imageCount: 0, sessionId, images: [] });
+    }
+    return;
+  }
+
+  const lines = readLines(sessionPath);
   const blocks = extractImageBlocks(lines);
   const markerDir = path.join(outDir, sessionId);
   // selectImages() picks the most recent N images from the WHOLE transcript, so a resolved
@@ -384,7 +614,16 @@ function main() {
       }
     }
     pruneMarkerDirs(outDir);
-    printResult(opts, { imageCount: written.length, sessionId, images: written, alreadyAnalyzed });
+    // images[] invariant: marker receipts (bytes: 0, .json path) NEVER belong
+    // here — they live in pendingMarkers[]. images[] is the materialized-only
+    // shape; detect/mark-pending mode keeps it empty by definition.
+    printResult(opts, {
+      imageCount: written.length,
+      sessionId,
+      images: [],
+      pendingMarkers: written,
+      alreadyAnalyzed,
+    });
     return;
   }
 
@@ -425,6 +664,8 @@ function main() {
     images.push({ sha: img.sha, path: filePath, mediaType: img.mediaType, bytes: decoded.length });
   }
   pruneImageFiles(outDir);
+  // images[] invariant: every entry has bytes > 0 and a non-.json extension —
+  // materialized image files only, never markers.
   printResult(opts, { imageCount: images.length, sessionId, images });
 }
 

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

@@ -93,10 +93,24 @@ function detectPastedImageViaExtractor({ rootDir = process.cwd() } = {}) {
 }
 
 /**
- * Gateway-aware model pick (TASK-003 aware). Calls detectUnicGateway() directly (not the CLI) to
- * avoid a spawn on the hot path. unicMode true -> unic-vision. unicMode false -> read
- * orchestration.modelTiers.vision.fallbackModel from config (TASK-001). Neither available -> omit
- * visionModel and return an advisory; a blind model is never silently named.
+ * Gateway-aware model pick (TASK-003 aware; TASK-008 lane-fallback). Calls detectUnicGateway()
+ * directly (not the CLI) to avoid a spawn on the hot path.
+ *
+ * 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 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.
+ *   - unicMode false -> read orchestration.modelTiers.vision.fallbackModel from config
+ *     (TASK-001).
+ *   - Neither available -> omit visionModel and return an advisory; a blind model is never
+ *     silently named.
  */
 async function resolveVisionModel({ rootDir = process.cwd() } = {}) {
   let gateway = null;
@@ -106,12 +120,29 @@ async function resolveVisionModel({ rootDir = process.cwd() } = {}) {
     gateway = null;
   }
 
+  const config = await readJson(path.join(rootDir, '.ukit', 'storage', 'config.json'), null);
+  const fallbackModel = config?.orchestration?.modelTiers?.vision?.fallbackModel;
+
+  if (gateway?.unicMode && gateway.aliasAvailable === false) {
+    if (typeof fallbackModel === 'string' && fallbackModel.trim()) {
+      return {
+        visionModel: fallbackModel.trim(),
+        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 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.',
+    };
+  }
+
   if (gateway?.unicMode) {
     return { visionModel: gateway.visionModel || 'unic-vision', visionAdvisory: null };
   }
 
-  const config = await readJson(path.join(rootDir, '.ukit', 'storage', 'config.json'), null);
-  const fallbackModel = config?.orchestration?.modelTiers?.vision?.fallbackModel;
   if (typeof fallbackModel === 'string' && fallbackModel.trim()) {
     return { visionModel: fallbackModel.trim(), visionAdvisory: null };
   }

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.',
   };
 }