@ngockhoale/ukit 2.7.6 → 2.7.8

package/scripts/perf/perf-measure.md

@@ -0,0 +1,271 @@
+# perf-measure.md — raw measurement notes (TASK-233)
+
+Generated: 2026-09-20T23:07:33.744Z
+
+Appendix source for `docs/AI_REPORT/AI_REVIEW_BUGS_REPORT.md`. Every number in
+`perf-findings.json` comes from one of the four sources below. TASK-236 re-runs
+the identical command for the before/after table (SPEC §5). Two numbers from two
+different snapshots are only comparable once their provenance line agrees.
+
+## 1. Reproduce
+
+```bash
+node scripts/perf/audit-perf.mjs \
+  --telemetry-dir "/Volumes/KHOA_EXTENAL/WORKING_PROJECT/WORKING/UKit/.ukit/storage/cache/hook-latency" \
+  --out "/Volumes/KHOA_EXTENAL/WORKING_PROJECT/WORKING/UKit/scripts/perf/perf-findings.json"
+node scripts/perf/diff-perf-findings.mjs <earlier-snapshot>.json scripts/perf/perf-findings.json
+node --test tests/handoff/c33/perfFindings.test.js
+
+- root: `/Volumes/KHOA_EXTENAL/WORKING_PROJECT/WORKING/UKit`
+- settings.json: `/Volumes/KHOA_EXTENAL/WORKING_PROJECT/WORKING/UKit/templates/.claude/settings.json`
+- hooks resolved from: `NOT FOUND`
+- telemetry: `/Volumes/KHOA_EXTENAL/WORKING_PROJECT/WORKING/UKit/.ukit/storage/cache/hook-latency` — 62854 rows in 120 files
+- snapshot provenance: generatedAt `2026-09-20T23:07:33.744Z`, telemetryRows: 62854, telemetryFiles: 120 — hooks append continuously, so a report is a point-in-time view, not a stable dataset
+- benchmark iterations per subject: 2
+
+## 2. Process floor (live spawnSync, ms)
+
+| subject | p50 | p95 | max |
+|---|---|---|---|
+| `bash -c true` | 3.13 | 3.13 | 3.13 |
+| `node -e 0` | 16.11 | 16.11 | 16.11 |
+| `node hook-telemetry.mjs --finish` | 19.50 | 19.50 | 19.50 |
+
+A hook row = wrapper bash + node runtime + advisory telemetry child = **3 processes**.
+
+## 3. Telemetry append overhead (O5 — in-process `appendTelemetryRow`, ms)
+
+| subject | iterations | p50 | p95 | max |
+|---|---|---|---|---|
+| `appendTelemetryRow` → throwaway temp root | 2 | 0.407 | 0.407 | 0.407 |
+
+Writer: `templates/.claude/ukit/runtime/hook-telemetry.mjs`. Measured against a temp project root, so auditing a tree never adds rows to the dataset it is counting.
+
+## 4. Per-hook standalone re-run (`/bin/bash <script>` with `{}` on stdin, ms)
+| hook | p50 | p95 | max |
+|---|---|---|---|
+| _(no settings hook resolvable from this root)_ | | | |
+
+## 5. Router/index helper cold start (ms)
+
+| helper | p50 | p95 | max |
+|---|---|---|---|
+| `skill-router.sh` | 105.2 | 105.2 | 105.2 |
+| `route-task.mjs` | 26.4 | 26.4 | 26.4 |
+| `query-index.mjs` | 23.6 | 23.6 | 23.6 |
+| `resolve-context.mjs` | 21.9 | 21.9 | 21.9 |
+
+## 6. Per-hook telemetry (every hook with rows)
+
+| hook | n | p50 | p95 | max | total |
+|---|---|---|---|---|---|
+| `hook-chain-runner` | 9453 | 80 | 375 | 2020 | 1269815 |
+| `block-dangerous.sh` | 5107 | 83 | 237 | 426 | 461434 |
+| `sensitive-data-guard.sh` | 5001 | 45 | 91 | 1591 | 398855 |
+| `context-hardcap-gate.sh` | 5650 | 55 | 88 | 291 | 334184 |
+| `auto-allow-bash.sh` | 4864 | 50 | 86 | 285 | 264888 |
+| `compress-output.sh` | 4701 | 49 | 66 | 207 | 237025 |
+| `record-execution.sh` | 4880 | 39 | 63 | 178 | 207226 |
+| `handoff-model-guard.sh` | 5603 | 22 | 53 | 189 | 136670 |
+| `verification-guard.sh` | 3520 | 33 | 61 | 137 | 136027 |
+| `skill-router.sh` | 1089 | 52 | 134 | 311 | 68680 |
+| `protect-files.sh` | 1544 | 21 | 156 | 344 | 58507 |
+| `task-watchdog.sh` | 930 | 38 | 216 | 237 | 42736 |
+| `pre-edit-backup.sh` | 732 | 50 | 72 | 216 | 35743 |
+| `stale-spec-guard.sh` | 745 | 46 | 70 | 169 | 34187 |
+| `post-edit-verify.sh` | 716 | 43 | 60 | 145 | 32444 |
+| `vision-router.sh` | 325 | 73 | 220 | 395 | 29834 |
+| `record-execution.mjs` | 2864 | 5 | 16 | 53 | 17607 |
+| `context-window-guard.sh` | 325 | 45 | 84 | 109 | 15798 |
+| `sensitive-data-guard.mjs` | 2812 | 4 | 6 | 15 | 11498 |
+| `completion-gate.sh` | 119 | 80 | 108 | 174 | 9881 |
+| `handoff-resume.sh` | 122 | 31 | 55 | 97 | 4307 |
+| `block-dangerous.mjs` | 1632 | 1 | 2 | 3 | 2334 |
+| `project-important.sh` | 47 | 38 | 61 | 62 | 1962 |
+| `auto-prune-bash.sh` | 19 | 34 | 44 | 44 | 679 |
+| `reset-compact-pressure.sh` | 19 | 34 | 38 | 38 | 647 |
+| `probe-source-only.sh` | 20 | 10 | 22 | 22 | 216 |
+| `probe-s2.sh` | 15 | 10 | 25 | 25 | 164 |
+
+## 7. Stdin stage vs execution split (O3 — the wall-time tail attributed)
+
+A row's `elapsedMs` is the stdin stage plus the hook's own execution. `stageMs`
+(direct rows) and `stdinStageMs` (chain rows) are the first half — the producer's
+time, not the hook's — and `exec` below is the remainder, derived from the SAME
+row so the two halves always sum to it. A row carrying neither field predates the
+split or never staged stdin: it is excluded, never counted as a 0ms stage.
+
+- rows with the split: 0 of 62854
+- overall: stage n/ams p50 / n/ams p95, exec n/ams p50 / n/ams p95
+
+| hook | field | n | stage p50 | stage p95 | exec p50 | exec p95 |
+|---|---|---|---|---|---|---|
+| _(no row carries the split on this tree)_ | | | | | | |
+
+## 8. Per tool / per event cost (chain-runner total where present, else direct sum)
+
+| scope | calls | cost p50 | cost p95 | hook rows/call p50 | direct / chain-runner calls |
+|---|---|---|---|---|---|
+| PostToolUse Bash | 4701 | 87 | 150 | 2 | 2406 / 2295 |
+| PostToolUse Edit | 610 | 129 | 222 | 3 | 351 / 259 |
+| PostToolUse Glob | 60 | 78 | 117 | 2 | 0 / 60 |
+| PostToolUse Grep | 275 | 15 | 101 | 2 | 0 / 275 |
+| PostToolUse Read | 1994 | 37 | 122 | 2 | 393 / 1601 |
+| PostToolUse Write | 103 | 132 | 219 | 4 | 46 / 57 |
+| PreToolUse Bash | 4853 | 307 | 474 | 6 | 2519 / 2334 |
+| PreToolUse Edit | 616 | 328 | 432 | 6 | 356 / 260 |
+| PreToolUse Glob | 60 | 59 | 74 | 2 | 0 / 60 |
+| PreToolUse Grep | 275 | 7 | 74 | 2 | 0 / 275 |
+| PreToolUse Read | 2005 | 39 | 71 | 2 | 404 / 1601 |
+| PreToolUse Write | 112 | 344 | 418 | 7 | 46 / 66 |
+| event (unattributed) (clustered, gap ≤ 1500ms) | 775 | 313 | 1567 | 1 | 752 / 23 |
+| event PostToolUse (clustered, gap ≤ 1500ms) | 7886 | 84 | 154 | 2 | 3339 / 4547 |
+| event PreCompact (clustered, gap ≤ 1500ms) | 6 | 49 | 53 | 1 | 0 / 6 |
+| event PreToolUse (clustered, gap ≤ 1500ms) | 8045 | 255 | 442 | 6 | 3431 / 4614 |
+| event SessionEnd (clustered, gap ≤ 1500ms) | 1 | 2020 | 2020 | 1 | 0 / 1 |
+| event SessionStart (clustered, gap ≤ 1500ms) | 113 | 119 | 289 | 2 | 38 / 75 |
+| event Stop (clustered, gap ≤ 1500ms) | 116 | 81 | 111 | 1 | 113 / 3 |
+| event UserPromptSubmit (clustered, gap ≤ 1500ms) | 349 | 291 | 582 | 4 | 200 / 149 |
+
+## 9. Hook multiplicity proof (repeat-fire check)
+
+| hook | max fires in one tool call | calls observed | fire-count distribution |
+|---|---|---|---|
+| `auto-allow-bash.sh` | 6 | 4859 | {"1":4858,"6":1} |
+| `auto-prune-bash.sh` | 2 | 17 | {"1":15,"2":2} |
+| `block-dangerous.mjs` | 1 | 1632 | {"1":1632} |
+| `block-dangerous.sh` | 24 | 3651 | {"1":3475,"2":59,"3":55,"6":1,"20":1,"22":58,"23":1,"24":1} |
+| `completion-gate.sh` | 3 | 117 | {"1":116,"3":1} |
+| `compress-output.sh` | 3 | 4699 | {"1":4698,"3":1} |
+| `context-hardcap-gate.sh` | 46 | 5601 | {"1":5599,"5":1,"46":1} |
+| `context-window-guard.sh` | 4 | 295 | {"1":272,"2":17,"3":5,"4":1} |
+| `handoff-model-guard.sh` | 46 | 5553 | {"1":5550,"2":1,"5":1,"46":1} |
+| `handoff-resume.sh` | 4 | 109 | {"1":99,"2":8,"3":1,"4":1} |
+| `post-edit-verify.sh` | 4 | 713 | {"1":712,"4":1} |
+| `pre-edit-backup.sh` | 6 | 727 | {"1":726,"6":1} |
+| `probe-s2.sh` | 15 | 1 | {"15":1} |
+| `probe-source-only.sh` | 20 | 1 | {"20":1} |
+| `project-important.sh` | 5 | 37 | {"1":33,"2":1,"3":1,"4":1,"5":1} |
+| `protect-files.sh` | 26 | 992 | {"1":881,"2":57,"3":1,"10":52,"26":1} |
+| `record-execution.mjs` | 1 | 2864 | {"1":2864} |
+| `record-execution.sh` | 4 | 4875 | {"1":4873,"3":1,"4":1} |
+| `reset-compact-pressure.sh` | 2 | 17 | {"1":15,"2":2} |
+| `sensitive-data-guard.mjs` | 3 | 2806 | {"1":2801,"2":4,"3":1} |
+| `sensitive-data-guard.sh` | 21 | 4949 | {"1":4927,"2":15,"3":3,"4":1,"5":2,"21":1} |
+| `skill-router.sh` | 26 | 1029 | {"1":1000,"2":22,"3":5,"4":1,"26":1} |
+| `stale-spec-guard.sh` | 6 | 736 | {"1":731,"2":4,"6":1} |
+| `task-watchdog.sh` | 4 | 925 | {"1":922,"2":2,"4":1} |
+| `verification-guard.sh` | 6 | 3515 | {"1":3514,"6":1} |
+| `vision-router.sh` | 4 | 295 | {"1":272,"2":17,"3":5,"4":1} |
+
+## 10. hook-chain-runner nested per-script (already-consolidated omp path)
+
+| script | n | p50 | p95 | max |
+|---|---|---|---|---|
+| `record-execution.mjs` | 2864 | 5 | 16 | 53 |
+| `sensitive-data-guard.mjs` | 2816 | 4 | 6 | 15 |
+| `handoff-model-guard.sh` | 2641 | 39 | 58 | 166 |
+| `context-hardcap-gate.sh` | 2635 | 68 | 82 | 152 |
+| `auto-allow-bash.sh` | 2350 | 72 | 82 | 426 |
+| `compress-output.sh` | 2295 | 73 | 92 | 169 |
+| `verification-guard.sh` | 2290 | 55 | 67 | 305 |
+| `record-execution.sh` | 1683 | 66 | 129 | 253 |
+| `block-dangerous.mjs` | 1636 | 1 | 2 | 3 |
+| `sensitive-data-guard.sh` | 1634 | 60 | 76 | 203 |
+| `block-dangerous.sh` | 737 | 79 | 150 | 425 |
+| `skill-router.sh` | 486 | 69 | 166 | 280 |
+| `protect-files.sh` | 336 | 50 | 59 | 360 |
+| `stale-spec-guard.sh` | 336 | 57 | 70 | 149 |
+| `pre-edit-backup.sh` | 325 | 59 | 72 | 115 |
+| `post-edit-verify.sh` | 316 | 67 | 90 | 184 |
+| `task-watchdog.sh` | 316 | 59 | 72 | 118 |
+| `vision-router.sh` | 160 | 83 | 161 | 231 |
+| `context-window-guard.sh` | 160 | 59 | 74 | 86 |
+| `project-important.sh` | 87 | 15 | 104 | 529 |
+| `auto-prune-bash.sh` | 86 | 26 | 64 | 75 |
+| `reset-compact-pressure.sh` | 86 | 26 | 56 | 70 |
+| `handoff-resume.sh` | 86 | 56 | 69 | 86 |
+| `reinject-context.sh` | 6 | 49 | 53 | 53 |
+| `completion-gate.sh` | 3 | 111 | 134 | 134 |
+| `t234-silent.sh` | 3 | 2 | 106 | 106 |
+| `session-episode.sh` | 1 | 2020 | 2020 | 2020 |
+
+## 11. settings.json groups (spawn budget per call)
+
+| event | matcher | hooks | registered timeouts | spawns/call |
+|---|---|---|---|---|
+| PreToolUse | Read|Grep|Glob | sensitive-data-guard.mjs:8 | 18s | 3 |
+| PreToolUse | Edit|Write | context-hardcap-gate.sh:8 | 73s | 3 |
+| PreToolUse | Bash | verification-guard.sh:8 | 65s | 3 |
+| PostToolUse | Read|Grep|Glob | record-execution.mjs:8 | 18s | 3 |
+| PostToolUse | Edit|Write | task-watchdog.sh:8 | 34s | 3 |
+| PostToolUse | Bash | record-execution.mjs:8 | 30s | 3 |
+| UserPromptSubmit | (all) | context-window-guard.sh:10 | 60s | 3 |
+| Stop | (all) | completion-gate.sh:8 | 18s | 3 |
+| PreCompact | (all) | reinject-context.sh:8 | 18s | 3 |
+| SessionStart | (all) | handoff-resume.sh:8 | 50s | 3 |
+| SessionEnd | (all) | session-episode.sh:8 | 18s | 3 |
+
+## 12. Recent hot-path additions (`git log --diff-filter=A`)
+
+| commit | date | subject | files added |
+|---|---|---|---|
+| `c0443e73` | 2026-09-20 | handoff: wave 2 — TASK-003 (block-dangerous.mjs port) + TASK-004 (record-execution.mjs + ledger emitter) + manifest module entries | `templates/.claude/hooks/block-dangerous.mjs`, `templates/.claude/hooks/record-execution.mjs` |
+| `79f747b6` | 2026-09-20 | handoff: wave 1 — TASK-001 (runner .mjs module-steps) + TASK-002 (sensitive-data-guard port + field-salvage) | `templates/.claude/hooks/sensitive-data-guard.mjs`, `templates/.claude/ukit/runtime/hook-field-salvage.mjs` |
+| `6b339905` | 2026-09-20 | handoff: wave 3 — TASK-231, TASK-232 | `templates/.claude/hooks/session-episode.sh` |
+| `4903ee62` | 2026-09-18 | handoff: restore wave-4a files removed by stale worktree diff | `templates/.claude/hooks/project-important.sh` |
+| `2b367850` | 2026-09-18 | handoff: wave 4a — TASK-041 (sessionstart wiring, hook template+manifest) | `templates/.claude/hooks/project-important.sh` |
+| `5ffefb09` | 2026-09-18 | handoff: wave 3 — TASK-038 | `templates/.claude/ukit/runtime/project-important.mjs`, `templates/.claude/ukit/runtime/sensitive-value-scanner.mjs` |
+| `ebb846b8` | 2026-09-17 | handoff: R4.5 fix round 1 — TASK-018, TASK-023 | `templates/.claude/ukit/runtime/hook-chain-budget.mjs` |
+| `c9da9734` | 2026-09-17 | handoff: wave 6 — TASK-025 copy-back (Stop coordinator) | `templates/.claude/ukit/runtime/stop-coordinator.mjs` |
+| `a1361afd` | 2026-09-17 | handoff: wave 5 — TASK-031 copy-back | `templates/.claude/ukit/runtime/hook-payload-store.mjs` |
+| `66787f98` | 2026-09-17 | handoff: wave 5 — TASK-019 copy-back | `templates/.claude/ukit/runtime/hook-telemetry.mjs`, `templates/.claude/ukit/runtime/hook-telemetry.sh` |
+| `3afc88e6` | 2026-09-17 | handoff: wave 5 — TASK-029 copy-back (context capacity negotiation) | `templates/.claude/ukit/runtime/context-capacity.mjs` |
+| `6f224875` | 2026-09-17 | handoff: wave 3 — TASK-028 copy-back | `templates/.claude/ukit/runtime/async-lock.mjs` |
+| `e4b647a3` | 2026-09-17 | handoff: wave 3 — TASK-016 copy-back | `templates/.claude/ukit/runtime/hook-process.mjs` |
+| `7aa89361` | 2026-09-17 | handoff: wave 2 — TASK-015, TASK-017 | `templates/.claude/ukit/runtime/transcript-tail.mjs` |
+| `2652bbff` | 2026-09-17 | milestone: TASK-014 bounded stdin transport (H01) | `templates/.claude/ukit/runtime/hook-input.mjs`, `templates/.claude/ukit/runtime/hook-input.sh` |
+| `6b40da83` | 2026-09-12 | handoff: wave 1 batch 2 — TASK-016 wall-clock watchdog hook (hardPolicy=split) | `templates/.claude/hooks/task-watchdog.sh`, `templates/.claude/ukit/runtime/task-watchdog.mjs` |
+| `0fc81692` | 2026-09-12 | handoff: wave 1 fix — anchor runtime-dir ignores, track lost TASK-014 CLI twin | `templates/.claude/ukit/index/task-budget-validator.mjs` |
+| `cfc3b7f1` | 2026-09-08 | 2.3.0 — fail-closed sensitive-data gate; contract tables unified to executionContracts.js; tierLane wiring; evidence + vision hardening | `templates/.claude/hooks/sensitive-data-guard.sh` |
+
+## 13. Findings emitted
+
+| id | evidence | p50 | p95 | status | fixTask |
+|---|---|---|---|---|---|
+| `chain-pretooluse-read-grep-glob` | telemetry | 37 | 72 | confirmed | TASK-234 |
+| `chain-pretooluse-edit-write` | telemetry | 331 | 429 | confirmed | TASK-234 |
+| `chain-pretooluse-bash` | telemetry | 307 | 474 | confirmed | TASK-234 |
+| `chain-posttooluse-read-grep-glob` | telemetry | 37 | 118 | confirmed | TASK-234 |
+| `chain-posttooluse-edit-write` | telemetry | 130 | 222 | confirmed | TASK-234 |
+| `chain-posttooluse-bash` | telemetry | 87 | 150 | confirmed | TASK-234 |
+| `chain-userpromptsubmit-all` | telemetry | 291 | 582 | confirmed | TASK-234 |
+| `chain-stop-all` | telemetry | 81 | 111 | confirmed | TASK-234 |
+| `chain-precompact-all` | telemetry | 49 | 53 | confirmed | TASK-234 |
+| `chain-sessionstart-all` | telemetry | 119 | 289 | confirmed | TASK-234 |
+| `chain-sessionend-all` | telemetry | 2020 | 2020 | confirmed | TASK-234 |
+| `hook-hook-chain-runner` | telemetry | 80 | 375 | confirmed | TASK-234 |
+| `hook-skill-router-sh` | telemetry | 52 | 134 | confirmed | TASK-234 |
+| `hook-vision-router-sh` | telemetry | 73 | 220 | confirmed | TASK-234 |
+| `hook-block-dangerous-sh` | telemetry | 83 | 237 | confirmed | TASK-234 |
+| `hook-context-hardcap-gate-sh` | telemetry | 55 | 88 | confirmed | TASK-234 |
+| `hook-completion-gate-sh` | telemetry | 80 | 108 | confirmed | TASK-234 |
+| `hook-project-important-tail` | telemetry | n/a | 61 | confirmed | TASK-235 |
+| `record-execution-multiplicity` | telemetry | 39 | 63 | not-a-bug | - |
+| `index-router-cold-start` | telemetry | 291 | 582 | confirmed | TASK-234 |
+| `c29-c32-hot-path-additions` | git-log | n/a | n/a | confirmed | TASK-234 |
+| `existing-chain-runner-baseline` | telemetry | 80 | 375 | confirmed | TASK-234 |
+| `process-floor` | micro-benchmark | 38.73741700000001 | 38.73741700000001 | not-a-bug | TASK-234 |
+| `telemetry-append-overhead` | micro-benchmark | 0.407125 | 0.407125 | not-a-bug | - |
+| `stdin-stage-vs-exec-split` | unavailable | n/a | n/a | deferred | - |
+| `hook-sensitive-data-guard-mjs-8-unmeasured` | unavailable | n/a | n/a | deferred | - |
+| `hook-context-hardcap-gate-sh-8-unmeasured` | unavailable | n/a | n/a | deferred | - |
+| `hook-verification-guard-sh-8-unmeasured` | unavailable | n/a | n/a | deferred | - |
+| `hook-record-execution-mjs-8-unmeasured` | unavailable | n/a | n/a | deferred | - |
+| `hook-task-watchdog-sh-8-unmeasured` | unavailable | n/a | n/a | deferred | - |
+| `hook-context-window-guard-sh-10-unmeasured` | unavailable | n/a | n/a | deferred | - |
+| `hook-completion-gate-sh-8-unmeasured` | unavailable | n/a | n/a | deferred | - |
+| `hook-reinject-context-sh-8-unmeasured` | unavailable | n/a | n/a | deferred | - |
+| `hook-handoff-resume-sh-8-unmeasured` | unavailable | n/a | n/a | deferred | - |
+| `hook-session-episode-sh-8-unmeasured` | unavailable | n/a | n/a | deferred | - |
+

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/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 } from '../../templates/.claude/ukit/runtime/async-lock.mjs';
+
 export async function pathExists(targetPath) {
   try {
     await fs.access(targetPath);
@@ -104,7 +108,17 @@ export async function writeFileAtomic(filePath, content) {
     } else {
       await fs.writeFile(tempPath, content, 'utf8');
     }
-    await fs.rename(tempPath, filePath);
+    try {
+      await 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 fs.copyFile(tempPath, filePath);
+      await fs.rm(tempPath, { force: true });
+    }
   } catch (error) {
     try {
       await fs.rm(tempPath, { force: true });
@@ -161,130 +175,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/core/hookChainDoctor.js

@@ -26,6 +26,10 @@ const FAILURE_OUTCOMES = new Set([
   'signal',
 ]);
 
+// The pre-O6 remedy, kept verbatim: a failure with no gate evidence must read
+// exactly as it did before escalation existed (SPEC §FR-012).
+const BASE_REMEDY = 'Inspect recent rows in .ukit/storage/cache/hook-latency/ for the failing scriptName/failureKind and fix or widen the gate budget.';
+
 function telemetryDirFor(projectRoot) {
   return path.join(projectRoot, '.ukit', 'storage', 'cache', 'hook-latency');
 }
@@ -80,6 +84,13 @@ export async function inspectHookChainHealth({ projectRoot, now = Date.now() } =
 
   const counts = { rowsScanned: 0, filesScanned: files.length, ok: 0 };
   let rowsLeft = MAX_ROWS;
+  // O6 (SPEC §FR-012): a failure that landed on a fail-closed gate is a
+  // different signal from a generic timeout — it means a real budget is too
+  // tight (or a gate broke), not that "something was slow". These are the two
+  // evidence shapes that prove it, collected in the same pass that counts
+  // outcomes so no second read of the rows is needed.
+  const gateFailures = new Set();
+  let budgetExhaustedChains = 0;
 
   for (const file of files) {
     if (rowsLeft <= 0) break;
@@ -102,6 +113,34 @@ export async function inspectHookChainHealth({ projectRoot, now = Date.now() } =
       counts.rowsScanned += 1;
       const outcome = typeof row.outcome === 'string' && row.outcome.length > 0 ? row.outcome : 'ok';
       counts[outcome] = (counts[outcome] ?? 0) + 1;
+
+      // Escalation evidence is only ever read off a FAILING row — a gate that
+      // ran fine is not evidence of anything, and SPEC §FR-012 scopes the
+      // budget signal to a non-ok row ("a non-ok row ... escalates only when
+      // its own outcome is budget-exhausted").
+      if (!FAILURE_OUTCOMES.has(outcome)) continue;
+      // A row that exhausted the chain budget never ran its later steps; that is
+      // the tight-budget signal whether or not any per-script detail survived
+      // into `scripts[]`. Recorded alongside the per-script scan below, never
+      // instead of it: one row can carry both a failed gate AND exhaustion
+      // (a gate step is added with failureKind 'budget-exhausted' when the
+      // budget ran out before it), and dropping either would lose signal.
+      if (row.budgetExhausted === true || outcome === 'budget-exhausted') {
+        budgetExhaustedChains += 1;
+      }
+      // Each failing entry names the step that failed. `failClosed` is the
+      // runner's OWN verdict on which paths it gated — the doctor reads that
+      // flag and never re-derives the gate list: a second copy of a
+      // security-relevant registry is a drift hazard, and only the runner knows
+      // which paths it treated as gates. Malformed entries are skipped, never
+      // fatal (a liveness/doctor check must not throw on hostile telemetry).
+      if (!Array.isArray(row.scripts)) continue;
+      for (const entry of row.scripts) {
+        if (!entry || typeof entry !== 'object') continue;
+        if (entry.failClosed !== true) continue;
+        if (typeof entry.failureKind !== 'string' || entry.failureKind === 'ok') continue;
+        gateFailures.add(typeof entry.scriptName === 'string' ? entry.scriptName : 'unknown');
+      }
     }
   }
 
@@ -136,14 +175,38 @@ export async function inspectHookChainHealth({ projectRoot, now = Date.now() } =
   }
 
   const breakdown = failureKinds.map((kind) => `${kind}=${counts[kind]}`).join(', ');
+  const baseDetail = `${counts.rowsScanned} chain row(s) scanned — fail-closed outcomes: ${breakdown}`;
+
+  // O6 (SPEC §FR-012): escalate only when a failure actually landed ON a gate —
+  // a gate that merely ran is not evidence. The escalation is purely additive:
+  // `baseDetail`/`BASE_REMEDY` stay the leading clause so the no-escalation
+  // branch is still byte-identical to the pre-O6 output, and a warning still
+  // never blocks (severity/remediationClass are unchanged), so doctor's exit
+  // code is unaffected. This is a richer signal, not a new alert channel (§14).
+  const gateList = [...gateFailures].sort();
+  const escalations = [];
+  const advices = [];
+  if (gateList.length > 0) {
+    escalations.push(`fail-closed gate(s) failed: ${gateList.join(', ')}`);
+    advices.push(
+      `A fail-closed gate actually failed (${gateList.join(', ')}) — that is a real budget or path problem, not a slow advisory hook; widen the failing gate's budget or fix that step.`,
+    );
+  }
+  if (budgetExhaustedChains > 0) {
+    escalations.push(`${budgetExhaustedChains} chain row(s) exhausted the total budget`);
+    advices.push(
+      `The chain total budget was exhausted before every step ran (${budgetExhaustedChains} row(s)) — raise it (UKIT_HOOK_CHAIN_BASE_MS or the per-script ":N" suffix) so the later steps, including any gate, still run.`,
+    );
+  }
+
   return {
     label,
     passed: false,
     failed: true,
     severity: 'warning',
     remediationClass: 'advisory',
-    detail: `${counts.rowsScanned} chain row(s) scanned — fail-closed outcomes: ${breakdown}`,
-    remedy: 'Inspect recent rows in .ukit/storage/cache/hook-latency/ for the failing scriptName/failureKind and fix or widen the gate budget.',
+    detail: escalations.length > 0 ? `${baseDetail}; escalated: ${escalations.join('; ')}` : baseDetail,
+    remedy: [BASE_REMEDY, ...advices].join(' '),
     counts,
   };
 }

package/src/core/memory/store.js

@@ -480,6 +480,13 @@ async function readProjectMemoryForId(runtimePaths, projectId) {
 
 const DEFAULT_MAX_ARCHIVED_SESSIONS = 50;
 
+// Same end-time key `archiveSessions` uses to decide whether a session is expired, so
+// "oldest" means the same thing on both sides of the archive boundary.
+function archivedSessionEndTime(session) {
+  const endedAt = Number(session?.endedAt ?? session?.startedAt ?? 0);
+  return Number.isFinite(endedAt) ? endedAt : 0;
+}
+
 async function appendSessionArchive(runtimePaths, projectId, archivedSessions, maxArchivedSessions) {
   if (!archivedSessions || archivedSessions.length === 0) {
     return;
@@ -493,7 +500,21 @@ async function appendSessionArchive(runtimePaths, projectId, archivedSessions, m
   const archivePath = path.join(runtimePaths.projectsDir, `${sanitizeProjectId(projectId)}.archive.json`);
   const existing = (await readMemoryJson(archivePath)) ?? { sessions: [] };
   const sessions = Array.isArray(existing.sessions) ? existing.sessions : [];
-  await writeJson(archivePath, { sessions: [...sessions, ...archivedSessions].slice(-cap) });
+
+  // The cap must drop the OLDEST sessions, not simply the earliest-written ones: appending
+  // and slicing capped the count but evicted by insertion position, so a session archived
+  // late carrying an older end time survived while a newer one written earlier was
+  // dropped. Ties keep insertion order, which is what the old equal-timestamp behavior did.
+  const kept = [...sessions, ...archivedSessions]
+    .map((session, index) => ({ session, index }))
+    .sort((left, right) => {
+      const delta = archivedSessionEndTime(left.session) - archivedSessionEndTime(right.session);
+      return delta !== 0 ? delta : left.index - right.index;
+    })
+    .slice(-cap)
+    .map((entry) => entry.session);
+
+  await writeJson(archivePath, { sessions: kept });
 }
 
 async function persistProjectMemoryWithHygiene(projectRoot, runtimePaths, projectId, filePath, memory) {