@ngockhoale/ukit 2.3.10 → 2.3.12

package/CHANGELOG.md

@@ -2,6 +2,86 @@
 
 All notable changes to UKit are documented here.
 
+## 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
+a self-refresh downgrade trap repaired during verification. All template/live mirrors are
+byte-synced.
+
+**P1 — SessionStart hook could hang the session forever.** `handoff-resume.sh`'s "advisory,
+always exit 0" rested on `|| true`, which never fires when the embedded node process wedges
+(hung runtime import, unresolved lock wait, stalled file read) — session start stalls mid-run
+with no visible reason. A 3s wall-clock watchdog (`UKIT_HOOK_DEADLINE_MS`, env-tunable) now
+exits 0 unconditionally, and the RUN.md read is async so sync I/O cannot block the timer.
+
+**P1 — router state writes could tear; route-audit merge lost entries.** All five
+`skill-router-state.json` / `route-audit.json` writes were direct `writeFileSync`: a torn or
+empty state parses as `{}` downstream and completion-gate.sh then releases a premature Stop
+with no message. Writes now go through tmp+rename (`writeJsonFileAtomic`), and the audit
+append runs under the standard PID + owner-token lock (5s bounded, fail-open). 16 concurrent
+router runs previously kept only 13/16 audit entries; now 16/16.
+
+**Incident — post-release self-refresh downgraded live hooks.** Running `ukit install` from a
+global CLI older than the published release rewrote six live hook mirrors with pre-release
+content, resurrecting just-fixed lock-theft bugs in the development workspace. Recovered by
+upgrading the global CLI and re-installing; the deferred guard candidate is a stale-CLI
+warning in `ukit install`.
+
 ## 2.3.10 - 2026-09-11
 
 Freeze-sweep waves 7-10 (post-2.3.9): twelve verified mid-run-freeze defects fixed, each locked

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "2.3.10",
+  "version": "2.3.12",
   "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/handoff-resume.sh

@@ -27,6 +27,14 @@ const fs = require('fs');
 const path = require('path');
 const { pathToFileURL } = require('url');
 
+// Wall-clock watchdog. This hook is ADVISORY ONLY, so any hang — a wedged runtime
+// import, a lock wait that never resolves, a stalled filesystem read — must end in a
+// clean exit 0 instead of stalling session start mid-run with no visible reason.
+// Every read below is async on purpose: sync I/O would block the loop and this timer
+// could never fire. Keep it that way.
+const HOOK_DEADLINE_MS = Number.parseInt(process.env.UKIT_HOOK_DEADLINE_MS || '', 10) || 3000;
+setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref();
+
 const payload = (() => {
   try {
     const parsed = JSON.parse(process.env.INPUT || '');
@@ -68,7 +76,8 @@ async function emitOrdinaryResume() {
 (async () => {
   let text;
   try {
-    text = fs.readFileSync(runPath, 'utf8');
+    // Async on purpose — a sync read on a stalled mount would block the watchdog timer.
+    text = await fs.promises.readFile(runPath, 'utf8');
   } catch {
     // No handoff cursor: an ordinary routed-task intent may still be resumable.
     await emitOrdinaryResume();

package/templates/.claude/hooks/skill-router.sh

@@ -121,6 +121,23 @@ const { pathToFileURL } = require('url');
     fs.mkdirSync(path.dirname(filePath), { recursive: true });
   }
 
+  function writeJsonFileAtomic(filePath, text) {
+    // tmp+rename: readers see old-or-new, never a torn/half file. A truncated
+    // skill-router-state.json parses as `{}` downstream and completion-gate.sh then
+    // releases a premature Stop with no message — the mid-run silent-stop class.
+    ensureDir(filePath);
+    const tempPath = `${filePath}.tmp-${process.pid}-${crypto.randomBytes(6).toString('hex')}`;
+    try {
+      fs.writeFileSync(tempPath, text);
+      fs.renameSync(tempPath, filePath);
+    } catch (error) {
+      try {
+        fs.rmSync(tempPath, { force: true });
+      } catch {}
+      throw error;
+    }
+  }
+
   function defaultRuntimeConfig() {
     return {
       memory: {
@@ -2286,45 +2303,124 @@ const { pathToFileURL } = require('url');
     };
   }
 
-  function appendRouteAuditEntry(filePath, entry) {
-    if (!entry || typeof entry !== 'object') {
-      return;
+  // Owner-token lock protocol, protocol-compatible with runtime token-utils withFileLock
+  // and the advisory permission hooks (mkdir-based `<file>.lock` + owner liveness).
+  // route-audit.json is a read-modify-write merge: without the lock, 16 concurrent
+  // router invocations were verified to keep only 13/16 entries (lost updates).
+  function isPidAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0) return false;
+    try {
+      process.kill(pid, 0);
+      return true;
+    } catch (error) {
+      return error?.code === 'EPERM';
     }
+  }
 
-    let parsed = { entries: [] };
-    if (fs.existsSync(filePath)) {
+  function readLockOwner(lockPath) {
+    const owner = readJson(path.join(lockPath, 'owner'), null);
+    return owner && Number.isInteger(owner.pid) && typeof owner.token === 'string'
+      ? owner
+      : null;
+  }
+
+  async function withStateLock(lockPath, fn) {
+    // Advisory bookkeeping: liveness over strictness — if the lock cannot be acquired
+    // within maxWaitMs the merge runs unlocked (pre-lock behaviour) rather than hanging
+    // or dropping the entry.
+    const staleMs = 10000;
+    const maxWaitMs = 5000;
+    const startedAt = Date.now();
+    const ownerToken = `${process.pid}-${crypto.randomBytes(8).toString('hex')}`;
+    let held = false;
+    while (!held) {
       try {
-        parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));
-      } catch {
-        parsed = { entries: [] };
+        fs.mkdirSync(lockPath);
+        try {
+          fs.writeFileSync(path.join(lockPath, 'owner'), JSON.stringify({
+            pid: process.pid,
+            token: ownerToken,
+            ts: Date.now(),
+          }));
+        } catch (error) {
+          try {
+            fs.rmSync(lockPath, { recursive: true, force: true });
+          } catch {}
+          throw error;
+        }
+        held = true;
+      } catch (error) {
+        if (!error || error.code !== 'EEXIST') return fn();
+        try {
+          const stat = fs.statSync(lockPath);
+          if (Date.now() - stat.mtimeMs > staleMs) {
+            const owner = readLockOwner(lockPath);
+            if (!owner || !isPidAlive(owner.pid)) {
+              try {
+                fs.rmSync(lockPath, { recursive: true, force: true });
+                continue;
+              } catch {}
+            }
+          }
+        } catch {}
+        if (Date.now() - startedAt > maxWaitMs) break;
+        await new Promise((resolve) => setTimeout(resolve, 3 + Math.floor(Math.random() * 9)));
+      }
+    }
+    try {
+      return await fn();
+    } finally {
+      if (held) {
+        const owner = readLockOwner(lockPath);
+        if (owner?.token === ownerToken) {
+          try {
+            fs.rmSync(lockPath, { recursive: true, force: true });
+          } catch {}
+        }
       }
     }
+  }
 
-    const entries = Array.isArray(parsed?.entries) ? parsed.entries : [];
-    const dedupeKey = stableMachineDigest({
-      requestKey: entry.requestKey,
-      executionMode: entry.executionMode,
-      nextActionType: entry.nextActionType,
-      nextMilestone: entry.nextMilestone,
-      repeatCount: entry.repeatCount,
-      rescueMode: entry.rescueMode,
-    });
-    const filtered = entries.filter((item) => {
-      const itemKey = stableMachineDigest({
-        requestKey: item?.requestKey || null,
-        executionMode: item?.executionMode || null,
-        nextActionType: item?.nextActionType || null,
-        nextMilestone: item?.nextMilestone || null,
-        repeatCount: item?.repeatCount || null,
-        rescueMode: item?.rescueMode || null,
+  async function appendRouteAuditEntry(filePath, entry) {
+    if (!entry || typeof entry !== 'object') {
+      return;
+    }
+
+    await withStateLock(`${filePath}.lock`, () => {
+      let parsed = { entries: [] };
+      if (fs.existsSync(filePath)) {
+        try {
+          parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+        } catch {
+          parsed = { entries: [] };
+        }
+      }
+
+      const entries = Array.isArray(parsed?.entries) ? parsed.entries : [];
+      const dedupeKey = stableMachineDigest({
+        requestKey: entry.requestKey,
+        executionMode: entry.executionMode,
+        nextActionType: entry.nextActionType,
+        nextMilestone: entry.nextMilestone,
+        repeatCount: entry.repeatCount,
+        rescueMode: entry.rescueMode,
+      });
+      const filtered = entries.filter((item) => {
+        const itemKey = stableMachineDigest({
+          requestKey: item?.requestKey || null,
+          executionMode: item?.executionMode || null,
+          nextActionType: item?.nextActionType || null,
+          nextMilestone: item?.nextMilestone || null,
+          repeatCount: item?.repeatCount || null,
+          rescueMode: item?.rescueMode || null,
+        });
+        return itemKey !== dedupeKey;
       });
-      return itemKey !== dedupeKey;
-    });
 
-    ensureDir(filePath);
-    fs.writeFileSync(filePath, JSON.stringify({
-      entries: [entry, ...filtered].slice(0, 40),
-    }));
+      writeJsonFileAtomic(filePath, JSON.stringify({
+        entries: [entry, ...filtered].slice(0, 40),
+      }));
+    });
   }
 
   function shouldIncludePreviousContext({ routingContext = {}, useIndexedContext = true } = {}) {
@@ -2551,7 +2647,7 @@ const { pathToFileURL } = require('url');
     // route: completion-gate.sh reads routeSummary/requestKey from this state to decide
     // whether a Stop is premature. Downgrading to a route-less state here silently disarms
     // the gate mid-task, so carry the previous route forward until a real route replaces it.
-    fs.writeFileSync(statePath, JSON.stringify({
+    writeJsonFileAtomic(statePath, JSON.stringify({
       ...(sessionId ? { sessionId } : {}),
       fingerprint,
       ts: now,
@@ -2672,7 +2768,7 @@ const { pathToFileURL } = require('url');
   };
   provisionalState.fingerprint = buildRouteStateFingerprint(provisionalState);
   ensureDir(statePath);
-  fs.writeFileSync(statePath, JSON.stringify(provisionalState));
+  writeJsonFileAtomic(statePath, JSON.stringify(provisionalState));
 
   let cacheUtils = null;
   if (fs.existsSync(cacheUtilsPath)) {
@@ -2733,8 +2829,8 @@ const { pathToFileURL } = require('url');
     }
 
     ensureDir(statePath);
-    fs.writeFileSync(statePath, JSON.stringify(reusedState));
-    appendRouteAuditEntry(routeAuditPath, buildRouteAuditEntry({
+    writeJsonFileAtomic(statePath, JSON.stringify(reusedState));
+    await appendRouteAuditEntry(routeAuditPath, buildRouteAuditEntry({
       state: reusedState,
     }));
 
@@ -2822,8 +2918,8 @@ const { pathToFileURL } = require('url');
     ...(helpers ? { helpers } : {}),
     routeSummary: compactRouteSummary(routeSummary),
   };
-  fs.writeFileSync(statePath, JSON.stringify(sharedState));
-  appendRouteAuditEntry(routeAuditPath, buildRouteAuditEntry({
+  writeJsonFileAtomic(statePath, JSON.stringify(sharedState));
+  await appendRouteAuditEntry(routeAuditPath, buildRouteAuditEntry({
     routingContext,
     routeSummary,
     state: sharedState,

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,21 @@ 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 the gateway itself says is unavailable); state the
+ *     unavailability in visionAdvisory so callers skip the lane and prefer native read.
+ *   - 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 +117,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 unic-vision alias is unavailable in the gateway '
+          + 'catalog; 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.',
+    };
+  }
+
   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 };
   }