@ngockhoale/ukit 2.4.3 → 2.5.0

package/CHANGELOG.md

@@ -2,6 +2,63 @@
 
 All notable changes to UKit are documented here.
 
+## 2.5.0 - 2026-09-18
+
+C20 feature release (14 handoff tasks + 3-lane review): project-owner instructions via a
+seeded root `PROJECT_IMPORTANT.md`, delivered once per context epoch on every supported
+host.
+
+- **`PROJECT_IMPORTANT.md` seed-once ownership**: `ukit install` creates the file only
+  when missing (`mergeStrategy: skip`, exclusive `'wx'` create, `lstat`-based existence);
+  it is never rewritten, merged, chmodded, tracked in `install.json.files`, or deleted —
+  reinstalls preserve it byte-for-byte, and delete + reinstall re-seeds.
+- **Once-per-epoch injection**: Claude Code `SessionStart` (including
+  `source:'compact'` post-compact) and omp `session_start`/`session_compact` (steer only
+  — exactly one copy per epoch) render the file into advisory context; Codex and OpenCode
+  get a static read-the-file pointer in `AGENTS.md` (pointer, not runtime delivery).
+- **Bounded deterministic render** (`src/core/projectImportant.js` + installed-runtime
+  mirror): 6,000-Unicode-code-point limit with an explicit oversized warning, strict
+  UTF-8 decode (malformed input is never injected), BOM excluded from count and body,
+  `O_NOFOLLOW`/`O_NONBLOCK` open so symlinks/FIFOs/devices are never followed or hung on,
+  and a byte-identical envelope (no volatile metadata) for identical input.
+- **Fail-closed secret gate** (`src/core/sensitiveValueScanner.js`): the exact body to
+  be injected is scanned for high-confidence secret shapes; blocks report labels only —
+  never a value, excerpt, or hash.
+- **Uninstall backup**: `ukit uninstall` backs the file up to a sibling
+  `PROJECT_IMPORTANT.md.ukit-backup[.n]` at project root (`COPYFILE_EXCL`, bounded suffix
+  walk, byte-identical reuse, dry-run plans only) and aborts before any managed deletion
+  if the backup cannot be made.
+- **Honest-status surface**: `ukit status`/`ukit doctor` report per-check remediation
+  classes (`owner-action`/`install-repairable`/`advisory-host-limit`) and label local
+  prompt-cache stats as `Local p-cache` — provider telemetry is reported `unknown`, never
+  zero.
+
+## 2.4.3 - 2026-09-18
+
+C19 liveness-hardening release (23 handoff tasks): a full sweep of the shipped hook and
+runtime surface against the freeze/stall/orphan classes behind the recurring "session
+stands still mid-turn" reports, plus the regression instruments that keep them closed.
+
+- **Bounded hook stdin staging (H01)**: `hook-input.sh`/`hook-input.mjs` runtime helpers
+  plus bounded-staging fallback blocks in all 16 hook wrapper templates — a producer that
+  never closes the pipe can no longer hold a hook open (SIGKILL at the staging bound).
+- **Deadline-aware hot-hook filesystem work**: hook runtime modules self-arm on
+  `UKIT_HOOK_DEADLINE_MS` so a wedged read or lock wait exits inside the hook budget
+  instead of orphaning a node child.
+- **Process-tree + lock containment**: bounded process-tree kill when a descendant escapes
+  its group, atomic quarantine of validated stale lock generations, owner-stamp failure
+  no longer runs the callback under an ownerless lock, and deep-freeze + containment
+  fail-closed for discovery snapshot reuse.
+- **Liveness suite + classifier**: `src/diagnostics/classifyHang.js`, `tests/liveness/`,
+  and the `test:liveness` script — evidence-only hang classification (an external signal
+  is not a TERM→KILL leak) with regression scenarios pinned in tests.
+- **Execution-ledger hardening**: bounded route-scoped ledger journal, overflow guard on
+  drain commits, journal-local locking, and the Stop coordinator
+  (`stop-coordinator.mjs`) with its extracted watchdog path.
+- **Runtime shipping fix**: the install pipeline ships every packaged
+  `.claude/ukit/runtime` module via the `ukit-runtime-scripts` directory item (TASK-035),
+  closing the class where a new runtime module shipped to npm but never installed.
+
 ## 2.4.2 - 2026-09-16
 
 Fix: the gateway resilience posture disabled the only recovery path a buffering gateway

package/README.md

@@ -69,6 +69,26 @@ If maintainers roll out a newer CLI build, the in-project workflow still stays t
 - `.claude/ukit/.ukit/` — installer manifests, metadata, backups
 - `.ukit/` — hidden shared runtime storage for config, cache, and cross-agent memory
 - `docs/` — PROJECT / MEMORY / AI_HANDOFF / WORKLOG baseline
+- `PROJECT_IMPORTANT.md` — your project-owner instruction file (see below)
+
+## `PROJECT_IMPORTANT.md` — project-owner instructions
+
+`ukit install` seeds a root `PROJECT_IMPORTANT.md` **once**. After that the file is
+yours: UKit never rewrites, merges, formats, chmods, tracks, or deletes it — edits
+survive every `ukit install` rerun byte-for-byte, and deleting it + reinstalling
+seeds a fresh copy. It is also excluded from `ukit uninstall` deletion; uninstall
+backs it up to a sibling `PROJECT_IMPORTANT.md.ukit-backup[.n]` file at project
+root (never overwritten — a new suffix is chosen, and dry-run creates nothing).
+
+Put your non-negotiable project rules there. On each session start your AI tool
+receives its contents as advisory project-owner context — Claude Code and omp via
+their session hooks (and once more after a compaction, which starts a new context
+epoch), Codex and OpenCode via a static pointer in `AGENTS.md` (read-the-file
+instructions, not a runtime hook). Keep the file at or below **6,000 Unicode code
+points** — anything past that is truncated with an explicit warning, and the fix is
+to shorten the file, not rerun `ukit install`. Do not put credentials or secrets in
+it: a fail-closed sensitive-value scan runs on the exact body before injection and
+blocks anything that looks like a key or token.
 
 ## UKit v1.3.1 Runtime
 

package/manifests/platform.full.yaml

@@ -19,6 +19,20 @@ items:
     packs:
       - core
 
+  # Owner-instruction seed. `mergeStrategy: skip` gives seed-once semantics: UKit writes it
+  # only when the path is truly absent (exclusive 'wx' create in applyPlan), never rewrites,
+  # merges, formats, chmods or tracks it in install.json afterwards.
+  - id: project-important
+    type: config
+    sourceTemplate: PROJECT_IMPORTANT.md
+    targetPath: PROJECT_IMPORTANT.md
+    requires: []
+    mergeStrategy: skip
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
   - id: docs-memory
     type: config
     sourceTemplate: docs/MEMORY.md
@@ -987,6 +1001,7 @@ items:
       - hook-block-dangerous
       - hook-handoff-model-guard
       - hook-auto-prune-bash
+      - hook-project-important
     # Env block is post-merged by applyGatewayResilienceEnv (TASK-011) to add managed
     # gateway-resilience defaults without clobbering user values, so the diff ignores
     # the env block — byte-equality on the rest of the file is enough to flag an update.
@@ -1111,11 +1126,15 @@ items:
     packs:
       - core
 
+  # requires: [ukit-runtime-scripts] is forward-declared for the shared sensitive-value
+  # scanner (consumed by the guard once TASK-039 wires it). The guard is fail-closed, so
+  # its runtime dependency must be installed first — keeps the ordering posture explicit.
   - id: hook-sensitive-data-guard
     type: hook
     sourceTemplate: .claude/hooks/sensitive-data-guard.sh
     targetPath: .claude/hooks/sensitive-data-guard.sh
-    requires: []
+    requires:
+      - ukit-runtime-scripts
     mergeStrategy: overwrite_with_backup
     variables: []
     enabledByDefault: true
@@ -1255,6 +1274,18 @@ items:
     packs:
       - core
 
+  - id: hook-project-important
+    type: hook
+    sourceTemplate: .claude/hooks/project-important.sh
+    targetPath: .claude/hooks/project-important.sh
+    requires:
+      - ukit-runtime-scripts
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
   - id: hook-worklog-session-start
     type: hook
     sourceTemplate: .claude/hooks/session-start.md

package/package.json

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

package/src/cli/commands/doctor.js

@@ -18,6 +18,10 @@ import {
   GATEWAY_RESILIENCE_ENV_DEFAULTS,
   scanProfileResilienceEnv,
 } from '../../core/gatewayResilienceEnv.js';
+import {
+  inspectProjectImportant,
+  inspectProjectImportantWiring,
+} from '../../core/projectImportant.js';
 
 export const DOCTOR_HELP_FLAGS = new Set(['--help', '-h']);
 const KNOWN_FLAGS = new Set([...DOCTOR_HELP_FLAGS, '--skills', '--gateway']);
@@ -103,6 +107,109 @@ export async function runDoctor({ packageRoot, projectRoot, argv = [], homeDir =
 
   const ok = (v) => (v ? '✓' : '✗');
 
+  // TASK-044 — typed PROJECT_IMPORTANT.md checks (spec §14). Each failure
+  // carries a class: install-repairable | owner-action | advisory-host-limit.
+  const INSTALL_REPAIR = 'Run ukit install';
+  const piInspection = await inspectProjectImportant({
+    projectRoot,
+    config: runtimeConfigInspection.config,
+  });
+  const piWiring = await inspectProjectImportantWiring(projectRoot, { trackedPaths });
+  const piState = piInspection.state;
+
+  const contentCheck = (failedState, label, remedy) => ({
+    label,
+    passed: piState !== failedState && piState !== 'missing' && piState !== 'unsafe-type' && piState !== 'unreadable',
+    applicable: piState !== 'missing' && piState !== 'unsafe-type' && piState !== 'unreadable',
+    failed: piState === failedState,
+    remediationClass: 'owner-action',
+    remedy,
+  });
+
+  const projectChecks = [
+    {
+      label: 'PROJECT_IMPORTANT.md exists',
+      passed: piState !== 'missing',
+      failed: piState === 'missing',
+      remediationClass: 'install-repairable',
+      remedy: INSTALL_REPAIR,
+    },
+    {
+      label: 'PROJECT_IMPORTANT.md is a regular non-symlink file',
+      passed: piState !== 'unsafe-type' && piState !== 'missing',
+      failed: piState === 'unsafe-type',
+      applicable: piState !== 'missing',
+      remediationClass: 'owner-action',
+      remedy: 'Replace PROJECT_IMPORTANT.md with a regular file at the project root.',
+    },
+    {
+      label: 'PROJECT_IMPORTANT.md is readable',
+      passed: piState !== 'unreadable' && piState !== 'missing' && piState !== 'unsafe-type',
+      failed: piState === 'unreadable',
+      applicable: piState !== 'missing' && piState !== 'unsafe-type',
+      remediationClass: 'advisory-host-limit',
+      remedy: 'Check PROJECT_IMPORTANT.md file permissions; the host cannot read it.',
+    },
+    contentCheck('invalid-utf8', 'PROJECT_IMPORTANT.md is valid UTF-8',
+      'Save PROJECT_IMPORTANT.md as valid UTF-8 without changing its intended content.'),
+    contentCheck('unsafe-control', 'PROJECT_IMPORTANT.md free of unsupported control characters',
+      'Remove unsupported control characters from PROJECT_IMPORTANT.md.'),
+    contentCheck('empty', 'PROJECT_IMPORTANT.md is not empty',
+      'Add project-owner instructions to PROJECT_IMPORTANT.md.'),
+    contentCheck('oversized', 'PROJECT_IMPORTANT.md within 6,000 code points',
+      'Shorten PROJECT_IMPORTANT.md to 6,000 Unicode code points or fewer.'),
+    contentCheck('secret-blocked', 'PROJECT_IMPORTANT.md free of unallowlisted secrets',
+      'Redact the secret or explicitly allowlist it.'),
+    {
+      label: 'Runtime module .claude/ukit/runtime/project-important.mjs',
+      passed: piWiring.claude.runtimeModule,
+      failed: !piWiring.claude.runtimeModule,
+      remediationClass: 'install-repairable',
+      remedy: INSTALL_REPAIR,
+    },
+    {
+      label: 'Hook wrapper .claude/hooks/project-important.sh installed and executable',
+      passed: piWiring.claude.hookInstalled && piWiring.claude.hookExecutable,
+      failed: !(piWiring.claude.hookInstalled && piWiring.claude.hookExecutable),
+      remediationClass: 'install-repairable',
+      remedy: INSTALL_REPAIR,
+    },
+    {
+      label: 'Claude settings SessionStart order (project-important.sh first)',
+      passed: piWiring.claude.settingsWired,
+      failed: !piWiring.claude.settingsWired,
+      remediationClass: 'install-repairable',
+      remedy: INSTALL_REPAIR,
+    },
+  ];
+  if (piWiring.omp.installed) {
+    projectChecks.push({
+      label: 'omp bridge session_start order (project-important.sh first)',
+      passed: piWiring.omp.wired,
+      failed: !piWiring.omp.wired,
+      remediationClass: 'install-repairable',
+      remedy: INSTALL_REPAIR,
+    });
+  }
+  if (piWiring.codex.installed) {
+    projectChecks.push({
+      label: 'Codex fallback present (AGENTS.md owner-instructions section)',
+      passed: piWiring.codex.wired,
+      failed: !piWiring.codex.wired,
+      remediationClass: 'install-repairable',
+      remedy: INSTALL_REPAIR,
+    });
+  }
+  if (piWiring.opencode.installed) {
+    projectChecks.push({
+      label: 'OpenCode fallback present (AGENTS.md owner-instructions section)',
+      passed: piWiring.opencode.wired,
+      failed: !piWiring.opencode.wired,
+      remediationClass: 'install-repairable',
+      remedy: INSTALL_REPAIR,
+    });
+  }
+
   const providerNames = Object.keys(providers.providers);
   const providerStatus = providerNames
     .map((name) => `${name}=${ok(providers.providers[name].supported)}`)
@@ -139,6 +246,12 @@ export async function runDoctor({ packageRoot, projectRoot, argv = [], homeDir =
   }
   console.log(`[UKit]   ${ok(checks.allProvidersConfigured)}  All providers configured`);
 
+  console.log('[UKit] Project rules checks:');
+  for (const check of projectChecks) {
+    if (check.applicable === false) continue;
+    console.log(`[UKit]   ${ok(check.passed)}  ${check.label}`);
+  }
+
   if (runtimeConfigInspection.errors.length > 0) {
     console.log(`[UKit] Runtime config issues: ${runtimeConfigInspection.errors.join(' | ')}`);
   }
@@ -254,8 +367,25 @@ export async function runDoctor({ packageRoot, projectRoot, argv = [], homeDir =
   }
 
   const allPassed = Object.values(checks).every(Boolean);
-  if (!allPassed) {
-    console.log('[UKit] Some checks failed. Run `ukit install` to fix missing files.');
+  const failedProjectChecks = projectChecks.filter(
+    (check) => check.applicable !== false && !check.passed,
+  );
+  const blockingFailures = failedProjectChecks.filter(
+    (check) => check.remediationClass === 'install-repairable' || check.remediationClass === 'owner-action',
+  );
+
+  if (failedProjectChecks.length > 0) {
+    console.log('[UKit] Remedies:');
+    for (const check of failedProjectChecks) {
+      console.log(`[UKit]   - [${check.remediationClass}] ${check.remedy}`);
+    }
+  }
+
+  if (!allPassed || blockingFailures.length > 0) {
+    console.log('[UKit] Some checks failed.');
+    if (!allPassed && blockingFailures.length === 0) {
+      console.log('[UKit] Re-run `ukit install` to repair install-managed files.');
+    }
     process.exitCode = 1;
   } else {
     console.log('[UKit] All checks passed.');

package/src/cli/commands/uninstall.js

@@ -42,10 +42,28 @@ export async function runUninstall({ projectRoot, argv = [] }) {
     for (const p of result.wouldRemove) {
       console.log(`  - ${path.relative(projectRoot, p)}`);
     }
+    for (const p of result.preservedPaths ?? []) {
+      console.log(`[UKit] Preserved ${path.basename(p)}.`);
+    }
+    if (result.wouldBackup && (result.backupPaths ?? []).length > 0) {
+      console.log(`[UKit] Would back up to ${path.basename(result.backupPaths[0])}.`);
+    }
+    for (const warning of result.backupWarnings ?? []) {
+      console.log(warning);
+    }
     console.log(`[UKit] Would remove ${result.wouldRemove.length} path(s). Run without --dry-run to actually uninstall.`);
     return;
   }
 
+  for (const p of result.preservedPaths ?? []) {
+    console.log(`[UKit] Preserved ${path.basename(p)}.`);
+  }
+  for (const p of result.backupPaths ?? []) {
+    console.log(`[UKit] Backup: ${path.basename(p)}`);
+  }
+  for (const warning of result.backupWarnings ?? []) {
+    console.log(warning);
+  }
   console.log(`[UKit] Uninstall complete. Removed ${result.removed}/${result.attempted} managed paths.`);
   console.log('[UKit] Note: docs/PROJECT.md, docs/MEMORY.md, docs/AI_HANDOFF/, docs/WORKLOG.md contain user content and were preserved. Delete manually if needed.');
 }

package/src/core/applyPlan.js

@@ -1,6 +1,6 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import { writeFileAtomic, copyFileSafe, createDirectoryLink, removeLinkOnly } from './fileOps.js';
+import { writeFileAtomic, writeFileExclusive, copyFileSafe, createDirectoryLink, removeLinkOnly } from './fileOps.js';
 
 // legacy: '.antigravity/' stays TCC-protected — Antigravity adapter removed in v2.2.0, but a
 // stale install may still have the dir and must not lose TCC protection.
@@ -107,9 +107,24 @@ export async function applyDiffResults(diffResults, { backupRoot, projectRoot }
           )
           : entry.renderedContent;
 
+    // Race-safe seed: a `create` entry with `mergeStrategy: skip` must not overwrite a
+    // target that appeared after the diff ran. Exclusive 'wx' create fails with EEXIST
+    // instead — that becomes a skipped create (no rewrite, no chmod, no tracked write),
+    // and install continues. Temp+rename is NOT used here because rename overwrites.
+    const exclusiveSkipCreate = entry.action === 'create' && entry.mergeStrategy === 'skip';
+
     try {
-      await writeFileAtomic(entry.targetPath, nextContent);
+      if (exclusiveSkipCreate) {
+        await writeFileExclusive(entry.targetPath, nextContent);
+      } else {
+        await writeFileAtomic(entry.targetPath, nextContent);
+      }
     } catch (writeError) {
+      if (writeError.code === 'EEXIST' && exclusiveSkipCreate) {
+        skippedUpdates += 1;
+        skippedByAction.create += 1;
+        continue;
+      }
       if (
         (writeError.code === 'EPERM' || writeError.code === 'EACCES') &&
         isTccProtectedPath(entry.targetPath)

package/src/core/diffPlan.js

@@ -132,6 +132,37 @@ function resolveFileAction(entry, existingContent) {
   return { ...entry, exists, action, existingContent };
 }
 
+// A `mergeStrategy: skip` target must never be classified as "missing" just because it
+// cannot be READ — a directory, broken symlink, FIFO/device, or unreadable (EACCES) file
+// at the seed path all mean "exists, do not touch". readFileOrNull would turn every one
+// of those into null → 'create' → an overwrite attempt. Existence for skip entries is
+// decided by lstat (no symlink follow, no device open — reading a FIFO would hang).
+async function resolveSkipEntryAction(entry) {
+  let stat;
+  try {
+    stat = await fs.lstat(entry.targetPath);
+  } catch {
+    // ENOENT (or a stat failure we cannot distinguish from it) is the only state that
+    // means "seed me"; the apply step still uses an exclusive 'wx' create for the race.
+    return { ...entry, exists: false, action: 'create', existingContent: null };
+  }
+
+  // Only a regular, readable file can prove byte-equality for an 'unchanged' verdict.
+  // Anything else — directory, symlink (valid or broken), FIFO, socket, device, or a
+  // file we cannot read — is simply 'skip': present, owner-owned, hands off.
+  let existingContent = null;
+  if (stat.isFile() && !stat.isSymbolicLink()) {
+    existingContent = await readFileOrNull(
+      entry.targetPath,
+      Buffer.isBuffer(entry.renderedContent) ? null : 'utf8',
+    );
+  }
+  if (existingContent === null) {
+    return { ...entry, exists: true, action: 'skip', existingContent: null };
+  }
+  return resolveFileAction(entry, existingContent);
+}
+
 export async function diffInstallPlan(plan) {
   // Check all entries in parallel
   const results = await Promise.all(
@@ -141,6 +172,10 @@ export async function diffInstallPlan(plan) {
         return { ...entry, exists: action !== 'create', action, existingContent: null };
       }
 
+      if (entry.mergeStrategy === 'skip') {
+        return resolveSkipEntryAction(entry);
+      }
+
       const existingContent = await readFileOrNull(
         entry.targetPath,
         Buffer.isBuffer(entry.renderedContent) ? null : 'utf8',

package/src/core/fileOps.js

@@ -128,6 +128,32 @@ export async function copyFileSafe(fromPath, toPath) {
   await fs.copyFile(fromPath, toPath);
 }
 
+/**
+ * Exclusive-create write ('wx'): succeeds only when `filePath` does not already exist.
+ * Used for seed-once (`mergeStrategy: skip`) creates so a file that appears between
+ * diff and apply is never overwritten — the caller maps EEXIST to a skipped create.
+ * Never used as a temp+rename pair: rename could overwrite a target that just appeared.
+ * @param {string} filePath
+ * @param {string|Buffer} content - raw bytes; no encoding/normalization is applied
+ */
+export async function writeFileExclusive(filePath, content) {
+  await ensureDir(path.dirname(filePath));
+  await fs.writeFile(filePath, content, { flag: 'wx' });
+}
+
+/**
+ * Raw-byte copy into a path that must not already exist (exclusive destination create,
+ * `fs.constants.COPYFILE_EXCL`). No decode/re-encode — the destination is byte-identical
+ * to the source. Source is opened by path; callers needing no-follow semantics must
+ * verify the source type before calling. EEXIST propagates for the caller to handle.
+ * @param {string} fromPath
+ * @param {string} toPath
+ */
+export async function copyFileRawExclusive(fromPath, toPath) {
+  await ensureDir(path.dirname(toPath));
+  await fs.copyFile(fromPath, toPath, fs.constants.COPYFILE_EXCL);
+}
+
 export async function writeJson(filePath, data) {
   await writeFileAtomic(filePath, `${JSON.stringify(data, null, 2)}\n`);
 }