@ngockhoale/ukit 2.2.9 → 2.2.10

package/CHANGELOG.md

@@ -2,6 +2,51 @@
 
 All notable changes to UKit are documented here.
 
+## 2.2.10 - 2026-08-29
+
+User report: long omp (Oh My Pi) sessions go idle roughly 15 minutes into a task — no output, no
+error, no notification, indistinguishable from a hang. Typing `continue` makes the session resume
+and finish correctly (the user's observation, not a measurement — no field reproduction of the
+stall exists on this machine to time it). Three real root causes were found by reading the source,
+not guessed:
+
+### Fixed
+
+- **`map-impact` — the mode wide implementation work actually routes to — was never gated by the
+  completion loop.** `templates/.claude/ukit/runtime/execution-ledger.mjs:12`'s `IMPLEMENT_MODES`
+  set omitted it, while `src/index/taskRouting.js:414` routes exactly this kind of task to
+  `map-impact` and `src/index/taskRouting.js:610` gives it the strictest contract
+  (`impact-evidence`, `write-evidence`, `verification-evidence`). So the longest tasks declared the
+  most evidence and got no gate at all — the session could stop with nothing written and nothing
+  verified, silently. `map-impact` is now in `IMPLEMENT_MODES`.
+- **Reaching the continuation cap ended the session with a log line, not a message.** At
+  `MAX_CONTINUATIONS` (6, unchanged), `evaluateCompletion` returned `{ capped: true }` and the only
+  reaction was `pi.logger.warn` — a log sink, not the transcript. This is also the mechanical reason
+  a new prompt (`continue`) appeared to "fix" the stall: a new prompt writes a fresh `requestKey`,
+  which resets the per-request continuation count back to zero. The gate now spends exactly one
+  final continuation (`finalNotice`) instructing the model to state what is unfinished and stop, and
+  persists a one-shot `notified` flag on the ledger so the notice cannot refire.
+- **The post-compact resume was delivered only to the next user turn, and every UKit→omp message was
+  `display: false`.** After an omp auto-compaction, the `docs/AI_HANDOFF/RUN.md` resume cursor was
+  sent with `deliverAs: 'nextTurn'` only — if compaction ended the agent loop, the cursor waited for
+  a human to type something. Separately, every message the bridge built hardcoded `display: false`,
+  so UKit had no user-visible channel in omp at all, for context or for stop notices.
+  `runSessionCompact` now sends the resume as `steer` (reaches a still-running turn) *and*
+  `nextTurn` (unchanged fallback), and `runSessionStop` now sends one `display: true` notice
+  whenever it stops with evidence still missing — including the previously-silent
+  `review-release` / ungated-mode case.
+
+**Two premises behind the third fix are unverified — omp is not installed in this development
+environment.** Whether omp still accepts a `steer` message after a compaction, and whether omp
+honours `display: true` on a bridge message, were not and could not be reproduced or measured here.
+Both changes are additive: if either premise is false, the `nextTurn` delivery and the model's own
+`finalNotice` message (from the second fix) still reach the user, so the worst case is unchanged
+from today's behaviour, never worse. See `docs/STATUS.md` for the open thread and the evidence that
+would confirm the continuation-cap path directly.
+
+- **`templates/.omp/RULES.md` gains one sticky rule**: ending a turn with no output is a defect, not
+  a pause — a model-side backstop for whatever a code gate cannot reach.
+
 ## 2.2.9 - 2026-08-28
 
 Retuning UKit's context budget used to mean editing five scattered places and hand-syncing two

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "2.2.9",
+  "version": "2.2.10",
   "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/ukit/runtime/execution-ledger.mjs

@@ -15,6 +15,7 @@ const IMPLEMENT_MODES = new Set([
   'local-build',
   'shared-edit',
   'find-cause',
+  'map-impact',
 ]);
 
 function safeSegment(value) {
@@ -159,6 +160,7 @@ function freshLedger(payload, routeState, harness) {
     receipts: [],
     blocker: null,
     continuationCount: 0,
+    notified: false,
     updatedAt: Date.now(),
   };
 }
@@ -252,24 +254,48 @@ export function evaluateCompletion({ state = {}, ledger = {} } = {}) {
   const routeSummary = state?.routeSummary || {};
   const mode = routeSummary.executionMode || routeSummary.approachSelector?.executionMode || null;
   const evidence = requiredEvidence(state);
-  if (!IMPLEMENT_MODES.has(mode) || evidence.length === 0 || ledger?.blocker) {
-    return { continue: false, missingEvidence: [] };
+  if (ledger?.blocker) {
+    return { continue: false, notify: false, missingEvidence: [] };
+  }
+  if (evidence.length === 0) {
+    return { continue: false, notify: false, missingEvidence: [] };
   }
 
   const sameRequest = !ledger?.requestKey || !state?.requestKey || ledger.requestKey === state.requestKey;
   const effectiveLedger = sameRequest ? ledger : {};
   const missingEvidence = evidence.filter((item) => !evidenceSatisfied(item, effectiveLedger));
   if (missingEvidence.length === 0) {
-    return { continue: false, missingEvidence: [] };
+    return { continue: false, notify: false, missingEvidence: [] };
+  }
+
+  const gated = IMPLEMENT_MODES.has(mode);
+  if (!gated) {
+    return {
+      continue: false,
+      notify: true,
+      missingEvidence,
+      reason: `UKit completion gate: missing ${missingEvidence.join(', ')}. This mode does not auto-continue; tell the user what is unfinished.`,
+    };
   }
 
   const continuationCount = Number(effectiveLedger?.continuationCount || 0);
   if (continuationCount >= MAX_CONTINUATIONS) {
+    if (effectiveLedger?.notified === true) {
+      return {
+        continue: false,
+        capped: true,
+        notify: true,
+        missingEvidence,
+        reason: `UKit continuation cap reached with missing evidence: ${missingEvidence.join(', ')}.`,
+      };
+    }
     return {
-      continue: false,
+      continue: true,
+      finalNotice: true,
+      notify: true,
       capped: true,
       missingEvidence,
-      reason: `UKit continuation cap reached with missing evidence: ${missingEvidence.join(', ')}.`,
+      reason: `UKit stopping with unfinished work: ${missingEvidence.join(', ')}. Tell the user what is unfinished and stop; do not continue further.`,
     };
   }
 
@@ -298,6 +324,13 @@ export async function incrementContinuation(projectRoot, payload = {}, ledger =
   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;
+}
+
 async function readStdin() {
   if (process.stdin.isTTY) return '';
   const chunks = [];
@@ -322,7 +355,8 @@ async function main() {
     const ledger = await readExecutionLedger(projectRoot, payload) || {};
     const result = evaluateCompletion({ state, ledger });
     if (result.continue) {
-      await incrementContinuation(projectRoot, payload, ledger);
+      if (result.finalNotice) await markNotified(projectRoot, payload, ledger);
+      else await incrementContinuation(projectRoot, payload, ledger);
       process.stdout.write(`${JSON.stringify({ decision: 'block', reason: result.reason })}\n`);
     } else if (result.capped) {
       process.stderr.write(`[ukit-completion] ${result.reason}\n`);

package/templates/.omp/RULES.md

@@ -57,6 +57,12 @@ Prefer unique current-file anchors over line numbers or stale pasted blocks. Nev
 stale spec — re-read current source and confirm before applying. Preserve existing BOM and line
 endings.
 
+## 8. Never end a turn silently
+
+Ending a turn with no output is a defect, not a pause. If you stop before the work is finished, the
+last thing you emit is one short line naming what is unfinished and what you need. Silence is never
+a status — the user cannot distinguish it from a crash.
+
 > Maintainer note, not a per-turn rule: `modelRoles` in `.omp/config.yml` ships UNIC gateway names.
 > On a non-UNIC provider, edit only the three cost tiers — `lite`, `code`, `smart` — never `vision`,
 > which stays `unic-vision` because it is a capability lane, not a cost tier.

package/templates/.omp/hooks/pre/ukit-bridge.js

@@ -12,6 +12,7 @@ import { spawnSync } from 'node:child_process';
 import {
   evaluateCompletion,
   incrementContinuation,
+  markNotified,
   readExecutionLedger,
   readRouteState,
   recordExecutionReceipt,
@@ -337,18 +338,18 @@ function textFromContent(content) {
     .join('\n');
 }
 
-function hookContextMessage(content) {
+function hookContextMessage(content, { display = false } = {}) {
   return {
     customType: 'ukit-hook-context',
     content,
-    display: false,
+    display,
   };
 }
 
-function sendContext(pi, context, deliverAs) {
+function sendContext(pi, context, deliverAs, { display = false } = {}) {
   const content = context.filter(Boolean).join('\n').trim();
   if (!content || typeof pi.sendMessage !== 'function') return;
-  pi.sendMessage(hookContextMessage(content), { deliverAs });
+  pi.sendMessage(hookContextMessage(content, { display }), { deliverAs });
 }
 
 export async function runToolCall(pi, event, { projectRoot, context: extensionContext = {} }) {
@@ -469,6 +470,9 @@ export async function runSessionCompact(pi, event, { projectRoot, context: exten
   const metadata = runtimeMetadata(event, extensionContext);
   const payload = buildHookPayload('SessionStart', { ...metadata, source: 'compact' });
   const result = await runScriptChain(pi, HOOK_EVENT_MAP.session_start, payload, { projectRoot });
+  // TODO(verify) PLAN.md §3 D3: whether omp still accepts a 'steer' message after a compaction
+  // is unverified. If it drops steer, the 'nextTurn' copy below preserves prior behavior.
+  sendContext(pi, result.context, 'steer');
   sendContext(pi, result.context, 'nextTurn');
   return undefined;
 }
@@ -490,12 +494,23 @@ export async function runSessionStop(
   const evaluation = evaluateCompletion({ state, ledger });
   if (!evaluation.continue) {
     if (evaluation.capped) pi.logger?.warn?.(`[UKit] ${evaluation.reason}`);
+    if (Array.isArray(evaluation.missingEvidence) && evaluation.missingEvidence.length > 0) {
+      const notice = [
+        `[UKit] Stopping with unfinished work: ${evaluation.missingEvidence.join(', ')}.`,
+        evaluation.reason,
+      ].filter(Boolean).join(' ');
+      // TODO(verify) PLAN.md §3 D4: whether omp honours display:true on a sendMessage payload
+      // is unverified (omp is not installed). If display is ignored, the finalNotice
+      // continuation below (the model's own message) is the channel guaranteed to render.
+      sendContext(pi, [notice], 'nextTurn', { display: true });
+    }
     return undefined;
   }
 
   if (suppliedLedger === undefined) {
     try {
-      await incrementContinuation(projectRoot, payload, ledger);
+      if (evaluation.finalNotice) await markNotified(projectRoot, payload, ledger);
+      else await incrementContinuation(projectRoot, payload, ledger);
     } catch (error) {
       pi.logger?.warn?.(`[UKit] continuation bookkeeping failed open: ${error?.message || error}`);
     }