@ngockhoale/ukit 3.4.26 → 3.4.28

package/src/core/updateSafety.js

@@ -0,0 +1,174 @@
+import { createHash } from 'node:crypto';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { spawnSync as defaultSpawnSync } from 'node:child_process';
+import { readInstallMetadata } from './metadata.js';
+import { writeFileAtomic } from './fileOps.js';
+
+// F5: safety net around `ukit update`.
+//
+//   preflight  -> before ANY change: npm answers, project metadata readable and project
+//                 writable. A failed preflight aborts with nothing modified.
+//   snapshot   -> copies every UKit-managed regular file (install.json ledger + the known
+//                 user-edited configs) plus a sha256 manifest, BEFORE `npm install -g`.
+//   restore    -> if the project refresh fails, puts the project back and VERIFIES hashes.
+//
+// Honest scope: the snapshot covers PROJECT files only. The global npm package is never
+// rolled back automatically — after a failed refresh the global CLI stays on the new
+// version while the project is back on the old files. The report says so and prints the
+// exact npm command to pin the previous version; it never claims a full rollback.
+
+const SNAPSHOT_REL_DIR = path.join('.claude', 'ukit', '.ukit', 'update-snapshots');
+const INSTALL_META_REL = path.join('.claude', 'ukit', '.ukit', 'install.json');
+const EXTRA_SNAPSHOT_PATHS = [
+  '.claude/settings.json',
+  '.ukit/storage/config.json',
+  '.omp/config.yml',
+  '.gitignore',
+  'CLAUDE.md',
+  'AGENTS.md',
+];
+export const SNAPSHOT_KEEP = 3;
+
+const toPosix = (p) => p.replace(/\\/g, '/');
+const sha256 = (buf) => createHash('sha256').update(buf).digest('hex');
+
+function insideProject(projectRoot, rel) {
+  const abs = path.resolve(projectRoot, rel);
+  const relBack = path.relative(path.resolve(projectRoot), abs);
+  return relBack !== '' && !relBack.startsWith('..') && !path.isAbsolute(relBack) ? abs : null;
+}
+
+export async function preflightUpdate({ projectRoot, spawnSync = defaultSpawnSync, checkNpm = true } = {}) {
+  const problems = [];
+  if (checkNpm) {
+    const r = spawnSync('npm', ['--version'], { encoding: 'utf8', timeout: 15_000, killSignal: 'SIGKILL' });
+    if (r.error || r.status !== 0) problems.push(`npm is not runnable (${r.error?.message ?? `exit ${r.status}`})`);
+  }
+  try {
+    await readInstallMetadata(path.join(projectRoot, INSTALL_META_REL));
+  } catch (error) {
+    problems.push(`install metadata unreadable: ${error.message}`);
+  }
+  try {
+    await fs.access(projectRoot, fs.constants.W_OK);
+  } catch {
+    problems.push(`project directory is not writable: ${projectRoot}`);
+  }
+  return { ok: problems.length === 0, problems };
+}
+
+async function listManagedFiles(projectRoot) {
+  const rels = new Set(EXTRA_SNAPSHOT_PATHS.map(toPosix));
+  rels.add(toPosix(INSTALL_META_REL));
+  try {
+    const meta = await readInstallMetadata(path.join(projectRoot, INSTALL_META_REL));
+    for (const entry of Array.isArray(meta?.files) ? meta.files : []) {
+      const p = typeof entry === 'string' ? entry : entry?.p;
+      if (typeof p === 'string' && p.trim()) rels.add(toPosix(p.trim()));
+    }
+  } catch {
+    // preflight already reported unreadable metadata
+  }
+  return [...rels].filter((rel) => !rel.startsWith(`${toPosix(SNAPSHOT_REL_DIR)}/`));
+}
+
+export async function createUpdateSnapshot({ projectRoot, previousGlobalVersion = null, now = Date.now() }) {
+  const dir = path.join(projectRoot, SNAPSHOT_REL_DIR, String(now));
+  const filesDir = path.join(dir, 'files');
+  await fs.mkdir(filesDir, { recursive: true });
+  const files = [];
+  for (const rel of await listManagedFiles(projectRoot)) {
+    const abs = insideProject(projectRoot, rel);
+    if (!abs) continue;
+    let stat;
+    try {
+      stat = await fs.lstat(abs);
+    } catch (error) {
+      if (error?.code === 'ENOENT') {
+        files.push({ rel, existed: false });
+        continue;
+      }
+      throw new Error(`snapshot failed: cannot stat ${rel}: ${error.message}`);
+    }
+    if (!stat.isFile()) continue; // links and directories are re-created by install
+    const content = await fs.readFile(abs);
+    const dest = path.join(filesDir, rel);
+    await fs.mkdir(path.dirname(dest), { recursive: true });
+    await fs.writeFile(dest, content);
+    files.push({ rel, existed: true, sha256: sha256(content), mode: stat.mode & 0o777 });
+  }
+  const manifest = { version: 1, createdAt: new Date(now).toISOString(), previousGlobalVersion, files };
+  await fs.writeFile(path.join(dir, 'manifest.json'), `${JSON.stringify(manifest, null, 2)}\n`);
+  await pruneSnapshots(path.join(projectRoot, SNAPSHOT_REL_DIR));
+  return { dir, manifest };
+}
+
+async function pruneSnapshots(root) {
+  try {
+    const names = (await fs.readdir(root)).filter((n) => /^\d+$/.test(n)).sort((a, b) => Number(b) - Number(a));
+    for (const name of names.slice(SNAPSHOT_KEEP)) await fs.rm(path.join(root, name), { recursive: true, force: true });
+  } catch {
+    // advisory
+  }
+}
+
+// Restore the project to the snapshot and verify every file by hash. Files the failed
+// install created (tracked in the NEW ledger but absent from the snapshot ledger) are removed.
+export async function restoreUpdateSnapshot({ projectRoot, snapshotDir }) {
+  const manifest = JSON.parse(await fs.readFile(path.join(snapshotDir, 'manifest.json'), 'utf8'));
+  const failures = [];
+  let restored = 0;
+
+  for (const file of manifest.files) {
+    const abs = insideProject(projectRoot, file.rel);
+    if (!abs) continue;
+    try {
+      if (file.existed) {
+        const content = await fs.readFile(path.join(snapshotDir, 'files', file.rel));
+        await writeFileAtomic(abs, content);
+        if (typeof file.mode === 'number') await fs.chmod(abs, file.mode).catch(() => {});
+        restored += 1;
+      } else {
+        await fs.rm(abs, { force: true }); // created by the failed refresh
+      }
+    } catch (error) {
+      failures.push(`${file.rel}: ${error.message}`);
+    }
+  }
+
+  // Files tracked by the failed install but unknown to the snapshot: created by it.
+  const known = new Set(manifest.files.map((f) => f.rel));
+  try {
+    const meta = await readInstallMetadata(path.join(projectRoot, INSTALL_META_REL));
+    for (const entry of Array.isArray(meta?.files) ? meta.files : []) {
+      const rel = toPosix(typeof entry === 'string' ? entry : entry?.p ?? '');
+      if (!rel || known.has(rel)) continue;
+      const abs = insideProject(projectRoot, rel);
+      if (!abs) continue;
+      const stat = await fs.lstat(abs).catch(() => null);
+      if (stat?.isFile()) await fs.rm(abs, { force: true });
+    }
+  } catch {
+    // ledger itself was restored above; nothing more to reconcile
+  }
+
+  const mismatches = [];
+  for (const file of manifest.files) {
+    const abs = insideProject(projectRoot, file.rel);
+    if (!abs) continue;
+    if (file.existed) {
+      const now = await fs.readFile(abs).catch(() => null);
+      if (!now || sha256(now) !== file.sha256) mismatches.push(file.rel);
+    } else if (await fs.lstat(abs).then(() => true, () => false)) {
+      mismatches.push(file.rel);
+    }
+  }
+  return {
+    ok: failures.length === 0 && mismatches.length === 0,
+    restored,
+    failures,
+    mismatches,
+    previousGlobalVersion: manifest.previousGlobalVersion ?? null,
+  };
+}

package/src/index/contextPack.js

@@ -0,0 +1,285 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import { getArtifactPath, INDEX_ARTIFACTS, INDEX_SCHEMA_VERSION, normalizeRelative } from './paths.js';
+import { getFileOutline, queryCodeIndex } from './queryIndex.js';
+import { inferRelatedTests } from './relatedTests.js';
+import { discoverProjectFiles } from './buildIndex.js';
+import { isSensitivePath } from './sensitivePath.js';
+
+// TASK-B2 (PLAN-ENDUR-B §B2): deterministic, bounded context pack built from the
+// existing index artifacts. No LLM, no network, no clock/random — the same
+// inputs + the same index always serialize to byte-identical JSON.
+//
+// Contract notes (recorded in TASK-B2 Discussion):
+// - `overBudget` (global constraint "flags overBudget instead of dropping a
+//   required item"): required entries (targets) are always admitted; if the
+//   admitted set alone violates maxBytes/maxFiles the pack says so honestly
+//   instead of silently dropping a target. `truncated` marks extras
+//   (related tests) dropped for budget — the pack then never exceeds the bounds.
+// - `fallback: 'path-only'` is set when the index artifacts are missing/corrupt
+//   (whole pack is raw target paths) OR when any individual target could not be
+//   resolved through the index (that target is listed as a raw path).
+// - `index` accepts preloaded `{ meta, files }` artifacts to override the disk
+//   reads used for targeting/fingerprint; symbol outlines still come from the
+//   on-disk symbols artifact via getFileOutline.
+
+export const DEFAULT_MAX_BYTES = 12000;
+export const DEFAULT_MAX_FILES = 8;
+
+const TARGET_SCORE = 1000;
+const RELATED_TEST_SCORE = 12;
+const SYMBOL_QUERY_LIMIT = 3;
+const RELATED_TEST_LIMIT = 6;
+
+const REQUIRED_REASONS = new Set(['target', 'target-symbol', 'unresolved-target', 'path-only']);
+
+/**
+ * Build a deterministic, bounded context pack from the existing index.
+ *
+ * @param {object} [options]
+ * @param {string} [options.rootDir] Project root (default: cwd).
+ * @param {string[]} [options.targets] Target paths or symbol names.
+ * @param {number} [options.maxBytes] Byte budget for the files payload (default 12000).
+ * @param {number} [options.maxFiles] File-count budget (default 8).
+ * @param {{meta?: object, files?: object}} [options.index] Preloaded meta/files artifacts.
+ * @returns {Promise<{ok: boolean, files: Array<{path: string, reason: string, outline: Array, bytes: number}>,
+ *   truncated: boolean, overBudget: boolean, stale: boolean, fallback: 'path-only'|null,
+ *   bytes: number, fingerprint: {fileCount: number, newestMtimeMs: number, digest: string|null}|null}>}
+ *   Never throws: every failure mode degrades to `ok: true` with a degraded pack.
+ */
+export async function buildContextPack({
+  rootDir = process.cwd(),
+  targets = [],
+  maxBytes = DEFAULT_MAX_BYTES,
+  maxFiles = DEFAULT_MAX_FILES,
+  index = null,
+} = {}) {
+  const absoluteRoot = path.resolve(rootDir);
+  const byteBudget = normalizeBudget(maxBytes, DEFAULT_MAX_BYTES);
+  const fileBudget = normalizeBudget(maxFiles, DEFAULT_MAX_FILES);
+  const requestedTargets = normalizeTargets(targets);
+
+  const [filesArtifact, metaArtifact] = await Promise.all([
+    index?.files ?? readJsonArtifact(absoluteRoot, INDEX_ARTIFACTS.files),
+    index?.meta ?? readJsonArtifact(absoluteRoot, INDEX_ARTIFACTS.meta),
+  ]);
+
+  const indexUsable = isValidItemArtifact(filesArtifact) && isValidSchemaArtifact(metaArtifact);
+  const recordedFingerprint = normalizeRecordedFingerprint(metaArtifact?.sourceFingerprint);
+
+  // Staleness: compare meta.sourceFingerprint's file count / newest mtime to a
+  // fresh discovery enumeration. No auto refresh, no clock — pure comparison.
+  let stale = false;
+  if (indexUsable) {
+    if (!recordedFingerprint) {
+      stale = true;
+    } else {
+      const discovered = await discoverProjectFiles(absoluteRoot).catch(() => null);
+      stale = discovered
+        ? isFingerprintStale(recordedFingerprint, fingerprintMetaFromEntries(absoluteRoot, discovered))
+        : true;
+    }
+  }
+
+  const candidates = [];
+  let anyUnresolved = false;
+
+  if (indexUsable) {
+    const indexedFileSet = new Set(
+      filesArtifact.items
+        .filter((item) => item && typeof item === 'object' && typeof item.filePath === 'string')
+        .map((item) => item.filePath),
+    );
+
+    let rank = 0;
+    const resolvedTargetPaths = [];
+    for (const target of requestedTargets) {
+      if (isSensitivePath(target)) {
+        rank += 1;
+        continue;
+      }
+      const score = Math.max(1, TARGET_SCORE - rank);
+      rank += 1;
+
+      const directPath = normalizeTargetPath(target);
+      if (indexedFileSet.has(directPath)) {
+        candidates.push({ path: directPath, reason: 'target', score });
+        resolvedTargetPaths.push(directPath);
+        continue;
+      }
+
+      const queryHits = await queryCodeIndex({ rootDir: absoluteRoot, query: target, limit: SYMBOL_QUERY_LIMIT })
+        .catch(() => []);
+      const bestHit = queryHits.find((hit) => hit?.filePath && !isSensitivePath(hit.filePath));
+      if (bestHit) {
+        candidates.push({ path: bestHit.filePath, reason: 'target-symbol', score });
+        resolvedTargetPaths.push(bestHit.filePath);
+      } else {
+        anyUnresolved = true;
+        candidates.push({ path: directPath, reason: 'unresolved-target', score });
+      }
+    }
+
+    const relatedTests = resolvedTargetPaths.length > 0
+      ? await inferRelatedTests({ rootDir: absoluteRoot, candidateFiles: resolvedTargetPaths, limit: RELATED_TEST_LIMIT })
+        .catch(() => [])
+      : [];
+    for (const related of relatedTests) {
+      if (!related?.filePath || isSensitivePath(related.filePath)) {
+        continue;
+      }
+      candidates.push({ path: related.filePath, reason: 'related-test', score: RELATED_TEST_SCORE });
+    }
+  } else {
+    // Missing/corrupt index: path-only fallback listing the raw target paths.
+    anyUnresolved = requestedTargets.length > 0;
+    let rank = 0;
+    for (const target of requestedTargets) {
+      if (isSensitivePath(target)) {
+        rank += 1;
+        continue;
+      }
+      candidates.push({
+        path: normalizeTargetPath(target),
+        reason: 'path-only',
+        score: Math.max(1, TARGET_SCORE - rank),
+      });
+      rank += 1;
+    }
+  }
+
+  // Stable order: score desc, then path asc (plan §B2 acceptance).
+  candidates.sort((a, b) => b.score - a.score || a.path.localeCompare(b.path));
+
+  const seenPaths = new Set();
+  const deduped = candidates.filter((candidate) => {
+    if (seenPaths.has(candidate.path)) {
+      return false;
+    }
+    seenPaths.add(candidate.path);
+    return true;
+  });
+
+  const withOutline = indexUsable;
+  const selected = [];
+  let usedBytes = 0;
+  for (const candidate of deduped.filter((entry) => REQUIRED_REASONS.has(entry.reason))) {
+    const entry = await materializeEntry(absoluteRoot, candidate, withOutline);
+    selected.push(entry);
+    usedBytes += entry.bytes;
+  }
+
+  let truncated = false;
+  for (const candidate of deduped.filter((entry) => !REQUIRED_REASONS.has(entry.reason))) {
+    const entry = await materializeEntry(absoluteRoot, candidate, withOutline);
+    if (selected.length >= fileBudget || usedBytes + entry.bytes > byteBudget) {
+      truncated = true;
+      continue;
+    }
+    selected.push(entry);
+    usedBytes += entry.bytes;
+  }
+
+  const overBudget = selected.length > fileBudget || usedBytes > byteBudget;
+
+  return {
+    ok: true,
+    files: selected,
+    truncated,
+    overBudget,
+    stale,
+    fallback: !indexUsable || anyUnresolved ? 'path-only' : null,
+    bytes: usedBytes,
+    fingerprint: recordedFingerprint,
+  };
+}
+
+function normalizeBudget(value, defaultValue) {
+  const parsed = Number(value);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : defaultValue;
+}
+
+function normalizeTargets(targets) {
+  const list = Array.isArray(targets) ? targets : [targets];
+  const seen = new Set();
+  const normalized = [];
+  for (const raw of list) {
+    const value = String(raw ?? '').trim();
+    if (!value || seen.has(value)) {
+      continue;
+    }
+    seen.add(value);
+    normalized.push(value);
+  }
+  return normalized;
+}
+
+function normalizeTargetPath(target) {
+  return String(target ?? '').replace(/\\/g, '/').replace(/^\.\//, '').replace(/^\/+/, '');
+}
+
+async function materializeEntry(absoluteRoot, candidate, withOutline) {
+  const outline = withOutline
+    ? await getFileOutline({ rootDir: absoluteRoot, filePath: candidate.path }).catch(() => [])
+    : [];
+  const row = { path: candidate.path, reason: candidate.reason, outline, bytes: 0 };
+  row.bytes = Buffer.byteLength(JSON.stringify({ path: row.path, reason: row.reason, outline }));
+  return row;
+}
+
+async function readJsonArtifact(rootDir, artifactName) {
+  try {
+    const content = await fs.readFile(getArtifactPath(rootDir, artifactName), 'utf8');
+    return JSON.parse(content);
+  } catch {
+    return null;
+  }
+}
+
+// Same gate queryIndex applies (C92-B-03): artifacts written under a different
+// INDEX_SCHEMA_VERSION are treated as absent. Item artifacts (files.json) must
+// carry an `items` array; meta.json has none, so schema currency is its only gate.
+function isValidItemArtifact(artifact) {
+  return Boolean(
+    artifact
+    && typeof artifact === 'object'
+    && Array.isArray(artifact.items)
+    && artifact.schemaVersion === INDEX_SCHEMA_VERSION,
+  );
+}
+
+function isValidSchemaArtifact(artifact) {
+  return Boolean(artifact && typeof artifact === 'object' && artifact.schemaVersion === INDEX_SCHEMA_VERSION);
+}
+
+function normalizeRecordedFingerprint(raw) {
+  if (!raw || typeof raw !== 'object') {
+    return null;
+  }
+  return {
+    fileCount: Number(raw.fileCount),
+    newestMtimeMs: Number(raw.newestMtimeMs),
+    digest: typeof raw.digest === 'string' ? raw.digest : null,
+  };
+}
+
+function isFingerprintStale(recorded, current) {
+  return recorded.fileCount !== current.fileCount || recorded.newestMtimeMs !== current.newestMtimeMs;
+}
+
+// Mirrors createSourceFingerprint's normalization (buildIndex.js) for the two
+// fields the plan's staleness contract compares: fileCount and newestMtimeMs.
+function fingerprintMetaFromEntries(rootDir, entries) {
+  let fileCount = 0;
+  let newestMtimeMs = 0;
+  for (const entry of Array.isArray(entries) ? entries : []) {
+    const filePath = normalizeRelative(rootDir, entry?.absolutePath ?? '');
+    if (!filePath || filePath === '.' || filePath.startsWith('../') || path.isAbsolute(filePath)) {
+      continue;
+    }
+    fileCount += 1;
+    newestMtimeMs = Math.max(newestMtimeMs, Number(entry.mtimeMs ?? -1));
+  }
+  return { fileCount, newestMtimeMs };
+}

package/src/index/sensitivePath.js

@@ -0,0 +1,21 @@
+// Pure (I/O-free) sensitive-path predicate shared by the context pack builder
+// (src/index/contextPack.js) and the delegation candidate mapper
+// (src/core/agentRuntime/context.js). One definition so the two cannot drift.
+export function isSensitivePath(value) {
+  const normalized = String(value ?? '').replace(/\\/g, '/');
+  const segments = normalized.split('/');
+  const base = segments[segments.length - 1] ?? '';
+  if (base.toLowerCase().startsWith('.env')) {
+    return true;
+  }
+  if (/\.(?:pem|key|p12|pfx|jks|keystore)$/i.test(base)) {
+    return true;
+  }
+  if (/^(?:credentials?|\.npmrc|\.netrc|\.pypirc)(?:\.[^/]*)?$/i.test(base)) {
+    return true;
+  }
+  if (/^id_(?:rsa|dsa|ecdsa|ed25519)(?:\.[^/]*)?$/i.test(base)) {
+    return true;
+  }
+  return segments.includes('.ssh') || segments.includes('.aws') || segments.includes('.gnupg');
+}

package/src/index/taskRouting.js

@@ -1193,6 +1193,9 @@ function hasMutationOrder({ promptText = '', commandText = '' } = {}) {
   const WAIT_TAIL = '[^.,;\\n]*?(?=\\s+(?:va|and|nhung|roi|then|later|sau\\s+do)\\s+[^.,;\\n]*?\\b(?:implement|apply|update|modify|add|create|ship|deliver|fix|refactor|remove|delete|rename|change|write|build|make|install|run|deploy|execute|edit|sua|them|tao|xoa|doi|thay\\s+the|cap\\s+nhat|viet|chay|cai|chinh|trien\\s+khai|cau\\s+hinh)(?![A-Za-z0-9_])|[.,;]|\\s*$)';
   const residue = trimmed
     .replace(/"[^"\n]*"|«[^»\n]*»/g, ' ')
+    // Descriptive state, not an order: "đã/vừa [được] + verb" ("hooks vừa được cài đặt") reports
+    // something already done. Only the verb is stripped, so a later imperative still survives.
+    .replace(/(?<![a-z0-9_])(?:da|vua)\s+(?:duoc\s+)?(?:implement|apply|update|modify|add|create|ship|deliver|fix|refactor|remove|delete|rename|change|write|build|make|install|run|deploy|execute|edit|sua|them|tao|xoa|doi|thay\s+the|cap\s+nhat|viet|chay|cai|chinh|trien\s+khai|cau\s+hinh)(?![a-z0-9_])/g, ' ')
     .replace(/\bwrite-evidence\b|\bverification-evidence\b|\bimpact-evidence\b|\broot-cause\b/g, ' ')
     .replace(new RegExp(`\\bgiu\\s+nguyen\\b${TAIL}`, 'g'), ' ')
     .replace(new RegExp(`\\bmuon\\s+giu\\b${TAIL}`, 'g'), ' ')

package/template_project/.claude/commands/ukit/ci-check.md

@@ -0,0 +1,53 @@
+# /ukit:ci-check — Manual cross-platform CI (Windows · macOS · Linux)
+
+**Role: ORCHESTRATOR**
+**Tool: Bash (`git`, `gh`, `node`)**
+**Model: code model** (sonnet · unic-code)
+
+---
+
+GitHub Actions CI never runs by itself in this project: `cross-platform-ci.yml` is `workflow_dispatch` only. **Only the user typing `/ukit:ci-check` (run mode) approves a dispatch.** Implement, commit, push, merge, review, release and handoff NEVER invoke this command implicitly.
+
+All work is done by one helper; run it yourself, do not ask the user to:
+
+```
+node .claude/ukit/index/ci-check.mjs [status [<runId>] | run] [--ref <branch>] [--dry-run] [--explicit] [--wait] [--json]
+```
+
+## Modes
+
+| User typed | You run | Dispatches? |
+|---|---|---|
+| `/ukit:ci-check` | `run --explicit --json` then `status --wait --max-wait 540` (repeat until complete) | **max 1** |
+| `/ukit:ci-check status` | `status --wait --max-wait 540` (read-only) | never |
+| `/ukit:ci-check --ref <branch>` | `run --explicit --ref <branch> --json` then `status --wait --max-wait 540` (repeat until complete) | **max 1** |
+| `/ukit:ci-check --dry-run` | `run --dry-run --json` (no `--explicit`) | never |
+
+`--explicit` is passed ONLY because the user typed the command in run mode. Never add it for status/dry-run, never from another workflow.
+
+## Steps
+
+1. **Run the helper once.** It performs: A. precheck (git repo/remote/branch, `gh auth`, every workflow manual-only, commit exists on origin, no duplicate/in-flight run, default-branch registration, budget guard) → B. local preflight (referenced files tracked, docs registry; cheap only, no full suite) → C. exactly one `gh workflow run`, run id written to the project runtime storage (ci-check state file) *before and right after* the dispatch.
+2. **If it reports `BLOCKED` / `PREFLIGHT_FAILED` / `DISPATCH_FAILED`: stop and report the blockers verbatim.** No dispatch happened (or one failed). Do NOT retry, do NOT push, do NOT edit the workflow to work around it. A branch missing on origin, or a local commit not on origin, needs the user's separate approval to push. A missing default-branch registration needs the bootstrap PR (`docs/design/CI-CROSS-PLATFORM-MATRIX.md`, "Default-branch bootstrap"); propose it, never do it silently.
+3. **Monitor** with `status --wait --max-wait 540` (one Bash call is capped at 10 min; if the report is `INCOMPLETE` with `timedOutWaiting`, call it again, never dispatch) until the run completes (long wait: say `Waiting for GitHub Actions — run <id>`). If you are interrupted, the run id is on disk: resume with `/ukit:ci-check status` — it can never dispatch.
+4. **Report** exactly this shape (helper output already contains the data):
+
+```
+CROSS_PLATFORM_CI: PASS | FAIL | INCOMPLETE
+WINDOWS: <verdict> · stages · tests · time · job URL
+MACOS:   ...
+LINUX:   ...
+Tests total / skipped (names) · failing stages · root cause WITH log evidence
+Runner usage (billed-minute equivalent) · issues to fix · recommended next action
+```
+
+   A missing platform or an unfinished job is `INCOMPLETE`, never `PASS`. One failed platform makes the whole result `FAIL`. Root causes must quote log lines; if the logs do not show it, say so.
+
+## Hard limits
+
+- At most ONE dispatch per invocation; no auto-retry, no re-run of failed jobs, no second dispatch for "just one more try".
+- Standard GitHub-hosted runners only; the budget guard fails closed (unknown runner, missing timeout, > `ciCheck.maxJobs` / `maxBilledMinutes`). Never edit `ciCheck.*` in `.ukit/storage/config.json` to get past a failed guard.
+- Never push, merge, publish, bump versions, change billing, or enable `push` / `pull_request` / `schedule` triggers.
+- The helper only reads/writes its own state under the project runtime storage; it never touches the real User Layer.
+
+Works the same on Claude Code, Codex and omp (plain `node` + `gh`, no engine-specific tools).

package/template_project/.claude/hooks/auto-allow-bash.sh

@@ -289,16 +289,34 @@ async function applyMutation() {
     // costs the normal permission prompt for this one command.
     return;
   }
+  // The default 1.2s slice is shorter than the queue a burst of parallel hooks builds on a
+  // loaded host, so waiters gave up "busy" and lost their rule (measured: 194 busy drops in
+  // 165 bursts of 30). A longer slice is still BOUNDED — lockBudgetMs takes the min with the
+  // remaining hook deadline minus the cleanup reserve — and exhaustion stays fail-closed.
   const deadlineMs = lockModule.lockBudgetMs({
     hookDeadlineMs: HOOK_DEADLINE_MS,
     startedAt: LOCK_STARTED_AT,
+    maxWaitMs: 3000,
   });
   const outcome = await lockModule.withAsyncLock(usagePath, { deadlineMs }, applyMutation);
   if (!outcome.ok) {
-    // busy or aborted: fail closed — write nothing unlocked, exit 0.
+    // busy or aborted: fail closed — write nothing unlocked, exit 0. The drop is journaled
+    // (reason + waited ms only — never the rule or command) so a lost allow rule is
+    // diagnosable instead of silent.
+    if (typeof lockModule.journalDroppedLockMutation === "function") {
+      await lockModule.journalDroppedLockMutation(usagePath, { reason: outcome.reason, waitedMs: outcome.waitedMs });
+    }
     return;
   }
-})().catch(() => {});
+})().catch(async (error) => {
+  // A throw inside the locked mutation (e.g. atomic rename failure) is also a dropped rule.
+  // Record only the errno-style code, never the message (it can embed paths/rule text).
+  try {
+    const code = /^[A-Z0-9_]{2,24}$/.test(String(error && error.code)) ? error.code : "UNKNOWN";
+    const lockModule = await import(pathToFileURL(path.join(process.env.UKIT_RUNTIME_DIR || "", "async-lock.mjs")).href);
+    await lockModule.journalDroppedLockMutation(process.argv[2], { reason: "error:" + code, waitedMs: Date.now() - LOCK_STARTED_AT });
+  } catch {}
+});
 ' "$SETTINGS_LOCAL" "$USAGE_FILE" "$AUDIT_FILE" "$RULE" "$NOW_UTC" "$MAX_RULES" >/dev/null 2>&1 || true
 
 exit 0

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

@@ -489,7 +489,8 @@ function shellWriteHit(rawCommand) {
   // fd duplication (`2>&1`, `>&2`, `>&-`) is excluded by the `(?!&)` target shape.
   for (const m of command.matchAll(/(^|[^>])&?>{1,2}\s*(?:&(?![0-9-]))?((?!&)\S+)/g)) {
     // `2>/dev/null;` / `2>/dev/null|` / `2>/dev/null)` glue the shell operator onto the target token.
-    if (!['/dev/null', '/dev/stdout', '/dev/stderr'].includes(m[2].replace(/[;&|)]+$/, ''))) return true;
+    // The target token ends at the first shell operator (`2>/dev/null||true`, `>/dev/null&&x`).
+    if (!['/dev/null', '/dev/stdout', '/dev/stderr'].includes(m[2].split(/[;&|)]/)[0])) return true;
   }
   return SHELL_WRITE_PATTERNS.some((re) => re.test(command));
 }
@@ -505,10 +506,16 @@ function patchTargets(input) {
     if (typeof body !== 'string') continue;
     const lines = body.split(/\r?\n/);
     const found = [];
-    for (const line of lines) {
+    for (let li = 0; li < lines.length; li++) {
+      const line = lines[li];
       let m = line.match(/^\*\*\*\s+(?:(?:Add|Update|Delete)\s+File|Move\s+to):\s*(.+?)\s*$/);
       if (!m) m = line.match(/^diff --git\s+(?:"?a\/)?(\S+)\s+"?b\/(\S+?)"?\s*$/);
       if (m) { found.push(...m.slice(1).filter(Boolean)); continue; }
+      // A `---`/`+++` line is a header only as an adjacent `--- a` / `+++ b` pair; a lone one is
+      // hunk content (`--- x` = deleted line `-- x`). Pairing keeps declared hunk counts from hiding a header.
+      const isOld = /^--- \S/.test(line) && /^\+\+\+ \S/.test(lines[li + 1] ?? '');
+      const isNew = /^\+\+\+ \S/.test(line) && /^--- \S/.test(lines[li - 1] ?? '');
+      if (!isOld && !isNew) continue;
       m = line.match(/^(?:---|\+\+\+)\s+(?:[ab]\/)?([^\t]+?)\s*(?:\t.*)?$/);
       if (m && m[1] !== '/dev/null') found.push(m[1]);
     }

package/template_project/.claude/hooks/handoff-resume.sh

@@ -103,7 +103,7 @@ setTimeout(() => {
 }, HOOK_DEADLINE_MS).unref();
 
 const projectRoot = process.env.PROJECT_ROOT;
-const runPath = path.join(projectRoot, 'docs', 'AI_HANDOFF', 'RUN.md');
+let runPath = path.join(projectRoot, 'docs', 'AI_HANDOFF', 'RUN.md');
 const runtimePath = path.join(projectRoot, '.claude', 'ukit', 'runtime', 'execution-ledger.mjs');
 const intentPath = path.join(projectRoot, '.claude', 'ukit', 'runtime', 'handoff-intent.mjs');
 
@@ -169,6 +169,17 @@ async function emitOrdinaryResume(payload, source) {
   })();
   const source = typeof payload.source === 'string' ? payload.source : 'startup';
 
+  // Worktree scoping: the host pins CLAUDE_PROJECT_DIR to the primary checkout, so a
+  // session in an independent linked worktree must not be handed the primary's
+  // cursor. Only a git-verified worktree of this repo re-scopes the cursor; any
+  // failure keeps the primary path.
+  try {
+    const mod = await import(pathToFileURL(intentPath).href);
+    if (typeof mod.resolveHandoffRunRoot === 'function') {
+      runPath = path.join(mod.resolveHandoffRunRoot(projectRoot, payload.cwd), 'docs', 'AI_HANDOFF', 'RUN.md');
+    }
+  } catch {}
+
   let text;
   try {
     text = await fs.promises.readFile(runPath, 'utf8');
@@ -188,6 +199,19 @@ async function emitOrdinaryResume(payload, source) {
     process.exit(0);
   }
 
+  // Structured PAUSED (C100 P1): never inject a resume for a paused run, on any source.
+  try {
+    const mod = await import(pathToFileURL(intentPath).href);
+    if (typeof mod.runCursorPaused === 'function' && mod.runCursorPaused(text) === true) {
+      process.stdout.write([
+        'UKit note: docs/AI_HANDOFF/RUN.md has a handoff-fullstack run that is PAUSED '
+          + `(Phase: ${phase}; Cursor: ${field('Cursor') || 'not recorded'}).`,
+        'Not resumed or spawned; only an explicit user instruction lifts the pause. RUN.md untouched.',
+      ].join('\n') + '\n');
+      process.exit(0);
+    }
+  } catch {}
+
   const goal = field('Goal');
   const base = field('Base');
   const cursor = field('Cursor');