@ngockhoale/ukit 2.7.7 → 2.7.9

package/CHANGELOG.md

@@ -2,6 +2,51 @@
 
 All notable changes to UKit are documented here.
 
+
+## 2.7.9 - 2026-09-22
+
+- **User permission mode is never overwritten**: `ukit install`/`ukit update`
+  used to rewrite `.claude/settings.json` wholesale, so the template's
+  `permissions.defaultMode: "bypassPermissions"` silently clobbered a
+  user-chosen mode (e.g. `plan`) on every install. `defaultMode` is now
+  user-owned in `merge_env_overwrite_with_backup`: excluded from the drift
+  comparison and merged back into the written content. The template default
+  still applies on fresh installs or when the user never set a mode.
+  (`src/core/diffPlan.js`, +4 tests in `tests/core/diffPlan.test.js`)
+
+## 2.7.8 - 2026-09-22
+
+Stall/hang fixes — cycle C43 (TASK-001..008): the indefinite-stall producers
+root-caused in `docs/AI_REPORT/2026-09-21-NORMAL_CHAT_STALL.md` are fixed
+across Claude Code, omp, and Codex runtimes.
+
+- **CX-8**: route-state writes are atomic + locked — torn `skill-router-state.json`
+  writes can no longer wedge the router.
+- **OMP-3/F-2**: omp receipt dedupe — a tool result is recorded once; duplicate
+  receipts no longer double-count execution records.
+- **RC-4/OMP-1/F-3/F-4**: breaker-freeze family — budgeted reclaim, pstart
+  stamps, fail-open streaks; continuation sidecar merge gate stamps
+  `lastContinuationAt` strictly newer than its base and materializes counter
+  state when the main ledger file is absent.
+- **F-5/F-5b**: `withFileLock` policy + reclaim — stale locks reclaimed via
+  pstart mismatch; recycled-pid regression tests added.
+- **F-15**: verifier-classification — verification outcomes classified so a
+  non-verification failure no longer masquerades as a test failure.
+- **F-RC-2**: `hook-chain-runner` exits promptly after verdict — bounded stdout
+  flush then `process.exit`; an abandoned in-proc step promise can no longer
+  pin the event loop for the full registered timeout.
+- **F-10/OMP-2**: omp Stop parity — omp sessions get the same handoff-cursor
+  Stop-gate lane as Claude Code.
+- **OMP-6/F-8/CX-10**: `createPayloadReference` staging runs under a deadline
+  with fail-open to inline payload (never throws, host loop not frozen); omp
+  SessionStart carries `session_id` so `reset-compact-pressure` no longer
+  wipes every session's pressure records; codex `requiredBeforeCompletion`
+  renders only commands that exist in `package.json`.
+- Housekeeping: stale "Kilo" tool labels scrubbed from handoff docs, agent
+  report contracts, and config help text (functional support was already
+  removed; the regression tests and gateway comments documenting that removal
+  are intentionally kept).
+
 ## 2.7.7 - 2026-09-21
 
 Audit-report remediation + hook observability — cycle C42 (TASK-001..011): all 12
@@ -64,6 +109,15 @@ findings from the three 2026-09-20 reports closed; the reports moved to
   fixture whose outcome depended on whether the clock ticked mid-array, so it
   passed on an unloaded box and failed under load; the fixture is now
   deterministic and the case fails against the old code.
+- `withFileLock` (both `templates/.claude/ukit/runtime/token-utils.mjs` and its
+  `src/core/fileOps.js` twin) is now fail-closed: a lock wait that exceeds
+  `maxWaitMs` skips the mutation instead of running it unlocked, and the drop is
+  journaled to `<file>.lock-drops.jsonl` (bounded 128-record JSONL). Both twins
+  delegate to `async-lock.mjs`, so owner stamping (pid + token + pstart),
+  recycled-pid detection, and claim+quarantine stale reclaim exist exactly once;
+  a stale lock whose recorded pid was recycled is now reclaimed instead of
+  wedging every mutation for that file. `writeJson`/`writeFileAtomic` fall back
+  to copy+unlink when `rename` fails with EXDEV (cross-mount tmp dirs).
 
 ## 2.7.6 - 2026-09-20
 

package/package.json

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

package/src/context/detectProjectContext.js

@@ -24,5 +24,10 @@ export async function detectProjectContext(projectRoot) {
       os: process.platform,
       nodeVersion: process.version,
     },
+    // CX-10: raw package.json scripts so renderers can emit only commands that
+    // actually exist (verify-context.mjs:186-191 does the same existence check).
+    scripts: packageJson?.scripts && typeof packageJson.scripts === 'object'
+      ? packageJson.scripts
+      : {},
   };
 }

package/src/core/codeintel/invalidation.js

@@ -105,6 +105,10 @@ export async function notifyEdit(projectRoot, relPaths) {
   for (let attempt = 0; attempt < MERGE_MAX_ATTEMPTS; attempt += 1) {
     try {
       const paths = await withFileLock(dirtyPath, mergeOnce);
+      // TASK-004: withFileLock is fail-closed — a contended lock skips the merge
+      // (journaled to dirty.json.lock-drops.jsonl) and resolves undefined. Return
+      // the current state like the exhausted-retry path; never retry unlocked.
+      if (paths === undefined) break;
       return { dirty: paths };
     } catch (error) {
       lastError = error;

package/src/core/diffPlan.js

@@ -34,6 +34,54 @@ async function checkLinkStatus(targetPath, linkTarget) {
 // template, so a template-side change to e.g. CLAUDE_CODE_AUTO_COMPACT_WINDOW still triggers
 // a real reinstall. Without this carve-out, the managed gateway keys written by the post-apply
 // step would cause a spurious "update" on every subsequent install.
+//
+// `permissions.defaultMode` is user-owned: the user picks their permission mode
+// (bypassPermissions / plan / acceptEdits / default) and UKit must never change it.
+// It is excluded from the drift comparison AND re-injected into the rendered content
+// before write (mergeSettingsJson), so an install/update can never flip the user's mode.
+// When the user has NOT set it, the template's shipped default applies on create/update.
+const USER_OWNED_PERMISSION_KEYS = new Set(['defaultMode']);
+
+function parseSettingsJson(content) {
+  if (typeof content !== 'string') return null;
+  try {
+    const parsed = JSON.parse(content);
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+// Strip user-owned permission keys from a parsed permissions object for comparison.
+// Returns a new object; never mutates the input.
+function stripUserOwnedPermissionKeys(permissions) {
+  if (!permissions || typeof permissions !== 'object' || Array.isArray(permissions)) {
+    return permissions;
+  }
+  const stripped = { ...permissions };
+  for (const key of USER_OWNED_PERMISSION_KEYS) delete stripped[key];
+  return stripped;
+}
+
+// Merge rendered settings.json with the user's existing file: the rendered template
+// wins every key EXCEPT user-owned permission keys (currently permissions.defaultMode),
+// which keep the value the user set. Returns the merged JSON as a string, or the
+// rendered content unchanged when either side is unparseable.
+export function mergeSettingsJson(existingContent, renderedContent) {
+  const existing = parseSettingsJson(existingContent);
+  const rendered = parseSettingsJson(renderedContent);
+  if (!existing || !rendered) return renderedContent;
+  const merged = { ...rendered };
+  if (existing.permissions && typeof existing.permissions === 'object' && !Array.isArray(existing.permissions)) {
+    const mergedPermissions = { ...(rendered.permissions && typeof rendered.permissions === 'object' ? rendered.permissions : {}) };
+    for (const key of USER_OWNED_PERMISSION_KEYS) {
+      if (key in existing.permissions) mergedPermissions[key] = existing.permissions[key];
+    }
+    merged.permissions = mergedPermissions;
+  }
+  return `${JSON.stringify(merged, null, 2)}\n`;
+}
+
 function settingsJsonIgnoresGatewayEnvDiff(existingContent, renderedContent) {
   if (typeof existingContent !== 'string' || typeof renderedContent !== 'string') {
     return false;
@@ -56,7 +104,13 @@ function settingsJsonIgnoresGatewayEnvDiff(existingContent, renderedContent) {
   for (const key of Object.keys(parsedRendered)) {
     if (key === 'env') continue;
     if (!(key in parsedExisting)) return false;
-    if (JSON.stringify(parsedExisting[key]) !== JSON.stringify(parsedRendered[key])) {
+    const renderedValue = key === 'permissions'
+      ? stripUserOwnedPermissionKeys(parsedRendered[key])
+      : parsedRendered[key];
+    const existingValue = key === 'permissions'
+      ? stripUserOwnedPermissionKeys(parsedExisting[key])
+      : parsedExisting[key];
+    if (JSON.stringify(existingValue) !== JSON.stringify(renderedValue)) {
       return false;
     }
   }
@@ -128,7 +182,12 @@ function resolveFileAction(entry, existingContent) {
     // Settings.json: ignore UKit-managed gateway resilience env keys (post-apply written
     // and may carry user overrides). All other top-level keys — and the rest of the env
     // block — must still match the template, so genuine template updates still reinstall.
+    // User-owned permission keys (permissions.defaultMode) are excluded from the drift
+    // check AND merged back into the content that gets written, so install/update can
+    // never flip the user's chosen permission mode.
+    const merged = mergeSettingsJson(existingContent, entry.renderedContent);
     action = settingsJsonIgnoresGatewayEnvDiff(existingContent, entry.renderedContent) ? 'unchanged' : 'update';
+    return { ...entry, renderedContent: merged, exists, action, existingContent };
   } else if (existingContent === entry.renderedContent) {
     action = 'unchanged';
   } else if (entry.mergeStrategy === 'skip') {

package/src/core/fileOps.js

@@ -1,7 +1,11 @@
-import crypto from 'node:crypto';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 
+// The shipped runtime carries the single lock implementation; src and the
+// installed package always ship templates/ together (package.json files list),
+// so the protocol twin delegates instead of keeping a driftable copy.
+import { journalDroppedLockMutation, withAsyncLock, withTransientFsRetry } from '../../templates/.claude/ukit/runtime/async-lock.mjs';
+
 export async function pathExists(targetPath) {
   try {
     await fs.access(targetPath);
@@ -99,12 +103,26 @@ export async function writeFileAtomic(filePath, content) {
   const tempPath = `${filePath}.tmp-${Date.now()}-${Math.random().toString(16).slice(2)}`;
 
   try {
+    // C44: temp write, rename, and the EXDEV copy+rm fallback each retry
+    // transient kernel errors (EAGAIN/EBUSY/EMFILE/ENFILE/ESTALE) — the same
+    // transient-open EAGAIN observed on external APFS volumes under metadata
+    // churn. Non-transient codes (EXDEV, EISDIR) throw immediately, unchanged.
     if (Buffer.isBuffer(content)) {
-      await fs.writeFile(tempPath, content);
+      await withTransientFsRetry(() => fs.writeFile(tempPath, content));
     } else {
-      await fs.writeFile(tempPath, content, 'utf8');
+      await withTransientFsRetry(() => fs.writeFile(tempPath, content, 'utf8'));
+    }
+    try {
+      await withTransientFsRetry(() => fs.rename(tempPath, filePath));
+    } catch (renameError) {
+      // EXDEV: the tmp file and the destination sit on different mounts (union
+      // mounts, per-dir bind mounts, tmpfs overlays), so rename cannot link them.
+      // The payload is already fully written — copy it over and unlink the tmp.
+      // Less atomic than rename, but the update must not be silently lost.
+      if (renameError?.code !== 'EXDEV') throw renameError;
+      await withTransientFsRetry(() => fs.copyFile(tempPath, filePath));
+      await withTransientFsRetry(() => fs.rm(tempPath, { force: true }));
     }
-    await fs.rename(tempPath, filePath);
   } catch (error) {
     try {
       await fs.rm(tempPath, { force: true });
@@ -161,130 +179,39 @@ export async function writeJson(filePath, data) {
 const LOCK_STALE_MS = 10_000;
 const LOCK_MAX_WAIT_MS = 5_000;
 
-function lockBackoffDelayMs() {
-  return 3 + Math.floor(Math.random() * 9);
-}
-
-function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
-function isPidAlive(pid) {
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch (error) {
-    // EPERM: the process exists but belongs to another user — still alive.
-    return error?.code === 'EPERM';
-  }
-}
-
-async function readLockOwner(lockPath) {
-  try {
-    const raw = JSON.parse(await fs.readFile(path.join(lockPath, 'owner'), 'utf8'));
-    const pid = Number(raw?.pid);
-    return Number.isInteger(pid) && pid > 0
-      ? { pid, token: typeof raw?.token === 'string' ? raw.token : null }
-      : null;
-  } catch {
-    return null;
-  }
-}
-
-// Same-pid holders are parallel async flows whose liveness a pid probe cannot prove.
-const inProcessLockHolders = new Map();
-
 /**
  * Serialize read-modify-write mutations of a shared state file — across processes
  * (hook invocations run as separate node processes) and across concurrent async
  * flows in one process (parallel subagents). The lock is a directory created next
  * to the target file: `mkdir` is atomic, so exactly one caller can create it.
- * Ownership is recorded in an `owner` file inside the lock dir: stale reclaim first
- * proves the recorded holder is gone (dead pid, or no in-process holder for our own
- * pid — no owner file keeps legacy mtime-only recovery). Release only removes a dir
- * this acquisition still owns, so a reclaimed-then-reacquired lock is never deleted
- * out from under its successor.
- * Liveness wins over strictness: if the lock cannot be acquired within maxWaitMs
- * the callback runs anyway (the pre-lock behaviour) — these state files are
- * advisory caches, and losing an update beats freezing a hook mid-flight.
- * Protocol-compatible with the runtime token-utils.mjs lock (same `<file>.lock`
- * path and owner-file format), so CLI and hook processes serialize against each other.
+ *
+ * The entire lock protocol lives in templates/.claude/ukit/runtime/async-lock.mjs
+ * (TASK-004 fix round 1): owner stamping (pid + token + pstart), recycled-pid
+ * detection via recordedProcessGone, claim+quarantine stale reclaim, and verified
+ * release exist exactly once there — this function and the token-utils.mjs twin
+ * both delegate to it so the two protocol copies can never drift apart again.
+ *
+ * FAIL-CLOSED (TASK-004, unified with async-lock/ledger policy): if the lock cannot
+ * be acquired within maxWaitMs the callback is SKIPPED — never run unlocked — and
+ * the drop is journaled to `<file>.lock-drops.jsonl`. These state files are
+ * advisory caches: losing an update was already the accepted outcome of the old
+ * fail-open race; now it is explicit and journaled instead of a silent torn write.
  * @param {string} filePath - state file the mutation targets (lock lives beside it)
  * @param {() => Promise<*>} fn - critical section; its result is returned
- * @returns {Promise<*>} whatever fn resolves with
+ * @returns {Promise<*|undefined>} whatever fn resolves with, or undefined when the
+ *   lock wait expired and the mutation was skipped (journaled)
  */
 export async function withFileLock(filePath, fn, { staleMs = LOCK_STALE_MS, maxWaitMs = LOCK_MAX_WAIT_MS } = {}) {
-  const lockPath = `${filePath}.lock`;
-  const startedAt = Date.now();
-  const ownerToken = `${process.pid}-${crypto.randomBytes(8).toString('hex')}`;
-  let locked = false;
-  let ownerStamped = false;
-
-  while (!locked) {
-    try {
-      await ensureDir(path.dirname(lockPath));
-      await fs.mkdir(lockPath); // atomic acquire — EEXIST means another holder exists
-      locked = true;
-      inProcessLockHolders.set(lockPath, ownerToken);
-      try {
-        await fs.writeFile(
-          path.join(lockPath, 'owner'),
-          `${JSON.stringify({ pid: process.pid, token: ownerToken, ts: Date.now() })}\n`,
-          'utf8',
-        );
-        ownerStamped = true;
-      } catch {
-        ownerStamped = false; // unverifiable release skips removal; stale reclaim cleans up
-      }
-      break;
-    } catch (error) {
-      if (error?.code !== 'EEXIST') throw error;
-    }
-
-    // Someone holds the lock. Reclaim it only when the holder is provably gone.
-    try {
-      const stat = await fs.stat(lockPath);
-      if (Date.now() - stat.mtimeMs > staleMs) {
-        const owner = await readLockOwner(lockPath);
-        const liveInProcess = inProcessLockHolders.has(lockPath);
-        const reclaimable = !owner || owner.pid === process.pid
-          ? !liveInProcess
-          : !isPidAlive(owner.pid);
-        if (reclaimable) {
-          await fs.rm(lockPath, { recursive: true, force: true });
-          continue; // the slot is free now — retry immediately
-        }
-      }
-    } catch (statError) {
-      // BUG-C22-17: a persistent stat error (EPERM/ENOTDIR/EIO on a failing
-      // mount, or ELOOP/ENOENT on a dangling symlink where mkdir still reports
-      // EEXIST) must not busy-spin — a bare `continue` skipped both the
-      // maxWait break and the backoff sleep, looping mkdir→stat→throw forever.
-      if (Date.now() - startedAt >= maxWaitMs) break; // fail open — run unlocked
-      if (statError?.code === 'ENOENT') continue; // lock vanished — retry immediately
-      await sleep(lockBackoffDelayMs());
-      continue;
-    }
-
-    if (Date.now() - startedAt >= maxWaitMs) break; // fail open — run unlocked
-    await sleep(lockBackoffDelayMs());
-  }
-
-  try {
-    return await fn();
-  } finally {
-    if (locked) {
-      try {
-        const current = ownerStamped ? await readLockOwner(lockPath) : null;
-        if (current && current.token === ownerToken) {
-          await fs.rm(lockPath, { recursive: true, force: true });
-        }
-        if (inProcessLockHolders.get(lockPath) === ownerToken) inProcessLockHolders.delete(lockPath);
-      } catch {
-        // best-effort release; a stale lock is reclaimed by the next waiter
-      }
-    }
-  }
+  const outcome = await withAsyncLock(filePath, { deadlineMs: maxWaitMs, staleMs }, fn);
+  if (outcome?.ok === true) return outcome.value;
+  // Fail closed: the mutation is dropped, never run unlocked. The drop is
+  // journaled so the lost update is auditable; callers treat undefined as
+  // "update skipped" (they already tolerated losing it silently).
+  await journalDroppedLockMutation(filePath, {
+    reason: 'lock-wait-expired',
+    waitedMs: outcome?.waitedMs ?? maxWaitMs,
+  });
+  return undefined;
 }
 
 /**

package/src/render/buildVariables.js

@@ -39,6 +39,16 @@ export function buildTemplateVariables({ projectContext, stackContext, packageVe
       os: projectContext.runtime.os,
       nodeVersion: projectContext.runtime.nodeVersion,
     },
+    verification: {
+      // CX-10: render only commands whose scripts exist in the target
+      // package.json — a hardcoded lint/typecheck list produced a permanently
+      // failing verification contract on projects without those scripts.
+      requiredBeforeCompletion: JSON.stringify(
+        ['test', 'lint', 'typecheck']
+          .filter((name) => projectContext?.scripts?.[name])
+          .map((name) => `${projectContext.runtime.packageManager} ${name}`),
+      ),
+    },
     stack: {
       // original flags
       frontend: stackContext.flags.frontend,

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

@@ -50,7 +50,7 @@ Systematic debugging — understand before fixing.
 
 ```
 STATUS: DONE | BLOCKED | PARTIAL
-EXECUTOR_TOOL: [claude-code | kilo-code | codex | other]
+EXECUTOR_TOOL: [claude-code | codex | omp | other]
 EXECUTOR_MODEL: [exact model name you are running as. "unknown" if you cannot tell.]
 EXECUTOR_SUBAGENT: [subagent name within your host, if any, else "-"]
 SUMMARY: [1-2 sentences — root cause and fix]

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

@@ -72,9 +72,9 @@ and even then, report it, don't ask about it.
 
 ```
 STATUS: DONE | BLOCKED | PARTIAL
-EXECUTOR_TOOL: [claude-code | kilo-code | codex | other]
+EXECUTOR_TOOL: [claude-code | codex | omp | other]
 EXECUTOR_MODEL: [exact model name you are running as — e.g. unic-code, claude-sonnet-4-5, gpt-5-mini. If you truly cannot tell, write "unknown" — reviewer treats unknown as suspicious and asks the human to confirm.]
-EXECUTOR_SUBAGENT: [name of the subagent you are, if your host has multiple — e.g. "Kilo:code", "Claude:feature-implementer". Otherwise "-".]
+EXECUTOR_SUBAGENT: [name of the subagent you are, if your host has multiple — e.g. "Claude:feature-implementer", "omp:task". Otherwise "-".]
 SUMMARY: [1-2 sentences of what was implemented]
 TEST_PLAN_FOLLOWED: [task §4 / inline / N/A — reason]
 FILES_CHANGED:

package/templates/.claude/commands/ukit/handoff-clear.md

@@ -42,6 +42,11 @@ Write `docs/AI_HANDOFF/archive/cycle-NNN.md` (if there is anything worth archivi
 ```
 If `archive/` has > 3 files → delete oldest, append 1-line summary to `HISTORY.md`.
 
+After writing the archive file, **verify the write** — read it back and confirm
+the `ABORTED` heading is present; on mismatch or read failure retry once, on
+second failure stop and report (same rule as handoff-fullstack's "State-file
+write verification").
+
 ## Step 4 — Reset state files
 
 ```
@@ -54,6 +59,12 @@ RUN.md   → set `Phase: done` (or delete) — a live cursor that is neither `do
 tasks/TASK-*.md → delete all (keep _TEMPLATE.md)
 ```
 
+Every file rewritten above is a state file — **verify the write** on each:
+read it back and confirm the marker you just wrote (empty INDEX header,
+`_(no active cycle)_`, `Phase: done`). On mismatch or read failure retry the
+write once; on second failure STOP and report — never leave unverified state
+files behind, or the next cycle resumes from stale bytes.
+
 ## Step 5 — Report
 
 ```

package/templates/.claude/commands/ukit/handoff-create.md

@@ -1,7 +1,7 @@
 # /ukit:handoff-create — Phase 1 + 2: Plan
 
 **Role: PLANNER**
-**Tool: any** (Claude Code / Codex / omp / Kilo — your choice)
+**Tool: any** (Claude Code / Codex / omp — your choice)
 **Model split:**
 - Read/understand → lite model (haiku · unic-lite · cheapest available)
 - Write plan + tasks → strong model (Opus · unic-smart · strongest available)

package/templates/.claude/commands/ukit/handoff-fullstack.md

@@ -1,7 +1,7 @@
 # /ukit:handoff-fullstack — Full Pipeline: Plan → Implement → Review
 
 **Role: ORCHESTRATOR**
-**Tool: any** (Claude Code / Codex / omp / Kilo — your choice)
+**Tool: any** (Claude Code / Codex / omp — your choice)
 
 ## Model Split
 
@@ -75,6 +75,23 @@ QuietScans: <n>/<required>   # only while sweeping for stragglers near the end
 This file is the resume contract. It costs one small write per step and is what turns an
 interrupted run into a continuable one.
 
+### State-file write verification — "verify the write"
+
+Every Write/Edit to a handoff state file — `INDEX.md`, `ACTIVE.md`, `RUN.md`,
+`SPEC.md`, `PLAN.md`, `tasks/TASK-*.md` — can be silently lost to a transient
+filesystem error (the Write tool's own `open()` has been observed to fail with
+EAGAIN while the write is reported as done). After each such write:
+
+1. **Read it back** and confirm the marker you just wrote is present — the
+   `Status:` row, `Phase:`/`Cursor:` line, or section heading the write was
+   supposed to change.
+2. **On mismatch or read failure, retry the write once.**
+3. **On second failure, STOP the pipeline** and report the file plus the error —
+   never continue on unverified state. A stale `INDEX.md`/`RUN.md` is how a run
+   ships silent corruption.
+
+Wherever a step below says **verify the write**, it means this rule.
+
 ### Resume — when the run is re-invoked mid-flight
 
 If `docs/AI_HANDOFF/RUN.md` exists with `Phase:` not `done` or `blocked`, this is a
@@ -240,6 +257,7 @@ The planner agent does the following (use P1 summary — do NOT re-read files):
 6. **Update `docs/AI_HANDOFF/INDEX.md`** — one row per task, `status=ready`. Every
    unfinished item from the Phase 0 sweep is either a row here or superseded by a
    `-R<n>` recovery row.
+   Then **verify the write** (read back the new rows).
 
 7. **Update `docs/AI_HANDOFF/ACTIVE.md`:**
    ```
@@ -249,6 +267,7 @@ The planner agent does the following (use P1 summary — do NOT re-read files):
    Tasks: <N> total
    Status: planning_done — ready for executor
    ```
+   Then **verify the write** (read back the `Status:` line).
 
 8. **Report:** task IDs, dependency graph, recovery/superseded tasks, any
    `needs_breakdown` tasks + reason.
@@ -444,6 +463,7 @@ already on disk (task files hold the full logs, git holds the code). Do all four
 
 2. **Update the run cursor** — rewrite `docs/AI_HANDOFF/RUN.md` with `Phase: I3`,
    `Cursor: wave <N> done`, `Next: wave <N+1>` (or `I4` if that was the last wave).
+   Then **verify the write** (read back the `Phase:`/`Cursor:` lines).
 
 3. **Collapse the wave in working memory.** From this point on, refer to the finished wave
    only by its one-line-per-task summary (`TASK-xxx PASS <files>`). Do not re-read the task
@@ -469,6 +489,7 @@ logs used to cost. That difference is what makes a multi-wave cycle finish in on
    - PASS tasks → `pending_review`
    - FAIL tasks → `blocked`
    - EXECUTOR_MODEL missing → `needs_executor_report`
+   Then **verify the write** (read back the updated status column).
 
 2. Verify cleanup:
    ```bash
@@ -647,6 +668,8 @@ conventions so a future session needs no transcript to understand the cycle:
    summary in `HISTORY.md` and remove it.
 3. Reset `ACTIVE.md` to its empty template; clear `INDEX.md` rows to a fresh header;
    remove `tasks/TASK-*.md`; clear `PLAN.md`/`SPEC.md` (templates stay).
+   Then **verify the write** on each reset file (read back the empty header /
+   template marker).
 4. Commit the docs + archive changes:
    `git add -A && git commit -m "handoff: finalize + archive cycle <ID>"`
 
@@ -654,6 +677,8 @@ conventions so a future session needs no transcript to understand the cycle:
 
 Set `Phase: done` in `docs/AI_HANDOFF/RUN.md`, disarm any watchdog job armed at the
 start, and emit the Final Report below.
+   Then **verify the write** (read back `Phase: done`) — a lost cursor write
+   leaves the next session resuming a finished run.
 
 ---
 

package/templates/.claude/commands/ukit/handoff-implement.md

@@ -1,7 +1,7 @@
 # /ukit:handoff-implement — Phase 3: Execute
 
 **Role: EXECUTOR (orchestrated)**
-**Tool: any** (Claude Code / Codex / omp / Kilo — your choice)
+**Tool: any** (Claude Code / Codex / omp — your choice)
 **Model: code model** (Sonnet · unic-code · cheap-smart)
 
 > **omp model tiers:** the tiers above map to `.omp/config.yml`'s `modelRoles`, referenced from agent frontmatter as `@smol` / `@default` / `@slow`.

package/templates/.claude/commands/ukit/handoff-review.md

@@ -1,7 +1,7 @@
 # /ukit:handoff-review — Phase 4: Review
 
 **Role: REVIEWER**
-**Tool: any** (Claude Code / Codex / omp / Kilo — your choice)
+**Tool: any** (Claude Code / Codex / omp — your choice)
 **Model: strong model, MUST differ from executor** (Opus · unic-smart · strongest available)
 
 > **omp model tiers:** the tiers above map to `.omp/config.yml`'s `modelRoles`, referenced from agent frontmatter as `@smol` / `@default` / `@slow`.

package/templates/.claude/hooks/context-hardcap-gate.sh

@@ -238,7 +238,10 @@ async function readRunCursor() {
     if (synced.reset || synced.probed) {
       // Persist a clean probe too: hook processes are ephemeral, so otherwise every
       // mutation would reopen and parse the same 4MB transcript tail.
-      state = await mod.writeCompactPressureState(projectRoot, synced.state, sessionConfig);
+      // TASK-004: withFileLock is fail-closed — a contended pressure lock skips the
+      // write and resolves undefined (journaled). Keep the synced in-memory state;
+      // the gate still decides on correct data, the persist just lands next run.
+      state = (await mod.writeCompactPressureState(projectRoot, synced.state, sessionConfig)) ?? synced.state;
     }
   } catch {
     state = await mod.buildCompactPressureState(rawState, sessionConfig);

package/templates/.claude/hooks/handoff-model-guard.sh

@@ -187,16 +187,24 @@ if (toolName === 'Write' || toolName === 'Edit') {
   const newVisible = stripHtmlComments(newContent);
   const currentVisible = stripHtmlComments(currentContent);
 
+  // A documented, human-approved override closes the tier contract for this
+  // cycle — e.g. a gateway with no smart-tier model where the human approved
+  // planning on the available tier. Same semantics as the push-time check.
+  const planHasHumanOverride = (text) =>
+    /## Model-Tier Guard Override/.test(text) && /OVERRIDE_APPROVED_BY:\s*human/i.test(text);
+
   if (isPlan && /## Planner Report/.test(newVisible)) {
     const plannerModel = extractField(newVisible, 'PLANNER_MODEL');
-    if (!plannerModel || /^unknown$/i.test(plannerModel)) {
-      block('PLANNER_MODEL missing/unknown in PLAN.md. Planning must run via Agent tool subagent_type: "handoff-planner" (opus/unic-smart) and self-report its model.');
-    }
-    if (tierOf(plannerModel) === 'vision') {
-      block(`PLANNER_MODEL "${plannerModel}" ${VISION_LANE_MESSAGE}`);
-    }
-    if (tierOf(plannerModel) !== 'smart') {
-      block(`PLANNER_MODEL "${plannerModel}" is not strong/opus tier. Planning must run via Agent tool subagent_type: "handoff-planner" (opus/unic-smart).`);
+    if (!planHasHumanOverride(newVisible)) {
+      if (!plannerModel || /^unknown$/i.test(plannerModel)) {
+        block('PLANNER_MODEL missing/unknown in PLAN.md. Planning must run via Agent tool subagent_type: "handoff-planner" (opus/unic-smart) and self-report its model.');
+      }
+      if (tierOf(plannerModel) === 'vision') {
+        block(`PLANNER_MODEL "${plannerModel}" ${VISION_LANE_MESSAGE}`);
+      }
+      if (tierOf(plannerModel) !== 'smart') {
+        block(`PLANNER_MODEL "${plannerModel}" is not strong/opus tier. Planning must run via Agent tool subagent_type: "handoff-planner" (opus/unic-smart).`);
+      }
     }
   }
 
@@ -209,8 +217,9 @@ if (toolName === 'Write' || toolName === 'Edit') {
     const isFreshTaskFile = !fileExists;
     if (isFreshTaskFile) {
       const planContent = (await pathExists(planPath)) ? await readTextSafe(planPath) : '';
-      const plannerModel = extractField(stripHtmlComments(planContent), 'PLANNER_MODEL');
-      if (!plannerModel || tierOf(plannerModel) !== 'smart') {
+      const planVisible = stripHtmlComments(planContent);
+      const plannerModel = extractField(planVisible, 'PLANNER_MODEL');
+      if (!planHasHumanOverride(planVisible) && (!plannerModel || tierOf(plannerModel) !== 'smart')) {
         block(`Cannot create ${taskId}.md — PLAN.md has no valid smart-tier PLANNER_MODEL yet. Run planning via Agent tool subagent_type: "handoff-planner" (opus/unic-smart) first.`);
       }
 
@@ -285,13 +294,15 @@ if (toolName === 'Write' || toolName === 'Edit') {
     if (hasReviewerVerdict && !currentReviewerReal) {
       const executorModel = extractField(currentVisible, 'EXECUTOR_MODEL') || extractField(newVisible, 'EXECUTOR_MODEL');
       const reviewerModel = extractField(newVisible, 'REVIEWER_MODEL');
+      const planContentForReview = (await pathExists(planPath)) ? await readTextSafe(planPath) : '';
+      const reviewOverride = planHasHumanOverride(stripHtmlComments(planContentForReview));
       if (isPlaceholderValue(reviewerModel) || /^unknown$/i.test(reviewerModel)) {
         if (!isFreshTaskFile) {
           block(`${taskId}: REVIEWER_MODEL missing/placeholder. Review must run via Agent tool subagent_type: "code-reviewer" (opus/unic-smart) and self-report its model.`);
         }
         // Else: skeleton Reviewer Verdict on a freshly created task file — Phase 4
         // appends the real verdict and it is validated there.
-      } else {
+      } else if (!reviewOverride) {
         if (tierOf(reviewerModel) === 'vision') {
           block(`${taskId}: REVIEWER_MODEL "${reviewerModel}" ${VISION_LANE_MESSAGE}`);
         }