@ngockhoale/ukit 3.4.69 → 3.4.70

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

@@ -7,6 +7,7 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
+import crypto from 'node:crypto';
 import { fileURLToPath } from 'node:url';
 import { spawnSync } from 'node:child_process';
 import {
@@ -1412,9 +1413,8 @@ export async function runSessionStop(
   };
   const payload = buildHookPayload('Stop', metadata);
 
-  // TASK-007 (OMP-2b): the coordinator's once-per-stop dedupe. omp can deliver
-  // two session_stop events for one logical stop; the second inside the window
-  // is skipped entirely — it must not burn a second continuation.
+  // Duplicate callbacks suppress evaluator mutations, not unresolved decisions.
+  // Successful releases always re-evaluate; episode side effects dedupe separately.
   let coordinator = null;
   try {
     coordinator = await loadStopCoordinatorModule();
@@ -1423,19 +1423,45 @@ export async function runSessionStop(
     // session — the completion gate below still owns the stop.
     pi.logger?.warn?.(`[UKit] stop-coordinator module unavailable (dedupe + handoff lanes skipped): ${error?.message || error}`);
   }
-  if (coordinator) {
-    const sessionKey = typeof payload.session_id === 'string' && payload.session_id
-      ? payload.session_id
-      : (typeof payload.transcript_path === 'string' && payload.transcript_path ? payload.transcript_path : 'no-session');
-    const duplicate = await coordinator.alreadyCoordinatedThisStop({
-      projectRoot,
-      sessionKey,
-      now,
-      dedupeWindowMs: dedupeWindowMs ?? coordinator.DEDUPE_WINDOW_MS,
-      lockBudgetMs,
-    });
-    if (duplicate) return undefined;
+  const state = suppliedState ?? await readRouteState(projectRoot, payload);
+  const ledger = suppliedLedger ?? await readExecutionLedger(projectRoot, payload) ?? {};
+  const authority = () => ({ state, ledger: suppliedLedger ?? null });
+  const claimToken = crypto.randomUUID();
+  const initialInput = coordinator
+    ? await coordinator.stopCoordinationInput({ projectRoot, payload, authority: authority() }) : null;
+  const key = initialInput ? `omp:${initialInput.key}` : null;
+  if (coordinator && await coordinator.alreadyCoordinatedThisStop({
+    projectRoot, sessionKey: key, now,
+    dedupeWindowMs: dedupeWindowMs ?? coordinator.DEDUPE_WINDOW_MS,
+    lockBudgetMs, replayOnlyBlocked: true, claimToken,
+  })) {
+    try {
+      const saved = JSON.parse(await fs.promises.readFile(path.join(projectRoot, '.ukit/storage/cache/stop-coordinator/state.json'), 'utf8'));
+      const decision = saved.stopClaims?.[key]?.decision;
+      if (decision?.decision === 'block') return decision.output;
+    } catch { /* pending/unknown does not authorize release */ }
+    return { continue: true, additionalContext: 'UKit completion gate: Stop evaluation ownership is pending or unavailable (duplicate, claim capacity, or lock contention). No evaluator was admitted and no completion has been verified; a subsequent Stop can recheck ownership.' };
   }
+  const finish = async (output) => {
+    if (coordinator) {
+      const evaluatedInput = await coordinator.stopCoordinationInput({ projectRoot, payload, authority: authority() });
+      await coordinator.publishStopDecision({
+        projectRoot, key,
+        evaluatedKey: initialInput.currency === evaluatedInput.currency ? `omp:${evaluatedInput.key}` : key,
+        claimToken, now, lockBudgetMs,
+        decision: output ? { decision: 'block', output } : { decision: null },
+      });
+    }
+    return output;
+  };
+  const recordEpisode = async () => {
+    const sessionKey = payload.session_id || payload.transcript_path || 'no-session';
+    const duplicate = coordinator && await coordinator.alreadyCoordinatedThisStop({
+      projectRoot, sessionKey: `omp-episode:${sessionKey}`, now,
+      dedupeWindowMs: dedupeWindowMs ?? coordinator.DEDUPE_WINDOW_MS, lockBudgetMs,
+    });
+    if (!duplicate) await runSessionEpisodeChain(pi, payload, projectRoot);
+  };
 
   // TASK-007 (OMP-2c): the handoff-cursor lane. While docs/AI_HANDOFF/RUN.md
   // reports a phase outside {done, blocked} the run owns this stop — the
@@ -1462,8 +1488,6 @@ export async function runSessionStop(
     sendContext(pi, [handoff.systemMessage], 'nextTurn', { display: true });
   }
 
-  const state = suppliedState ?? await readRouteState(projectRoot, payload);
-  const ledger = suppliedLedger ?? await readExecutionLedger(projectRoot, payload) ?? {};
   let evaluation;
   try {
     // Command authority (RC-A): same shared phase signal the Claude Stop path uses, so a
@@ -1483,17 +1507,17 @@ export async function runSessionStop(
         + 'The completion gate is DOWN, not your work: run `ukit install` to repair, '
         + 'then re-send the task in a new message if the run must continue.',
       ], 'nextTurn', { display: true });
-      await runSessionEpisodeChain(pi, payload, projectRoot);
-      return undefined;
+      await recordEpisode();
+      return finish(undefined);
     }
     pi.logger?.warn?.(`[UKit] completion evaluator crashed (streak ${streak}/${maxStreak}): ${error?.message || error}`);
-    return {
+    return finish({
       continue: true,
       additionalContext:
         `UKit stop coordinator: infrastructure failure while evaluating this stop (crash streak ${streak}/${maxStreak}) — `
         + 'the stop is blocked fail-closed (details withheld). Run: ukit install, then re-send the task in a new message.'
         + (handoffBlock ? `\n${HANDOFF_PROVENANCE_PREFIX}${handoffBlock}` : ''),
-    };
+    });
   }
   // A clean evaluation resets the consecutive-crash streak (shared with the shell hook).
   await resetCompletionCrashStreak(projectRoot);
@@ -1520,10 +1544,10 @@ export async function runSessionStop(
     // completion). Its own stall streak — not the ledger continuation counter —
     // bounds this lane, so no continuation bookkeeping runs here.
     if (handoffBlock) {
-      return { continue: true, additionalContext: handoffBlock };
+      return finish({ continue: true, additionalContext: handoffBlock });
     }
-    await runSessionEpisodeChain(pi, payload, projectRoot);
-    return undefined;
+    await recordEpisode();
+    return finish(undefined);
   }
 
   if (suppliedLedger === undefined) {
@@ -1536,14 +1560,14 @@ export async function runSessionStop(
       pi.logger?.warn?.(`[UKit] continuation bookkeeping failed open: ${error?.message || error}`);
     }
   }
-  return {
+  return finish({
     continue: true,
     // Coordinator merge order: the completion gate owns the continuation, and a
     // losing handoff-cursor block travels inside the winning reason.
     additionalContext: handoffBlock
       ? `${evaluation.reason}\n${HANDOFF_PROVENANCE_PREFIX}${handoffBlock}`
       : evaluation.reason,
-  };
+  });
 }
 
 function installedProjectRoot() {

package/scripts/dev/capture-omp-stall.mjs

@@ -1,246 +0,0 @@
-#!/usr/bin/env node
-// One-shot development capture. Every subprocess is bounded; OMP is never signalled or modified.
-import fs from 'node:fs/promises';
-import path from 'node:path';
-import os from 'node:os';
-import { spawn } from 'node:child_process';
-import { fileURLToPath } from 'node:url';
-import { readBoundedTail, summarizeSessionTail, buildStallSnapshot, associateSessionEvidence, classifySessionActivity, parseProcessInventory, processInventoryCommand, parseOwnerPids, runBoundedProcess } from '../../src/diagnostics/ompStallSnapshot.js';
-const ownPath = fileURLToPath(import.meta.url);
-const args = process.argv.slice(2);
-const option = (key) => { const at = args.indexOf(key); return at < 0 ? null : args[at + 1]; };
-const worker = process.env.UKIT_STALL_CAPTURE_WORKER === '1';
-
-if (!worker) {
-  const child = spawn(process.execPath, [ownPath, '--worker', ...args], { stdio: ['ignore', 'pipe', 'ignore'], env: { ...process.env, UKIT_STALL_CAPTURE_WORKER: '1' } });
-  let output = '';
-  let failed = false;
-  const timer = setTimeout(() => { failed = true; child.kill('SIGKILL'); }, 5000);
-  child.stdout.on('data', (chunk) => {
-    output += chunk;
-    if (Buffer.byteLength(output) > 131072) { failed = true; child.kill('SIGKILL'); }
-  });
-  child.on('error', () => { clearTimeout(timer); console.error('Capture unavailable'); process.exitCode = 1; });
-  child.on('close', async (code) => {
-    clearTimeout(timer);
-    if (code !== 0 || failed) { console.error('Capture incomplete: collector deadline or bounded I/O failure; OMP untouched.'); process.exitCode = 1; return; }
-    try {
-      const report = JSON.parse(output);
-      const dir = path.resolve(option('--output-dir') || path.join(os.tmpdir(), 'ukit-stall-captures'));
-      await fs.mkdir(dir, { recursive: true, mode: 0o700 });
-      const dirStat = await fs.lstat(dir);
-      if (!dirStat.isDirectory() || dirStat.isSymbolicLink()) throw new Error('unsafe output directory');
-      await fs.chmod(dir, 0o700);
-      let file = null;
-      let handle = null;
-      const startSlot = Date.now() % 8;
-      for (let attempt = 0; attempt < 8 && !file; attempt += 1) {
-        const slot = (startSlot + attempt) % 8;
-        const candidate = path.join(dir, `snapshot-${slot}.json`);
-        try {
-          const existing = await fs.lstat(candidate);
-          if (!existing.isFile() || existing.isSymbolicLink()) continue;
-          await fs.unlink(candidate);
-        } catch (error) { if (error.code !== 'ENOENT') throw error; }
-        file = candidate;
-        const temporary = path.join(dir, `snapshot-${slot}-${process.pid}-${Math.random().toString(16).slice(2)}.tmp`);
-        try {
-          handle = await fs.open(temporary, 'wx', 0o600);
-          await handle.chmod(0o600);
-          await handle.writeFile(`${JSON.stringify(report, null, 2)}\n`);
-          await handle.close();
-          handle = null;
-          await fs.rename(temporary, file);
-        } catch (error) {
-          if (handle) await handle.close();
-          await fs.unlink(temporary).catch(() => {});
-          file = null;
-          if (attempt === 7) throw error;
-        }
-      }
-      if (!file) throw new Error('no safe snapshot slot available');
-      console.log(`${report.captureStatus} — snapshot saved: ${file}`);
-    } catch {
-      console.error('Capture incomplete: private snapshot could not be saved; OMP untouched.');
-      process.exitCode = 1;
-    }
-  });
-} else {
-  const maxSessions = 32;
-  const maxLogs = 8;
-  const home = option('--omp-home') || path.join(os.homedir(), '.omp');
-  const sessionsRoot = option('--sessions-root') || path.join(home, 'agent', 'sessions');
-  const ownersRoot = option('--owners-root') || path.join(home, 'run', 'session-owners');
-  const logsRoot = option('--logs-root') || path.join(home, 'logs');
-  const explicitSession = option('--session');
-  const packageInfo = JSON.parse(await fs.readFile(new URL('../../package.json', import.meta.url), 'utf8'));
-
-  async function discoverTranscripts(root) {
-    const candidates = [];
-    let truncated = false;
-    try {
-      const rootDir = await fs.opendir(root);
-      let visited = 0;
-      for await (const entry of rootDir) {
-        if (++visited > 128) { truncated = true; break; }
-        if (entry.isFile() && entry.name.endsWith('.jsonl')) candidates.push(path.join(root, entry.name));
-        if (!entry.isDirectory()) continue;
-        let childCount = 0;
-        try {
-          const childDir = await fs.opendir(path.join(root, entry.name));
-          for await (const child of childDir) {
-            if (++childCount > 128 || candidates.length >= maxSessions) { truncated = true; break; }
-            if (child.isFile() && child.name.endsWith('.jsonl')) candidates.push(path.join(root, entry.name, child.name));
-          }
-        } catch { truncated = true; }
-        if (candidates.length >= maxSessions) { truncated = true; break; }
-      }
-      return { state: 'OBSERVED', paths: candidates.slice(0, maxSessions), truncated };
-    } catch { return { state: 'NOT_OBSERVABLE', paths: [], truncated: true }; }
-  }
-
-  async function discoverOwnerIds(root) {
-    try {
-      const dir = await fs.opendir(root);
-      const ids = [];
-      let visited = 0;
-      let truncated = false;
-      for await (const entry of dir) {
-        if (++visited > 128) { truncated = true; break; }
-        if (!entry.isFile() || !entry.name.endsWith('.lock')) continue;
-        const sessionId = entry.name.slice(0, -5);
-        if (/^[\w.-]{1,120}$/.test(sessionId)) ids.push(sessionId);
-        if (ids.length >= maxSessions) { truncated = true; break; }
-      }
-      return { state: 'OBSERVED', ids, truncated };
-    } catch { return { state: 'NOT_OBSERVABLE', ids: [], truncated: true }; }
-  }
-
-  async function runBounded(command, commandArgs, timeout = 650) {
-    return runBoundedProcess(command, commandArgs, { timeoutMs: timeout, maxBuffer: 65536 });
-  }
-
-
-  async function probeOwnerLock(sessionId, rootExists) {
-    if (!rootExists || !/^[\w.-]{1,120}$/.test(sessionId)) return { state: 'NOT_OBSERVABLE', pids: [] };
-    const file = path.join(ownersRoot, `${sessionId}.lock`);
-    try {
-      const stat = await fs.lstat(file);
-      if (!stat.isFile()) return { state: 'NOT_OBSERVABLE', pids: [] };
-    } catch (error) {
-      return error.code === 'ENOENT' ? { state: 'UNHELD', pids: [] } : { state: 'NOT_OBSERVABLE', pids: [] };
-    }
-    if (process.platform === 'win32') {
-      const handles = await runBounded('handle.exe', ['-nobanner', file], 400);
-      if (!handles.ok) return { state: 'NOT_OBSERVABLE', pids: [] };
-      const expected = path.resolve(file).replaceAll('/', '\\').toLowerCase();
-      const matches = handles.stdout.split(/\r?\n/).flatMap((line) => {
-        const match = line.match(/\bpid:\s*(\d+)\s+type:\s*File\b.*?:\s*(.+)$/i);
-        if (!match || match[2].trim().replaceAll('/', '\\').toLowerCase() !== expected) return [];
-        return [Number(match[1])];
-      });
-      const pids = [...new Set(matches)];
-      return pids.length === 1 ? { state: 'OBSERVED', pids } : { state: 'NOT_OBSERVABLE', pids: [] };
-    }
-    const lsof = await runBounded('lsof', ['-t', '--', file], 250);
-    if (lsof.ok) return { state: 'OBSERVED', pids: parseOwnerPids('lsof', lsof.stdout) };
-    if (lsof.exitCode === 1) return /permission|denied|error/i.test(lsof.stderr) ? { state: 'NOT_OBSERVABLE', pids: [] } : { state: 'OBSERVED', pids: [] };
-    if (lsof.errorCode !== 'ENOENT') return { state: 'NOT_OBSERVABLE', pids: [] };
-    const fuser = await runBounded('fuser', ['-f', file], 250);
-    if (fuser.ok) return { state: 'OBSERVED', pids: parseOwnerPids('fuser', `${fuser.stdout}\n${fuser.stderr}`) };
-    if (fuser.exitCode === 1) return /permission|denied|error/i.test(fuser.stderr) ? { state: 'NOT_OBSERVABLE', pids: [] } : { state: 'OBSERVED', pids: [] };
-    return { state: 'NOT_OBSERVABLE', pids: [] };
-  }
-
-
-  async function readProcessInventory() {
-    const [command, commandArgs] = processInventoryCommand(process.platform);
-    const result = await runBounded(command, commandArgs);
-    if (!result.ok) return { state: 'NOT_OBSERVABLE', processes: [], ompProcessCount: null };
-    const processes = parseProcessInventory(process.platform, result.stdout);
-    return { state: 'OBSERVED', processes, ompProcessCount: processes.filter((entry) => /^omp(?:\.exe)?$/i.test(entry.name)).length };
-  }
-
-  async function readOmpLog(pid) {
-    try {
-      const names = [];
-      const directory = await fs.opendir(logsRoot);
-      let visited = 0;
-      for await (const entry of directory) {
-        if (++visited > 256) break;
-        if (entry.isFile() && new RegExp(`^omp\\.\\d{4}-\\d{2}-\\d{2}\\.${pid}\\.log$`).test(entry.name)) names.push(entry.name);
-      }
-      names.sort();
-      const name = names.at(-1);
-      if (!name) return null;
-      const tail = await readBoundedTail(path.join(logsRoot, name), { maxBytes: 32768 });
-      const rows = [];
-      for (const line of tail.text.split('\n')) {
-        try {
-          const row = JSON.parse(line);
-          // Never copy message text, URLs, account fields, headers or response bodies.
-          const timestamp = typeof row.timestamp === 'string' && Number.isFinite(Date.parse(row.timestamp)) ? new Date(row.timestamp).toISOString() : null;
-          rows.push({ timestamp,
-            level: ['debug', 'info', 'warn', 'error'].includes(row.level) ? row.level : null,
-            status: Number.isInteger(row.status) ? row.status : null });
-        } catch { /* Partial log row. */ }
-      }
-      return { pid, bytesRead: tail.bytesRead, rows: rows.slice(-16) };
-    } catch { return null; }
-  }
-
-  let discovery;
-  if (explicitSession) discovery = { state: 'OBSERVED', paths: [explicitSession] };
-  else discovery = await discoverTranscripts(sessionsRoot);
-  const transcriptSessions = [];
-  for (const transcriptPath of discovery.paths.slice(0, maxSessions)) {
-    try {
-      const tail = await readBoundedTail(transcriptPath);
-      const summary = summarizeSessionTail(tail.text);
-      const filenameId = path.basename(transcriptPath).replace(/\.jsonl$/i, '');
-      const uuidFromFilename = /^[a-f0-9]{8}-[a-f0-9]{4}-[1-8][a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/i.test(filenameId) ? filenameId : null;
-      const sessionId = summary.sessionId || uuidFromFilename;
-      const summarySessionId = summary.sessionId;
-      summary.sessionId = sessionId;
-      transcriptSessions.push({ sessionId, transcriptPath, summary, sourceCoverage: { sessionTailBytes: tail.bytesRead, truncated: tail.truncated, sessionIdentityObserved: summarySessionId !== null || uuidFromFilename !== null } });
-    } catch { transcriptSessions.push({ sessionId: null, transcriptPath, summary: null, sourceCoverage: { state: 'NOT_OBSERVABLE' } }); }
-  }
-  const ownerDiscovery = await discoverOwnerIds(ownersRoot);
-  const sessions = [...transcriptSessions];
-  for (const sessionId of ownerDiscovery.ids) if (!sessions.some((entry) => entry.sessionId === sessionId)) sessions.push({ sessionId, transcriptPath: null, summary: null, sourceCoverage: { state: 'NOT_OBSERVABLE' } });
-  const boundedSessions = sessions.slice(0, maxSessions);
-  const ownerRootExists = ownerDiscovery.state === 'OBSERVED';
-  const [ownerResults, processInventory] = await Promise.all([
-    Promise.all(boundedSessions.filter((entry) => entry.sessionId).map(async (entry) => [entry.sessionId, await probeOwnerLock(entry.sessionId, ownerRootExists)])),
-    readProcessInventory(),
-  ]);
-  const ownerLocks = Object.fromEntries(ownerResults);
-  const logs = (await Promise.all([...new Set(ownerResults.flatMap(([, lock]) => lock.state === 'OBSERVED' ? lock.pids : []))].slice(0, maxLogs).map(readOmpLog))).filter(Boolean);
-  const associations = associateSessionEvidence({ sessions: boundedSessions, ownerLocks, processInventory, logs });
-  const snapshots = associations.map((association, index) => {
-    const source = boundedSessions[index];
-    const summary = source.summary;
-    const sessionActivity = classifySessionActivity({ association: association.sessionAssociation, summary });
-    return { ...association, sessionActivity, ...(summary || {}), sourceCoverage: source.sourceCoverage };
-  });
-  const activeOwners = snapshots.filter((entry) => entry.sessionAssociation === 'ACTIVE_OWNER');
-  const allLocksUnheld = ownerResults.length === boundedSessions.filter((entry) => entry.sessionId).length
-    && ownerResults.every(([, lock]) => lock.state === 'UNHELD');
-  const coverageComplete = !discovery.truncated && !ownerDiscovery.truncated && sessions.length <= maxSessions;
-  const transcriptsFullyIdentified = transcriptSessions.every((entry) => entry.sessionId !== null);
-  const executionState = activeOwners.length ? 'EXECUTING'
-    : coverageComplete && transcriptsFullyIdentified && ownerDiscovery.state === 'OBSERVED' && processInventory.state === 'OBSERVED'
-      && processInventory.ompProcessCount === 0 && allLocksUnheld ? 'NO_EXECUTION' : 'NOT_OBSERVABLE';
-  const activity = activeOwners.length === 1 ? activeOwners[0].sessionActivity
-    : activeOwners.length > 1 ? 'MULTIPLE_ACTIVE_SESSIONS' : executionState === 'NO_EXECUTION' ? 'NO_EXECUTION' : 'NOT_OBSERVABLE';
-  const captureStatus = activeOwners.length > 0 && activeOwners.every((entry) => entry.sourceCoverage && entry.summary)
-    && discovery.state === 'OBSERVED' && !discovery.truncated && ownerDiscovery.state === 'OBSERVED' && !ownerDiscovery.truncated
-    && processInventory.state === 'OBSERVED' && ownerResults.every(([, lock]) => lock.state === 'OBSERVED' || lock.state === 'UNHELD')
-    && snapshots.every((entry) => entry.sessionId !== null && entry.identityVerified) ? 'CAPTURE_READY' : 'CAPTURE_PARTIAL';
-  const snapshot = buildStallSnapshot({ executionState, activity, captureStatus,
-    sessionDiscovery: discovery.state, ownerLockDiscovery: ownerDiscovery.state,
-    processInventory: { state: processInventory.state, ompProcessCount: processInventory.ompProcessCount },
-    sessions: snapshots, ompVersion: 'NOT_OBSERVABLE', ukitVersion: packageInfo.version,
-    limitations: ['Persisted transcript events do not prove live stream or gateway state.', 'Unobservable ownership and operation states remain NOT_OBSERVABLE.', 'No OMP freeze root cause is inferred.'] });
-  process.stdout.write(JSON.stringify(snapshot) + '\n');
-}