leerness 1.36.299 → 1.36.301

package/CHANGELOG.md

@@ -1,5 +1,61 @@
 # Changelog
 
+## 1.36.301 - 2026-10-14
+
+- Changed: public CI runs its long work in parallel shards (T-0359). 1.36.300's CI run (38332288454) took five hours: each Windows gate job (199-300 min) ran e2e.js after `test:commands`, and the Windows fast job took 46 min (79 min in 1.36.299's run 38193803239).
+  - `scripts/ci-shard.js` splits the work. Every shard of a job computes the same split from the same inputs: the units in source order, weighted by measured seconds (`scripts/ci-shard-weights.json`), placed largest first on the least-loaded shard. So the shards of one job run each unit exactly once.
+  - e2e.js: each top-level case now starts with `if (e2eShard.take('<key>')) {`, with its `total++;` inside. `LEERNESS_E2E_SHARD=i/k` runs shard i of k; without it every case runs, as before.
+  - Cases that mention the shared fixture project or its helpers (`tmp`, `run`, `dsPath`, `dsText`, `secretFile`; 104 of 423, a text match that errs toward grouping) run together in one shard, in file order, because one case leaves state for the next. A first version without this group failed three of them on Linux.
+  - The cases start after the line `// e2e-shard: cases start here`. An e2e run fails when a guard is malformed or repeated, a guard is not reached exactly once, or code below that line and outside a case opens a block, a control-flow block or an immediately invoked function, or counts a case. Whatever wraps a case that lost its guard, its `total++` is outside a guard. Each shard still runs the smoke preamble above the line and the run-wide checks at the end (runtime DEP0190 warnings, repository isolation); those checks end the file, and each of their counters is marked `// e2e-shard: run-wide check`.
+  - `test:commands` and `test:fast` run as leaves: `node ./scripts/ci-shard.js npm <script> i/k` expands `npm run` steps and runs that shard's `node` leaves in order. It refuses any other step shape and any script with a `pre` or `post` lifecycle script. Unlike an `&&` chain, it runs every leaf of its shard and then fails if any failed.
+  - The workflow: e2e in 4 shards on each Windows Node version and 2 on each Ubuntu one; `test:commands` in 2 shards on Windows; the Windows fast job in 3; the other gate steps in one `gate core` job per configuration. The OS/Node configurations and steps are those of 1.36.300.
+  - From the per-case times of run 38193803239, an e2e shard should take about 56 min on Windows Node 18 (226 min unsharded), 43-48 min on Node 20-24 and at most 25 min on Ubuntu, plus job setup. This release's CI run is the first measurement.
+  - CONTRIBUTING.md describes the case form and how to refresh weights (`LEERNESS_E2E_TIMES`, `LEERNESS_CI_SHARD_TIMES`, `ci-shard.js weights`).
+- Fixed: a command waiting for a workspace migration failed when the migration took longer than the lock wait (T-0348). Such a migration is another command moving a legacy `.harness` workspace to `.leerness`.
+  - Measured on this PC: a first migration of 400 files of 8 KiB took 13.1-14.7 s on Windows with Node 20.20.2 and 22.23.3, against 4.7 s on 26.3.0. That is past the 10 s that waiting commands allowed.
+  - Most of that time went to reading each fresh copy back to verify it. The first read of a file just written cost about 10 ms on Node 20 and 22 there. Copying took 0.4 s.
+  - The migrating process now refreshes the lock file's modification time while it works, at most every 500 ms: in every loop over the migrated files (the walk and its sorting, mapping, collision and destination checks, copies, hashes, comparisons, reference rewrites and rollback). Not covered: one built-in call whose time grows with the file count, such as listing a folder of a million files; at the size of real legacy workspaces such calls take milliseconds. Waiting commands keep waiting while the lock changes. With every wrappable file call of a migration of 60 files slowed by 30 ms, the lock never stays unchanged for 1.5 s; with 15 ms per call on 80 files, the longest unchanged time measured was 588 ms.
+  - The list of files to copy no longer searches the already-present files once per file. That search grew with the square of the file count: 11.6 s for 60,000 files on this PC, now 30 ms.
+  - `LEERNESS_WORKSPACE_MIGRATION_LOCK_WAIT_MS` (default 10 s) is now the longest wait without progress. A lock left by a process that died stops changing, and its waiters still fail after that time. The whole wait is capped at 15 minutes. A positive value below 1.5 s counts as 1.5 s, three refresh intervals, so a short wait does not expire between two refreshes; 0 still does not wait. The refresh interval and the waits are measured on a monotonic clock, so setting the system clock back or forward neither stops the refreshes nor ends a wait.
+  - On this PC, `simultaneous-first-migrations-converge-with-lock-wait` in `scripts/workspace-dir-migration-probe.js` now passes; before, it failed here, while the GitHub runner passed it.
+  - `docs/runtime-compatibility-api.md` describes the wait.
+- Fixed: `leerness readme sync` counted only column-0 `total++;` lines for a README e2e badge, so a case whose counter sits inside a shard guard was not counted. Projects without guards count as before.
+- Tests (T-0348): `scripts/workspace-migration-heartbeat-probe.js` (`npm run test:migration-heartbeat`, in `test`, `test:core` and `test:fast`) has thirteen cases:
+  - every loop of the migration functions must refresh the lock unless it waits for another process's lock or walks a fixed list (a check of the source: the CPU-only loops cannot be slowed from outside);
+  - the list of files to copy for 60,000 files must take under 2 s;
+  - a waiter set to 100 ms must still outlast a migration slowed to 40 ms per copy, and a positive wait is at least 1.5 s while 0 does not wait (fake clock);
+  - the owner's wall clock set back 30 s after its tenth copy must not stop the refreshes, and a waiter's wall clock jumping 60 s forward must not end a 5 s wait;
+  - a migration with every wrappable file call slowed (lstat and stat are left alone: the runtime layout refuses a wrapped one): the lock must not stay unchanged for 1.5 s;
+  - migrations slowed in one step at a time, 40 ms per copy, per reference rewrite or per destination check, each with another migration waiting 1.5 s for it;
+  - a writer waiting 1 s on a lock refreshed for 3.5 s and then released;
+  - a lock that never changes, and one that stops changing after 4 s.
+  - On the old code it passes only the never-changing case (1 of 13). With the migrating process's refresh turned off it passes 7 of 13: the six cases with a slowed or clock-shifted migration fail. Without the 1.5 s minimum, the two short-wait cases fail; with the wall clock instead of the monotonic one, both clock cases fail in 5 of 5 runs.
+- Tests (T-0359):
+  - `scripts/ci-shard-probe.js` (`npm run test:ci-shard`, in `test`, `test:core` and `test:fast`), 13 checks: the split is a deterministic partition for 1-8 shards; every leaf of the sharded npm scripts and every e2e case runs in exactly one shard for 1-6 shards; the shared-fixture cases stay in one shard; the guard parser, the runtime check, the npm step parser, the leaf runner and the workflow's shard lists each catch their broken inputs; `readme sync` counts guarded cases. 24 mutants of the runner and the badge count each fail it.
+  - `scripts/release-runtime-probe.js` reads the workflow's shard lists: Windows Node 24 must list every e2e shard. A dropped shard, a mismatched shard count, a missing shard variable and a changed e2e command each fail it.
+  - Linux (Docker node:20): HEAD's e2e.js 468/468 and this release's 469/469 print the same result labels apart from the new check. The final version's 3 shards pass (249/150/162), and every case label falls in exactly one shard. The first reviewed version also passed in 3 (259/149/153) and in 2 shards (313/202).
+  - Windows (this PC, Node 26.3.0, 4 shards in parallel, first reviewed version): 223/122/136/126, and the labels match the Windows Node 24 e2e step of run 38332288454. Since then e2e.js changed only by comments: the cases-start line and the run-wide marks.
+  - Reviewed by codex gpt-6.1-sol and gpt-6-astra over nine rounds; each finding got a test that fails on the reviewed code (rounds 4-9 by owner decision).
+
+## 1.36.300 - 2026-10-13
+
+- Fixed: `leerness lazy detect --auto-track` registered TODOs that a task already covered (T-0345).
+  - When a batch of new TODOs mixed files that no tracker row references with a file a task already referenced, every new TODO got a task, including those in the referenced file.
+  - Now only the TODOs whose file no row references are registered, decided under the tracker lock as before, and `known-todos.json` gains exactly those. A TODO in a referenced file is left as it is, as without `--auto-track`.
+- Tests (T-0345, T-0346):
+  - `scripts/lazy-auto-track-probe.js` (`npm run test:lazy-auto-track`, in `test:commands`) checks a mixed batch, a rerun, and two controls: nothing referenced, and everything referenced. On the old code the two mixed-batch cases fail: the referenced file's two TODOs got tasks too.
+  - The 30 races of `scripts/e2e-concurrency.js` now check that the two commands overlapped. Before, the first command's publication stalled for a fixed 1.2 s, and a second command that started later than that passed without racing.
+    - The second command now runs with `scripts/lock-probe.js` too. After each operation on the stalled file it reports: a finished read, open, stat or existence check, and the result of its first attempt at that file's lock or at a lock the first command held when it stalled (refused because held, or taken). It reads those held locks once, when it starts; if they cannot be read, the race does not count. It marks its report complete when it exits. A report that cannot be written sets its exit code to 97 at once, and an incomplete report does not count.
+    - The first command stays stalled until a report exists (at most 15 s), then 1.2 s more. `scripts/race-overlap.js` judges the reports. A race counts when such a lock attempt was refused because the first command held the lock. For a command that tried none of those locks, it counts when its read finished before the first command resumed. A first attempt that took such a lock means the first command had already released it, and the race does not count.
+    - `scripts/race-overlap-probe.js` (`npm run test:race-overlap`, in `test`, `test:core` and `test:fast`) runs the handshake with two small processes on ten fixed schedules. They include a second process that is slow to reach its lock attempt, one that reads during the stall but takes a lock after the release, held locks that cannot be read, and a report that can no longer be rewritten, also after the report was completed. Write failures are injected (`LOCKPROBE_REPORT_FAIL_AFTER`), so the test does not depend on file permissions. Ablations:
+      - every lock attempt reported as refused, whatever its result: 8 of 10;
+      - a first process that does not wait for the report: 6 of 10;
+      - the held locks read at the first lock attempt, and a failed read kept as "none": 8 of 10;
+      - a report judged without the completion mark: 9 of 10;
+      - a failed write that sets the exit code only in the closing exit listener: 9 of 10.
+    - Measured from the stall to the first report: 468-1,704 ms on this Windows PC and 123-217 ms on Linux (Docker node:20). In `creds-refresh` the second command reached the stalled file 1,704 ms after the stall began, 504 ms after the old fixed stall would have ended, so with the old harness that race would have passed without overlapping.
+    - On the current code all 30 races overlapped and passed, on Windows and on Linux. On Linux the second command's lock attempt was refused by the first command's lock in all 30; on Windows in 29, and `bugfix-start-vs-task-add` counted by its read. On Linux with the 1.36.296 code (before T-0343) all 30 overlapped too, and 20 failed: the 19 races T-0343 added and `plan-init-vs-remove`, whose `plan init` T-0343 also fixed. The other 10 pass there, as before.
+
 ## 1.36.299 - 2026-10-12
 
 - Fixed: on Windows, `leerness skill publish` made a `.zip` instead of the `.tgz` when Git for Windows' GNU tar came first on PATH, as it does in Git Bash and in agent shells built on it (T-0352).

package/CONTRIBUTING.md

@@ -35,6 +35,8 @@ Prefer **behavioral** tests over source-grep guards. A source-grep guard asserts
 
 When you add a guard, construct the **discriminating case**: an input where the old code passes and only the new check catches it. If you cannot construct one, the check may not be measuring what you think.
 
+Each top-level case in `scripts/e2e.js` starts with `if (e2eShard.take('<unique key>')) {` and counts itself with `total++;` inside the block. CI runs that file, `test:commands` and `test:fast` in parallel shards (`scripts/ci-shard.js`): every shard computes the same split from `scripts/ci-shard-weights.json`, so the shards of one job run each case and leaf exactly once. A top-level block without the guard, a repeated key, or a guard that is not reached exactly once fails the e2e run. `node ./scripts/ci-shard.js plan e2e 4` shows the split; a run with `LEERNESS_E2E_TIMES=<file>` (e2e) or `LEERNESS_CI_SHARD_TIMES=<file>` (npm leaves) writes measured seconds, and `node ./scripts/ci-shard.js weights e2e <file>` stores them.
+
 ## Release
 
 `npm test` (gate) → bump `VERSION` in `bin/leerness.js` **and** `version` in `package.json` (selftest asserts they match) → CHANGELOG entry → commit → publish → push.

package/README.md

@@ -195,7 +195,7 @@ MIT
 <!-- leerness:project-readme:start -->
 ## Leerness Project Harness
 
-이 프로젝트는 Leerness v1.36.299 하네스를 사용합니다. AI 에이전트는 작업 전 `leerness handoff`로 컨텍스트를 적재하고, 작업 후 `leerness check`/`leerness audit`/`leerness session close`를 수행해야 합니다.
+이 프로젝트는 Leerness v1.36.301 하네스를 사용합니다. AI 에이전트는 작업 전 `leerness handoff`로 컨텍스트를 적재하고, 작업 후 `leerness check`/`leerness audit`/`leerness session close`를 수행해야 합니다.
 
 ### 정체성 — AI 에이전트 운영 레이어 (UR-0030)
 
@@ -249,7 +249,7 @@ leerness memory restore decision <date|title>
 
 ### MCP server (외부 AI 통합)
 
-Leerness v1.36.299는 stdio JSON-RPC MCP server를 내장합니다 — Claude Code · Cursor · Codex CLI 등 외부 AI에 **102개 도구**를 노출:
+Leerness v1.36.301는 stdio JSON-RPC MCP server를 내장합니다 — Claude Code · Cursor · Codex CLI 등 외부 AI에 **102개 도구**를 노출:
 
 ```jsonc
 // 카테고리별
@@ -270,7 +270,7 @@ Leerness v1.36.299는 stdio JSON-RPC MCP server를 내장합니다 — Claude Co
 `<<autonomous-loop-dynamic>>` 신호만 보내면 AI가:
 1) 다음 라운드 후보 선정 → 2) 코드 변경 → 3) 회귀 테스트 갱신 → 4) 전체 e2e 스위트 통과 → 5) npm publish + git tag → 6) main push → 7) session close → 8) 다음 라운드 예약.
 
-현재 사용 중인 하네스 버전: **1.36.299**. 공개 릴리스 여부는 공개 저장소의 태그와 배포 기록에서 별도로 확인합니다.
+현재 사용 중인 하네스 버전: **1.36.301**. 공개 릴리스 여부는 공개 저장소의 태그와 배포 기록에서 별도로 확인합니다.
 
 ### 성능 가이드
 
@@ -308,7 +308,7 @@ leerness release pack --close --auto-main-push
 - `.leerness/session-handoff.md`: 다음 세션 인수인계 (자동 작성)
 - `.leerness/lessons.md` / `decisions.md` / `rules.md`: 영구 메모리 (5 surface)
 
-Last synced by Leerness v1.36.299: 2026-09-30
+Last synced by Leerness v1.36.301: 2026-09-30
 <!-- leerness:project-readme:end -->
 GitHub 로그인 계정 확인용 서버 어댑터: [설정·연결·승인과의 구분](docs/github-login.md). 실제 앱 등록/브라우저 세션 연결과 대상별 승인은 후속입니다.
 

package/bin/leerness.js

@@ -115,7 +115,7 @@ const {
   migrateLegacyWorkspace,
 } = require('../lib/workspace-dir');
 
-const VERSION = '1.36.299';
+const VERSION = '1.36.301';
 
 // MCP lifecycle 주소 표식은 현재 CLI 호출 한 번에만 유효하다. CLI bootstrap에서 즉시 env에서
 // 떼어 두어 `--no-record`/hook처럼 presence 기록 함수에 도달하지 않는 경로도 후속 child에 유출하지 않는다.
@@ -1582,8 +1582,11 @@ function syncReadme(root, versionOverride = null) {
       const e2ePath = path.join(root, 'scripts', 'e2e.js');
       if (exists(e2ePath)) {
         // 1.9.271: e2e 테스트 수 = `total++;` 블록 + `run(...)` 호출 (run 헬퍼가 내부에서 total++ 수행) → 실제 결과와 일치.
+        // T-0359: leerness's own e2e.js counts each case inside its CI shard guard (`if (e2eShard.take('<key>')) {`
+        //   followed by `  total++;`). Those count too, so guarding the cases does not shrink the estimate.
         const body = read(e2ePath);
-        const total = (body.match(/^total\+\+;/gm) || []).length + (body.match(/^run\(/gm) || []).length;
+        const total = (body.match(/^total\+\+;/gm) || []).length + (body.match(/^run\(/gm) || []).length
+          + (body.match(/^if \(e2eShard\.take\('[^'\r\n]+'\)\) \{\r?\n {2}total\+\+;/gm) || []).length;
         if (total > 0) {
           updated = updated.replace(/badge\/e2e-(\d+)%2F(\d+)-success/g, `badge/e2e-${total}%2F${total}-success`);
         }
@@ -17528,23 +17531,27 @@ function lazyDetect(root, opts = {}) {
           const header = progressHeader(root, input.text);
           const rows2 = readProgressRows(root, input.text);
           const lockedText = rows2.map(r => `${r.request || ''} ${r.evidence || ''}`).join('\n');
-          if (!newTodos.some(t => !lockedText.includes(t.file))) return false;
+          // T-0345: only the TODOs whose file no row references. A batch with one untracked file registered every
+          //   new TODO, so TODOs in files a task already covered were registered again.
+          const toRegister = newTodos.filter(t => !lockedText.includes(t.file));
+          if (!toRegister.length) return [];
           let maxT = _historyRetention.reservedTaskMax(root); const idRe = /\bT-(\d{4,})\b/g;
           const scanSrc = (exists(planPath(root)) ? read(planPath(root)) : '') + '\n' + rows2.map(r => r.id).join('\n');
           let mm; while ((mm = idRe.exec(scanSrc))) maxT = Math.max(maxT, Number(mm[1]));
-          _historyRetention.assertTaskIdCapacity(maxT, newTodos.length);
-          for (const t of newTodos) {
+          _historyRetention.assertTaskIdCapacity(maxT, toRegister.length);
+          for (const t of toRegister) {
             maxT++;
             rows2.push({ id: `T-${String(maxT).padStart(4, '0')}`, status: 'requested', request: `TODO ${t.file}:${t.line}`, evidence: 'auto-tracked', nextAction: t.text.slice(0, 80), updated: today() });
           }
           writeProgressRows(root, header, rows2, { input });
-          return true;
+          return toRegister;
         });
-        if (registered) {
-          // known-todos에 추가 — 다음 detect에서 재카운트 안 하도록
-          const merged = [...knownList, ...newTodos.map(t => ({ ...t, ackAt: now() }))];
+        if (registered.length) {
+          // known-todos에 추가 — 다음 detect에서 재카운트 안 하도록. T-0345: only what was registered; a TODO in a
+          //   file a task already references stays as it is, as without --auto-track.
+          const merged = [...knownList, ...registered.map(t => ({ ...t, ackAt: now() }))];
           writeUtf8(knownPath, JSON.stringify(merged, null, 2) + '\n');
-          if (!jsonMode) ok(`${newTodos.length}개 TODO를 progress-tracker에 자동 등록 + known-todos.json 갱신`);
+          if (!jsonMode) ok(`${registered.length}개 TODO를 progress-tracker에 자동 등록 + known-todos.json 갱신`);
         }
       } else if (newTodos.length && !jsonMode) {
         log(`    💡 자동 등록: leerness lazy detect --auto-track`);

package/docs/runtime-compatibility-api.md

@@ -96,10 +96,14 @@ New writer operations may read-only wait for an existing regular, single-linked
 workspace migration lock before classifying ownership. They reclassify after the peer
 finishes; waiting never grants lock ownership or permission to overwrite a conflict.
 The existing migration wait budget defaults to 10 seconds, is configurable through
-`LEERNESS_WORKSPACE_MIGRATION_LOCK_WAIT_MS`, and is clamped to 0–60 seconds. Expired or
-non-regular/linked lock observations block with `workspace_dir_migration_locked`; no
-lock is read, reclaimed or deleted by admission. The budget bounds contention waiting,
-not unrelated Git/filesystem I/O. Public `state compatibility` remains immediate.
+`LEERNESS_WORKSPACE_MIGRATION_LOCK_WAIT_MS`, and is clamped to 0–60 seconds; a positive value below 1.5 seconds
+counts as 1.5 seconds (three refresh intervals), and 0 does not wait. It is the longest
+wait without progress: the migrating process refreshes the lock file's modification time while
+it works (at most every 500 ms), and a waiter keeps waiting while the lock's size or modification
+time changes, up to 15 minutes in all. A lock that does not change for the budget, such as one
+left by a process that died, and non-regular/linked lock observations block with
+`workspace_dir_migration_locked`; no lock is read, reclaimed or deleted by admission. The budget
+bounds contention waiting, not unrelated Git/filesystem I/O. Public `state compatibility` remains immediate.
 An observed non-workspace denial is terminal even if a peer subsequently removes its
 descriptor. A conflict snapshot gets at most one extra classification when no lock is
 seen, covering a peer that completed between observations without accepting persistent

package/lib/runtime-layout.js

@@ -388,13 +388,17 @@ function createRuntimeWriterAdmission(root = process.cwd(), lockWaitMs) {
     const configured = lockWaitMs === undefined ? envValue('LEERNESS_WORKSPACE_MIGRATION_LOCK_WAIT_MS') : lockWaitMs;
     const parsed = configured === '' || configured === undefined ? NaN : Number(configured);
     const budget = Number.isFinite(parsed) ? Math.max(0, Math.min(60000, parsed)) : 10000;
-    const deadline = started + budget;
+    // T-0348: the budget is the longest wait without progress: the migrating process refreshes the lock file's
+    //   modification time as it works (lib/workspace-dir.js), and a lock that stops changing fails after it.
+    const lockWait = W.migrationLockWait(lock, budget, W.MIGRATION_LOCK_MAX_WAIT_MS, clock);
+    let lastLockStat = null;
     const contention = () => {
       waitedForLock = true;
-      if (clock() >= deadline) fail('workspace_dir_migration_locked');
+      if (lockWait.expired(lastLockStat)) fail('workspace_dir_migration_locked');
     };
     const pending = () => {
       const stat = statMaybe(lock);
+      lastLockStat = stat;
       if (!stat) return false;
       if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1n) fail('workspace_dir_migration_locked');
       return true;
@@ -403,7 +407,7 @@ function createRuntimeWriterAdmission(root = process.cwd(), lockWaitMs) {
     for (;;) {
       while (pending()) {
         contention();
-        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, Math.max(0, Math.min(25, deadline - clock())));
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, Math.max(0, Math.min(25, lockWait.remainingMs())));
       }
       const reader = createRuntimeCompatibilityReader(location.root);
       const report = reader();

package/lib/workspace-dir.js

@@ -82,13 +82,15 @@ function _inspectDir(root, name) {
     try { entries = fs.readdirSync(abs); }
     catch (error) { inspectionError = error.code || 'unknown'; }
   }
-  const markers = entries.filter((entry) => STRONG_MARKERS.has(entry));
+  // T-0348 review round 8: a migration inspects the workspace again after taking its lock, so these per-entry
+  //   filters refresh the lock too (a no-op outside a migration).
+  const markers = entries.filter((entry) => { _beat(); return STRONG_MARKERS.has(entry); });
   const live = markers.length > 0;
   const substrateEntries = name === CANONICAL_WORKSPACE_DIR
-    ? entries.filter((entry) => SUBSTRATE_TOP_LEVEL.has(entry))
+    ? entries.filter((entry) => { _beat(); return SUBSTRATE_TOP_LEVEL.has(entry); })
     : [];
   const nonSubstrateEntries = name === CANONICAL_WORKSPACE_DIR
-    ? entries.filter((entry) => !SUBSTRATE_TOP_LEVEL.has(entry))
+    ? entries.filter((entry) => { _beat(); return !SUBSTRATE_TOP_LEVEL.has(entry); })
     : entries.slice();
   const substrateOnly = name === CANONICAL_WORKSPACE_DIR
     && isDirectory && !live && substrateEntries.length > 0 && nonSubstrateEntries.length === 0;
@@ -205,9 +207,11 @@ function legacyWorkspacePath(root, ...parts) {
 }
 
 function _hashFile(file) {
+  _beat();
   const h = crypto.createHash('sha256');
   let body;
   for (let attempt = 0; ; attempt++) {
+    _beat();
     try { body = fs.readFileSync(file); break; }
     catch (error) {
       const transient = error && ['EBUSY', 'EPERM', 'EACCES'].includes(error.code);
@@ -222,6 +226,7 @@ function _hashFile(file) {
 function _walkFiles(base) {
   const out = [];
   function visit(rel) {
+    _beat();
     const abs = rel ? path.join(base, rel) : base;
     const stat = fs.lstatSync(abs);
     if (stat.isSymbolicLink()) {
@@ -232,7 +237,10 @@ function _walkFiles(base) {
       );
     }
     if (stat.isDirectory()) {
-      for (const entry of fs.readdirSync(abs).sort()) visit(rel ? path.join(rel, entry) : entry);
+      // Review round 7: sorting a huge folder is CPU work before the first visit; the comparator refreshes the lock.
+      //   `a < b` on strings compares UTF-16 code units, the order of the default sort.
+      const entries = fs.readdirSync(abs).sort((a, b) => { _beat(); return a < b ? -1 : a > b ? 1 : 0; });
+      for (const entry of entries) visit(rel ? path.join(rel, entry) : entry);
       return;
     }
     if (stat.isFile()) out.push({ rel, abs, size: stat.size, hash: _hashFile(abs) });
@@ -253,6 +261,7 @@ function _mappedRelative(rel) {
 }
 
 function _copyFile(src, dst) {
+  _beat();
   fs.mkdirSync(path.dirname(dst), { recursive: true });
   fs.copyFileSync(src, dst);
 }
@@ -285,6 +294,8 @@ function _safeRemoveCanonicalDir(root, target) {
 }
 
 function _rewriteLegacyReference(file) {
+  // T-0348 review round 1: the rewrite pass after the copy is long for a large workspace; it refreshes the lock too.
+  _beat();
   let raw;
   try { raw = fs.readFileSync(file); } catch { return false; }
   if (raw.length > 4 * 1024 * 1024 || raw.includes(0)) return false;
@@ -363,18 +374,21 @@ function _isTransientLockFsError(error) {
 }
 
 function _removeOwnedLockFile(lockFile) {
-  const deadline = Date.now() + 2000;
+  const deadline = _monotonicMs() + 2000;
   while (true) {
     try { fs.unlinkSync(lockFile); return; }
     catch (error) {
       if (error && error.code === 'ENOENT') return;
-      if (!_isTransientLockFsError(error) || Date.now() >= deadline) return;
-      _sleepSync(Math.min(25, Math.max(1, deadline - Date.now())));
+      if (!_isTransientLockFsError(error) || _monotonicMs() >= deadline) return;
+      _sleepSync(Math.min(25, Math.max(1, deadline - _monotonicMs())));
     }
   }
 }
 
 function _destinationSnapshot(file) {
+  // T-0348 review round 2: the check before the copy finds most destinations missing and hashes nothing, so it
+  //   refreshes the lock itself.
+  _beat();
   if (!fs.existsSync(file)) return { kind: 'missing', hash: null };
   const stat = fs.lstatSync(file);
   if (stat.isSymbolicLink()) {
@@ -384,6 +398,20 @@ function _destinationSnapshot(file) {
   return { kind: 'file', hash: _hashFile(file) };
 }
 
+// The destinations to copy: every mapped file except those already identical there. T-0348 review round 3: this used
+//   to search the skipped list once per file, quadratic in the file count (60,000 skipped files took 33 s in the
+//   reviewer's reproduction, past a waiter's 10 s); a Set keeps it linear, and each file refreshes the lock.
+function _copiedFiles(mapped, skippedFiles) {
+  const skipped = new Set(skippedFiles);
+  const out = [];
+  for (const item of mapped) {
+    _beat();
+    const rel = item.mappedRel.replace(/\\/g, '/');
+    if (!skipped.has(rel)) out.push(rel);
+  }
+  return out;
+}
+
 function _sameDestinationSnapshot(a, b) {
   return !!a && !!b && a.kind === b.kind && a.hash === b.hash;
 }
@@ -395,6 +423,58 @@ function _migrationLockWaitMs(opts = {}) {
   return Number.isFinite(parsed) ? Math.max(0, Math.min(60000, parsed)) : 10000;
 }
 
+// T-0348: a first migration can take longer than the lock wait. On Windows with Node 20 and 22, 400 files took
+// 11-15 s here, mostly reading each fresh copy back to verify it. The commands waiting for it then failed while it
+// was still working. So the owner refreshes the lock file's modification time while it works, at most every
+// 500 ms, from each step of its walk, checks, copies, hashes, rewrites and rollback. A waiter keeps waiting while that
+// time moves. The lock wait (LEERNESS_WORKSPACE_MIGRATION_LOCK_WAIT_MS, default 10 s, at least 1.5 s when set) is now
+// the longest wait without progress; a lock left by a process that died stops moving, and its waiters still fail
+// after it. The whole wait is capped at 15 min.
+const MIGRATION_LOCK_MAX_WAIT_MS = 15 * 60 * 1000;
+const _MIGRATION_HEARTBEAT_MS = 500;
+// Review round 5: elapsed times use a monotonic clock (as the runtime-layout admission does). With the wall clock, a
+//   clock set back stopped the refreshes until it caught up, and one set forward ended a wait at once.
+const _monotonicMs = () => Number(process.hrtime.bigint() / 1000000n);
+let _migrationHeartbeat = null;
+function _beat() { if (_migrationHeartbeat) _migrationHeartbeat(); }
+function _startMigrationHeartbeat(lockFd) {
+  let last = -Infinity;
+  _migrationHeartbeat = () => {
+    const now = _monotonicMs();
+    if (now - last < _MIGRATION_HEARTBEAT_MS) return;
+    last = now;
+    // The stored time only has to change; it is the wall clock, whatever it says.
+    try { const at = new Date(); fs.futimesSync(lockFd, at, at); } catch {}
+  };
+  _migrationHeartbeat();
+}
+function _stopMigrationHeartbeat() { _migrationHeartbeat = null; }
+
+// The wait of a process that found the migration lock taken. `expired()` observes the lock once and is true when
+// its size and modification time (or its absence) have not changed for `idleMs`, or `capMs` passed since the wait
+// began. A caller that has just read the lock's bigint lstat passes it (or null when the lock was missing), so the
+// lock is not read twice. `remainingMs()` is the time until it would expire without a further change.
+// Review round 4: the owner refreshes at most every 500 ms, so a shorter wait could expire between two refreshes of
+// a migration that is progressing. A positive wait is therefore at least three refresh intervals; 0 still means
+// "do not wait".
+const MIGRATION_LOCK_MIN_WAIT_MS = 3 * _MIGRATION_HEARTBEAT_MS;
+function migrationLockWait(lockFile, waitMs, capMs = MIGRATION_LOCK_MAX_WAIT_MS, clock = _monotonicMs) {
+  const idleMs = waitMs > 0 ? Math.max(waitMs, MIGRATION_LOCK_MIN_WAIT_MS) : 0;
+  const startedAt = clock();
+  let lastSignature, lastChangeAt = startedAt;
+  const signatureOf = st => (st ? `${st.size}:${st.mtimeNs}` : 'absent');
+  const signature = () => { try { return signatureOf(fs.lstatSync(lockFile, { bigint: true })); } catch { return 'absent'; } };
+  return {
+    startedAt,
+    expired(observed) {
+      const now = clock(), current = observed === undefined ? signature() : signatureOf(observed);
+      if (current !== lastSignature) { lastSignature = current; lastChangeAt = now; }
+      return now - lastChangeAt >= idleMs || now - startedAt >= capMs;
+    },
+    remainingMs() { return Math.max(0, Math.min(lastChangeAt + idleMs, startedAt + capMs) - clock()); },
+  };
+}
+
 function _newMigrationReport(state, opts = {}) {
   const at = opts.at || new Date().toISOString();
   const version = String(opts.version || 'unknown');
@@ -436,8 +516,8 @@ function migrateLegacyWorkspace(root, opts = {}) {
 
   const lockWaitMs = _migrationLockWaitMs(opts);
   const lockFile = path.join(initial.root, '.leerness-workspace-migration.lock');
-  const startedAt = Date.now();
-  const deadline = startedAt + lockWaitMs;
+  const startedAt = _monotonicMs();
+  const lockWait = migrationLockWait(lockFile, lockWaitMs);
   let lockFd = null;
   let waited = false;
 
@@ -450,31 +530,33 @@ function migrateLegacyWorkspace(root, opts = {}) {
         report.blockedReason = 'workspace-dir-migration-failed';
         report.errors.push(error && error.message ? error.message : String(error));
         report.waitedForLock = waited;
-        report.lockWaitedMs = waited ? Math.max(0, Date.now() - startedAt) : 0;
+        report.lockWaitedMs = waited ? Math.max(0, _monotonicMs() - startedAt) : 0;
         return report;
       }
       waited = true;
-      if (Date.now() >= deadline) {
+      if (lockWait.expired()) {
         const report = _newMigrationReport(initial, opts);
         report.blocked = true;
         report.blockedReason = 'workspace-dir-migration-locked';
         report.errors.push(`another workspace migration still owns: ${lockFile}`);
         report.waitedForLock = true;
-        report.lockWaitedMs = Math.max(0, Date.now() - startedAt);
+        report.lockWaitedMs = Math.max(0, _monotonicMs() - startedAt);
         return report;
       }
-      _sleepSync(Math.min(50, Math.max(1, deadline - Date.now())));
+      _sleepSync(Math.min(50, Math.max(1, lockWait.remainingMs())));
     }
   }
 
+  _startMigrationHeartbeat(lockFd);
   try {
     const report = _migrateLegacyWorkspace(initial.root, { ...opts, [_MIGRATION_LOCK_OWNED]: true });
     if (waited) {
       report.waitedForLock = true;
-      report.lockWaitedMs = Math.max(report.lockWaitedMs || 0, Date.now() - startedAt);
+      report.lockWaitedMs = Math.max(report.lockWaitedMs || 0, _monotonicMs() - startedAt);
     }
     return report;
   } finally {
+    _stopMigrationHeartbeat();
     try { fs.closeSync(lockFd); } catch {}
     _removeOwnedLockFile(lockFile);
   }
@@ -504,8 +586,8 @@ function _migrateLegacyWorkspace(root, opts = {}) {
   // applying any conflict verdict; otherwise simultaneous first handoffs race
   // against an intermediate state and some fail before reaching the lock.
   if (!dryRun && !migrationLockOwned && fs.existsSync(lockFile)) {
-    const peerStartedAt = Date.now();
-    const peerDeadline = peerStartedAt + lockWaitMs;
+    const peerStartedAt = _monotonicMs();
+    const peerWait = migrationLockWait(lockFile, lockWaitMs);
     report.waitedForLock = true;
     while (fs.existsSync(lockFile)) {
       const latest = inspectWorkspace(state.root);
@@ -515,18 +597,21 @@ function _migrateLegacyWorkspace(root, opts = {}) {
         report.alreadyCanonical = true;
         report.backupDir = fs.existsSync(path.join(state.root, LEGACY_BACKUP_WORKSPACE_DIR))
           ? path.join(state.root, LEGACY_BACKUP_WORKSPACE_DIR) : null;
-        report.lockWaitedMs = Math.max(0, Date.now() - peerStartedAt);
+        report.lockWaitedMs = Math.max(0, _monotonicMs() - peerStartedAt);
         return report;
       }
-      if (Date.now() >= peerDeadline) {
-        report.lockWaitedMs = Math.max(0, Date.now() - peerStartedAt);
+      if (peerWait.expired()) {
+        report.lockWaitedMs = Math.max(0, _monotonicMs() - peerStartedAt);
         return block('workspace-dir-migration-locked', `another workspace migration still owns: ${lockFile}`);
       }
-      _sleepSync(Math.min(50, Math.max(1, peerDeadline - Date.now())));
+      _sleepSync(Math.min(50, Math.max(1, peerWait.remainingMs())));
     }
     // The peer released without completing (normally after rollback). Start a
     // fresh inspection instead of trusting the intermediate snapshot above.
-    return migrateLegacyWorkspace(state.root, { ...opts, lockWaitMs: Math.max(0, peerDeadline - Date.now()) });
+    // T-0348: what is left of the wait, at most the full wait without progress; observing the release first counts
+    //   it as progress, while the 15-minute cap still applies.
+    peerWait.expired();
+    return migrateLegacyWorkspace(state.root, { ...opts, lockWaitMs: Math.min(lockWaitMs, peerWait.remainingMs()) });
   }
 
   // The initial inspection and the lock existence check are not one atomic
@@ -582,9 +667,13 @@ function _migrateLegacyWorkspace(root, opts = {}) {
     return block(error.code === 'E_WORKSPACE_DIR_SYMLINK' ? 'workspace-dir-symlink' : 'workspace-dir-read-failed', error.message);
   }
 
-  const mapped = sourceFiles.map((item) => ({ ...item, mappedRel: _mappedRelative(item.rel) }));
+  // T-0348 review round 6: every loop over the migrated files refreshes the lock, the CPU-only ones too (mapping
+  //   and the collision check took 3.2 s for 120,000 long paths in the reviewer's reproduction). The heartbeat
+  //   probe checks that each per-file loop of this function calls _beat().
+  const mapped = sourceFiles.map((item) => { _beat(); return { ...item, mappedRel: _mappedRelative(item.rel) }; });
   const mappedDestinations = new Map();
   for (const item of mapped) {
+    _beat();
     const rel = item.mappedRel.replace(/\\/g, '/');
     const key = process.platform === 'win32' ? rel.toLowerCase() : rel;
     if (mappedDestinations.has(key)) {
@@ -595,6 +684,7 @@ function _migrateLegacyWorkspace(root, opts = {}) {
     mappedDestinations.set(key, item.rel.replace(/\\/g, '/'));
   }
   for (const item of mapped) {
+    _beat();
     if (item.mappedRel !== item.rel) report.mappedFiles.push({ from: item.rel.replace(/\\/g, '/'), to: item.mappedRel.replace(/\\/g, '/') });
     const dst = path.join(state.canonical.abs, item.mappedRel);
     let snapshot;
@@ -615,6 +705,7 @@ function _migrateLegacyWorkspace(root, opts = {}) {
     else report.conflicts.push(item.mappedRel.replace(/\\/g, '/'));
   }
   const unsafeTypeConflict = mapped.some((item) => {
+    _beat();
     const dst = path.join(state.canonical.abs, item.mappedRel);
     if (!fs.existsSync(dst)) return false;
     try {
@@ -630,9 +721,7 @@ function _migrateLegacyWorkspace(root, opts = {}) {
       `destination has ${report.conflicts.length} conflicting file(s)`);
   }
 
-  report.copiedFiles = mapped
-    .filter((item) => !report.skippedFiles.includes(item.mappedRel.replace(/\\/g, '/')))
-    .map((item) => item.mappedRel.replace(/\\/g, '/'));
+  report.copiedFiles = _copiedFiles(mapped, report.skippedFiles);
   report.overwrittenFiles = report.conflicts.slice();
   if (dryRun) return report;
 
@@ -645,8 +734,8 @@ function _migrateLegacyWorkspace(root, opts = {}) {
   const canonicalExisted = state.canonical.exists;
   let legacyRenamed = false;
   try {
-    const lockDeadline = Date.now() + lockWaitMs;
-    const lockStartedAt = Date.now();
+    const lockStartedAt = _monotonicMs();
+    const lockWait = lockFd === null ? migrationLockWait(lockFile, lockWaitMs) : null;
     while (lockFd === null) {
       try { lockFd = fs.openSync(lockFile, 'wx'); }
       catch (error) {
@@ -661,16 +750,17 @@ function _migrateLegacyWorkspace(root, opts = {}) {
           report.dstExists = true;
           report.alreadyCanonical = true;
           report.backupDir = fs.existsSync(sourceBackup) ? sourceBackup : null;
-          report.lockWaitedMs = Math.max(0, Date.now() - lockStartedAt);
+          report.lockWaitedMs = Math.max(0, _monotonicMs() - lockStartedAt);
           return report;
         }
-        if (Date.now() >= lockDeadline) {
+        if (lockWait.expired()) {
           throw new WorkspaceDirectoryError('E_WORKSPACE_DIR_LOCKED', `another workspace migration still owns: ${lockFile}`);
         }
-        _sleepSync(Math.min(50, Math.max(1, lockDeadline - Date.now())));
+        _sleepSync(Math.min(50, Math.max(1, lockWait.remainingMs())));
       }
     }
-    if (report.waitedForLock) report.lockWaitedMs = Math.max(0, Date.now() - lockStartedAt);
+    if (!migrationLockOwned) _startMigrationHeartbeat(lockFd);
+    if (report.waitedForLock) report.lockWaitedMs = Math.max(0, _monotonicMs() - lockStartedAt);
     // The previous owner can finish between our last EEXIST observation and
     // this successful open. Re-inspect under ownership before applying the
     // pre-lock source/backup snapshot.
@@ -693,6 +783,7 @@ function _migrateLegacyWorkspace(root, opts = {}) {
     fs.mkdirSync(migrationRoot, { recursive: true });
 
     for (const item of mapped) {
+      _beat();
       const dst = path.join(state.canonical.abs, item.mappedRel);
       const currentSnapshot = _destinationSnapshot(dst);
       if (!_sameDestinationSnapshot(item.destinationSnapshot, currentSnapshot)) {
@@ -713,14 +804,15 @@ function _migrateLegacyWorkspace(root, opts = {}) {
 
     // A writer that ignored the migration lock must not be silently discarded.
     const after = _walkFiles(state.legacy.abs);
-    const beforeSig = sourceFiles.map((x) => `${x.rel}\0${x.hash}`).join('\n');
-    const afterSig = after.map((x) => `${x.rel}\0${x.hash}`).join('\n');
+    const beforeSig = sourceFiles.map((x) => { _beat(); return `${x.rel}\0${x.hash}`; }).join('\n');
+    const afterSig = after.map((x) => { _beat(); return `${x.rel}\0${x.hash}`; }).join('\n');
     if (beforeSig !== afterSig) throw new WorkspaceDirectoryError('E_WORKSPACE_DIR_CHANGED', `${LEGACY_WORKSPACE_DIR} changed during migration`);
 
     // Rewrite only files that are part of the migrated workspace plus a small,
     // explicit set of leerness integration files at the project root.  The
     // source backup remains byte-for-byte legacy data for recovery.
     for (const item of mapped) {
+      _beat();
       const dst = path.join(state.canonical.abs, item.mappedRel);
       if (_rewriteLegacyReference(dst)) report.rewrittenReferences.push(path.relative(state.root, dst).replace(/\\/g, '/'));
     }
@@ -822,8 +914,9 @@ function _migrateLegacyWorkspace(root, opts = {}) {
         fs.renameSync(sourceBackup, state.legacy.abs);
         legacyRenamed = false;
       }
-      for (const item of overwritten.reverse()) _copyFile(item.backup, item.dst);
-      for (const file of created.reverse()) if (fs.existsSync(file)) fs.rmSync(file, { force: true });
+      for (const item of overwritten.reverse()) { _beat(); _copyFile(item.backup, item.dst); }
+      for (const file of created.reverse()) { _beat(); if (fs.existsSync(file)) fs.rmSync(file, { force: true }); }
+      _beat();
       if (!canonicalExisted && fs.existsSync(state.canonical.abs)) _safeRemoveCanonicalDir(state.root, state.canonical.abs);
     } catch (rollbackError) {
       report.errors.push(`rollback failed: ${rollbackError.message}`);
@@ -831,6 +924,7 @@ function _migrateLegacyWorkspace(root, opts = {}) {
     return report;
   } finally {
     if (!migrationLockOwned && lockFd !== null) {
+      _stopMigrationHeartbeat();
       try { fs.closeSync(lockFd); } catch {}
       _removeOwnedLockFile(lockFile);
     }
@@ -838,6 +932,11 @@ function _migrateLegacyWorkspace(root, opts = {}) {
 }
 
 module.exports = {
+  // T-0348: the progress-based wait for the migration lock, shared with lib/runtime-layout.js.
+  migrationLockWait,
+  MIGRATION_LOCK_MAX_WAIT_MS,
+  MIGRATION_LOCK_MIN_WAIT_MS,
+  _copiedFiles,
   CANONICAL_WORKSPACE_DIR,
   LEGACY_WORKSPACE_DIR,
   LEGACY_BACKUP_WORKSPACE_DIR,