@ngockhoale/ukit 3.4.46 → 3.4.47

package/CHANGELOG.md

@@ -2,13 +2,13 @@
 
 All notable changes to UKit are documented here.
 
-## Unreleased
-
-**`/ukit:ci-check`: manual-only cross-platform CI (not yet released; no version bump).**
-- `cross-platform-ci.yml` is now `workflow_dispatch` only (push trigger removed). No push/pull_request/schedule/workflow_run path can start CI.
-- New `/ukit:ci-check` command + `ci-check.mjs` helper (core pack): prechecks, fail-closed budget guard, local preflight, at most one dispatch per invocation, write-ahead run-id state, `status` (never dispatches), `--ref`, `--dry-run`, per-OS report. Never pushes, merges or publishes.
-- Default-branch bootstrap stub documented in `docs/design/CI-CROSS-PLATFORM-MATRIX.md` (requires separate approval).
+## 3.4.47 - 2026-10-18
 
+**Supervisor subagent usage attribution and rendered-instruction parity checks.**
+- Record subagent usage at the supervisor's terminal completion/cancellation boundary, using typed operation metadata and existing exactly-once guards. Provider-authenticated usage remains blocked; host transcript values are not relabeled as provider data.
+- Add read-only `render-instructions.mjs --parity` to byte-compare rendered root instructions with existing root files, including fixture-target support and drift diagnostics.
+- Add manual-only `/ukit:ci-check` cross-platform CI tooling; it remains opt-in and never pushes, merges, or publishes.
+- Locally verified on macOS/Node 22. Q-C98-1 and Q-C98-3 remain blocked on provider-authenticated data/privacy approval; no provider identity/pricing/cache model is claimed.
 ## 3.4.46 - 2026-10-18
 
 **Completion contract P0: forensic intent, attributable release evidence and conditional NO-GO.**

package/package.json

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

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

@@ -0,0 +1,246 @@
+#!/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');
+}

package/scripts/docs/render-instructions.mjs

@@ -1,8 +1,11 @@
 #!/usr/bin/env node
 // DOC-102 renderer CLI (SPEC §8.2).
 //   node scripts/docs/render-instructions.mjs --write   (default) regenerate all outputs
-//   node scripts/docs/render-instructions.mjs --check   print DRIFT <path> per mismatch, exit 1
+//   node scripts/docs/render-instructions.mjs --parity  check installed root instructions read-only
+// `--parity` takes precedence over `--check`/`--write`; `--parity-root` overrides only the
+// comparison target directory for fixture/testing use, never the source/layout root.
 import path from 'node:path';
+import fs from 'node:fs';
 import { fileURLToPath } from 'node:url';
 
 import {
@@ -12,18 +15,39 @@ import {
 
 const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
 
-const USAGE = 'usage: render-instructions.mjs [--write|--check]';
 
+const USAGE = 'usage: render-instructions.mjs [--write|--check|--parity] [--parity-root <dir>]';
 const args = process.argv.slice(2);
-const unknown = args.filter((a) => a !== '--write' && a !== '--check');
-if (unknown.length > 0) {
-  console.error(`${USAGE}\nunknown flag: ${unknown[0]}`);
+const parityRootArg = args.indexOf('--parity-root');
+const parityRoot = parityRootArg === -1 ? repoRoot : path.resolve(args[parityRootArg + 1] || '');
+const unknown = args.filter((a, i) => a !== '--write' && a !== '--check' && a !== '--parity'
+  && a !== '--parity-root' && !(parityRootArg !== -1 && i === parityRootArg + 1));
+if (unknown.length > 0 || (parityRootArg !== -1 && !args[parityRootArg + 1])) {
+  console.error(`${USAGE}\nunknown flag or missing value: ${unknown[0] || '--parity-root'}`);
+  process.exit(2);
+}
+if (parityRootArg !== -1 && !args.includes('--parity')) {
+  console.error(`${USAGE}\n--parity-root requires --parity`);
   process.exit(2);
 }
 
 const mode = args.includes('--check') ? 'check' : 'write';
+const parity = args.includes('--parity');
 
 try {
+  if (parity) {
+    const rendered = await renderInstructionsFromDisk({ repoRoot, write: false });
+    const targets = [...rendered].filter(([target]) => target === 'CLAUDE.md' || target === 'AGENTS.md');
+    const drift = targets.filter(([target, content]) => {
+      const file = path.join(parityRoot, target);
+      return !fs.existsSync(file) || !fs.readFileSync(file).equals(Buffer.from(content));
+    });
+    for (const [target] of drift) console.log(`DRIFT ${target}`);
+    if (drift.length > 0) process.exit(1);
+    console.log(`PARITY OK ${targets.length} files`);
+    process.exit(0);
+  }
+
   if (mode === 'check') {
     const drift = await checkRenderedInstructions({ repoRoot });
     for (const target of drift) {

package/src/core/agentRuntime/supervisor.js

@@ -47,8 +47,8 @@ import {
   durationMs,
   reasonCodeForFailure,
   projectRootFromRuntimeDir,
+  recordSubagentUsage,
 } from './telemetry.js';
-
 const SUPERVISOR_FLAG = 'decisionRuntime.supervisor.stage';
 // G6 (DR-09): `decisionRuntime.promotion.stage` — absent/malformed → 'off';
 // 'shadow' consults selectWaitPolicy at the caller-wait decision and records a
@@ -396,6 +396,13 @@ export function createSupervisor(opts = {}) {
             errorCode: reasonCodeForFailure({ cancelReason: op.cancelReason ?? 'cancel_requested' }),
             exitCode: op.exitInfo?.code,
           });
+          if (op.spansClosed) {
+            recordSubagentUsage(telemetry, op.telemetryCtx, {
+              components: op.spec?.subagentUsage?.components,
+              parentRunId: op.spec?.parentRunId,
+              usage: op.spec?.subagentUsage?.usage,
+            });
+          }
         });
       }
     }, limits.killGraceMs));
@@ -521,6 +528,13 @@ export function createSupervisor(opts = {}) {
         exitCode: op.exitInfo?.code,
       });
     }
+    if (op.spansClosed) {
+      recordSubagentUsage(telemetry, op.telemetryCtx, {
+        components: op.spec?.subagentUsage?.components,
+        parentRunId: op.spec?.parentRunId,
+        usage: op.spec?.subagentUsage?.usage,
+      });
+    }
   }
 
   function onExit(op, code, signal) {

package/src/diagnostics/ompStallSnapshot.js

@@ -0,0 +1,199 @@
+// Development-only incident capture: bounded metadata, no session control or payload persistence.
+import fs from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { spawn } from 'node:child_process';
+
+const ID_PATTERN = /^[\w.:/-]{1,120}$/;
+const id = (value) => typeof value === 'string' && ID_PATTERN.test(value) ? value : null;
+const time = (value) => Number.isFinite(Date.parse(value)) ? new Date(value).toISOString() : null;
+
+
+export async function runBoundedProcess(command, args = [], { timeoutMs = 650, maxBuffer = 65536 } = {}) {
+  return new Promise((resolve) => {
+    let settled = false;
+    let timedOut = false;
+    let oversized = false;
+    let stdoutBytes = 0;
+    let stderrBytes = 0;
+    const stdout = [];
+    const stderr = [];
+    let timer;
+    const finish = (result) => { if (!settled) { settled = true; clearTimeout(timer); resolve(result); } };
+    let child;
+    try { child = spawn(command, args, { stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true }); }
+    catch (error) { resolve({ ok: false, errorCode: error.code || 'UNKNOWN', stdout: '', stderr: '' }); return; }
+    timer = setTimeout(() => { timedOut = true; child.kill('SIGKILL'); }, Math.max(1, timeoutMs));
+    const collect = (chunks, field) => (chunk) => {
+      const next = field === 'stdout' ? stdoutBytes + chunk.length : stderrBytes + chunk.length;
+      if (next + (field === 'stdout' ? stderrBytes : stdoutBytes) > maxBuffer) { oversized = true; child.kill('SIGKILL'); return; }
+      chunks.push(chunk);
+      if (field === 'stdout') stdoutBytes = next; else stderrBytes = next;
+    };
+    child.stdout.on('data', collect(stdout, 'stdout'));
+    child.stderr.on('data', collect(stderr, 'stderr'));
+    child.on('error', (error) => finish({ ok: false, errorCode: error.code || 'UNKNOWN', stdout: '', stderr: '' }));
+    child.on('close', (code) => finish({ ok: !timedOut && !oversized && code === 0,
+      errorCode: timedOut ? 'ETIMEDOUT' : oversized ? 'MAXBUFFER' : code === 0 ? null : 'EXIT_NONZERO',
+      exitCode: code, stdout: Buffer.concat(stdout).toString('utf8'), stderr: Buffer.concat(stderr).toString('utf8') }));
+  });
+}
+
+export async function readBoundedTail(file, { maxBytes = 262144 } = {}) {
+  const cap = Math.max(1, Math.min(1048576, maxBytes));
+  const handle = await fs.open(file, constants.O_RDONLY | (constants.O_NONBLOCK || 0) | (constants.O_NOFOLLOW || 0));
+  try {
+    const stat = await handle.stat();
+    if (!stat.isFile()) throw new Error('capture requires a regular file');
+    const size = Math.min(cap, stat.size);
+    const buffer = Buffer.alloc(size);
+    const { bytesRead } = await handle.read(buffer, 0, size, Math.max(0, stat.size - size));
+    let text = buffer.subarray(0, bytesRead).toString('utf8');
+    const truncated = stat.size > size;
+    if (truncated) text = text.includes('\n') ? text.slice(text.indexOf('\n') + 1) : '';
+    return { text, bytesRead, truncated, size: stat.size, modifiedAt: stat.mtimeMs };
+  } finally { await handle.close(); }
+}
+
+const operationKinds = ['model', 'tool', 'hook', 'subagent'];
+const activeStates = new Set(['started', 'running', 'pending', 'waiting']);
+const terminalStates = new Set(['completed', 'finished', 'failed', 'stopped', 'cancelled']);
+export function processInventoryCommand(platform) {
+  return platform === 'win32' ? ['tasklist', ['/FO', 'CSV', '/NH']]
+    : ['ps', ['-A', '-o', 'pid=,ppid=,stat=,etime=,comm=']];
+}
+
+export function parseProcessInventory(platform, text) {
+  if (platform === 'win32') return text.split(/\r?\n/).flatMap((line) => {
+    const fields = line.match(/"(?:[^"]|"")*"|[^,]+/g) || [];
+    const name = fields[0]?.replace(/^"|"$/g, '').replace(/""/g, '"');
+    const pid = Number(fields[1]?.replaceAll('"', ''));
+    return Number.isSafeInteger(pid) && pid > 0 ? [{ pid, name: (name || '').split(/[\\/]/).at(-1) }] : [];
+  });
+  return text.split('\n').flatMap((line) => {
+    const match = line.match(/^\s*(\d+)\s+(\d+)\s+(\S+)\s+(\S+)\s+(.+)$/);
+    return match ? [{ pid: Number(match[1]), name: match[5].trim().split(/[\\/]/).at(-1) }] : [];
+  });
+}
+
+export function parseOwnerPids(command, text) {
+  const values = command === 'fuser' ? (text.match(/:\s*([^\r\n]+)/g) || []).flatMap((line) => line.slice(line.indexOf(':') + 1).trim().split(/\s+/).map((token) => token.match(/^(\d+)[A-Za-z]*$/)?.[1]).filter(Boolean))
+    : (text.match(/\b\d+\b/g) || []);
+  return [...new Set(values.map(Number).filter((pid) => Number.isSafeInteger(pid) && pid > 0))];
+}
+
+export function classifySessionActivity({ association = 'NOT_OBSERVABLE', summary = null, now = Date.now(), idleMs = 120000 } = {}) {
+  if (summary?.operatorBlock === 'OBSERVED_BLOCK') return 'OPERATOR_BLOCK';
+  if (summary?.sessionState === 'STOPPED') return 'STOPPED';
+  if (association !== 'ACTIVE_OWNER' || !summary) return 'NOT_OBSERVABLE';
+  const progressAge = Number.isFinite(summary.lastProgressAt) ? Math.max(0, now - summary.lastProgressAt) : null;
+  const outputAge = Number.isFinite(summary.lastOutputAt) ? Math.max(0, now - summary.lastOutputAt) : null;
+  const pending = summary.pendingOperations || {};
+  if (progressAge === null) return 'NOT_OBSERVABLE';
+  if (progressAge >= idleMs) return 'SUSPECTED_STALL';
+  if (Object.values(pending).some((items) => Array.isArray(items) && items.length > 0)
+    && Object.entries(pending).some(([kind, items]) => items.length > 0 && summary.operationObservability?.[kind] === 'OBSERVED')) return 'WAITING';
+  if (outputAge !== null && outputAge >= idleMs) return 'NO_OUTPUT';
+  return 'ACTIVE_PROGRESS';
+}
+
+
+export function summarizeSessionTail(text) {
+  const result = { sessionId: null, modelAlias: 'NOT_OBSERVABLE', resolvedRoute: 'NOT_OBSERVABLE', currentTurn: 'NOT_OBSERVABLE', lastCompletedTurn: 'NOT_OBSERVABLE',
+    pendingModelRequest: 'NOT_OBSERVABLE', lastChunk: 'NOT_OBSERVABLE', terminalEvent: 'NOT_OBSERVABLE', pendingTools: [], unmatchedToolCallCandidates: [], pendingSubagent: 'NOT_OBSERVABLE',
+    pendingOperations: { model: [], tool: [], hook: [], subagent: [] }, operationObservability: { model: 'NOT_OBSERVABLE', tool: 'NOT_OBSERVABLE', hook: 'NOT_OBSERVABLE', subagent: 'NOT_OBSERVABLE' },
+    operatorBlock: 'NOT_OBSERVABLE', turnState: 'NOT_OBSERVABLE', sessionState: 'NOT_OBSERVABLE', compaction: 'NOT_OBSERVABLE', stopContinuation: 'NOT_OBSERVABLE',
+    lastProgressAt: 'NOT_OBSERVABLE', lastOutputAt: 'NOT_OBSERVABLE', outputState: 'NOT_OBSERVABLE' };
+  const operations = Object.fromEntries(operationKinds.map((kind) => [kind, new Map()]));
+  const tools = new Map();
+  const observedOperations = new Set();
+  const operatorBlocks = new Map();
+  for (const line of text.split('\n')) {
+    let row;
+    try { row = JSON.parse(line); } catch { continue; }
+    const ts = time(row.timestamp);
+    if (ts) result.lastProgressAt = Date.parse(ts);
+    if (row.type === 'session' && id(row.id)) { result.sessionId = id(row.id); result.sessionIdentityObserved = true; }
+    if (row.type === 'compaction') result.compaction = { timestamp: ts, id: id(row.id), tokensBefore: Number.isFinite(row.tokensBefore) ? row.tokensBefore : null };
+    if (row.type === 'session_end' || row.type === 'session_stopped') result.sessionState = 'STOPPED';
+
+    if (row.type === 'operation' && operationKinds.includes(row.operation) && id(row.id)) {
+      observedOperations.add(row.operation);
+      const state = typeof row.state === 'string' ? row.state.toLowerCase() : '';
+      if (activeStates.has(state)) operations[row.operation].set(row.id, { id: row.id, ...(id(row.name) ? { name: id(row.name) } : {}) });
+      if (terminalStates.has(state)) operations[row.operation].delete(row.id);
+    }
+    const eventState = String(row.state || '').toLowerCase();
+    if (row.type === 'operator_block' || row.operation === 'operator') {
+      const key = id(row.id) || `block-${operatorBlocks.size}`;
+      if (['pending', 'blocked', 'waiting'].includes(eventState)) operatorBlocks.set(key, { id: id(row.id), state: 'BLOCKED' });
+      if (terminalStates.has(eventState) || ['unblocked', 'cleared'].includes(eventState)) operatorBlocks.delete(key);
+    }
+
+    const message = row.message;
+    if (!message) continue;
+    if (message.role === 'toolResult' && id(message.toolCallId)) tools.delete(message.toolCallId);
+    if (message.role !== 'assistant') continue;
+    result.modelAlias = { provider: id(message.provider), model: id(message.model) };
+    if (message.stopReason) {
+      const stopReason = ['stop', 'toolUse', 'error', 'aborted', 'length'].includes(message.stopReason) ? message.stopReason : 'other';
+      result.lastCompletedTurn = { id: id(row.id), timestamp: ts, stopReason };
+      result.terminalEvent = stopReason;
+      result.turnState = message.stopReason === 'aborted' ? 'TURN_ABORTED' : message.stopReason === 'error' ? 'TURN_ERROR' : 'TURN_COMPLETED';
+    }
+    if (Array.isArray(message.content)) {
+      for (const part of message.content) {
+        if (part.type === 'toolCall' && id(part.id)) tools.set(part.id, { id: id(part.id), name: id(part.name) });
+        if (part.type === 'text' && ts) {
+          result.lastOutputAt = Date.parse(ts);
+          result.outputState = 'OBSERVED_OUTPUT';
+        }
+      }
+    }
+  }
+  result.unmatchedToolCallCandidates = [...tools.values()].slice(-32);
+  result.pendingOperations = Object.fromEntries(operationKinds.map((kind) => [kind, [...operations[kind].values()].slice(-32)]));
+  result.pendingTools = result.pendingOperations.tool;
+  result.operationObservability = Object.fromEntries(operationKinds.map((kind) => [kind, observedOperations.has(kind) || (kind === 'tool' && tools.size > 0) ? 'OBSERVED' : 'NOT_OBSERVABLE']));
+  result.pendingModelRequest = result.operationObservability.model === 'OBSERVED' ? (result.pendingOperations.model.length ? 'OBSERVED_PENDING_EVENT' : 'NO_PENDING_EVENT_OBSERVED') : 'NOT_OBSERVABLE';
+  result.pendingSubagent = result.operationObservability.subagent === 'OBSERVED' ? (result.pendingOperations.subagent.length ? 'OBSERVED_PENDING_EVENT' : 'NO_PENDING_EVENT_OBSERVED') : 'NOT_OBSERVABLE';
+  result.operatorBlock = operatorBlocks.size ? 'OBSERVED_BLOCK' : 'NOT_OBSERVABLE';
+  return result;
+}
+
+export function associateSessionEvidence({ sessions = [], ownerLocks = {}, processInventory = { state: 'NOT_OBSERVABLE', processes: [] }, logs = [] } = {}) {
+  const sessionCounts = new Map();
+  for (const session of sessions) if (id(session.sessionId)) sessionCounts.set(session.sessionId, (sessionCounts.get(session.sessionId) || 0) + 1);
+  return sessions.map((session) => {
+    const sessionId = id(session.sessionId);
+    const lock = sessionId ? ownerLocks[sessionId] : null;
+    const lockState = lock?.state || 'NOT_OBSERVABLE';
+    const pids = lockState === 'OBSERVED' && Array.isArray(lock.pids) ? [...new Set(lock.pids.filter((pid) => Number.isSafeInteger(pid) && pid > 0))] : [];
+    const uniqueOwnerPid = pids.length === 1 ? pids[0] : null;
+    const duplicateSession = sessionId !== null && sessionCounts.get(sessionId) > 1;
+    const process = uniqueOwnerPid !== null && processInventory.state === 'OBSERVED'
+      ? processInventory.processes.find((entry) => entry.pid === uniqueOwnerPid && /^omp(?:\.exe)?$/i.test(entry.name)) || null : null;
+    const processAssociation = duplicateSession ? 'AMBIGUOUS_TRANSCRIPT' : pids.length > 1 ? 'AMBIGUOUS_OWNER_LOCK'
+      : uniqueOwnerPid === null ? (lockState === 'NOT_OBSERVABLE' ? 'NOT_OBSERVABLE' : 'UNHELD')
+        : processInventory.state !== 'OBSERVED' ? 'NOT_OBSERVABLE' : process ? 'VERIFIED' : 'PID_NOT_FOUND';
+    const ownerPid = duplicateSession ? null : uniqueOwnerPid;
+    const identityVerified = session?.sessionIdentityObserved === true || session?.sourceCoverage?.sessionIdentityObserved === true;
+    const ompLog = ownerPid === null ? null : logs.find((entry) => entry.pid === ownerPid) || null;
+    const logAssociation = ownerPid === null ? 'NOT_OBSERVABLE' : ompLog ? 'VERIFIED' : 'NOT_OBSERVABLE';
+    return { sessionId, transcript: typeof session.transcriptPath === 'string' ? session.transcriptPath.split(/[\\/]/).at(-1) : null,
+      sessionAssociation: identityVerified && processAssociation === 'VERIFIED' && logAssociation === 'VERIFIED' ? 'ACTIVE_OWNER' : 'NOT_OBSERVABLE',
+      ownerLockState: duplicateSession ? 'AMBIGUOUS_TRANSCRIPT' : lockState, ownerPid, processAssociation, logAssociation, identityVerified,
+      process: process ? { pid: process.pid, name: id(process.name) } : null, ompLog };
+  });
+}
+
+export function buildStallSnapshot({ now = Date.now(), lastProgressAt = null, lastOutputAt = null, idleMs = 120000, executionState = 'NOT_OBSERVABLE', ...evidence } = {}) {
+  const age = (ts) => Number.isFinite(ts) ? Math.max(0, now - ts) : null;
+  const progressAgeMs = age(lastProgressAt);
+  const outputAgeMs = age(lastOutputAt);
+  const activity = evidence.activity || (executionState === 'NO_EXECUTION' ? 'NO_EXECUTION'
+    : executionState !== 'EXECUTING' ? 'NOT_OBSERVABLE'
+      : progressAgeMs === null ? 'NOT_OBSERVABLE' : progressAgeMs >= idleMs ? 'NO_OBSERVED_PROGRESS'
+        : outputAgeMs !== null && outputAgeMs >= idleMs ? 'NO_OUTPUT' : 'RECENT_PROGRESS');
+  return { schemaVersion: 1, capturedAt: new Date(now).toISOString(), verdict: 'INSUFFICIENT_EVIDENCE', activity,
+    executionState, progressAgeMs, outputAgeMs, ...evidence };
+}

package/template_project/.claude/ukit/runtime/stop-coordinator.mjs

@@ -1966,6 +1966,7 @@ export async function runStopCoordinator({
     await captureUsageShadow({ projectRoot, payload });
   } catch { /* advisory */ }
 
+
   // TASK-005 (FR-005): the coordinator's terminal verdict lands ONE
   // `outcome.observed` record per coordinated stop — the merged evaluator
   // decision is the session's honest outcome at this stop. Fire-and-forget: