@ngockhoale/ukit 3.4.26 → 3.4.28

package/CHANGELOG.md

@@ -2,6 +2,36 @@
 
 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.28 - 2026-10-09
+
+**Release-safety close-out: config preservation, safe `ukit update`, OMP eval/Bash hardening (local RC; not yet published).**
+- **U1 `.claude/settings.json` ownership merge.** User `model`, `permissions.allow|deny|ask`, `permissions.defaultMode`, user environment entries, `statusLine`, plugins and unknown keys survive install/update. UKit-owned: `hooks` (safety wiring) and the template's own environment keys. Permission lists are a union (template entries always present). Behaviour change: user-added top-level keys no longer count as drift.
+- **U2 `.ukit/storage/config.json` ownership merge** (`src/core/runtimeConfigMerge.js`). User values (model routing, `autonomy`, `orchestration.permissionMode`, thresholds, unknown keys) win; new template keys are filled; `version`/`agent`/`_help` follow the release. The opt-in `orchestration.allowUnsafeEval` is reset to `false` on every upgrade and reported. A merge that would produce an invalid config leaves the file untouched; a corrupt file is replaced (timestamped backup first).
+- **F5 safe `ukit update`.** Preflight (npm runnable, install metadata readable, project writable), project snapshot with sha256 manifest before `npm install -g`, automatic restore + hash verification when the project refresh fails. The global package is **never** rolled back automatically: the output says so and prints `npm install -g @ngockhoale/ukit@<previous>`. Last 3 snapshots kept under `.claude/ukit/.ukit/update-snapshots/`.
+- **F1 OMP `eval` payload** (`{language, code}`) is now seen by the Bash guard chain (was an empty command).
+- **F2 OMP `eval` default-deny** in the bridge itself (independent of `.omp/config.yml`): allowed only with `orchestration.allowUnsafeEval=true`. The guard is best-effort for eval; threat model in `docs/release/MULTI-ENGINE-RELEASE-GATE.md`.
+- **F4 OMP Bash/eval fail closed** on hook-runner transport failure (no verdict = no execution). Read/Grep/Glob stay fail-open. User escape hatch: `UKIT_OMP_BASH_FAIL_OPEN=1`. The Stop lane is unaffected (no Stop loop).
+- Known limits: OMP tools `task`, MCP, `browser`, `user_bash`, `user_python` have no UKit guard chain; the Read/Grep secret guard is advisory on a runner outage.
+
+## 3.4.27 - 2026-10-09
+
+**Stop-gate evidence loop hardening and linked-worktree isolation (follow-up to 3.4.26).**
+- `execution-ledger`: `yarn`/`npm`/`pnpm release:verify` is recorded as a verification receipt. A verification command piped through `| tail`/`| grep` no longer journals as a pass unless `pipefail`/`PIPESTATUS` proves the real exit status. Verification verdicts are scoped to the checkout they ran in, and path-qualified runners are recognised; Bash work in sibling worktrees is attributed to the right checkout.
+- `stop-coordinator` / `handoff-resume`: the Stop/SessionStart handoff cursor is scoped to the git-verified linked worktree, so a run in one worktree no longer blocks or resumes another.
+- `safe-patch` / `pre-edit-backup`: Edit/Write targets inside git-listed linked worktrees of the same repo are accepted; backups are isolated per worktree even when two worktrees share one relative path.
+- `hook-chain-runner --emit-verdict`: multi-document JSON on stdout from chained hooks is coalesced into one valid document.
+- `auto-allow-bash`: a burst of concurrent hooks no longer silently loses allow rules. Dropped rules are journaled and the bounded lock slice is widened. Trade-off: worst-case lock wait under contention rises from ~1.2 s to ~3 s.
+- Dev tooling: `scripts/dev/worktree-preflight.mjs` bootstraps the gitignored runtime in a fresh worktree via `ukit install`, re-renders drifted gitignored `CLAUDE.md`/`AGENTS.md`, warns on a symlinked `node_modules`, and bounds its git/render children with explicit timeouts. `manifests/documentation.yaml` declares `WORKLOG_ARCHIVE.md` as `local_only`.
+- Test-only: route-audit `tmpDir` cleanup retries so a detached decision-shadow child cannot fail `afterEach` with `ENOTEMPTY`.
+- Known limits: 1 of 165 stress iterations of the concurrent auto-allow burst still lost a rule (cause not yet identified). Existing checkouts must re-run `ukit install` to pick up the new runtime.
+
 ## 3.4.26 - 2026-10-08
 
 **P1 fix: completion gate no longer reports `missing write-evidence` for tracked-file changes made through Bash.**

package/manifests/documentation.yaml

@@ -282,6 +282,8 @@ entries:
     load_policy: on-demand
     validation: [manual]
     archive_policy: never
+    local_only: true
+    notes: gitignored machine-local rotation target (created by the WORKLOG archive workflow); absent on a clean checkout is valid, validated normally when present
 
   # ── docs/ runtime + dir families ─────────────────────────────────────────
   - id: docs-status
@@ -416,6 +418,28 @@ entries:
     validation: [none]
     archive_policy: immutable
     notes: C99 measurement-only sub-agent cost audit snapshot; registered in 3.4.25 (was unclassified on 3.4.24)
+  - id: docs-analysis-c100-frag-a-d
+    path: docs/analysis/c100/frag-A-D.md
+    class: archive
+    audience: [maintainer]
+    owner: product
+    source_of_truth: docs/analysis/c100/frag-A-D.md
+    merge_strategy: none
+    load_policy: never
+    validation: [none]
+    archive_policy: immutable
+    notes: C100 report fragment A+D (cache-accounting trace, model/provider confidence, telemetry gaps); landed pre-integration, registered during MB-1
+  - id: docs-analysis-c100-frag-b-c
+    path: docs/analysis/c100/frag-B-C.md
+    class: archive
+    audience: [maintainer]
+    owner: product
+    source_of_truth: docs/analysis/c100/frag-B-C.md
+    merge_strategy: none
+    load_policy: never
+    validation: [none]
+    archive_policy: immutable
+    notes: C100 report fragment B+C (127-agent fan-out findings, root cause, productive vs avoidable); landed pre-integration, registered during MB-1
   - id: docs-skill-audits
     path: docs/skill-audits/
     class: archive
@@ -752,6 +776,7 @@ entries:
     load_policy: on-demand
     validation: [manual]
     archive_policy: never
+    local_only: true
   - id: mirror-omp-dir
     path: .omp/
     class: derived
@@ -772,6 +797,7 @@ entries:
     load_policy: on-demand
     validation: [manual]
     archive_policy: never
+    local_only: true
 
   # ── Same-wave additions (DOC-201 batch; files authored by TASK-208/212) ────
   - id: docs-host-capability-matrix
@@ -819,6 +845,41 @@ entries:
     archive_policy: never
     notes: C69 G7 operator doc — timeline render, support bundle contents/exclusions, replay limits
 
+  - id: docs-design-ci-cross-platform-matrix
+    path: docs/design/CI-CROSS-PLATFORM-MATRIX.md
+    class: canonical
+    audience: [maintainer]
+    owner: product
+    source_of_truth: docs/design/CI-CROSS-PLATFORM-MATRIX.md
+    merge_strategy: none
+    load_policy: on-demand
+    validation: [manual]
+    archive_policy: never
+    notes: C100 native CI matrix design (macOS/Windows/Linux); maintainer-only, not shipped to user projects
+
+  - id: docs-release-multi-engine-release-gate
+    path: docs/release/MULTI-ENGINE-RELEASE-GATE.md
+    class: canonical
+    audience: [maintainer]
+    owner: product
+    source_of_truth: docs/release/MULTI-ENGINE-RELEASE-GATE.md
+    merge_strategy: none
+    load_policy: on-demand
+    validation: [manual]
+    archive_policy: never
+    notes: OMP-first multi-engine release gate report (3.4.28 candidate); maintainer-only, not shipped to user projects
+
+  - id: docs-release-3-4-28-team-upgrade-notice
+    path: docs/release/3.4.28-TEAM-UPGRADE-NOTICE.md
+    class: canonical
+    audience: [maintainer]
+    owner: product
+    source_of_truth: docs/release/3.4.28-TEAM-UPGRADE-NOTICE.md
+    merge_strategy: none
+    load_policy: on-demand
+    validation: [manual]
+    archive_policy: never
+    notes: Team upgrade notice for 3.4.28 (local RC); maintainer-only, not shipped to user projects
 # Declared complexity→docs mapping consumed by the router's `docs=` summary segment
 # (src/index/taskRouting.js CONTEXT_LAYER_DOCS mirrors this block; DOC-201 FR-001/002).
 # queued-task intent omitted v1: docs/TASKS.md is optional per-repo (SPEC §14).

package/manifests/platform.full.yaml

@@ -1174,6 +1174,18 @@ items:
     packs:
       - core
 
+  - id: command-ci-check
+    type: command
+    sourceTemplate: .claude/commands/ukit/ci-check.md
+    targetPath: .claude/commands/ukit/ci-check.md
+    requires:
+      - ukit-ci-check-script
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
   - id: command-handoff-fullstack
     type: command
     sourceTemplate: .claude/commands/ukit/handoff-fullstack.md
@@ -1629,6 +1641,18 @@ items:
     packs:
       - core
 
+  - id: ukit-ci-check-script
+    type: config
+    sourceTemplate: .claude/ukit/index/ci-check.mjs
+    targetPath: .claude/ukit/index/ci-check.mjs
+    requires:
+      - ukit-index-safe-patch-script
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
   - id: ukit-index-provision-worktree-script
     type: config
     sourceTemplate: .claude/ukit/index/provision-worktree.mjs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "3.4.26",
+  "version": "3.4.28",
   "description": "Install/update an index-first AI workspace for Claude Code, OpenAI Codex and omp (Oh My Pi).",
   "license": "MIT",
   "type": "module",
@@ -30,6 +30,10 @@
     "bin/",
     "src/",
     "scripts/",
+    "!scripts/audit/c100/attribution-gap.mjs",
+    "!scripts/audit/c100/implementer-attribution.mjs",
+    "!scripts/audit/c100/trees-lifetimes.mjs",
+    "!scripts/audit/c100/usage-provenance.mjs",
     "template_project/",
     "template_user/",
     "!template_project/**/.smbdelete*",
@@ -56,8 +60,10 @@
     "index:query": "node ./scripts/index/query-index.mjs",
     "bug:triage": "node ./scripts/bug/triage.mjs",
     "skill:audit": "node ./scripts/skill/audit-skill.mjs",
+    "worktree:preflight": "node ./scripts/dev/worktree-preflight.mjs",
     "docs:render": "node scripts/docs/render-instructions.mjs --write",
     "docs:render:check": "node scripts/docs/render-instructions.mjs --check",
+    "test:python:setup": "node tests/python/setup-test-venv.mjs",
     "test:artifact": "vitest run tests/integration/packageArtifact.test.js tests/integration/artifactReferenceIntegrity.test.js",
     "test:release-core": "vitest run --exclude tests/integration/packageArtifact.test.js",
     "release:verify": "node ./scripts/release/verify-release.mjs",

package/scripts/audit/subagent-cost/metrics.mjs

@@ -39,9 +39,21 @@ const totalFor = (calls) => ({
   uncached: calls.reduce((n, c) => n + uncached(c), 0),
   inputSide: calls.reduce((n, c) => n + inputSide(c), 0),
 });
+// Cache metadata is only trustworthy when the read key was recorded (present_zero/present_positive).
+// Absent/invalid calls are excluded from the hit-rate denominator — they are UNKNOWN, not a miss.
+// Calls without a status (historical corpora built before MB-1) are treated as recorded.
+const cacheKnown = (call) => call.cacheMetadataStatus == null
+  || call.cacheMetadataStatus === 'present_zero' || call.cacheMetadataStatus === 'present_positive';
 const cacheFor = (calls) => {
-  const totals = totalFor(calls);
-  return { hitRate: ratio(totals.cacheRead, totals.inputSide), cacheRead: totals.cacheRead, inputSide: totals.inputSide };
+  const known = calls.filter(cacheKnown);
+  const totals = totalFor(known);
+  return {
+    hitRate: ratio(totals.cacheRead, totals.inputSide),
+    cacheRead: totals.cacheRead,
+    inputSide: totals.inputSide,
+    knownCalls: known.length,
+    unknownCalls: calls.length - known.length,
+  };
 };
 const sortedTop = (items, getValue, getKey) => [...items]
   .map((item) => ({ ...item, uncached: getValue(item), inputSide: getKey(item) }))

package/scripts/audit/subagent-cost/reader.mjs

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import readline from 'node:readline';
 import { createHash } from 'node:crypto';
+import { classifyCacheRead, classifyCacheWrite, cacheMetadataStatus, extractIdentity } from './usage-fields.mjs';
 
 const sha1 = (value) => createHash('sha1').update(value).digest('hex').slice(0, 12);
 const timestampMs = (value) => {
@@ -82,12 +83,15 @@ async function readMeta(file) {
   }
 }
 
-function makeCall(record, sessionId, agentId, agentType, depth, ts, priorTs) {
+function makeCall(record, sessionId, agentId, agentType, depth, ts, priorTs, meta = null) {
   const message = record.message ?? {};
   const usage = message.usage ?? {};
   const input = Number(usage.input_tokens) || 0;
-  const cacheRead = Number(usage.cache_read_input_tokens ?? usage.cache_read_tokens) || 0;
-  const cacheWrite = Number(usage.cache_creation_input_tokens ?? usage.cache_creation_tokens) || 0;
+  const readMetric = classifyCacheRead(usage);
+  const writeMetric = classifyCacheWrite(usage);
+  const cacheRead = readMetric.value;
+  const cacheWrite = writeMetric.value;
+  const identity = extractIdentity(record, meta);
   const output = Number(usage.output_tokens) || 0;
   const key = message.id ?? record.requestId ?? record.uuid;
   return {
@@ -102,6 +106,13 @@ function makeCall(record, sessionId, agentId, agentType, depth, ts, priorTs) {
     input,
     cacheRead,
     cacheWrite,
+    cacheReadStatus: readMetric.status,
+    cacheWriteStatus: writeMetric.status,
+    cacheMetadataStatus: cacheMetadataStatus(readMetric, writeMetric),
+    providerId: identity.providerId,
+    gatewayId: identity.gatewayId,
+    taskId: identity.taskId,
+    spawnPrefixHash: identity.spawnPrefixHash,
     output,
     zero: input === 0 && cacheRead === 0 && cacheWrite === 0 && output === 0,
     depth,
@@ -181,6 +192,7 @@ export async function loadCorpus(root, { since = null, until = null } = {}) {
         depth,
         ts,
         previousTs,
+        meta,
       );
       previousTs = ts;
       const key = call._dedupeKey ?? `line:${stats.lines}`;

package/scripts/audit/subagent-cost/usage-fields.mjs

@@ -0,0 +1,82 @@
+// MB-1 (C100) — telemetry correctness helpers shared by the sub-agent cost reader.
+// Pure, local, no LLM calls. Rules: a missing/invalid usage field is NEVER a measured zero;
+// an explicit 0 stays 0; provider/gateway/task/prefix identity is read only from explicit
+// allowlisted keys (the model name is never a signal) and unknown stays null.
+
+export const CACHE_STATUS = Object.freeze({
+  PRESENT_ZERO: 'present_zero',
+  PRESENT_POSITIVE: 'present_positive',
+  ABSENT: 'absent',
+  INVALID: 'invalid',
+});
+
+const READ_KEYS = ['cache_read_input_tokens', 'cache_read_tokens'];
+const WRITE_KEYS = ['cache_creation_input_tokens', 'cache_creation_tokens'];
+const PROVIDER_KEYS = ['providerId', 'provider_id', 'provider', 'apiProvider'];
+const GATEWAY_KEYS = ['gatewayId', 'gateway_id', 'gatewayName', 'gateway'];
+const MAX_ID_LENGTH = 128;
+const SAFE_ID = /^[A-Za-z0-9._:/@-]{1,128}$/;
+const SECRET_LIKE = /sk-[A-Za-z0-9]{8,}|bearer|secret|passw|token=|key=|api[_-]?key/i;
+
+function numericOrNull(raw) {
+  if (typeof raw === 'number') return Number.isFinite(raw) ? raw : null;
+  if (typeof raw === 'string' && raw.trim() !== '') {
+    const value = Number(raw);
+    return Number.isFinite(value) ? value : null;
+  }
+  return null;
+}
+
+/** Classify one cache metric. `value` is only the measured number; 0 for absent/invalid is a
+ * summing convenience — consumers must read `status`, never infer a miss from value 0. */
+export function classifyCacheMetric(usage, keys) {
+  if (!usage || typeof usage !== 'object') return { status: CACHE_STATUS.ABSENT, value: 0 };
+  for (const key of keys) {
+    const raw = usage[key];
+    if (raw === undefined || raw === null) continue;
+    const value = numericOrNull(raw);
+    if (value === null || value < 0) return { status: CACHE_STATUS.INVALID, value: 0 };
+    return { status: value === 0 ? CACHE_STATUS.PRESENT_ZERO : CACHE_STATUS.PRESENT_POSITIVE, value };
+  }
+  return { status: CACHE_STATUS.ABSENT, value: 0 };
+}
+
+export const classifyCacheRead = (usage) => classifyCacheMetric(usage, READ_KEYS);
+export const classifyCacheWrite = (usage) => classifyCacheMetric(usage, WRITE_KEYS);
+
+/** Combined status for a call: a known read status wins; otherwise the worse of the pair. */
+export function cacheMetadataStatus(read, write) {
+  if (read.status === CACHE_STATUS.INVALID || write.status === CACHE_STATUS.INVALID) return CACHE_STATUS.INVALID;
+  if (read.status === CACHE_STATUS.ABSENT) return CACHE_STATUS.ABSENT;
+  return read.status;
+}
+
+function safeId(raw) {
+  if (typeof raw !== 'string') return null;
+  const value = raw.trim();
+  if (value.length === 0 || value.length > MAX_ID_LENGTH) return null;
+  if (!SAFE_ID.test(value) || SECRET_LIKE.test(value)) return null;
+  return value;
+}
+
+function firstId(sources, keys) {
+  for (const source of sources) {
+    if (!source || typeof source !== 'object') continue;
+    for (const key of keys) {
+      const id = safeId(source[key]);
+      if (id) return id;
+    }
+  }
+  return null;
+}
+
+/** Identity metadata from explicit keys only; null means UNKNOWN (never a guessed value). */
+export function extractIdentity(record, meta = null) {
+  const sources = [record, record?.message, meta];
+  return {
+    providerId: firstId(sources, PROVIDER_KEYS),
+    gatewayId: firstId(sources, GATEWAY_KEYS),
+    taskId: firstId(sources, ['taskId', 'task_id']),
+    spawnPrefixHash: firstId(sources, ['spawnPrefixHash', 'spawn_prefix_hash']),
+  };
+}

package/scripts/dev/worktree-preflight.mjs

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+// Bootstrap the gitignored UKit runtime in a fresh `git worktree` so targeted tests can run.
+//
+// A new worktree only has tracked files. `.claude/`, `.ukit/`, `CLAUDE.md`, … are generated by
+// `ukit install` and gitignored, so mirror/runtime tests fail there for environment reasons.
+// This reuses `bin/ukit install` (no new generator), idempotently:
+//   - already bootstrapped            → no-op
+//   - missing prerequisites           → run `ukit install` once, re-check
+//   - not a linked worktree           → refuse (the primary checkout's .claude/ is the maintainer runtime)
+// `ukit install` writes the install flavour of root CLAUDE.md/AGENTS.md, but those files are
+// gitignored *render outputs* of template_project/instructions (docs:render). The preflight
+// re-renders them when they drift — never a tracked render target, which is only reported.
+// It copies nothing from another checkout (no sessions, secrets, handoff state) and does not
+// link node_modules — run `yarn install` in the worktree (a symlinked node_modules is warned:
+// realpath-sensitive hooks resolve it outside the project and misjudge delete targets).
+//
+// Usage: node scripts/dev/worktree-preflight.mjs [--root <dir>] [--check] [--json]
+// Exit:  0 ready · 1 prerequisites missing (--check, or bootstrap failed) · 2 refused
+
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// Generated by `ukit install`; each is required by a mirror/runtime test family.
+export const PREREQUISITES = [
+  'node_modules',
+  '.claude/settings.json',
+  '.claude/hooks',
+  '.claude/ukit/runtime/execution-ledger.mjs',
+  '.ukit/storage/config.json',
+  'CLAUDE.md',
+  'AGENTS.md',
+];
+
+// Explicit bounds so a wedged git/render child can never hang the preflight. Normal runs take
+// milliseconds; these sit far above that yet below `ukit install`'s own 120s budget.
+const GIT_TIMEOUT_MS = 30_000;
+const RENDER_TIMEOUT_MS = 60_000;
+
+function git(root, args) {
+  const res = spawnSync('git', args, { cwd: root, encoding: 'utf8', timeout: GIT_TIMEOUT_MS });
+  return res.status === 0 ? res.stdout.trim() : null;
+}
+
+export function isLinkedWorktree(root) {
+  const gitDir = git(root, ['rev-parse', '--path-format=absolute', '--git-dir']);
+  const common = git(root, ['rev-parse', '--path-format=absolute', '--git-common-dir']);
+  return Boolean(gitDir && common && path.resolve(gitDir) !== path.resolve(common));
+}
+
+function isTracked(root, rel) {
+  const res = spawnSync('git', ['ls-files', '--error-unmatch', '--', rel], { cwd: root, stdio: 'ignore', timeout: GIT_TIMEOUT_MS });
+  // A timed-out probe proves nothing: treat as tracked so the file is reported, never overwritten.
+  return res.status === 0 || Boolean(res.error);
+}
+
+const RENDER_CLI = 'scripts/docs/render-instructions.mjs';
+
+// → rel paths whose rendered bytes differ from disk (`DRIFT <target>` lines of --check).
+export function renderDrift(root) {
+  const res = spawnSync(process.execPath, [path.join(root, RENDER_CLI), '--check'], { cwd: root, encoding: 'utf8', timeout: RENDER_TIMEOUT_MS });
+  // A killed check prints nothing, which would read as "no drift" — fail loudly instead.
+  if (res.error) throw new Error(`render check did not complete (${res.error.code || res.error.message})`);
+  return `${res.stdout || ''}`.split('\n').map((l) => l.match(/^DRIFT (.+)$/)?.[1]).filter(Boolean);
+}
+
+export function missingPrerequisites(root) {
+  return PREREQUISITES.filter((rel) => !fs.existsSync(path.join(root, rel)));
+}
+
+export function preflight({ root, check = false } = {}) {
+  const projectRoot = fs.realpathSync(root);
+  const result = { root: projectRoot, ok: false, bootstrapped: false, missing: [], rendered: [], warnings: [], home: null, error: null };
+
+  if (!fs.existsSync(path.join(projectRoot, 'bin/ukit'))) {
+    return { ...result, exitCode: 2, error: `not a UKit checkout (no bin/ukit): ${projectRoot}` };
+  }
+  if (!isLinkedWorktree(projectRoot)) {
+    return { ...result, exitCode: 2, error: 'refusing: not a linked worktree (git worktree add …); the primary checkout keeps its own runtime' };
+  }
+
+  result.missing = missingPrerequisites(projectRoot);
+  if (result.missing.length > 0) {
+    if (check) return { ...result, exitCode: 1 };
+    if (result.missing.includes('node_modules')) {
+      return { ...result, exitCode: 1, error: 'node_modules missing — run `yarn install` in the worktree first (not linked from another checkout)' };
+    }
+
+    // `ukit install` also writes user-level state (~/.ukit playbooks). Point HOME inside the
+    // worktree's ignored .cache/ so a preflight never mutates the real home or leaks from it.
+    result.home = path.join(projectRoot, '.cache/worktree-preflight-home');
+    fs.mkdirSync(result.home, { recursive: true });
+    const install = spawnSync(process.execPath, [path.join(projectRoot, 'bin/ukit'), 'install'], {
+      cwd: projectRoot,
+      encoding: 'utf8',
+      env: { ...process.env, HOME: result.home, USERPROFILE: result.home },
+      timeout: 120_000,
+    });
+    result.bootstrapped = true;
+    result.missing = missingPrerequisites(projectRoot);
+    if (install.status !== 0 || result.missing.length > 0) {
+      const tail = `${install.stdout || ''}${install.stderr || ''}`.trim().split('\n').slice(-5).join('\n');
+      return { ...result, exitCode: 1, error: `ukit install did not produce all prerequisites (exit ${install.status})\n${tail}` };
+    }
+  }
+
+  if (fs.lstatSync(path.join(projectRoot, 'node_modules')).isSymbolicLink()) {
+    result.warnings.push('node_modules is a symlink — realpath-sensitive tests (block-dangerous) fail; run `yarn install` in this worktree for a real copy');
+  }
+
+  const drift = renderDrift(projectRoot);
+  if (drift.length > 0) {
+    if (check) return { ...result, missing: drift.map((t) => `render:${t}`), exitCode: 1 };
+    const tracked = drift.filter((t) => isTracked(projectRoot, t));
+    if (tracked.length > 0) {
+      return { ...result, exitCode: 1, error: `tracked render target(s) drifted, not overwriting: ${tracked.join(', ')} — commit or revert the source edit` };
+    }
+    const write = spawnSync(process.execPath, [path.join(projectRoot, RENDER_CLI), '--write'], { cwd: projectRoot, encoding: 'utf8', timeout: RENDER_TIMEOUT_MS });
+    const still = renderDrift(projectRoot);
+    if (write.status !== 0 || still.length > 0) {
+      return { ...result, exitCode: 1, error: `docs:render did not clear drift: ${still.join(', ') || (write.stderr || '').trim()}` };
+    }
+    result.rendered = drift;
+  }
+  return { ...result, ok: true, exitCode: 0 };
+}
+
+function main(argv) {
+  const args = { root: process.cwd(), check: false, json: false };
+  for (let i = 0; i < argv.length; i += 1) {
+    if (argv[i] === '--root') args.root = path.resolve(argv[++i] || '');
+    else if (argv[i] === '--check') args.check = true;
+    else if (argv[i] === '--json') args.json = true;
+  }
+  const { exitCode, ...result } = preflight(args);
+  if (args.json) {
+    process.stdout.write(`${JSON.stringify(result)}\n`);
+  } else if (result.ok) {
+    console.log(`[worktree-preflight] ready${result.bootstrapped ? ' (bootstrapped via ukit install)' : ' (already bootstrapped)'}: ${result.root}`);
+  } else {
+    console.error(`[worktree-preflight] ${result.error || `missing: ${result.missing.join(', ')}`}`);
+  }
+  process.exit(exitCode);
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) main(process.argv.slice(2));

package/src/cli/commands/update.js

@@ -1,8 +1,14 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { preflightUpdate, createUpdateSnapshot, restoreUpdateSnapshot } from '../../core/updateSafety.js';
 import { updateUkit, runInstallAfterUpdate, readInstalledGlobalVersion, UKIT_PACKAGE_NAME } from '../../core/update.js';
 
 const KNOWN_UPDATE_FLAGS = new Set(['--help', '-h', '--no-install']);
 
-export async function runUpdate({ packageVersion, argv = [], cwd = process.cwd() }) {
+const projectHasUkit = (cwd) => ['.ukit', path.join('.claude', 'ukit')].some((m) => fs.existsSync(path.join(cwd, m)));
+const INSTALL_FAILURE = /^install-(failed|exited)/;
+
+export async function runUpdate({ packageVersion, argv = [], cwd = process.cwd(), safety = { preflightUpdate, createUpdateSnapshot, restoreUpdateSnapshot } }) {
   if (argv.includes('--help') || argv.includes('-h')) {
     console.log('Usage: ukit update [--no-install]');
     console.log('');
@@ -28,9 +34,39 @@ export async function runUpdate({ packageVersion, argv = [], cwd = process.cwd()
   }
 
   console.log(`[UKit] Version before update: ${packageVersion}`);
+
+  // F5: preflight + project snapshot BEFORE anything changes. A failed preflight aborts
+  // with nothing modified; the snapshot is what makes a failed project refresh recoverable.
+  const refreshWanted = !argv.includes('--no-install') && projectHasUkit(cwd);
+  let snapshot = null;
+  if (refreshWanted) {
+    const pre = await safety.preflightUpdate({ projectRoot: cwd });
+    if (!pre.ok) {
+      console.log('[UKit] Update NOT started — preflight failed, nothing was changed:');
+      for (const problem of pre.problems) console.log(`  - ${problem}`);
+      process.exitCode = 1;
+      return;
+    }
+    try {
+      snapshot = await safety.createUpdateSnapshot({ projectRoot: cwd, previousGlobalVersion: packageVersion });
+      console.log(`[UKit] Project snapshot saved: ${path.relative(cwd, snapshot.dir) || snapshot.dir}`);
+    } catch (error) {
+      console.log(`[UKit] Update NOT started — could not snapshot the project (${error.message}). Nothing was changed.`);
+      process.exitCode = 1;
+      return;
+    }
+  }
+
   console.log(`[UKit] Running: npm install -g ${UKIT_PACKAGE_NAME}`);
 
-  updateUkit();
+  try {
+    updateUkit();
+  } catch (error) {
+    console.log(`[UKit] npm update failed: ${error.message}`);
+    console.log('[UKit] The project was not touched. The global package may be partially installed — run `ukit --version` to check, then retry `ukit update`.');
+    process.exitCode = 1;
+    return;
+  }
 
   // This process still runs the OLD code, so report the version the update actually
   // installed (read from disk), never the stale `packageVersion`.
@@ -72,5 +108,26 @@ export async function runUpdate({ packageVersion, argv = [], cwd = process.cwd()
     return;
   }
   console.log(`[UKit] CLI upgraded, but the project refresh did not finish (${reason}).`);
+  process.exitCode = 1;
+  if (snapshot && INSTALL_FAILURE.test(reason || '')) {
+    let result;
+    try {
+      result = await safety.restoreUpdateSnapshot({ projectRoot: cwd, snapshotDir: snapshot.dir });
+    } catch (error) {
+      result = { ok: false, failures: [error.message], mismatches: [] };
+    }
+    if (result.ok) {
+      console.log(`[UKit] PROJECT files restored from the snapshot and verified (${result.restored} files).`);
+    } else {
+      console.log('[UKit] PROJECT restore was incomplete — snapshot kept for manual recovery:');
+      for (const item of [...result.failures, ...result.mismatches]) console.log(`  - ${item}`);
+      console.log(`[UKit] Snapshot: ${snapshot.dir}`);
+    }
+    // Never imply a full rollback: only project files were restored.
+    console.log(`[UKit] The GLOBAL package was NOT rolled back — it is still ${installedVersion ?? 'the new version'}, while this project is on the previous files.`);
+    console.log(`[UKit] To return to the old CLI as well: npm install -g ${UKIT_PACKAGE_NAME}@${packageVersion}`);
+    console.log('[UKit] To retry the migration with the new CLI: ukit install');
+    return;
+  }
   console.log('[UKit] Run `ukit install` to retry.');
 }