@ngockhoale/ukit 2.3.4 → 2.3.6

package/CHANGELOG.md

@@ -2,6 +2,56 @@
 
 All notable changes to UKit are documented here.
 
+## 2.3.6 - 2026-09-10
+
+Anti-stall coverage parity release: the compact-recovery and stop-reason directives that
+UKit hooks inject at runtime on Claude Code and omp now also reach harnesses that have no
+hook system at all.
+
+A new `## Long-Run Continuity` section ships in both `templates/CLAUDE.md` and
+`templates/AGENTS.md` (byte-identical, enforced by the per-section context-docs parity
+test). Codex and OpenCode load no hooks, so root `AGENTS.md` is their only instruction
+channel — before this release those sessions never saw the near-cap recovery order (LAND
+one thing → DEFER the rest to `docs/STATUS.md` → DELEGATE broad work to subagents → only
+then compact) or the post-compact discipline (no rereads of pre-compact context; if the
+first turn after a compact still sits at ≥60% of the cap, recover by delegating or starting
+fresh from disk state instead of burning the window again).
+
+The same session closed the long-running stall investigation with debug-log evidence: the
+observed "runs a while, then goes silent" behaviour is UNIC-gateway/network streaming
+latency (repeated 30s slow-first-byte, one 300s byte-idle abort), not UKit hooks —
+hook-error cache empty, exec ledgers healthy. When a dead stream ends a turn early, the
+existing ≥2.3.3 Stop-hook completion gate blocks the premature stop, so staying current
+(`ukit update`) plus restarting stale sessions (hook config loads at session start) is the
+full remediation available in-repo; gateway-side idle/failover fixes belong upstream.
+
+## 2.3.5 - 2026-09-10
+
+Source-audit hardening release: the code index cannot corrupt itself, and a corrupt runtime
+cache can no longer take down `ukit status` or `ukit memory`.
+
+Index artifacts (`files`, `symbols`, `imports`, `calls`, `tests-map`, `hotspots`,
+`archetypes`, `relations`, `analogs`, `meta`) are now written through same-directory
+`.tmp-<timestamp>-<random>` files followed by an atomic `rename`, in both the source builder
+(`src/index/buildIndex.js`) and the shipped `templates/.claude/ukit/index/lib/index-core.mjs`
+runtime mirror. A build that crashes mid-write — or two builds racing in one repo — can no
+longer leave a half-written artifact that poisons every subsequent index read; failed writes
+clean their temp file up before rethrowing.
+
+`ukit status` and `ukit memory` now read their cache/memory JSON through tolerant readers:
+a corrupt `compact-history.json`, `compact-pressure.json`, `prompt-cache.json`,
+`output-history.json`, or memory file prints a warning naming the exact file path and falls
+back to defaults instead of crashing the whole command mid-report. `readJsonIfExists` itself
+stays strict everywhere else, so genuinely bad callers still fail loudly.
+
+Nested test layouts (`packages/widget/tests/unit/...`) are now recognized as tests by the
+source path classifier and both runtime-mirror predicates — those files previously slipped
+past test detection, broke archetype classification, and never appeared in the test map.
+
+Each fix ships with regression coverage: a rename-spy test asserting all ten artifacts move
+through temp files, corrupt-fixture tests asserting the warned paths and surviving output,
+and a nested-`tests/` mapping/archetype test. Full suite: 77 files, 1,348 tests green.
+
 ## 2.3.4 - 2026-09-10
 
 Silent-stall audit and compact-recovery release. Two themes: every block reports a

package/package.json

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

package/src/core/memory/store.js

@@ -14,6 +14,15 @@ function defaultUserMemory() {
   };
 }
 
+async function readMemoryJson(filePath) {
+  try {
+    return await readJsonIfExists(filePath);
+  } catch (error) {
+    console.warn(`[UKit] Ignoring corrupt memory JSON file ${filePath}: ${error?.message ?? String(error)}`);
+    return null;
+  }
+}
+
 async function readDirectoryJsonItems(dirPath) {
   let entries = [];
   try {
@@ -29,7 +38,7 @@ async function readDirectoryJsonItems(dirPath) {
     }
 
     const fullPath = path.join(dirPath, entry.name);
-    const content = await readJsonIfExists(fullPath);
+    const content = await readMemoryJson(fullPath);
     if (content) {
       items.push({
         fileName: entry.name,
@@ -91,7 +100,7 @@ function createSearchableText(type, content) {
 
 export async function exportMemory(projectRoot) {
   const runtimePaths = buildRuntimePaths(projectRoot);
-  const user = (await readJsonIfExists(runtimePaths.userMemoryPath)) ?? defaultUserMemory();
+  const user = (await readMemoryJson(runtimePaths.userMemoryPath)) ?? defaultUserMemory();
   const projects = (await readDirectoryJsonItems(runtimePaths.projectsDir)).map((item) => item.content);
   const sessions = (await readDirectoryJsonItems(runtimePaths.sessionsDir)).map((item) => item.content);
 
@@ -100,7 +109,7 @@ export async function exportMemory(projectRoot) {
 
 export async function listMemoryItems(projectRoot) {
   const runtimePaths = buildRuntimePaths(projectRoot);
-  const userMemory = (await readJsonIfExists(runtimePaths.userMemoryPath)) ?? defaultUserMemory();
+  const userMemory = (await readMemoryJson(runtimePaths.userMemoryPath)) ?? defaultUserMemory();
   const projectMemories = await readDirectoryJsonItems(runtimePaths.projectsDir);
   const sessionMemories = await readDirectoryJsonItems(runtimePaths.sessionsDir);
 
@@ -188,7 +197,7 @@ function projectMemoryPath(runtimePaths, projectId) {
 
 async function readProjectMemoryForId(runtimePaths, projectId) {
   const filePath = projectMemoryPath(runtimePaths, projectId);
-  const existing = await readJsonIfExists(filePath);
+  const existing = await readMemoryJson(filePath);
   const memory = {
     id: projectId,
     conventions: [],
@@ -204,7 +213,7 @@ async function appendSessionArchive(runtimePaths, projectId, archivedSessions) {
   }
 
   const archivePath = path.join(runtimePaths.projectsDir, `${sanitizeProjectId(projectId)}.archive.json`);
-  const existing = (await readJsonIfExists(archivePath)) ?? { sessions: [] };
+  const existing = (await readMemoryJson(archivePath)) ?? { sessions: [] };
   const sessions = Array.isArray(existing.sessions) ? existing.sessions : [];
   await writeJson(archivePath, { sessions: [...sessions, ...archivedSessions] });
 }

package/src/core/status.js

@@ -5,7 +5,7 @@ import { loadRuntimeConfig } from './runtimeConfig.js';
 import { summarizeOutputHistory } from './output/index.js';
 import { buildPromptCacheStats } from './token/index.js';
 import { countMemoryItems } from './memory/store.js';
-import { readCompactPressureState } from './compact/threshold.js';
+import { buildCompactPressureState } from './compact/threshold.js';
 import { detectProjectContext } from '../context/detectProjectContext.js';
 
 function formatPrimaryAgent(agentKey) {
@@ -122,6 +122,15 @@ function formatRecoveryLabel(count) {
   return ` / ${count} recover${count === 1 ? 'y' : 'ies'}`;
 }
 
+async function readStatusJson(filePath) {
+  try {
+    return await readJsonIfExists(filePath);
+  } catch (error) {
+    console.warn(`[UKit] Ignoring corrupt status JSON file ${filePath}: ${error?.message ?? String(error)}`);
+    return null;
+  }
+}
+
 export async function buildStatusReport(projectRoot) {
   const runtimePaths = buildRuntimePaths(projectRoot);
   const runtimeExists = await pathExists(runtimePaths.runtimeRoot);
@@ -131,11 +140,14 @@ export async function buildStatusReport(projectRoot) {
 
   const projectContext = await detectProjectContext(projectRoot);
   const config = await loadRuntimeConfig(projectRoot);
-  const compactHistory = normalizeCompactEntries(await readJsonIfExists(runtimePaths.compactHistoryPath));
+  const compactHistory = normalizeCompactEntries(await readStatusJson(runtimePaths.compactHistoryPath));
   const compactSummary = buildCompactSummary(compactHistory);
-  const compactPressure = await readCompactPressureState(projectRoot, config);
-  const promptCacheStats = buildPromptCacheStats(await readJsonIfExists(runtimePaths.promptCachePath));
-  const outputCompressionStats = summarizeOutputHistory(await readJsonIfExists(runtimePaths.outputHistoryPath));
+  const compactPressure = buildCompactPressureState(
+    await readStatusJson(runtimePaths.compactPressurePath),
+    config,
+  );
+  const promptCacheStats = buildPromptCacheStats(await readStatusJson(runtimePaths.promptCachePath));
+  const outputCompressionStats = summarizeOutputHistory(await readStatusJson(runtimePaths.outputHistoryPath));
   const memoryCounts = await countMemoryItems(projectRoot);
   const adapters = await detectAdapterLabels(projectRoot, config.agent);
 

package/src/index/buildIndex.js

@@ -1197,7 +1197,20 @@ function areSourceFingerprintsEqual(previousFingerprint, nextFingerprint) {
 
 async function writeArtifact(rootDir, artifactName, payload) {
   const artifactPath = getArtifactPath(rootDir, artifactName);
-  await fs.writeFile(artifactPath, JSON.stringify(payload, null, 2));
+  const temporaryPath = `${artifactPath}.tmp-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+
+  try {
+    await fs.writeFile(temporaryPath, JSON.stringify(payload, null, 2));
+    await fs.rename(temporaryPath, artifactPath);
+  } catch (error) {
+    try {
+      await fs.rm(temporaryPath, { force: true });
+    } catch {
+      // ignore cleanup errors
+    }
+
+    throw error;
+  }
 }
 
 async function readArtifactIfExists(rootDir, artifactName) {

package/src/index/paths.js

@@ -37,6 +37,7 @@ export function isLikelyTestFilePath(filePath) {
     || lower.startsWith('specs/')
     || lower.includes('/__tests__/')
     || lower.includes('/test/')
+    || lower.includes('/tests/')
     || lower.includes('/spec/')
     || lower.includes('/specs/')
     || lower.endsWith('.test.js')

package/templates/.claude/ukit/index/lib/index-core.mjs

@@ -2028,7 +2028,21 @@ function areBugIndexSnapshotsEqual(previousSnapshot, nextSnapshot) {
 }
 
 async function writeArtifact(rootDir, artifactName, payload) {
-  await fs.writeFile(getArtifactPath(rootDir, artifactName), JSON.stringify(payload, null, 2));
+  const artifactPath = getArtifactPath(rootDir, artifactName);
+  const temporaryPath = `${artifactPath}.tmp-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+
+  try {
+    await fs.writeFile(temporaryPath, JSON.stringify(payload, null, 2));
+    await fs.rename(temporaryPath, artifactPath);
+  } catch (error) {
+    try {
+      await fs.rm(temporaryPath, { force: true });
+    } catch {
+      // ignore cleanup errors
+    }
+
+    throw error;
+  }
 }
 
 async function readArtifact(rootDir, artifactName) {
@@ -2557,6 +2571,7 @@ function isLikelyTestFilePath(filePath) {
     || lower.startsWith('specs/')
     || lower.includes('/__tests__/')
     || lower.includes('/test/')
+    || lower.includes('/tests/')
     || lower.includes('/spec/')
     || lower.includes('/specs/')
     || lower.endsWith('.test.js')
@@ -2988,6 +3003,7 @@ function isLikelyTestFile(filePath) {
     || lower.startsWith('specs/')
     || lower.includes('/__tests__/')
     || lower.includes('/test/')
+    || lower.includes('/tests/')
     || lower.includes('/spec/')
     || lower.includes('/specs/')
     || lower.endsWith('.test.js')

package/templates/AGENTS.md

@@ -26,6 +26,14 @@
 - **Do NOT say "done", "applied", or "fixed" after Read/Grep/analysis alone.** Completion wording requires concrete Edit/Write evidence in the current turn, and verification when the scope is risky.
 - **Every stop says why — no silent idle.** When a turn ends because only the user can act (login, approval, protected-file edit), open the reply with one line naming the exact action: `WAITING ON YOU: <command/action>`, and schedule a one-shot wakeup (~20-30 min) when the harness provides one so the session re-checks and auto-continues once the user has acted. An ended turn cannot observe external/auth changes by itself, so without that line (and the wakeup) the idle session looks identical to a stall. Any error — failed command, hook, test, publish — is reported verbatim in the same turn, never silently retried past the user.
 
+## Long-Run Continuity
+
+Mirrors what UKit hooks inject at runtime on Claude Code and omp; on harnesses without hooks (Codex, OpenCode) this section is the only carrier — keep it in sync with `.claude/hooks/context-window-guard.sh`.
+
+- Near token-cap: **LAND one thing** — finish the smallest in-flight item end-to-end (edit + verify, ≤3 tool calls) and report it done. **DEFER the rest** — one line per remaining step into `docs/STATUS.md`, or split into bounded `docs/AI_HANDOFF/` tasks. **DELEGATE** broad work (searches, big reads, multi-file edits) to subagents whose tool output lives in their own windows. Only then compact.
+- After any compact or handoff: do not reread pre-compact context — continue from the persisted disk state, delegate broad work, keep replies short. If the first turn after a compact still sits at ≥60% of the cap, stop rereading immediately and recover by delegating or starting a fresh session from the disk state; do not burn the window again.
+- A run ends only on completion evidence, a genuine blocker, or a user-only action — and per the Execution Contract above, every such stop names its reason in the final reply.
+
 ## Index-First Loop
 
 For any task that needs code context:

package/templates/CLAUDE.md

@@ -26,6 +26,14 @@
 - **Do NOT say "done", "applied", or "fixed" after Read/Grep/analysis alone.** Completion wording requires concrete Edit/Write evidence in the current turn, and verification when the scope is risky.
 - **Every stop says why — no silent idle.** When a turn ends because only the user can act (login, approval, protected-file edit), open the reply with one line naming the exact action: `WAITING ON YOU: <command/action>`, and schedule a one-shot wakeup (~20-30 min) when the harness provides one so the session re-checks and auto-continues once the user has acted. An ended turn cannot observe external/auth changes by itself, so without that line (and the wakeup) the idle session looks identical to a stall. Any error — failed command, hook, test, publish — is reported verbatim in the same turn, never silently retried past the user.
 
+## Long-Run Continuity
+
+Mirrors what UKit hooks inject at runtime on Claude Code and omp; on harnesses without hooks (Codex, OpenCode) this section is the only carrier — keep it in sync with `.claude/hooks/context-window-guard.sh`.
+
+- Near token-cap: **LAND one thing** — finish the smallest in-flight item end-to-end (edit + verify, ≤3 tool calls) and report it done. **DEFER the rest** — one line per remaining step into `docs/STATUS.md`, or split into bounded `docs/AI_HANDOFF/` tasks. **DELEGATE** broad work (searches, big reads, multi-file edits) to subagents whose tool output lives in their own windows. Only then compact.
+- After any compact or handoff: do not reread pre-compact context — continue from the persisted disk state, delegate broad work, keep replies short. If the first turn after a compact still sits at ≥60% of the cap, stop rereading immediately and recover by delegating or starting a fresh session from the disk state; do not burn the window again.
+- A run ends only on completion evidence, a genuine blocker, or a user-only action — and per the Execution Contract above, every such stop names its reason in the final reply.
+
 ## Index-First Loop
 
 For any task that needs code context: