@ngockhoale/ukit 2.4.2 → 2.5.0

package/templates/.claude/ukit/runtime/task-watchdog.mjs

@@ -2,10 +2,14 @@
 /**
  * task-watchdog.mjs — wall-clock watchdog runtime for handoff tasks.
  *
- * Self-contained runtime module. No imports from `src/`, no sibling imports
- * beyond `node:` builtins (the `token-utils` file lock is intentionally NOT
- * used — file-locking watchdog state under a Stop hook with a 4s budget is a
- * recipe for getting killed mid-write by its own chain).
+ * Self-contained runtime module. No imports from `src/`; the one allowed sibling
+ * import is the shared hook async-lock runtime (TASK-028, `./async-lock.mjs`) —
+ * since TASK-024, every state mutation is a lock-scoped read-modify-write through
+ * it, because atomic temp+rename alone still loses updates when two concurrent
+ * Stop hooks read-modify-write the same counters (last-writer-wins). The lock's
+ * budget-capped, never-callback-unlocked design keeps the mutation inside the
+ * hook deadline: an expired acquisition budget is a typed fail-open outcome, and
+ * nothing is ever written unlocked.
  *
  * Exports:
  *   DEFAULT_CONFIG                — fail-open defaults; identical to the
@@ -23,7 +27,19 @@
  *   readState(statePath) / writeState(statePath, value) —
  *                                   `.ukit/storage/cache/task-watchdog/state.json`,
  *                                   shape { firstSeen, hardBlocks }; any I/O error
- *                                   → treat as empty, never throw.
+ *                                   → treat as empty, never throw. writeState is
+ *                                   the low-level persist helper — call it only
+ *                                   from inside mutateWatchdogState (or tests).
+ *   mutateWatchdogState(statePath, updater, {signal, deadlineMs}) —
+ *                                   the ONLY way to mutate state: one lock-scoped
+ *                                   read → updater → write. Committed state, or a
+ *                                   typed `lock-timeout` outcome with no mutation.
+ *   evaluateStopWatchdog({...})   — TASK-025: the Stop-branch evaluation extracted
+ *                                   from task-watchdog.sh's heredoc. Returns a
+ *                                   normalized { kind, reason?, systemMessage? }
+ *                                   result for the stop coordinator, which merges
+ *                                   it with the completion gate's decision and
+ *                                   emits at most one Stop decision.
  *
  * The hard clock does not reset on Progress appends on purpose: trickling entries
  * every 4 minutes must not buy an unlimited task. The newest Progress timestamp is
@@ -33,6 +49,8 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 
+import { withAsyncLock } from './async-lock.mjs';
+
 // ─── Defaults ─────────────────────────────────────────────────────────────
 export const DEFAULT_CONFIG = Object.freeze({
   taskBudgets: {
@@ -126,15 +144,65 @@ export async function readState(statePath) {
 
 export async function writeState(statePath, value) {
   if (!statePath) return;
+  let tempPath = null;
   try {
     await fs.mkdir(path.dirname(statePath), { recursive: true });
     // temp + rename to avoid leaving a half-written state file if the hook is killed.
-    const tempPath = `${statePath}.${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}.tmp`;
+    tempPath = `${statePath}.${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}.tmp`;
     await fs.writeFile(tempPath, `${JSON.stringify(value, null, 1)}\n`, 'utf8');
     await fs.rename(tempPath, statePath);
+    tempPath = null; // renamed into place — nothing left to clean up
   } catch {
     // Fail-open: never throw from state writes.
+  } finally {
+    if (tempPath) {
+      // TASK-024: a failed write/rename must not leak its temp file.
+      try {
+        await fs.rm(tempPath, { force: true });
+      } catch {}
+    }
+  }
+}
+
+/**
+ * Lock-scoped read-modify-write of the watchdog state file (TASK-024). The ONLY
+ * sanctioned way to mutate state: read → updater → write all happen inside one
+ * `withAsyncLock` acquisition, so concurrent Stop hooks can never lose each
+ * other's firstSeen anchors or hard-block counts to last-writer-wins.
+ *
+ * The updater receives the freshly read state and mutates it in place (matching
+ * the existing ensureFirstSeen / bumpHardBlocks helpers); its return value is
+ * ignored and the mutated state is what gets persisted. An expired acquisition
+ * budget or an aborted signal is a typed fail-open outcome: the updater NEVER
+ * runs unlocked and nothing is written — the caller picks the policy.
+ *
+ * @param {string} statePath - state file to mutate (lock lives beside it)
+ * @param {(state: { firstSeen: Record<string, number>, hardBlocks: Record<string, number> }) => (void | Promise<void>)} updater
+ * @param {{ signal?: AbortSignal, deadlineMs?: number }} [options]
+ * @returns {Promise<{ ok: true, state: * } | { ok: false, reason: 'lock-timeout' | 'aborted', waitedMs: number }>}
+ *   committed state, or the typed no-mutation outcome
+ */
+export async function mutateWatchdogState(statePath, updater, { signal, deadlineMs } = {}) {
+  if (typeof statePath !== 'string' || !statePath) {
+    throw new TypeError('mutateWatchdogState(statePath, updater, options) requires a state path');
+  }
+  if (typeof updater !== 'function') {
+    throw new TypeError('mutateWatchdogState(statePath, updater, options) requires an updater function');
   }
+  const outcome = await withAsyncLock(statePath, { signal, deadlineMs }, async () => {
+    const state = await readState(statePath);
+    await updater(state);
+    await writeState(statePath, state);
+    return state;
+  });
+  if (outcome.ok) {
+    return { ok: true, state: outcome.value };
+  }
+  // 'busy' (acquisition budget expired) is what the watchdog interface names a
+  // lock-timeout; 'aborted' passes through unchanged. Either way nothing ran.
+  return outcome.reason === 'aborted'
+    ? { ok: false, reason: 'aborted', waitedMs: outcome.waitedMs }
+    : { ok: false, reason: 'lock-timeout', waitedMs: outcome.waitedMs };
 }
 
 // ─── Task parser ──────────────────────────────────────────────────────────
@@ -297,3 +365,109 @@ export function pickLastGreen(task) {
   if (!task?.lastProgressIso) return null;
   return { iso: task.lastProgressIso, label: 'milestone' };
 }
+
+// ─── Stop evaluation (TASK-025) ───────────────────────────────────────────
+/**
+ * Evaluate the watchdog policy for ONE Stop event and return a normalized result
+ * the stop coordinator (stop-coordinator.mjs) can merge with the completion gate's
+ * decision:
+ *   { kind: 'block', reason }
+ *   { kind: 'advisory', systemMessage }
+ *   { kind: 'none' }
+ *
+ * Semantics are the extracted Stop branch of task-watchdog.sh, unchanged:
+ * anchors firstSeen once per task in one lock-scoped read-modify-write, then
+ * evaluates budgets; split policy + hard trip bumps the task's hardBlocks counter
+ * exactly once (cap-checked inside the same critical section); pause policy and
+ * degraded/cap-exhausted paths are advisory only and never emit a decision.
+ *
+ * Throws on infrastructure failure — the coordinator owns the failure policy
+ * (advisory lane: reported verbatim, never blocking the completion decision).
+ *
+ * @param {object} [options]
+ * @param {string} options.projectRoot - installed project root
+ * @param {number} [options.now] - evaluation clock (epochMs)
+ * @param {object} [options.config] - pre-loaded config (defaults to loadConfig of
+ *   `<root>/.ukit/storage/config.json`, fail-open defaults)
+ * @param {Array} [options.tasks] - pre-discovered in_progress tasks (defaults to
+ *   listInProgressTasks(projectRoot))
+ * @param {number} [options.lockBudgetMs] - per-acquisition lock budget; the
+ *   coordinator passes a short slice so two acquisitions fit the hook deadline
+ */
+export async function evaluateStopWatchdog({ projectRoot, now = Date.now(), config = null, tasks = null, lockBudgetMs } = {}) {
+  if (!config) config = await loadConfig(path.join(projectRoot, '.ukit', 'storage', 'config.json'));
+  if (!tasks) tasks = await listInProgressTasks(projectRoot);
+
+  const statePath = path.join(projectRoot, '.ukit', 'storage', 'cache', 'task-watchdog', 'state.json');
+  const state = await readState(statePath);
+  const lockOptions = Number.isFinite(lockBudgetMs) ? { deadlineMs: lockBudgetMs } : {};
+
+  // Anchor firstSeen via one lock-scoped read-modify-write (TASK-024 semantics).
+  try {
+    await mutateWatchdogState(statePath, (fresh) => {
+      for (const task of tasks) {
+        try {
+          ensureFirstSeen(fresh, task.id, now);
+        } catch {}
+      }
+    }, lockOptions);
+  } catch {}
+
+  const evals = evaluateBudgets({ tasks, state, now, config });
+  const hardResults = evals.filter((r) => r.phase === 'hard');
+  const softResults = evals.filter((r) => r.phase === 'soft');
+
+  if (hardResults.length === 0) {
+    if (softResults.length > 0) {
+      return {
+        kind: 'advisory',
+        systemMessage: softResults.map((r) => describeSoft(r, r.id)).join('\n'),
+      };
+    }
+    return { kind: 'none' };
+  }
+
+  const hardPolicy = String(config.taskBudgets?.hardPolicy || 'split');
+  const firstHard = hardResults[0];
+
+  if (hardPolicy !== 'split') {
+    // pause (or anything non-split) → advisory only, never a decision.
+    return {
+      kind: 'advisory',
+      systemMessage: hardResults.map((r) => describePause({ id: r.id, result: r })).join('\n'),
+    };
+  }
+
+  // split policy + hard trip: the cap check and the bump are ONE lock-scoped
+  // read-modify-write — one invocation bumps at most once (TASK-024).
+  let bumped = false;
+  const bumpOutcome = await mutateWatchdogState(statePath, (fresh) => {
+    const current = Number(fresh.hardBlocks[firstHard.id] || 0);
+    if (current >= (HARD_BLOCK_CAP || 2)) return;
+    try {
+      bumpHardBlocks(fresh, firstHard.id);
+      bumped = true;
+    } catch {}
+  }, lockOptions);
+  const persistedBlocks = Number(
+    (bumpOutcome.ok ? bumpOutcome.state : state)?.hardBlocks?.[firstHard.id] || 0,
+  );
+
+  if (!bumpOutcome.ok || !bumped) {
+    return {
+      kind: 'advisory',
+      systemMessage: describeDegraded({ id: firstHard.id, hardBlocks: persistedBlocks }),
+    };
+  }
+
+  const task = tasks.find((t) => t.id === firstHard.id) || { id: firstHard.id };
+  return {
+    kind: 'block',
+    reason: describeSplitReason({
+      id: firstHard.id,
+      result: firstHard,
+      hardBlocks: persistedBlocks,
+      lastGreen: pickLastGreen(task),
+    }),
+  };
+}

package/templates/.claude/ukit/runtime/transcript-tail.mjs

@@ -30,7 +30,7 @@ function positiveInteger(value, fallback) {
 }
 
 async function scanOnce(filePath, maxBytes) {
-  const cap = positiveInteger(maxBytes, DEFAULT_TAIL_MAX_BYTES);
+  const cap = Math.min(positiveInteger(maxBytes, DEFAULT_TAIL_MAX_BYTES), DEFAULT_TAIL_MAX_BYTES);
   const stat = await fsp.stat(filePath);
   if (!stat.isFile() || stat.size <= 0) {
     return EMPTY_RESULT();

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

@@ -18,6 +18,17 @@ import {
   readRouteState,
   recordExecutionReceipt,
 } from '../../../.claude/ukit/runtime/execution-ledger.mjs';
+import {
+  PAYLOAD_INLINE_MAX_BYTES,
+  createPayloadReference,
+  maybeSweepStalePayloads,
+  probePayloadIntegrity,
+} from '../../../.claude/ukit/runtime/hook-payload-store.mjs';
+// TASK-018 review fix round 1: the chain budget is resolved by ONE shared module,
+// so the runner's inner deadline and this bridge's outer pi.exec timeout can never
+// drift apart (a configured 60-120s chain used to be killed here at 14-20s, which
+// for Edit|Write is a fail-closed transport failure = every edit blocked).
+import { resolveChainExecTimeoutMs } from '../../../.claude/ukit/runtime/hook-chain-budget.mjs';
 
 export const HOOK_EVENT_MAP = {
   tool_call: {
@@ -45,7 +56,7 @@ export const HOOK_EVENT_MAP = {
   },
   before_agent_start: ['sensitive-data-guard.sh', 'skill-router.sh', 'vision-router.sh', 'context-window-guard.sh'],
   'session.compacting': ['reinject-context.sh'],
-  session_start: ['auto-prune-bash.sh', 'reset-compact-pressure.sh', 'handoff-resume.sh'],
+  session_start: ['project-important.sh', 'auto-prune-bash.sh', 'reset-compact-pressure.sh', 'handoff-resume.sh'],
 };
 
 const TOOL_NAME_MAP = {
@@ -100,6 +111,7 @@ export const ADVISORY_SCRIPTS = new Set([
   'task-watchdog.sh',
   'compress-output.sh',
   'reinject-context.sh',
+  'project-important.sh',
   'auto-prune-bash.sh',
   'reset-compact-pressure.sh',
   'handoff-resume.sh',
@@ -118,6 +130,48 @@ function classifyFailure(scriptName) {
 // whose dangerous-command check timed out stays blocked with the honest reason.
 const TIMEOUT_STAYS_CLOSED = new Set(['block-dangerous.sh']);
 
+// TASK-018: the hook-chain-runner's failure taxonomy. Infrastructure outcomes
+// (overflow / timeout / signal / budget-exhausted) produced NO verdict, so their
+// captured output is untrustworthy and never reaches the model context, a block
+// reason, or telemetry. Legacy runner entries (killed without a kind) keep the
+// pre-TASK-018 timeout behavior.
+const INFRASTRUCTURE_FAILURE_KINDS = new Set([
+  'output-overflow',
+  'timeout',
+  'signal',
+  'budget-exhausted',
+]);
+
+// Telemetry redaction (TASK-018): hook stdout content never enters diagnostics by
+// construction (the runner drops it for infrastructure kinds, and only lengths are
+// recorded); stderr excerpts are bounded and high-signal secret shapes are masked
+// before anything is written to .ukit/storage/cache/hook-errors/ or logged.
+const SECRET_SHAPE_PATTERNS = [
+  /-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----[\s\S]*?(?:-----END [A-Z0-9 ]*PRIVATE KEY-----|$)/g,
+  /\b(?:sk|pk|rk)-[A-Za-z0-9_-]{16,}\b/g,
+  /\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{20,}\b/g,
+  /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/g,
+  /\bAKIA[0-9A-Z]{16}\b/g,
+  /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{5,}\b/g,
+  /\b[0-9a-f]{40,}\b/gi,
+];
+
+// TASK-018 review fix round 1 (minor): mask BEFORE truncating. Truncating first
+// cut a secret that straddled the boundary, leaving a fragment whose pattern no
+// longer matched (the truncated head leaked). The raw string is bounded by the
+// runner's maxBuffer, so masking the full text stays cheap.
+function redactDiagnosticText(text, maxChars = 500) {
+  const raw = String(text ?? '');
+  if (!raw) return '';
+  let redacted = raw;
+  for (const pattern of SECRET_SHAPE_PATTERNS) {
+    redacted = redacted.replace(pattern, '<redacted>');
+  }
+  return raw.length > maxChars
+    ? `${redacted.slice(0, maxChars)}…[+${raw.length - maxChars} chars]`
+    : redacted;
+}
+
 function runtimeMetadata(event = {}, context = {}) {
   const sessionManager = context?.sessionManager;
   return {
@@ -170,24 +224,61 @@ function parseStructuredDecision(stdout) {
 }
 
 function translateExecResult(scriptName, execResult) {
-  const killed = Boolean(execResult?.killed);
-  const stdout = execResult?.stdout ?? '';
-  const stderr = killed
-    ? (execResult?.stderr || `${scriptName} was killed before it completed`)
+  const failureKind = typeof execResult?.failureKind === 'string' ? execResult.failureKind : null;
+  // Infrastructure outcomes produce no verdict: no captured content travels with
+  // them (overflowed stdout is truncated mid-stream and may embed secrets).
+  const infrastructure = failureKind
+    ? INFRASTRUCTURE_FAILURE_KINDS.has(failureKind)
+    : Boolean(execResult?.killed);
+  const stdout = infrastructure ? '' : (execResult?.stdout ?? '');
+  const stderr = infrastructure
+    ? redactDiagnosticText(execResult?.stderr)
     : (execResult?.stderr ?? '');
 
-  if (killed) {
+  if (infrastructure) {
+    if (failureKind === 'output-overflow') {
+      if (FAIL_CLOSED_SCRIPTS.has(scriptName)) {
+        return {
+          block: true,
+          reason: `${scriptName} overflowed its output capture buffer and was stopped before it produced a verdict, so UKit could not verify the call — the call stays blocked and no overflowed hook output was kept.`,
+          stdout,
+          stderr: '',
+        };
+      }
+      return {
+        block: false,
+        warning: `${scriptName} overflowed its output capture buffer and was stopped; its output was discarded — an infrastructure event, not a verdict.`,
+        stdout,
+        stderr: '',
+      };
+    }
     if (TIMEOUT_STAYS_CLOSED.has(scriptName)) {
       return {
         block: true,
-        reason: `${scriptName} exceeded its hook budget and was killed, so UKit could not verify the command is safe — the call stays blocked. Retry once; if this repeats, the machine is too slow for the guard to finish.`,
+        reason: `${scriptName} ${failureKind === 'budget-exhausted' ? 'was never reached — the hook chain total budget was exhausted' : 'exceeded its hook budget and was killed'}, so UKit could not verify the command is safe — the call stays blocked. Retry once; if this repeats, the machine is too slow for the guard to finish.`,
         stdout,
         stderr,
       };
     }
+    const why = failureKind === 'signal'
+      ? 'was terminated by a signal'
+      : failureKind === 'budget-exhausted'
+        ? 'did not run — the hook chain total budget was exhausted before it could'
+        : 'exceeded its hook budget and was killed';
+    // TASK-018 review finding 3: the 16s ceiling makes a budget-exhausted skip of a
+    // LATE fail-closed guard (handoff-model-guard.sh / context-hardcap-gate.sh)
+    // realistic, and that guard fails open. This is deliberate anti-freeze policy:
+    // a guard that produced NO verdict is an infrastructure event, and blocking on
+    // it froze every Edit|Write whenever the machine was slow. Only
+    // block-dangerous.sh stays closed (TIMEOUT_STAYS_CLOSED) because destructive-
+    // command protection was explicitly required to never fail open. Stated in the
+    // warning so a skipped guard is never a silent one.
+    const failOpenTradeOff = FAIL_CLOSED_SCRIPTS.has(scriptName) && !TIMEOUT_STAYS_CLOSED.has(scriptName)
+      ? ` ${scriptName} is a fail-closed guard, but a guard that never produced a verdict is treated as "could not verify" rather than a block — the deliberate anti-freeze trade-off for infrastructure events; only block-dangerous.sh stays closed.`
+      : '';
     return {
       block: false,
-      warning: `${scriptName} exceeded its hook budget and was killed — treated as "could not verify", not as a block (a timeout is an infrastructure event, not a verdict): ${stderr}`,
+      warning: `${scriptName} ${why} — treated as "could not verify", not as a block (an infrastructure event, not a verdict): ${stderr || 'no stderr'}.${failOpenTradeOff}`,
       stdout,
       stderr,
     };
@@ -224,7 +315,7 @@ function translateExecResult(scriptName, execResult) {
   }
   return {
     block: false,
-    warning: `${scriptName} exited ${code} (failing open): ${stderr || 'no stderr'}`,
+    warning: `${scriptName} exited ${code} (failing open): ${redactDiagnosticText(stderr) || 'no stderr'}`,
     stdout,
     stderr,
   };
@@ -232,15 +323,13 @@ function translateExecResult(scriptName, execResult) {
 
 export { translateExecResult };
 
-// Mirrors hook-chain-runner.mjs's TOTAL/CHILD budget constants: the exec timeout must
-// exceed the runner's own chain budget (max(10s, scripts×4s)) plus parse margin, or the
-// bridge orphans the runner mid-chain once a chain grows past 2 scripts.
-const HOOK_CHAIN_BASE_BUDGET_MS = 10000;
-const HOOK_CHAIN_CHILD_BUDGET_MS = 4000;
-function chainExecTimeoutMs(scriptCount) {
-  const budget = Math.max(HOOK_CHAIN_BASE_BUDGET_MS, scriptCount * HOOK_CHAIN_CHILD_BUDGET_MS);
-  return Math.min(30000, budget + 2000);
-}
+// The exec timeout must exceed the runner's own chain budget (resolved from the
+// SAME UKIT_HOOK_CHAIN_* knobs by hook-chain-budget.mjs) plus enough margin to
+// cover the runner's TERM→KILL grace and hard settle slack, or the bridge orphans
+// the runner mid-chain. TASK-018: the ceiling caps what used to be linear growth.
+// Review fix round 1: this used to be a separate hardcoded formula under a fixed
+// 30s cap that silently disagreed with the runner whenever the env knobs were set.
+const chainExecTimeoutMs = resolveChainExecTimeoutMs;
 
 function recordHookErrorDiagnostic(projectRoot, sessionId, diagnostic) {
   try {
@@ -277,37 +366,25 @@ function resolveNodeExecutable() {
   return cachedNodeExecutable;
 }
 
-// argv is bounded: macOS allows ~256KB per argument (E2BIG), and PostToolUse Bash payloads
-// embed the whole tool output — routinely past that limit — so the exec fails before ANY
-// hook runs and the chain verdict is lost. Pass the payload through a temp file instead
-// (runner reads `@path` markers); inline argv stays as the fallback for read-only project
-// roots, and remains unambiguous because raw JSON never starts with '@'.
-function sweepStalePayloadFiles(dir) {
-  try {
-    const cutoff = Date.now() - 60 * 60 * 1000;
-    for (const name of fs.readdirSync(dir)) {
-      const filePath = path.join(dir, name);
-      try {
-        if (fs.statSync(filePath).mtimeMs < cutoff) fs.rmSync(filePath, { force: true });
-      } catch { /* raced away — fine */ }
-    }
-  } catch { /* sweeping is best effort */ }
+// TASK-031: payload staging moved to hook-payload-store.mjs. Small payloads stay inline
+// (zero filesystem work); over-cap payloads stage atomically into an owner-only file
+// (macOS allows ~256KB per argument (E2BIG), and PostToolUse Bash payloads embed whole
+// tool outputs — routinely past that limit, so the exec would fail before ANY hook runs
+// and the chain verdict would be lost). Stale sweeping is sampled, bounded, and deferred
+// off the request path; inline argv remains the fallback for read-only roots, unambiguous
+// because raw JSON never starts with '@'.
+function payloadsDirFor(projectRoot) {
+  return path.join(projectRoot, '.ukit', 'storage', 'cache', 'hook-payloads');
 }
 
-function writePayloadFile(projectRoot, payload) {
-  try {
-    const dir = path.join(projectRoot, '.ukit', 'storage', 'cache', 'hook-payloads');
-    fs.mkdirSync(dir, { recursive: true });
-    sweepStalePayloadFiles(dir);
-    const filePath = path.join(
-      dir,
-      `${Date.now()}-${process.pid}-${Math.random().toString(36).slice(2, 8)}.json`,
-    );
-    fs.writeFileSync(filePath, JSON.stringify(payload), 'utf8');
-    return filePath;
-  } catch {
-    return null;
-  }
+function schedulePayloadSweep(projectRoot) {
+  // Deferred: runs after the current turn settles, never inside the chain request.
+  const timer = setTimeout(() => {
+    try {
+      maybeSweepStalePayloads(payloadsDirFor(projectRoot));
+    } catch { /* deferred sweeping is best effort */ }
+  }, 0);
+  timer.unref?.();
 }
 
 export async function runScriptChain(
@@ -326,9 +403,13 @@ export async function runScriptChain(
   const scriptPaths = scripts.map((scriptName) => path.join(projectRoot, '.claude', 'hooks', scriptName));
   const nodeExecutable = resolveNodeExecutable();
   const startedAt = Date.now();
-  const payloadFile = writePayloadFile(projectRoot, payload);
-  const payloadArg = payloadFile ? `@${payloadFile}` : JSON.stringify(payload);
+  const payloadReference = createPayloadReference(JSON.stringify(payload), {
+    maxBytes: PAYLOAD_INLINE_MAX_BYTES,
+    dir: payloadsDirFor(projectRoot),
+  });
+  const payloadArg = payloadReference.arg;
   let execResult;
+  let payloadProbe = null;
   try {
     execResult = await pi.exec(
       nodeExecutable,
@@ -338,9 +419,12 @@ export async function runScriptChain(
   } catch (error) {
     execResult = { code: 1, stdout: '', stderr: error?.message ?? String(error), killed: false };
   } finally {
-    if (payloadFile) {
-      try { fs.rmSync(payloadFile, { force: true }); } catch { /* best effort cleanup */ }
-    }
+    // TASK-031: verify the staged payload survived the chain intact BEFORE removing it —
+    // a file that vanished or was truncated mid-flight means the scripts ran against a
+    // different payload than the host captured, so their verdicts are void.
+    payloadProbe = probePayloadIntegrity(payloadReference);
+    payloadReference.cleanup();
+    if (payloadReference.mode === 'file') schedulePayloadSweep(projectRoot);
   }
   const elapsedMs = Date.now() - startedAt;
 
@@ -355,7 +439,11 @@ export async function runScriptChain(
   }
 
   const hasUsableResults = Boolean(chainResult) && Array.isArray(chainResult.results) && chainResult.results.length > 0;
-  const transportFailed = Boolean(execResult?.killed) || Boolean(parseError) || Boolean(chainResult?.wrapperError) || !hasUsableResults;
+  const transportFailed = payloadProbe !== null
+    || Boolean(execResult?.killed)
+    || Boolean(parseError)
+    || Boolean(chainResult?.wrapperError)
+    || !hasUsableResults;
 
   if (transportFailed) {
     // The aggregate runner produced no verifiable per-script verdict. Never relabel this as a
@@ -366,7 +454,13 @@ export async function runScriptChain(
       killed: Boolean(execResult?.killed),
       code: execResult?.code ?? null,
       stdoutLength: (execResult?.stdout || '').length,
-      stderr: execResult?.stderr || '',
+      // TASK-018: bounded + secret-masked excerpt only — raw hook/runner output
+      // never reaches the hook-errors telemetry file.
+      stderrExcerpt: redactDiagnosticText(execResult?.stderr),
+      // TASK-031: payload integrity is recorded as a classification + byte count,
+      // never as content.
+      payloadProbe,
+      payloadBytes: payloadReference.bytes,
       elapsedMs,
       nodeExecutable,
       nodeVersion: process.version,
@@ -375,15 +469,36 @@ export async function runScriptChain(
       wrapperError: chainResult?.wrapperError || null,
     };
     recordHookErrorDiagnostic(projectRoot, payload.session_id, diagnostic);
+    // TASK-031: a staged payload that was lost or corrupted mid-chain voids every
+    // verdict below it. Chains that must not fail open on an unverifiable verdict
+    // (Edit|Write transport policy, and block-dangerous.sh's never-fail-open rule)
+    // stay closed; everything else fails open loudly. Neither reason carries any
+    // payload content — only the classification and byte count.
+    const payloadStaysClosed = payloadProbe !== null
+      && (failClosedOnTransportError || scripts.includes('block-dangerous.sh'));
+    if (payloadStaysClosed) {
+      const integrityReason = `UKit hook payload transport failed: the staged payload file was `
+        + `${payloadProbe === 'missing' ? 'removed' : 'truncated'} before the chain could read it `
+        + `(expected ${payloadReference.bytes} bytes), so the scripts may have run against an empty `
+        + `or partial payload and their verdicts were discarded — the call could not be verified. `
+        + `See .ukit/storage/cache/hook-errors/.`;
+      return { block: true, reason: integrityReason, context, invoked };
+    }
     const nodePathHint = process.env.UKIT_NODE_PATH
       ? ''
       : ` UKit already tried process.execPath and a "node" PATH lookup; neither resolved to a `
         + `working Node.js binary (runtime="${diagnostic.nodeExecutable}"). Set UKIT_NODE_PATH to `
         + `an explicit Node.js binary path to override, e.g.: export UKIT_NODE_PATH="$(command -v node)".`;
-    const reason = `UKit OMP hook runner failed before producing a valid result `
-      + `(killed=${diagnostic.killed}, code=${diagnostic.code}, elapsedMs=${diagnostic.elapsedMs}, `
-      + `runtime=${diagnostic.nodeExecutable}). No safety-gate verdict was available for [${scripts.join(', ')}]. `
-      + `See .ukit/storage/cache/hook-errors/.${nodePathHint}`;
+    const reason = payloadProbe !== null
+      ? `UKit hook payload transport failed: the staged payload file was `
+        + `${payloadProbe === 'missing' ? 'removed' : 'truncated'} before the chain could read it `
+        + `(expected ${payloadReference.bytes} bytes), so the scripts may have run against an empty `
+        + `or partial payload and their verdicts were discarded — treated as "could not verify", `
+        + `not as a block. See .ukit/storage/cache/hook-errors/.`
+      : `UKit OMP hook runner failed before producing a valid result `
+        + `(killed=${diagnostic.killed}, code=${diagnostic.code}, elapsedMs=${diagnostic.elapsedMs}, `
+        + `runtime=${diagnostic.nodeExecutable}). No safety-gate verdict was available for [${scripts.join(', ')}]. `
+        + `See .ukit/storage/cache/hook-errors/.${nodePathHint}`;
     if (failClosedOnTransportError) {
       return { block: true, reason, context, invoked };
     }
@@ -589,10 +704,12 @@ export async function runSessionCompact(pi, event, { projectRoot, context: exten
   // session_compact fires only after agent.replaceMessages()/rebaseAfterCompaction() already
   // ran (session-maintenance.ts), i.e. the session is idle here, and agent-session.ts's
   // sendCustomMessage() non-streaming branch appends the message to the live context
-  // regardless of deliverAs — so 'steer' is accepted right after a compaction. Not a live
-  // repro, so the 'nextTurn' copy below stays as defense in depth.
+  // regardless of deliverAs — so 'steer' is accepted right after a compaction.
+  // TASK-042: delivery is exact-once. The former defense-in-depth 'nextTurn' copy produced
+  // a second model-visible duplicate of the same context; per spec §10/§17 Phase 5 keep
+  // 'steer' only (switch to 'nextTurn' ONLY if a live omp smoke proves 'steer' is not
+  // retained after compact — never both).
   sendContext(pi, result.context, 'steer');
-  sendContext(pi, result.context, 'nextTurn');
   return undefined;
 }
 

package/templates/AGENTS.md

@@ -238,6 +238,14 @@ At the start of every OpenCode session, before working on the first task:
 4. If the route result points to a skill, read that SKILL.md before acting — do not skip this step.
 5. If `.ukit/storage/config.json` has `router.enabled: true`, prefer the router output over ad-hoc guessing.
 
+## Project Owner Instructions — Codex and OpenCode
+
+When running in Codex or OpenCode, read and follow the root
+`PROJECT_IMPORTANT.md` before doing project work. It is the canonical
+project-owner instruction source. Do not copy its contents into this file.
+If it is missing or unreadable, state that limitation and continue with the
+remaining project instructions.
+
 ## Skills
 
 - Canonical skills live in `.claude/skills/`.

package/templates/PROJECT_IMPORTANT.md

@@ -0,0 +1,9 @@
+# Project Important Instructions
+
+<!--
+Add project-specific, non-negotiable AI instructions here.
+
+UKit creates this file only when it is missing. After creation, UKit never rewrites,
+merges, formats, chmods, or deletes it. Keep it at or below 6,000 Unicode code
+points for complete runtime injection. Do not put credentials or secrets here.
+-->