@ngockhoale/ukit 2.3.7 → 2.3.9

package/templates/.claude/ukit/runtime/compact-threshold.mjs

@@ -43,6 +43,15 @@ function finiteNumber(value, fallback = 0) {
   return Number.isFinite(number) ? number : fallback;
 }
 
+// A malformed hard cap must fail back to a safe ceiling, never collapse to one token and
+// brick every Edit/Write/Bash call. Unlike token estimates, configuration is an operator
+// contract: accept only whole positive token counts.
+function positiveInteger(value, fallback) {
+  return typeof value === 'number' && Number.isFinite(value) && Number.isInteger(value) && value > 0
+    ? value
+    : fallback;
+}
+
 function uniqueStrings(values) {
   const seen = new Set();
   const unique = [];
@@ -452,7 +461,7 @@ export function buildCompactThresholds(config = {}) {
   // env.CLAUDE_CODE_AUTO_COMPACT_WINDOW and omp's compaction.thresholdTokens are rendered
   // from this number at install time (70% of it), so the client auto-compacts before the
   // gate blocks tools without anyone hand-syncing a second value.
-  const hardCapTokens = Math.max(1, finiteNumber(config?.compact?.hardCapTokens, 500_000));
+  const hardCapTokens = positiveInteger(config?.compact?.hardCapTokens, 500_000);
 
   return {
     softThreshold,
@@ -668,7 +677,71 @@ export function resolveThresholdCompactBudget({
   };
 }
 
+// ---- session-scoped pressure document ---------------------------------------
+// compact-pressure.json holds ONE record per session id. A session starting must never
+// zero another live session's pressure bookkeeping (its hard-cap gate and compact
+// advisories), and a brand-new session must not inherit a sibling's totals. The newest
+// record's flat fields stay projected at the document's top level so readers that predate
+// this shape (raw JSON readers) still see a coherent state.
+const PRESSURE_SESSIONS_MAX = 8;
+
+function normalizeSessionId(value) {
+  const id = typeof value === 'string' ? value.trim() : '';
+  return id || null;
+}
+
+function readPressureDocument(raw) {
+  if (raw && typeof raw === 'object' && raw.sessions && typeof raw.sessions === 'object') {
+    const sessions = {};
+    for (const [id, record] of Object.entries(raw.sessions)) {
+      if (id && record && typeof record === 'object') {
+        sessions[id] = record;
+      }
+    }
+    return sessions;
+  }
+  // Legacy single-record file: preserve the in-flight session under a shared bucket.
+  return raw && typeof raw === 'object' ? { default: raw } : {};
+}
+
+function pickPressureSession(sessions, sessionId) {
+  if (sessionId) {
+    // A session id that has no record yet starts clean — it must not inherit another
+    // session's totals, and the other way round nothing here touches that session.
+    return { id: sessionId, record: sessions[sessionId] ?? null };
+  }
+  const entries = Object.entries(sessions);
+  if (!entries.length) {
+    return { id: 'default', record: null };
+  }
+  const newest = entries
+    .sort(([, left], [, right]) => finiteNumber(right?.updatedAt, 0) - finiteNumber(left?.updatedAt, 0))[0];
+  return { id: newest[0], record: newest[1] };
+}
+
+function resolvePressureRecord(raw, config) {
+  if (!raw || typeof raw !== 'object' || !raw.sessions || typeof raw.sessions !== 'object') {
+    return raw; // flat legacy state — normalized as-is below
+  }
+  const { record } = pickPressureSession(readPressureDocument(raw), normalizeSessionId(config?.sessionId));
+  return record;
+}
+
+function projectPressureDocument(sessions) {
+  const newestFirst = Object.entries(sessions)
+    .sort(([, left], [, right]) => finiteNumber(right?.updatedAt, 0) - finiteNumber(left?.updatedAt, 0))
+    .slice(0, PRESSURE_SESSIONS_MAX);
+  const newestRecord = newestFirst[0]?.[1] ?? null;
+  return {
+    ...(newestRecord && typeof newestRecord === 'object' ? newestRecord : {}),
+    updatedAt: finiteNumber(newestRecord?.updatedAt, Date.now()),
+    v: 2,
+    sessions: Object.fromEntries(newestFirst),
+  };
+}
+
 export function buildCompactPressureState(rawState = null, config = {}) {
+  rawState = resolvePressureRecord(rawState, config);
   const thresholds = buildCompactThresholds(config);
   const rawSoftThreshold = finiteNumber(rawState?.softThreshold, 0);
   const rawHardThreshold = finiteNumber(rawState?.hardThreshold, 0);
@@ -1056,13 +1129,18 @@ export async function readCompactPressureState(projectRoot, config = {}) {
 // All compact-pressure mutations share one lock on the state file: without it,
 // concurrent hook processes (parallel subagents) and same-process flows interleave
 // their read-modify-write cycles and silently drop each other's sessionTokens.
+// Mutations are session-scoped: only the calling session's record is rewritten;
+// sibling session records pass through untouched.
 async function mutateCompactPressureState(projectRoot, mutator, config = {}) {
   const runtimePaths = buildRuntimePaths(projectRoot);
   return withFileLock(runtimePaths.compactPressurePath, async () => {
-    const current = buildCompactPressureState(await readJson(runtimePaths.compactPressurePath, null), config);
+    const sessions = readPressureDocument(await readJson(runtimePaths.compactPressurePath, null));
+    const { id, record } = pickPressureSession(sessions, normalizeSessionId(config?.sessionId));
+    const current = buildCompactPressureState(record, config);
     const next = mutator(current);
     const normalized = buildCompactPressureState(next, config);
-    await writeJson(runtimePaths.compactPressurePath, normalized);
+    sessions[id] = { ...normalized, updatedAt: Date.now() };
+    await writeJson(runtimePaths.compactPressurePath, projectPressureDocument(sessions));
     return normalized;
   });
 }
@@ -1070,22 +1148,42 @@ async function mutateCompactPressureState(projectRoot, mutator, config = {}) {
 export async function writeCompactPressureState(projectRoot, state, config = {}) {
   const runtimePaths = buildRuntimePaths(projectRoot);
   return withFileLock(runtimePaths.compactPressurePath, async () => {
+    const sessions = readPressureDocument(await readJson(runtimePaths.compactPressurePath, null));
+    const { id } = pickPressureSession(sessions, normalizeSessionId(config?.sessionId));
     const normalized = buildCompactPressureState(state, config);
-    await writeJson(runtimePaths.compactPressurePath, normalized);
+    sessions[id] = { ...normalized, updatedAt: Date.now() };
+    await writeJson(runtimePaths.compactPressurePath, projectPressureDocument(sessions));
     return normalized;
   });
 }
 
+function pressureSessionConfig(payload = {}, config = {}) {
+  const sessionId = normalizeSessionId(payload?.sessionId) ?? normalizeSessionId(config?.sessionId);
+  return sessionId ? { ...config, sessionId } : config;
+}
+
 export async function updateCompactPressureFromPrompt(projectRoot, payload, config = {}) {
-  return mutateCompactPressureState(projectRoot, (current) => registerPromptPressure(current, payload, config), config);
+  return mutateCompactPressureState(
+    projectRoot,
+    (current) => registerPromptPressure(current, payload, config),
+    pressureSessionConfig(payload, config),
+  );
 }
 
 export async function updateCompactPressureFromOutput(projectRoot, payload, config = {}) {
-  return mutateCompactPressureState(projectRoot, (current) => registerOutputPressure(current, payload, config), config);
+  return mutateCompactPressureState(
+    projectRoot,
+    (current) => registerOutputPressure(current, payload, config),
+    pressureSessionConfig(payload, config),
+  );
 }
 
 export async function writeThresholdCompactPlan(projectRoot, plan, config = {}) {
-  return mutateCompactPressureState(projectRoot, (current) => registerThresholdCompactPlan(current, plan, config), config);
+  return mutateCompactPressureState(
+    projectRoot,
+    (current) => registerThresholdCompactPlan(current, plan, config),
+    pressureSessionConfig(plan, config),
+  );
 }
 
 async function loadRuntimeConfig(projectRoot) {
@@ -1141,6 +1239,16 @@ async function runCli() {
       return;
     }
 
+    // Session-scoped bookkeeping: every read/write in this branch targets the calling
+    // session's record, so a sibling session starting in the same project cannot zero
+    // this session's pressure history.
+    const sessionConfig = {
+      ...config,
+      sessionId: typeof payload.session_id === 'string' && payload.session_id.trim()
+        ? payload.session_id.trim()
+        : undefined,
+    };
+
     // Heal a stale counter BEFORE the phase is computed. Auto-compact paths that never
     // fire the PreCompact hook leave sessionTokens counting history that was already
     // summarised away — that phantom total is how a healthy session got hard-cap blocked.
@@ -1148,21 +1256,22 @@ async function runCli() {
     // automatic, so they are the correction signal here.
     try {
       const synced = await syncCompactPressureStateWithTranscript(
-        await readCompactPressureState(projectRoot, config),
-        config,
+        await readCompactPressureState(projectRoot, sessionConfig),
+        sessionConfig,
         payload.transcript_path,
       );
       if (synced.reset) {
-        await writeCompactPressureState(projectRoot, synced.state, config);
+        await writeCompactPressureState(projectRoot, synced.state, sessionConfig);
       }
     } catch { /* advisory healing only — never block the prompt over it */ }
 
     const nextState = await updateCompactPressureFromPrompt(projectRoot, {
       promptText,
+      sessionId: sessionConfig.sessionId,
       routingContext: routeState?.routingContext ?? {},
       previousContext: routeState?.previousContext ?? null,
       routeSummary: routeState?.routeSummary ?? null,
-    }, config);
+    }, sessionConfig);
 
     if (nextState.phase === 'hard') {
       process.stdout.write(

package/templates/.claude/ukit/runtime/execution-ledger.mjs

@@ -5,6 +5,7 @@ import fs from 'node:fs/promises';
 import fsSync from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { withFileLock } from './token-utils.mjs';
 
 const LEDGER_VERSION = 1;
 const RESUME_INTENT_VERSION = 1;
@@ -512,6 +513,28 @@ export function evaluateCompletion({ state = {}, ledger = {} } = {}) {
     return { continue: false, notify: false, missingEvidence: [] };
   }
 
+  // `find-cause` can validly end clean: an investigation may establish that no actionable
+  // defect exists. Its contract says a FIX cannot be claimed without write + verification;
+  // it does not make a mutation mandatory. Treating missing evidence as an unconditional
+  // command to edit made a clean audit self-block forever (Stop -> "make an Edit" -> no
+  // honest edit exists -> Stop again). Once a mutation was attempted, retain the normal
+  // recovery gate — only a no-mutation, recommend-only investigation that has not already
+  // observed a failed verification gets this release valve. A route that named an actionable
+  // command, or a failing check, has concrete unfinished work and must keep recovering.
+  if (
+    mode === 'find-cause'
+    && routeSummary.policyMode === 'recommend-only'
+    && !effectiveLedger.writeAttempted
+    && !effectiveLedger.verificationFailed
+  ) {
+    return {
+      continue: false,
+      notify: true,
+      missingEvidence,
+      reason: 'UKit investigation ended without a mutation. A clean audit is valid; report whether no actionable defect was found or a concrete blocker remains. Do not claim a bug was fixed without write and verification evidence.',
+    };
+  }
+
   const gated = IMPLEMENT_MODES.has(mode);
   if (!gated) {
     return {
@@ -566,29 +589,38 @@ export function evaluateCompletion({ state = {}, ledger = {} } = {}) {
 }
 
 export async function incrementContinuation(projectRoot, payload = {}, ledger = null, requestKey = null) {
-  const current = ledger || await readExecutionLedger(projectRoot, payload) || freshLedger(payload, null, 'unknown');
-  // Mirror evaluateCompletion's staleness rule: a count minted by an earlier request must
-  // not be carried into the new request's budget, or the cap fires early (evaluate says 0,
-  // persist says 7) and the next request inherits a nearly exhausted budget.
-  const stale = requestKey
-    && current?.continuationRequestKey
-    && current.continuationRequestKey !== requestKey;
-  const next = {
-    ...current,
-    continuationCount: (stale ? 0 : Number(current.continuationCount || 0)) + 1,
-    ...(requestKey ? { continuationRequestKey: requestKey } : {}),
-    lastContinuationAt: Date.now(),
-    updatedAt: Date.now(),
-  };
-  await writeJsonAtomic(ledgerPath(projectRoot, payload), next);
-  return next;
+  const target = ledgerPath(projectRoot, payload);
+  // Locked re-read: parallel subagents firing Stop hooks share one ledger file, and a
+  // stale-snapshot rewrite would reset each other's continuationCount — the budget would
+  // never advance and the gate would keep issuing continuations.
+  return withFileLock(target, async () => {
+    const current = await readExecutionLedger(projectRoot, payload) || ledger || freshLedger(payload, null, 'unknown');
+    // Mirror evaluateCompletion's staleness rule: a count minted by an earlier request must
+    // not be carried into the new request's budget, or the cap fires early (evaluate says 0,
+    // persist says 7) and the next request inherits a nearly exhausted budget.
+    const stale = requestKey
+      && current?.continuationRequestKey
+      && current.continuationRequestKey !== requestKey;
+    const next = {
+      ...current,
+      continuationCount: (stale ? 0 : Number(current.continuationCount || 0)) + 1,
+      ...(requestKey ? { continuationRequestKey: requestKey } : {}),
+      lastContinuationAt: Date.now(),
+      updatedAt: Date.now(),
+    };
+    await writeJsonAtomic(target, next);
+    return next;
+  });
 }
 
 export async function markNotified(projectRoot, payload = {}, ledger = null) {
-  const current = ledger || await readExecutionLedger(projectRoot, payload) || freshLedger(payload, null, 'unknown');
-  const next = { ...current, notified: true, updatedAt: Date.now() };
-  await writeJsonAtomic(ledgerPath(projectRoot, payload), next);
-  return next;
+  const target = ledgerPath(projectRoot, payload);
+  return withFileLock(target, async () => {
+    const current = await readExecutionLedger(projectRoot, payload) || ledger || freshLedger(payload, null, 'unknown');
+    const next = { ...current, notified: true, updatedAt: Date.now() };
+    await writeJsonAtomic(target, next);
+    return next;
+  });
 }
 
 async function readStdin() {

package/templates/.claude/ukit/runtime/output-compression.mjs

@@ -1189,6 +1189,14 @@ async function main() {
 
   const projectRoot = process.env.CLAUDE_PROJECT_DIR || process.cwd();
   const config = await loadRuntimeConfig(projectRoot);
+  // Session-scoped pressure bookkeeping: output tokens must land in the calling
+  // session's record, never a sibling session's.
+  const sessionConfig = {
+    ...config,
+    sessionId: typeof payload.session_id === 'string' && payload.session_id.trim()
+      ? payload.session_id.trim()
+      : undefined,
+  };
   if (!shouldCompress(config)) {
     process.exit(0);
     return;
@@ -1247,7 +1255,7 @@ async function main() {
         tokensAfter: cached.tokensAfter ?? 0,
         savedTokens: cached.savedTokens ?? 0,
         exitCode,
-      }, config);
+      }, sessionConfig);
       process.stdout.write(String(cached.content));
       return;
     }
@@ -1345,7 +1353,7 @@ async function main() {
     tokensAfter: result.tokensAfter,
     savedTokens: result.savedTokens,
     exitCode,
-  }, config);
+  }, sessionConfig);
 
   if (config?.tokenPipeline?.promptCache) {
     await writePromptCacheEntry(projectRoot, {

package/templates/.claude/ukit/runtime/reinject-context.mjs

@@ -43,6 +43,30 @@ async function main() {
     ? process.env.CLAUDE_PROJECT_DIR
     : process.cwd();
   const config = await loadRuntimeConfig(projectRoot);
+  // Session-scoped pressure bookkeeping: this PreCompact run must zero ONLY the calling
+  // session's record. Reading stdin here is safe — the harness payload is modest and this
+  // process owns it exclusively.
+  const rawHookInput = await (async () => {
+    if (process.stdin.isTTY) return '';
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+      chunks.push(typeof chunk === 'string' ? chunk : chunk.toString('utf8'));
+    }
+    return chunks.join('');
+  })();
+  const hookPayload = (() => {
+    try {
+      return JSON.parse(rawHookInput || '{}');
+    } catch {
+      return {};
+    }
+  })();
+  const sessionConfig = {
+    ...config,
+    sessionId: typeof hookPayload.session_id === 'string' && hookPayload.session_id.trim()
+      ? hookPayload.session_id.trim()
+      : undefined,
+  };
   const state = await loadFreshRouteState(projectRoot);
   const compressEnabled = shouldCompress(config);
   const header = '=== PROJECT CONTEXT (post-compaction) ===';
@@ -67,15 +91,16 @@ async function main() {
 
   const rawBodyLines = [...rawStaticLines, ...dynamicLines];
   const bodyLines = [...staticLines, ...dynamicLines];
-  const pressureState = await readCompactPressureState(projectRoot, config);
+  const pressureState = await readCompactPressureState(projectRoot, sessionConfig);
 
   // Reset the hard-cap tracker as early as possible: this hook fires on every real
   // compaction, and it is the only signal that context actually shrank. It must happen
   // before the promptCache early-return below, otherwise a cache hit would skip it and
   // leave context-hardcap-gate.sh permanently tripped. Downstream writes
   // (writeThresholdCompactPlan) re-read from disk, so they build on the zeroed state and
-  // keep their own stats increments intact.
-  await writeCompactPressureState(projectRoot, resetCompactPressureState(pressureState, config), config);
+  // keep their own stats increments intact. Session-scoped: sibling sessions keep their
+  // own records.
+  await writeCompactPressureState(projectRoot, resetCompactPressureState(pressureState, sessionConfig), sessionConfig);
   const anchorLines = dynamicLines.filter((line) => (
     line.startsWith('- Recent routed lane:')
     || line.startsWith('- Current approach:')
@@ -153,7 +178,8 @@ async function main() {
       tokensBefore: compactedBody.tokensBefore,
       tokensAfter: compactedBody.tokensAfter,
       savedTokens: compactedBody.savedTokens,
-    }, config);
+      sessionId: sessionConfig.sessionId,
+    }, sessionConfig);
   }
 
   const compactSource = thresholdPlan.active

package/templates/.omp/agents/bug-debugger.md

@@ -17,7 +17,7 @@ Systematic debugging — understand before fixing.
 
 - Run the failing command/action.
 - Capture exact error message and stack trace.
-- If not reproducible → document conditions and ask user.
+- If not reproducible → document conditions, run the next most-discriminating bounded repro, then report any exact missing user-only artifact/permission to the parent agent. Never wait for or ask a user directly — you are a worker.
 
 ### 2. Trace Root Cause
 
@@ -82,4 +82,4 @@ Daily mode: skip. Handoff mode: set task status `pending_review` in `INDEX.md`;
   - non-trivial bug: `docs/MEMORY.md` + `docs/PROJECT.md` + `docs/CODE_MAP.md`
   - read `docs/WORKLOG.md` only recent relevant entries
 - Keep fix scope minimal — no drive-by refactors.
-- If root cause is unclear after 5 minutes of tracing → ask user for more context.
+- If root cause is unclear after 5 minutes of tracing → try one bounded alternative hypothesis/repro, then report precise evidence plus the smallest needed missing context to the parent agent. Never wait for or ask a user directly — the parent owns user communication.

package/templates/.omp/agents/feature-implementer.md

@@ -11,7 +11,9 @@ Implement requested behavior with minimal scope drift.
 - **Daily/ad-hoc mode** (DEFAULT): task didn't come from `docs/AI_HANDOFF/` → use the original lightweight workflow. Tests only when touched code already has coverage. No reviewer trigger.
 - **Handoff mode**: task file is `docs/AI_HANDOFF/tasks/TASK-xxx.md` OR user explicitly invokes handoff (e.g. "execute task TASK-001") → activate full Quality Gate: test-first → green → reviewer.
 
-If unsure which mode applies, ask the user. Don't apply Handoff mode rules to a quick one-off fix.
+If unsure which mode applies, default to Daily/ad-hoc mode unless the task path or prompt
+explicitly selects Handoff. Do not ask a user — you are a worker; report the ambiguity and
+reasoning to the parent agent so it can decide whether to re-route.
 
 **In Handoff mode you are running unattended — ask nothing.** You were spawned by an
 orchestrator driving a pipeline; there is no human in your conversation to answer, and a
@@ -32,7 +34,7 @@ and even then, report it, don't ask about it.
   - non-trivial: `docs/MEMORY.md` + `docs/PROJECT.md` + `docs/CODE_MAP.md`
 - Identify target files and existing patterns.
 - If task came from handoff, read `tasks/TASK-xxx.md` and locate its **Test Plan** + **Verification Commands**.
-- Daily mode: if confidence is low or risk is high, ask one short clarifying question before deeper analysis. Handoff mode: do not ask — decide and record the decision (see above).
+- Daily mode: if confidence is low or risk is high, inspect the next bounded source/context signal and hand back a concise `STATUS: BLOCKED` report with the exact missing decision or artifact if confidence remains low. Do not ask a user directly. Handoff mode: do not ask — decide and record the decision (see above).
 
 ### 2. Plan Approach (< 1 minute)
 
@@ -43,7 +45,7 @@ and even then, report it, don't ask about it.
 
 - Write the test(s) from §2 / from task Test Plan.
 - Run them: must FAIL for the expected reason. Capture output.
-- If test passes immediately → test is wrong or behavior already exists. Fix the test or stop and report.
+- If test passes immediately → test is wrong or behavior already exists. Fix the test; if the intended behavior cannot be inferred, hand back `STATUS: BLOCKED` with the observed behavior and the smallest decision the parent must resolve. Never silently stop.
 - **Daily mode**: skip this step unless touched code already has tests (then follow original rule).