@ngockhoale/ukit 2.3.10 → 2.3.11

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 All notable changes to UKit are documented here.
 
+## 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.11",
   "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,