leerness 1.36.176 → 1.36.178

package/lib/health.js

@@ -189,9 +189,11 @@ function healthCmd(root, deps = {}) {
       isKoreanWindows: runtimeEnv.locale.isKoreanWindows || false,
       codepage: runtimeEnv.locale.codepage || null,
       nodeVersion: runtimeEnv.node.version,
-      shellScriptsScanned: encScan.scanned,
-      encodingRiskCount: encScan.atRisk.length,
-      encodingRiskFiles: encScan.atRisk.slice(0, 5).map(r => r.file),
+      shellScriptsScanned: encScan.scanned,
+      encodingRiskCount: encScan.atRisk.length,
+      encodingRiskFiles: encScan.atRisk.slice(0, 5).map(r => r.file),
+      encodingScanErrorCount: (encScan.scanErrors || []).length,
+      encodingScanErrors: (encScan.scanErrors || []).slice(0, 5),
       // 1.9.249 (UR-0018): 터미널 출력 인코딩 안전 여부 + 자동 회복 결과
       terminalEncodingOk: runtimeEnv.locale.codepage === 65001 || !runtimeEnv.locale.isKoreanWindows,
       autoChcpApplied: process.env._LEERNESS_AUTOCHCP_APPLIED || null,
@@ -301,7 +303,8 @@ function healthCmd(root, deps = {}) {
   if (out.checks.security?.hasDotEnv && out.checks.security?.envInGitignore === false) issues.push(t('🚨 .env가 .gitignore에 누락 (보안 CRITICAL)', '🚨 .env missing from .gitignore (security CRITICAL)'));
   if (out.checks.security?.envExampleMissing?.length) issues.push(t(`.env→.env.example 누락 ${out.checks.security.envExampleMissing.length}건`, `.env→.env.example missing ${out.checks.security.envExampleMissing.length}`));
   if (out.checks.security?.gitignoreMissingSecrets?.length) issues.push(t(`.gitignore 시크릿 누락 ${out.checks.security.gitignoreMissingSecrets.length}건`, `.gitignore missing secret patterns ${out.checks.security.gitignoreMissingSecrets.length}`));
-  if (out.checks.stateIntegrity?.corruptedCount > 0) issues.push(t(`🗄 상태파일 JSON 손상 ${out.checks.stateIntegrity.corruptedCount}건 (${out.checks.stateIntegrity.corrupted.map(c => c.file).join(', ')}) — 수동 복구/leerness init 필요`, `🗄 ${out.checks.stateIntegrity.corruptedCount} corrupted state JSON file(s) (${out.checks.stateIntegrity.corrupted.map(c => c.file).join(', ')}) — repair or leerness init`));  // 1.36.1 (클린룸 리뷰 FN)
+  if (out.checks.stateIntegrity?.corruptedCount > 0) issues.push(t(`🗄 상태파일 JSON 손상 ${out.checks.stateIntegrity.corruptedCount}건 (${out.checks.stateIntegrity.corrupted.map(c => c.file).join(', ')}) — 수동 복구/leerness init 필요`, `🗄 ${out.checks.stateIntegrity.corruptedCount} corrupted state JSON file(s) (${out.checks.stateIntegrity.corrupted.map(c => c.file).join(', ')}) — repair or leerness init`));  // 1.36.1 (클린룸 리뷰 FN)
+  if (out.envInfo?.encodingScanErrorCount > 0) issues.push(t(`인코딩 스캔 읽기 실패 ${out.envInfo.encodingScanErrorCount}건 — 결과 불완전`, `${out.envInfo.encodingScanErrorCount} encoding scan read error(s) — result incomplete`));
   out.issues = issues;
   out.healthy = issues.length === 0;
 

package/lib/io.js

@@ -6,6 +6,7 @@
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
+const cp = require('child_process');
 
 // 1.10.2 (UR-0146): quiet 모드 — 사람용 출력(log/ok/warn) 억제. init --json 등에서 큰 핸들러의 다수 log 를 비침투적으로 묵음 → 순수 JSON 1개만 출력.
 //   fail/failJson(오류)은 묵음 대상 아님(에러는 항상 노출). setQuiet 로 토글, 호출부 finally 에서 반드시 복구.
@@ -222,6 +223,246 @@ function writeUtf8(p, s) {
     throw e;
   }
 }
+function _concurrentModification(p, backupFile) {
+  const recovery = backupFile ? ` (복구 백업: ${backupFile})` : '';
+  const e = new Error(`검사 후 파일이 변경되어 덮어쓰기를 거부했습니다: ${p}${recovery}`);
+  e.code = 'E_CONCURRENT_MODIFICATION';
+  e.file = p;
+  if (backupFile) e.backupFile = backupFile;
+  return e;
+}
+function _cleanupWriteArtifact(p) {
+  let lastError = null;
+  for (let i = 0; i < 5; i++) {
+    try { if (fs.existsSync(p)) fs.unlinkSync(p); return null; } catch (e) { lastError = e; _sleepMsSync(20 + i * 20); }
+  }
+  return lastError || new Error(`임시 쓰기 아티팩트를 정리하지 못했습니다: ${p}`);
+}
+function _cleanupWriteScratch(p) {
+  if (!p) return null;
+  let lastError = null;
+  for (let i = 0; i < 5; i++) {
+    try { if (fs.existsSync(p)) fs.rmSync(p, { recursive: true }); return null; } catch (e) { lastError = e; _sleepMsSync(20 + i * 20); }
+  }
+  return lastError || new Error(`임시 쓰기 디렉터리를 정리하지 못했습니다: ${p}`);
+}
+function _mutationIdentity(stat) {
+  return {
+    dev: stat.dev,
+    ino: stat.ino,
+    nlink: stat.nlink,
+    mode: stat.mode,
+  };
+}
+function _sameMutationIdentity(a, b) {
+  return !!a && !!b && a.dev === b.dev && a.ino === b.ino;
+}
+function _readMutationIdentity(p) {
+  const link = fs.lstatSync(p);
+  if (link.isSymbolicLink()) {
+    const e = new Error(`심볼릭 링크 대상은 자동 교체하지 않습니다: ${p}`);
+    e.code = 'E_UNSAFE_LINK';
+    throw e;
+  }
+  if (!link.isFile()) {
+    const e = new Error(`일반 파일만 자동 교체할 수 있습니다: ${p}`);
+    e.code = 'E_UNSAFE_FILE_TYPE';
+    throw e;
+  }
+  return _mutationIdentity(link);
+}
+function _identityChanged(p, expected) {
+  const current = _readMutationIdentity(p);
+  if (!_sameMutationIdentity(current, expected) || current.nlink !== 1 || (current.mode & 0o222) === 0) {
+    const e = _concurrentModification(p);
+    e.expectedIdentity = expected;
+    e.actualIdentity = current;
+    throw e;
+  }
+  return current;
+}
+function _mutationRecoveryParent(p, expectedIdentity) {
+  let dir = path.dirname(path.resolve(p));
+  const volumeRoot = path.parse(dir).root;
+  while (true) {
+    const workspace = path.join(dir, '.leerness');
+    try {
+      if (fs.statSync(workspace).isDirectory() && fs.statSync(dir).dev === expectedIdentity.dev) {
+        const recovery = path.join(workspace, 'archive', 'mutation-recovery');
+        mkdirp(recovery);
+        return recovery;
+      }
+    } catch {}
+    if (dir === volumeRoot) break;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return path.dirname(p);
+}
+function _attachRecoveryArtifacts(e, candidates, expected, planned, targetPath) {
+  const seen = new Set();
+  const artifacts = [];
+  for (const candidate of candidates) {
+    if (!candidate || !candidate.path || seen.has(candidate.path)) continue;
+    seen.add(candidate.path);
+    let stat;
+    try { stat = fs.lstatSync(candidate.path); } catch { continue; }
+    const artifact = {
+      role: candidate.role,
+      path: candidate.path,
+      kind: stat.isDirectory() ? 'directory' : 'file',
+    };
+    if (stat.isFile()) {
+      artifact.size = stat.size;
+      try {
+        const bytes = fs.readFileSync(candidate.path);
+        artifact.content = bytes.equals(expected) ? 'expected-original'
+          : (bytes.equals(planned) ? 'planned-replacement' : 'concurrent-or-unknown');
+      } catch (readError) {
+        artifact.content = 'unreadable';
+        artifact.readError = readError.code || readError.message;
+      }
+    }
+    artifacts.push(artifact);
+  }
+  if (!artifacts.length) return e;
+  e.recoveryArtifacts = artifacts;
+  const recovery = artifacts.find(a => a.path !== targetPath && a.content === 'concurrent-or-unknown')
+    || artifacts.find(a => a.path !== targetPath && a.role === 'displaced-original')
+    || artifacts.find(a => a.path !== targetPath && a.kind === 'file');
+  if (recovery && !e.backupFile) e.backupFile = recovery.path;
+  const detail = artifacts.map(a => `${a.role}=${a.path} (${a.content || a.kind})`).join(', ');
+  if (!e.message.includes('복구 아티팩트:')) e.message = `${e.message} (복구 아티팩트: ${detail})`;
+  return e;
+}
+// ReplaceFileW (via the inbox Windows PowerShell runtime) is the only portable
+// primitive available to this zero-dependency package that atomically replaces
+// the default stream while retaining the destination's ACLs and alternate data
+// streams. A real backup path also lets the caller detect a change that landed
+// in the final compare -> replace window and retain the displaced file object
+// instead of attempting another inherently racy replacement.
+function _replaceWindowsWithBackup(from, to, backup) {
+  const systemRoot = process.env.SystemRoot || process.env.WINDIR || 'C:\\Windows';
+  const powershell = path.join(systemRoot, 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe');
+  const command = "$utf8 = New-Object System.Text.UTF8Encoding($false); [Console]::OutputEncoding = $utf8; $OutputEncoding = $utf8; $ErrorActionPreference='Stop'; try { [IO.File]::Replace($env:LEERNESS_REPLACE_FROM, $env:LEERNESS_REPLACE_TO, $env:LEERNESS_REPLACE_BACKUP) } catch { $e = $_.Exception; while ($e.InnerException) { $e = $e.InnerException }; $win32 = ($e.HResult -band 0xFFFF); [Console]::Error.WriteLine(('LEERNESS_REPLACE_ERROR:{0}:{1}' -f $win32, $e.Message)); exit 1 }";
+  let waited = 0;
+  let attempts = 0;
+  for (;;) {
+    attempts++;
+    const r = cp.spawnSync(powershell, ['-NoLogo', '-NoProfile', '-NonInteractive', '-Command', command], {
+      encoding: 'utf8',
+      windowsHide: true,
+      timeout: 15000,
+      env: {
+        ...process.env,
+        LEERNESS_REPLACE_FROM: from,
+        LEERNESS_REPLACE_TO: to,
+        LEERNESS_REPLACE_BACKUP: backup,
+      },
+    });
+    if (!r.error && r.status === 0) return;
+    const raw = r.error ? r.error.message : String(r.stderr || r.stdout || `exit ${r.status}`).trim();
+    const marker = /LEERNESS_REPLACE_ERROR:(\d+):([\s\S]*)/.exec(raw);
+    const win32Code = marker ? Number(marker[1]) : null;
+    const detail = marker ? marker[2].trim() : raw;
+    const transientSharing = win32Code === 32 || win32Code === 33;
+    // Retry only a proven sharing/lock violation while ReplaceFileW has made
+    // no observable progress. An existing backup or consumed source makes the
+    // result uncertain, so the caller must preserve recovery data instead.
+    const retrySafe = transientSharing && waited < 2000 && fs.existsSync(from) && !fs.existsSync(backup);
+    if (!retrySafe) {
+      const e = new Error(`Windows 메타데이터 보존 교체 실패: ${detail}`);
+      e.code = (r.error && r.error.code) || 'E_ATOMIC_REPLACE';
+      e.win32Code = win32Code;
+      e.attempts = attempts;
+      throw e;
+    }
+    const delay = Math.min(50 * (2 ** Math.min(attempts - 1, 3)), 400, 2000 - waited);
+    _sleepMsSync(delay);
+    waited += delay;
+  }
+}
+// 1.36.177 (T-0022): compare-and-set binary write for mutators that must
+// retain the original byte stream. The expected bytes are checked both before
+// and immediately after preparing the temp file. Windows additionally uses a
+// replacement backup to close the last compare -> replace race without losing
+// ACLs/alternate streams. The displaced object remains as an explicit recovery
+// artifact because an already-open Windows handle can write to it after our
+// validation. Other platforms are rejected: Node's rename can
+// replace a read-only inode and discard ownership, ACLs, xattrs, and hard-link
+// identity, while Node exposes no portable metadata-preserving replacement.
+function writeBufferIfUnchanged(p, expectedValue, value, opts = {}) {
+  _dryCheck(p);
+  if (process.platform !== 'win32') {
+    const e = new Error(`메타데이터 보존 원자 교체를 지원하지 않는 플랫폼입니다: ${process.platform}`);
+    e.code = 'E_METADATA_PRESERVATION_UNAVAILABLE';
+    throw e;
+  }
+  const expected = Buffer.isBuffer(expectedValue) ? expectedValue : Buffer.from(expectedValue);
+  const buf = Buffer.isBuffer(value) ? value : Buffer.from(value);
+  const expectedIdentity = opts.expectedIdentity || _readMutationIdentity(p);
+  _identityChanged(p, expectedIdentity);
+  let current = fs.readFileSync(p);
+  if (!current.equals(expected)) throw _concurrentModification(p);
+  if (current.equals(buf)) return { unchanged: true, recoveryArtifacts: [] };
+  mkdirp(path.dirname(p));
+  const mode = expectedIdentity.mode & 0o777;
+  // mkdtemp is an exclusive namespace reservation. Keeping next/before
+  // inside it prevents a parallel agent from pre-creating a predictable backup
+  // name that File.Replace would otherwise overwrite.
+  const recoveryParent = _mutationRecoveryParent(p, expectedIdentity);
+  let scratch = fs.mkdtempSync(path.join(recoveryParent, `.leerness-write-${process.pid}-`));
+  const tmp = path.join(scratch, 'next');
+  let backup = null;
+  let replaceAttempted = false;
+  try {
+    fs.writeFileSync(tmp, buf, { flag: 'wx', mode });
+    _identityChanged(p, expectedIdentity);
+    current = fs.readFileSync(p);
+    if (!current.equals(expected)) throw _concurrentModification(p);
+    backup = path.join(scratch, 'before');
+    replaceAttempted = true;
+    _replaceWindowsWithBackup(tmp, p, backup);
+    if (fs.existsSync(tmp)) {
+      const e = new Error(`Windows 교체가 성공을 보고했지만 replacement source가 남았습니다: ${tmp}`);
+      e.code = 'E_ATOMIC_REPLACE_UNCERTAIN';
+      throw e;
+    }
+    const replaced = fs.readFileSync(backup);
+    const displacedIdentity = _readMutationIdentity(backup);
+    const targetNow = fs.readFileSync(p);
+    if (!replaced.equals(expected) || !targetNow.equals(buf)
+        || !_sameMutationIdentity(displacedIdentity, expectedIdentity)
+        || displacedIdentity.nlink !== 1) {
+      throw _concurrentModification(p, backup);
+    }
+    // Keep the displaced file object intentionally. A normal Windows writer
+    // may already hold a delete-sharing handle and write to this object after
+    // our validation; removing it here would silently discard that late edit.
+    // Retention also preserves hard-link/ADS changes that cannot be proven by
+    // comparing the unnamed stream alone. Callers must surface backupFile.
+    return {
+      backupFile: backup,
+      recoveryArtifacts: [{ role: 'displaced-original', path: backup, kind: 'file', size: replaced.length, content: 'expected-original' }],
+    };
+  } catch (e) {
+    const cleanupError = !replaceAttempted ? _cleanupWriteArtifact(tmp) : null;
+    const scratchCleanupError = !replaceAttempted && !cleanupError ? _cleanupWriteScratch(scratch) : null;
+    if (cleanupError || scratchCleanupError) {
+      e.cleanupError = (cleanupError || scratchCleanupError).message;
+    }
+    _attachRecoveryArtifacts(e, replaceAttempted ? [
+      { role: 'live-target', path: p },
+      { role: 'planned-source', path: tmp },
+      { role: 'displaced-original', path: backup },
+    ] : [
+      ...(cleanupError ? [{ role: 'cleanup-failed-source', path: tmp }] : []),
+      ...(cleanupError || scratchCleanupError ? [{ role: 'cleanup-failed-scratch', path: scratch }] : []),
+    ], expected, buf, p);
+    throw e;
+  }
+}
 // 1.36.132 (P1, 실측): Windows 에서 **락을 제대로 잡고 있어도** 원자적 교체가 실패한다 —
 //   읽기는 락을 잡지 않으므로, 다른 프로세스가 대상 파일을 연 채로 있으면 rename 이 EPERM/EACCES 를 낸다.
 //   실측: 32 프로세스 동시 `task add` → EPERM 3건, 그 3행이 통째로 유실되고 자식은 exit 1 로 죽었다
@@ -243,4 +484,4 @@ function _renameWithRetry(from, to) {
 function append(p, s) { _dryCheck(p); mkdirp(path.dirname(p)); fs.appendFileSync(p, s, 'utf8'); }
 function rel(root, p) { return path.relative(root, p).replace(/\\/g, '/') || '.'; }
 
-module.exports = { log, ok, warn, fail, failJson, setQuiet, today, now, absRoot, exists, read, readBuf, mkdirp, writeUtf8, append, rel, setDryRunGuard, mkdirpRaw };
+module.exports = { log, ok, warn, fail, failJson, setQuiet, today, now, absRoot, exists, read, readBuf, mkdirp, writeUtf8, writeBufferIfUnchanged, append, rel, setDryRunGuard, mkdirpRaw };

package/lib/session-close.js

@@ -7,6 +7,7 @@ const cp = require('child_process');
 const os = require('os');
 const path = require('path');
 const fs = require('fs');
+const { applyShellScriptUtf8Bom } = require('./shell-encoding');
 const { log, ok, warn, fail, failJson, today, now, absRoot, exists, read, readBuf, mkdirp, writeUtf8, append, rel } = require('./io');
 const { _sanitizeFences, _parseArchiveBlocks, _milestoneSurface, _recentChangesAggregate } = require('./pure-utils');
 
@@ -346,6 +347,42 @@ function sessionClose(root, opts = {}, deps = {}) {
     // 1.9.103: stdout 복원
     if (jsonMode) process.stdout.write = _origWrite;
   }
+  // 1.36.177 (T-0022): mutation must not depend on the renderer. Previously
+  // this lived only in the human-output branch, so `--json` accepted the flag,
+  // returned success, and silently skipped every file. Run once before either
+  // renderer and retain every applied/skipped/failed result for honest output.
+  let encodingAutoFix = null;
+  if (has('--auto-fix-encoding')) {
+    encodingAutoFix = { requested: true, scanned: 0, atRisk: 0, added: 0, skipped: 0, failed: 0, scanErrors: [], results: [] };
+    try {
+      const encScan = _scanShellScriptsEncoding(root);
+      encodingAutoFix.scanned = encScan.scanned || 0;
+      encodingAutoFix.atRisk = Array.isArray(encScan.atRisk) ? encScan.atRisk.length : 0;
+      encodingAutoFix.scanErrors = Array.isArray(encScan.scanErrors) ? encScan.scanErrors.slice() : [];
+      for (const scanError of encodingAutoFix.scanErrors) {
+        encodingAutoFix.failed++;
+        encodingAutoFix.results.push({ file: scanError.file, action: 'failed-scan', code: scanError.code, error: scanError.error, operation: scanError.operation });
+      }
+      for (const r of (encScan.atRisk || [])) {
+        try {
+          const applied = applyShellScriptUtf8Bom(path.join(root, r.file), r.file);
+          encodingAutoFix.results.push(applied);
+          if (applied.action === 'utf8-bom-added') encodingAutoFix.added++;
+          else if (applied.action.startsWith('skipped-')) encodingAutoFix.skipped++;
+        } catch (e) {
+          encodingAutoFix.failed++;
+          encodingAutoFix.results.push({ file: r.file, action: 'failed', code: e.code || 'error', error: e.message, ...(e.backupFile ? { backupFile: e.backupFile } : {}), ...(e.recoveryArtifacts ? { recoveryArtifacts: e.recoveryArtifacts } : {}) });
+          console.error(t(`⚠ 인코딩 자동 수정 거부: ${r.file} — ${e.message}`, `⚠ encoding auto-fix refused: ${r.file} — ${e.message}`));
+        }
+      }
+    } catch (e) {
+      encodingAutoFix.failed++;
+      encodingAutoFix.results.push({ file: null, action: 'failed', code: e.code || 'error', error: e.message, ...(e.backupFile ? { backupFile: e.backupFile } : {}), ...(e.recoveryArtifacts ? { recoveryArtifacts: e.recoveryArtifacts } : {}) });
+      console.error(t(`⚠ 인코딩 자동 수정 오류: ${e.message}`, `⚠ encoding auto-fix error: ${e.message}`));
+    }
+    if (encodingAutoFix.failed > 0) process.exitCode = 1;
+    jsonResult.encodingAutoFix = encodingAutoFix;
+  }
   // 1.9.103: JSON 모드 — 구조화 출력
   if (jsonMode) {
     try {
@@ -479,6 +516,8 @@ function sessionClose(root, opts = {}, deps = {}) {
           shellScriptsScanned: encScan.scanned,
           encodingRiskCount: encScan.atRisk.length,
           encodingRiskFiles: encScan.atRisk.slice(0, 5).map(r => r.file),
+          encodingScanErrorCount: (encScan.scanErrors || []).length,
+          encodingScanErrors: (encScan.scanErrors || []).slice(0, 5),
           // 1.9.249 (UR-0018): 터미널 출력 인코딩 안전 여부 + 자동 회복 결과
           terminalEncodingOk: runtimeEnv.locale.codepage === 65001 || !runtimeEnv.locale.isKoreanWindows,
           autoChcpApplied: process.env._LEERNESS_AUTOCHCP_APPLIED || null,
@@ -672,22 +711,14 @@ function sessionClose(root, opts = {}, deps = {}) {
       //   1.9.224 (--auto-apply-delivered) / 1.9.237 (--auto-cleanup-branches) 패턴 확장
       //   마감 시 한국어/일본어/중국어 PowerShell 인코딩 위험 자동 BOM 추가
       try {
-        const encScan = _scanShellScriptsEncoding(root);
-        if (encScan.atRisk && encScan.atRisk.length > 0) {
-          if (has('--auto-fix-encoding')) {
-            let ok = 0;
-            for (const r of encScan.atRisk) {
-              try {
-                const fullPath = path.join(root, r.file);
-                const orig = fs.readFileSync(fullPath);
-                const bom = Buffer.from([0xEF, 0xBB, 0xBF]);
-                const fixed = Buffer.concat([bom, orig]);
-                fs.writeFileSync(fullPath, fixed);
-                ok++;
-              } catch {}
-            }
-            log(grn(t(`  ✓ 인코딩 위험 ${ok}/${encScan.atRisk.length}건 UTF-8 BOM 자동 추가 (--auto-fix-encoding 1.9.243)`, `  ✓ ${ok}/${encScan.atRisk.length} encoding risk(s) auto-fixed with UTF-8 BOM (--auto-fix-encoding)`)));
-          } else {
+        if (encodingAutoFix) {
+          const a = encodingAutoFix;
+          if (a.atRisk > 0) log(grn(t(`  ✓ 인코딩 위험 ${a.added}/${a.atRisk}건 UTF-8 BOM 자동 추가${a.skipped > 0 ? ` · 안전상 건너뜀 ${a.skipped}건` : ''}${a.failed > 0 ? ` · 실패 ${a.failed}건` : ''} (--auto-fix-encoding 1.9.243)`, `  ✓ ${a.added}/${a.atRisk} encoding risk(s) auto-fixed${a.skipped > 0 ? ` · safely skipped ${a.skipped}` : ''}${a.failed > 0 ? ` · ${a.failed} failed` : ''} (--auto-fix-encoding)`)));
+          for (const r of a.results.filter(r => r.backupFile)) log(yel(t(`     ↳ 원본/동시 편집 복구본 보존: ${r.backupFile}`, `     ↳ retained original/concurrent recovery copy: ${r.backupFile}`)));
+        } else {
+          const encScan = _scanShellScriptsEncoding(root);
+          if (encScan.scanErrors && encScan.scanErrors.length > 0) log(yel(t(`  ⚠ 인코딩 스캔 읽기 실패 ${encScan.scanErrors.length}건 — 결과 불완전`, `  ⚠ ${encScan.scanErrors.length} encoding scan read error(s) — result incomplete`)));
+          if (encScan.atRisk && encScan.atRisk.length > 0) {
             log(yel(t(`  ⚠ 셸 스크립트 인코딩 위험 ${encScan.atRisk.length}건 (1.9.241) — 자동 회복 가능`, `  ⚠ ${encScan.atRisk.length} shell-script encoding risk(s) — auto-fixable`)));
             log(dim(t(`     → leerness env encoding --apply (수동) 또는 session close --auto-fix-encoding (1.9.243 자동)`, `     → leerness env encoding --apply (manual) or session close --auto-fix-encoding (auto)`)));
           }

package/lib/shell-encoding.js

@@ -0,0 +1,175 @@
+// lib/shell-encoding.js — shared precondition + atomic mutation for UTF-8 BOM fixes.
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { writeBufferIfUnchanged } = require('./io');
+
+const UTF8_BOM = Buffer.from([0xEF, 0xBB, 0xBF]);
+
+function _validUtf8(buf) {
+  return Buffer.from(buf.toString('utf8'), 'utf8').equals(buf);
+}
+
+function _validCp949(buf) {
+  let decoder;
+  try {
+    // WHATWG euc-kr is the Windows-compatible unified Korean decoder. Node 18+
+    // normally ships it through ICU. Small-ICU/custom builds may not expose the
+    // decoder at all; that is "unknown", not proof that the bytes are invalid
+    // CP949. `fatal` matters because replacement characters would turn arbitrary
+    // bytes into false encoding provenance.
+    decoder = new TextDecoder('euc-kr', { fatal: true });
+  } catch {
+    return null;
+  }
+  try {
+    decoder.decode(buf);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Detection and mutation are deliberately joined at the final write boundary:
+// callers may act on a scan result that is already stale. Re-read the current
+// bytes and re-check every destructive precondition immediately before writing.
+function planShellScriptUtf8Bom(file, input) {
+  const buf = Buffer.isBuffer(input) ? input : Buffer.from(input);
+  const ext = path.extname(String(file || '')).toLowerCase();
+  if (buf.subarray(0, UTF8_BOM.length).equals(UTF8_BOM)) {
+    if (!_validUtf8(buf.subarray(UTF8_BOM.length))) {
+      return { action: 'skipped-invalid-bom-body (UTF-8 BOM 뒤 본문이 유효한 UTF-8이 아님 — 기존 손상 가능성, 수동 복구 필요)' };
+    }
+    return { action: 'skipped-existing-bom' };
+  }
+  const shebang = buf.length >= 2 && buf[0] === 0x23 && buf[1] === 0x21;
+  if (ext === '.sh' || shebang) {
+    return { action: 'skipped-shebang (BOM은 shebang을 깨뜨림 — .sh는 no-BOM UTF-8 유지)' };
+  }
+  if (ext === '.bat' || ext === '.cmd') {
+    return { action: 'skipped-batch (cmd.exe: 첫 줄에 chcp 65001 추가가 정답 — BOM은 코드페이지를 안 바꿈)' };
+  }
+  if (ext !== '.ps1') {
+    return { action: 'skipped-unsupported (자동 BOM 적용 대상은 .ps1만 지원)' };
+  }
+  if (!buf.some((byte) => byte >= 0x80)) {
+    return { action: 'skipped-ascii (비-ASCII 인코딩 위험 없음)' };
+  }
+  if (!_validUtf8(buf)) {
+    return { action: 'skipped-nonutf8 (본문이 비-UTF-8(CP949 등) — BOM 추가는 손상. UTF-8 로 먼저 transcode 필요)' };
+  }
+  const cp949Validity = _validCp949(buf);
+  if (cp949Validity !== false) {
+    return { action: cp949Validity === true
+      ? 'skipped-ambiguous-encoding (UTF-8과 CP949 모두로 유효하지만 의미가 다를 수 있음 — 명시적 transcode 후 재시도)'
+      : 'skipped-ambiguous-encoding (CP949 decoder unavailable — 레거시 인코딩이 아님을 증명할 수 없어 자동 수정 거부)' };
+  }
+  return { action: 'utf8-bom-added', bytes: Buffer.concat([UTF8_BOM, buf]) };
+}
+
+function scanShellScriptsEncoding(root, opts = {}) {
+  const classifyCJK = typeof opts.classifyCJK === 'function'
+    ? opts.classifyCJK : () => ({ korean: 0, japanese: 0, chinese: 0, other: 0 });
+  const riskLabel = typeof opts.riskLabel === 'function'
+    ? opts.riskLabel : () => ({ type: 'non-ascii', risk: 'BOM 없는 비-ASCII 셸 스크립트' });
+  const result = { scanned: 0, atRisk: [], scanErrors: [], notes: [] };
+  const scanError = (operation, fp, e) => result.scanErrors.push({
+    operation,
+    file: path.relative(root, fp) || '.',
+    code: e && e.code ? e.code : 'error',
+    error: e && e.message ? e.message : String(e),
+  });
+  function walk(dir, depth = 0) {
+    if (depth > 3) return;
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch (e) { scanError('readdir', dir, e); return; }
+    for (const entry of entries) {
+      const fp = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (/^(node_modules|\.git|__pycache__|venv|\.venv|dist|build)$/.test(entry.name)) continue;
+        walk(fp, depth + 1);
+        continue;
+      }
+      if (!entry.isFile() || !/\.(ps1|bat|cmd|sh)$/i.test(entry.name)) continue;
+      try {
+        const buf = fs.readFileSync(fp);
+        result.scanned++;
+        const hasBOM = buf.subarray(0, UTF8_BOM.length).equals(UTF8_BOM);
+        const plan = planShellScriptUtf8Bom(fp, buf);
+        let nonAscii = false;
+        for (let i = hasBOM ? UTF8_BOM.length : 0; i < Math.min(buf.length, 4096); i++) {
+          if (buf[i] >= 0x80) { nonAscii = true; break; }
+        }
+        const invalidBomBody = plan.action.startsWith('skipped-invalid-bom-body');
+        if ((!hasBOM && nonAscii) || invalidBomBody) {
+          const cjk = classifyCJK(buf, 4096);
+          const label = riskLabel(cjk);
+          result.atRisk.push({
+            file: path.relative(root, fp),
+            ext: path.extname(fp),
+            hasBOM,
+            nonAscii: true,
+            riskType: invalidBomBody ? 'invalid-bom-body' : label.type,
+            cjk,
+            risk: invalidBomBody
+              ? 'UTF-8 BOM 뒤 본문이 유효한 UTF-8이 아님 — 기존 손상 가능성, 수동 복구 필요'
+              : label.risk,
+            fixAction: plan.action,
+          });
+        }
+      } catch (e) {
+        scanError('read', fp, e);
+      }
+    }
+  }
+  walk(root);
+  if (result.atRisk.length > 0) {
+    result.notes.push('해결: 인코딩 출처가 명확한 .ps1만 UTF-8로 transcode 후 BOM을 추가. UTF-8/CP949 양쪽으로 유효한 본문은 자동 수정하지 않음');
+  }
+  if (result.scanErrors.length > 0) result.notes.push('읽지 못한 경로가 있어 검사가 불완전함 — 권한/잠금을 해결한 뒤 다시 실행');
+  result.riskTypeCounts = result.atRisk.reduce((m, r) => {
+    m[r.riskType] = (m[r.riskType] || 0) + 1;
+    return m;
+  }, {});
+  return result;
+}
+
+function applyShellScriptUtf8Bom(fullPath, displayFile = fullPath) {
+  const linkStat = fs.lstatSync(fullPath);
+  if (linkStat.isSymbolicLink()) return { file: displayFile, action: 'skipped-symlink (링크 대상을 자동 교체하지 않음)' };
+  if (!linkStat.isFile()) return { file: displayFile, action: 'skipped-nonfile (일반 파일만 자동 교체)' };
+  if (linkStat.nlink > 1) return { file: displayFile, action: 'skipped-multiple-links (하드링크 별칭 불일치 방지)' };
+  const original = fs.readFileSync(fullPath);
+  const afterRead = fs.lstatSync(fullPath);
+  if (afterRead.isSymbolicLink() || afterRead.dev !== linkStat.dev || afterRead.ino !== linkStat.ino
+      || afterRead.nlink !== 1 || afterRead.mode !== linkStat.mode) {
+    const e = new Error(`읽는 동안 파일 정체성/링크/권한이 변경되어 자동 수정을 거부했습니다: ${displayFile}`);
+    e.code = 'E_CONCURRENT_MODIFICATION';
+    throw e;
+  }
+  const plan = planShellScriptUtf8Bom(fullPath, original);
+  if (plan.action !== 'utf8-bom-added') return { file: displayFile, action: plan.action };
+  // BOM is a Windows PowerShell compatibility repair. On POSIX, replacing an
+  // inode atomically with Node cannot retain arbitrary ACLs/xattrs/ownership;
+  // fail closed instead of claiming a safe repair while discarding metadata.
+  if (process.platform !== 'win32') return { file: displayFile, action: 'skipped-platform (Windows 메타데이터 보존 교체만 지원)' };
+  // Writability is a mutation precondition, not a scan/skip precondition. A
+  // read-only .sh or a POSIX .ps1 is still a successful byte-exact no-op.
+  if ((linkStat.mode & 0o222) === 0) {
+    const e = new Error(`읽기 전용 파일은 자동 수정하지 않습니다: ${displayFile}`);
+    e.code = 'E_READ_ONLY';
+    throw e;
+  }
+  const written = writeBufferIfUnchanged(fullPath, original, plan.bytes, {
+    expectedIdentity: { dev: linkStat.dev, ino: linkStat.ino, nlink: linkStat.nlink, mode: linkStat.mode },
+  });
+  return {
+    file: displayFile,
+    action: plan.action,
+    ...(written && written.backupFile ? { backupFile: written.backupFile } : {}),
+    ...(written && written.recoveryArtifacts ? { recoveryArtifacts: written.recoveryArtifacts } : {}),
+  };
+}
+
+module.exports = { planShellScriptUtf8Bom, scanShellScriptsEncoding, applyShellScriptUtf8Bom };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "leerness",
-  "version": "1.36.176",
+  "version": "1.36.178",
   "description": "The AI-coding operations layer that makes \"done\" require evidence — persistent memory, evidence-gated completion checks, and clean handoffs for any AI agent (Claude Code, Codex, Cursor). State lives as plain files in your repo. CLI + MCP, 0 runtime dependencies.",
   "keywords": [
     "leerness",
@@ -48,13 +48,13 @@
     "LICENSE"
   ],
   "scripts": {
-    "test": "node ./scripts/lint.js && node ./scripts/workspace-dir-source-ratchet.js && node ./scripts/workspace-dir-migration-probe.js && node ./scripts/workspace-dir-lock-order-probe.js && node ./scripts/lock-probe.js && node ./scripts/platform-smoke.js && node ./scripts/verify-code-cross-runtime-probe.js && node ./scripts/release-runtime-probe.js && node ./scripts/which-shim-probe.js && node ./bin/leerness.js --version && node ./bin/leerness.js selftest && node ./scripts/e2e-core.js && node ./scripts/handoff-readonly-probe.js && node ./scripts/mcp-presence-probe.js && npm run test:commands && npm run test:installed && node ./scripts/e2e.js",
-    "test:core": "node ./scripts/lint.js && node ./scripts/workspace-dir-source-ratchet.js && node ./scripts/workspace-dir-migration-probe.js && node ./scripts/workspace-dir-lock-order-probe.js && node ./scripts/lock-probe.js && node ./scripts/platform-smoke.js && node ./scripts/verify-code-cross-runtime-probe.js && node ./scripts/release-runtime-probe.js && node ./scripts/which-shim-probe.js && node ./bin/leerness.js --version && node ./bin/leerness.js selftest && node ./scripts/e2e-core.js && node ./scripts/handoff-readonly-probe.js && node ./scripts/mcp-presence-probe.js",
+    "test": "node ./scripts/lint.js && node ./scripts/workspace-dir-source-ratchet.js && node ./scripts/workspace-dir-migration-probe.js && node ./scripts/workspace-dir-lock-order-probe.js && node ./scripts/lock-probe.js && node ./scripts/platform-smoke.js && node ./scripts/verify-code-cross-runtime-probe.js && node ./scripts/release-runtime-probe.js && node ./scripts/which-shim-probe.js && node ./bin/leerness.js --version && node ./bin/leerness.js selftest && node ./scripts/e2e-core.js && node ./scripts/mutation-integrity-probe.js && node ./scripts/handoff-readonly-probe.js && node ./scripts/mcp-presence-probe.js && npm run test:commands && npm run test:installed && node ./scripts/e2e.js",
+    "test:core": "node ./scripts/lint.js && node ./scripts/workspace-dir-source-ratchet.js && node ./scripts/workspace-dir-migration-probe.js && node ./scripts/workspace-dir-lock-order-probe.js && node ./scripts/lock-probe.js && node ./scripts/platform-smoke.js && node ./scripts/verify-code-cross-runtime-probe.js && node ./scripts/release-runtime-probe.js && node ./scripts/which-shim-probe.js && node ./bin/leerness.js --version && node ./bin/leerness.js selftest && node ./scripts/e2e-core.js && node ./scripts/mutation-integrity-probe.js && node ./scripts/handoff-readonly-probe.js && node ./scripts/mcp-presence-probe.js",
     "test:commands": "node ./scripts/command-flags-probe.js && node ./scripts/dead-flags-probe.js && node ./scripts/false-claim-probe.js && node ./scripts/next-action-suggestion-probe.js && node ./scripts/claims-baseline-probe.js && node ./scripts/claims-baseline-concurrency-probe.js && node ./scripts/e2e-command-surface.js",
     "test:next-actions": "node ./scripts/next-action-suggestion-probe.js",
     "test:installed": "node ./scripts/installed-cleanroom-probe.js",
     "test:handoff": "node ./scripts/handoff-readonly-probe.js",
-    "test:fast": "node ./scripts/lint.js && node ./scripts/workspace-dir-source-ratchet.js && node ./scripts/workspace-dir-migration-probe.js && node ./scripts/workspace-dir-lock-order-probe.js && node ./scripts/lock-probe.js && node ./scripts/platform-smoke.js && node ./scripts/release-runtime-probe.js && node ./scripts/which-shim-probe.js && node ./scripts/mcp-presence-probe.js && node ./scripts/false-claim-probe.js && node ./scripts/smoke.js",
+    "test:fast": "node ./scripts/lint.js && node ./scripts/workspace-dir-source-ratchet.js && node ./scripts/workspace-dir-migration-probe.js && node ./scripts/workspace-dir-lock-order-probe.js && node ./scripts/lock-probe.js && node ./scripts/platform-smoke.js && node ./scripts/release-runtime-probe.js && node ./scripts/which-shim-probe.js && node ./scripts/mutation-integrity-probe.js && node ./scripts/mcp-presence-probe.js && node ./scripts/false-claim-probe.js && node ./scripts/smoke.js",
     "test:false-claims": "node ./scripts/false-claim-probe.js",
     "test:workspace-lock-order": "node ./scripts/workspace-dir-lock-order-probe.js",
     "test:mcp-presence": "node ./scripts/mcp-presence-probe.js",

package/scripts/e2e-core.js

@@ -122,12 +122,23 @@ console.log('# leerness core (test:core) — flagship behavioral guarantees');
   cp.spawnSync(process.execPath, [CLI, 'env', 'encoding-check', '--apply', '--path', d], { encoding: 'utf8', timeout: 40000 });
   const after = fs.readFileSync(path.join(d, 'cp949.ps1'));
   assert('encoding --apply: CP949 .ps1 NOT mutated (no destructive BOM-on-CP949)', after.equals(cp949) && !(after[0] === 0xEF && after[1] === 0xBB && after[2] === 0xBF));
-  // 유효 UTF-8 .ps1(한글, no BOM)은 정당하게 BOM 추가되어야 함
-  fs.writeFileSync(path.join(d, 'utf8.ps1'), Buffer.from('Write-Host "안녕"\r\n', 'utf8'));
+  // UTF-8/CP949 양쪽으로 유효한 바이트는 의미가 다를 수 있어 보수적으로 skip.
+  const ambiguous = Buffer.from([0x41, 0xC2, 0xA1, 0x42]); // UTF-8 A¡B / CP949 A징B
+  fs.writeFileSync(path.join(d, 'ambiguous.ps1'), ambiguous);
+  // Emoji의 0x80 trail은 CP949에서 무효이므로 UTF-8 출처를 바이트로 증명할 수 있다.
+  const utf8Only = Buffer.from('Write-Host "😀"\r\n', 'utf8');
+  fs.writeFileSync(path.join(d, 'utf8.ps1'), utf8Only);
   cp.spawnSync(process.execPath, [CLI, 'env', 'encoding-check', '--apply', '--path', d], { encoding: 'utf8', timeout: 40000 });
   const u = fs.readFileSync(path.join(d, 'utf8.ps1'));
+  const a = fs.readFileSync(path.join(d, 'ambiguous.ps1'));
   const uValid = Buffer.from(u.toString('utf8'), 'utf8').equals(u);
-  assert('encoding --apply: valid-UTF-8 .ps1 gets BOM (still valid)', u[0] === 0xEF && u[1] === 0xBB && u[2] === 0xBF && uValid);
+  assert('encoding --apply: UTF-8/CP949 ambiguous .ps1 remains exact', a.equals(ambiguous));
+  assert('encoding --apply: unambiguous UTF-8 .ps1 follows platform contract', process.platform === 'win32'
+    ? (u[0] === 0xEF && u[1] === 0xBB && u[2] === 0xBF && uValid)
+    : u.equals(utf8Only));
+  for (const e of fs.readdirSync(d, { withFileTypes: true }).filter(e => e.isDirectory() && e.name.startsWith('.leerness-write-'))) {
+    fs.rmSync(path.join(d, e.name), { recursive: true, force: true });
+  }
   fs.rmSync(d, { recursive: true, force: true });
 }