leerness 1.36.300 → 1.36.301

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # 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).

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.300 하네스를 사용합니다. 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.300는 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.300는 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.300**. 공개 릴리스 여부는 공개 저장소의 태그와 배포 기록에서 별도로 확인합니다.
+현재 사용 중인 하네스 버전: **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.300: 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.300';
+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`);
         }

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,