@su-record/vibe 2.12.5 → 2.14.0

package/hooks/scripts/__tests__/sentinel-guard.test.js

@@ -24,7 +24,6 @@ function runGuard(args = []) {
 
 /**
  * Run sentinel-guard.js with stdin JSON payload.
- * 스크립트가 fs.readSync(0, ...)로 stdin을 읽으므로 execFileSync input 옵션이 동작.
  */
 function runGuardWithStdin(payload) {
   const json = typeof payload === 'string' ? payload : JSON.stringify(payload);
@@ -41,24 +40,25 @@ function runGuardWithStdin(payload) {
 }
 
 // ══════════════════════════════════════════════════
-// Sentinel path protection
+// Sentinel path protection — evolution machinery
 // ══════════════════════════════════════════════════
 describe('sentinel-guard', () => {
-  describe('Write/Edit to sentinel paths via argv', () => {
-    it('should block Write to src/infra/lib/autonomy/', () => {
+  // ─── 실제 보호 경로: src/infra/lib/evolution/ ───
+  describe('Write/Edit to evolution sentinel path via argv', () => {
+    it('should block Write to src/infra/lib/evolution/', () => {
       const result = runGuard([
         'Write',
-        JSON.stringify({ file_path: 'src/infra/lib/autonomy/policy.ts' }),
+        JSON.stringify({ file_path: 'src/infra/lib/evolution/EvolutionOrchestrator.ts' }),
       ]);
       expect(result.exitCode).toBe(2);
       expect(result.stdout).toContain('block');
       expect(result.stdout).toContain('Sentinel files are protected');
     });
 
-    it('should block Edit to sentinel path', () => {
+    it('should block Edit to evolution sentinel path', () => {
       const result = runGuard([
         'Edit',
-        JSON.stringify({ file_path: 'src/infra/lib/autonomy/config.ts' }),
+        JSON.stringify({ file_path: 'src/infra/lib/evolution/GuardAnalyzer.ts' }),
       ]);
       expect(result.exitCode).toBe(2);
       expect(result.stdout).toContain('block');
@@ -67,7 +67,7 @@ describe('sentinel-guard', () => {
     it('should block Write with backslash path separators', () => {
       const result = runGuard([
         'Write',
-        JSON.stringify({ file_path: 'src\\infra\\lib\\autonomy\\file.ts' }),
+        JSON.stringify({ file_path: 'src\\infra\\lib\\evolution\\file.ts' }),
       ]);
       expect(result.exitCode).toBe(2);
       expect(result.stdout).toContain('Sentinel files are protected');
@@ -76,32 +76,62 @@ describe('sentinel-guard', () => {
     it('should block Write with ./ prefix', () => {
       const result = runGuard([
         'Write',
-        JSON.stringify({ file_path: './src/infra/lib/autonomy/index.ts' }),
+        JSON.stringify({ file_path: './src/infra/lib/evolution/index.ts' }),
       ]);
       expect(result.exitCode).toBe(2);
     });
   });
 
+  // ─── 실제 보호 경로: hooks/scripts/lib/ ───
+  describe('Write/Edit to hooks/scripts/lib/ sentinel path', () => {
+    it('should block Write to hooks/scripts/lib/', () => {
+      const result = runGuard([
+        'Write',
+        JSON.stringify({ file_path: 'hooks/scripts/lib/dispatcher.js' }),
+      ]);
+      expect(result.exitCode).toBe(2);
+      expect(result.stdout).toContain('Sentinel files are protected');
+    });
+
+    it('should block Edit to hook-context.js', () => {
+      const result = runGuard([
+        'Edit',
+        JSON.stringify({ file_path: 'hooks/scripts/lib/hook-context.js' }),
+      ]);
+      expect(result.exitCode).toBe(2);
+    });
+  });
+
+  // ─── stdin 경로 ───
   describe('Write/Edit to sentinel paths via stdin', () => {
-    it('should block Edit via stdin payload', () => {
+    it('should block Edit evolution path via stdin payload', () => {
       const result = runGuardWithStdin({
         tool_name: 'Edit',
-        tool_input: { file_path: './src/infra/lib/autonomy/config.ts' },
+        tool_input: { file_path: './src/infra/lib/evolution/InsightStore.ts' },
       });
       expect(result.exitCode).toBe(2);
       expect(result.stdout).toContain('block');
     });
 
-    it('should block Write via stdin payload', () => {
+    it('should block Write evolution path via stdin payload', () => {
       const result = runGuardWithStdin({
         tool_name: 'Write',
-        tool_input: { file_path: 'src/infra/lib/autonomy/policy.ts' },
+        tool_input: { file_path: 'src/infra/lib/evolution/CircuitBreaker.ts' },
       });
       expect(result.exitCode).toBe(2);
       expect(result.stdout).toContain('Sentinel files are protected');
     });
+
+    it('should block Write hooks/scripts/lib/ path via stdin', () => {
+      const result = runGuardWithStdin({
+        tool_name: 'Write',
+        tool_input: { file_path: 'hooks/scripts/lib/run-ledger.js' },
+      });
+      expect(result.exitCode).toBe(2);
+    });
   });
 
+  // ─── 허용 경로 ───
   describe('allowed operations', () => {
     it('should allow Write to non-sentinel paths', () => {
       const result = runGuard([
@@ -114,7 +144,7 @@ describe('sentinel-guard', () => {
     it('should allow Read to sentinel paths (read is not blocked)', () => {
       const result = runGuard([
         'Read',
-        JSON.stringify({ file_path: 'src/infra/lib/autonomy/policy.ts' }),
+        JSON.stringify({ file_path: 'src/infra/lib/evolution/GuardAnalyzer.ts' }),
       ]);
       expect(result.exitCode).toBe(0);
     });
@@ -126,23 +156,40 @@ describe('sentinel-guard', () => {
       ]);
       expect(result.exitCode).toBe(0);
     });
+
+    it('should allow Write to hooks/scripts/ top level (not lib/ subdir)', () => {
+      const result = runGuard([
+        'Write',
+        JSON.stringify({ file_path: 'hooks/scripts/step-counter.js' }),
+      ]);
+      expect(result.exitCode).toBe(0);
+    });
+
+    it('should allow Write to src/infra/lib/ parent (not evolution subdir)', () => {
+      const result = runGuard([
+        'Write',
+        JSON.stringify({ file_path: 'src/infra/lib/constants.ts' }),
+      ]);
+      expect(result.exitCode).toBe(0);
+    });
   });
 
+  // ─── 위험한 bash + sentinel 경로 ───
   describe('dangerous bash commands targeting sentinel paths', () => {
-    it('should block rm -rf targeting sentinel path', () => {
+    it('should block rm -rf targeting evolution path', () => {
       const result = runGuard([
         'Bash',
-        JSON.stringify({ command: 'rm -rf src/infra/lib/autonomy/' }),
+        JSON.stringify({ command: 'rm -rf src/infra/lib/evolution/' }),
       ]);
       expect(result.exitCode).toBe(2);
       expect(result.stdout).toContain('block');
       expect(result.stdout).toContain('Dangerous command targeting sentinel path');
     });
 
-    it('should block kill -9 targeting sentinel path', () => {
+    it('should block rm -rf targeting hooks/scripts/lib/', () => {
       const result = runGuard([
         'Bash',
-        JSON.stringify({ command: 'kill -9 1234 && rm src/infra/lib/autonomy/x' }),
+        JSON.stringify({ command: 'rm -rf hooks/scripts/lib/' }),
       ]);
       expect(result.exitCode).toBe(2);
     });
@@ -164,33 +211,41 @@ describe('sentinel-guard', () => {
     });
   });
 
+  // ─── Bash 명령어 문자열이 sentinel 경로로 시작하는 경우 ───
   describe('Bash command containing sentinel path in command string', () => {
-    it('should block when command string itself starts with sentinel path', () => {
+    it('should block when command string itself starts with evolution sentinel path', () => {
       const result = runGuard([
         'Bash',
-        JSON.stringify({ command: 'src/infra/lib/autonomy/run.sh' }),
+        JSON.stringify({ command: 'src/infra/lib/evolution/run.sh' }),
       ]);
       expect(result.exitCode).toBe(2);
       expect(result.stdout).toContain('Sentinel files are protected');
     });
 
+    it('should block when command string starts with hooks/scripts/lib/', () => {
+      const result = runGuard([
+        'Bash',
+        JSON.stringify({ command: 'hooks/scripts/lib/dispatcher.js' }),
+      ]);
+      expect(result.exitCode).toBe(2);
+    });
+
     it('should not block non-dangerous commands referencing sentinel path mid-string', () => {
-      // isSentinelPath only checks startsWith, and the DANGEROUS_BASH_RE +
-      // includes check requires both a dangerous command and sentinel path
       const result = runGuard([
         'Bash',
-        JSON.stringify({ command: 'cat src/infra/lib/autonomy/policy.ts | wc -l' }),
+        JSON.stringify({ command: 'cat src/infra/lib/evolution/GuardAnalyzer.ts | wc -l' }),
       ]);
       // 'cat' is not a dangerous command, command does not start with sentinel path
       expect(result.exitCode).toBe(0);
     });
   });
 
+  // ─── stdin vs argv 우선순위 ───
   describe('stdin vs argv priority', () => {
     it('should prefer stdin payload over argv', () => {
       const payload = JSON.stringify({
         tool_name: 'Write',
-        tool_input: { file_path: 'src/infra/lib/autonomy/x.ts' },
+        tool_input: { file_path: 'src/infra/lib/evolution/x.ts' },
       });
       try {
         execFileSync('node', [SCRIPT, 'Read', '{}'], {

package/hooks/scripts/__tests__/step-counter.test.js

@@ -75,27 +75,31 @@ describe('step-counter PostToolUse hook', () => {
       expect(data.startedAt).toMatch(/^\d{4}-\d{2}-\d{2}T/);
     });
 
-    it('연속 호출 시 steps 누적', () => {
-      for (let i = 0; i < 3; i++) {
+    it('연속 호출 시 steps 누적 (10이벤트 재작성 주기 고려)', () => {
+      // 10이벤트마다 재작성 — 10회 호출 후에는 steps=10 이 보장됨
+      for (let i = 0; i < 10; i++) {
         runCounter({
           payload: { tool_name: 'Bash', tool_input: { command: 'echo hi' }, tool_response: {} },
           projectDir,
         });
       }
       const data = readJson(runJson);
-      expect(data.steps).toBe(3);
+      expect(data.steps).toBe(10);
     });
 
-    it('손상된 JSON 이 있어도 새로 시작', () => {
+    it('손상된 JSON 이 있어도 새로 시작 (10회 후 재작성으로 확인)', () => {
       fs.mkdirSync(path.join(projectDir, '.vibe', 'metrics'), { recursive: true });
       fs.writeFileSync(runJson, '{ broken json');
-      const r = runCounter({
-        payload: { tool_name: 'Bash', tool_input: {}, tool_response: {} },
-        projectDir,
-      });
-      expect(r.status).toBe(0);
+      // 10회 호출해야 재작성 주기 도달
+      for (let i = 0; i < 10; i++) {
+        runCounter({
+          payload: { tool_name: 'Bash', tool_input: {}, tool_response: {} },
+          projectDir,
+        });
+      }
       const data = readJson(runJson);
-      expect(data.steps).toBe(1);
+      expect(data.steps).toBe(10);
+      expect(data.startedAt).toMatch(/^\d{4}-\d{2}-\d{2}T/);
     });
   });
 
@@ -149,7 +153,8 @@ describe('step-counter PostToolUse hook', () => {
       expect(readJson(runJson).steps).toBe(1);
     });
 
-    it('연속 호출 시 jsonl 누적', () => {
+    it('연속 호출 시 jsonl 누적 (Read는 조기 종료 — 기록 안 됨)', () => {
+      // Read 는 READ_ONLY_TOOLS 조기 종료 → jsonl 미기록
       runCounter({
         payload: { tool_name: 'Read', tool_input: { file_path: 'a.ts' }, tool_response: {} },
         projectDir,
@@ -159,8 +164,8 @@ describe('step-counter PostToolUse hook', () => {
         projectDir,
       });
       const lines = readJsonl(runJsonl);
-      expect(lines).toHaveLength(2);
-      expect(lines.map((l) => l.tool)).toEqual(['Read', 'Edit']);
+      expect(lines).toHaveLength(1);
+      expect(lines[0].tool).toBe('Edit');
     });
   });
 
@@ -322,10 +327,10 @@ describe('step-counter PostToolUse hook', () => {
       // 같은 카테고리 실패 2회
       failBash('a', err, projectDir);
       failBash('b', err, projectDir);
-      // 성공 툴콜로 윈도우 채움 (10줄 이상)
+      // 성공 툴콜로 윈도우 채움 (10줄 이상) — Bash 를 사용 (Read 는 조기 종료로 jsonl 미기록)
       for (let i = 0; i < 10; i++) {
         runCounter({
-          payload: { tool_name: 'Read', tool_input: { file_path: `f${i}.ts` }, tool_response: {} },
+          payload: { tool_name: 'Bash', tool_input: { command: `echo ${i}` }, tool_response: {} },
           projectDir,
         });
       }
@@ -355,4 +360,79 @@ describe('step-counter PostToolUse hook', () => {
       expect(r.status).toBe(0);
     });
   });
+
+  // ───────── 읽기 전용 도구 조기 종료 (defense-in-depth) ─────────
+  describe('읽기 전용 도구 조기 종료', () => {
+    const READ_ONLY = ['Read', 'Grep', 'Glob', 'WebFetch', 'WebSearch', 'TodoWrite', 'ToolSearch', 'ListMcpResourcesTool'];
+
+    it.each(READ_ONLY)('%s 호출 시 파일 미생성 + exit 0', (toolName) => {
+      const r = runCounter({
+        payload: { tool_name: toolName, tool_input: { file_path: 'src/foo.ts' }, tool_response: {} },
+        projectDir,
+      });
+      expect(r.status).toBe(0);
+      // jsonl에 기록하지 않아야 함
+      const jsonlPath = path.join(projectDir, '.vibe', 'metrics', 'current-run.jsonl');
+      expect(fs.existsSync(jsonlPath)).toBe(false);
+      // current-run.json 도 생성하지 않아야 함
+      const jsonPath = path.join(projectDir, '.vibe', 'metrics', 'current-run.json');
+      expect(fs.existsSync(jsonPath)).toBe(false);
+    });
+  });
+
+  // ───────── 쓰기 스로틀 ─────────
+  describe('쓰기 스로틀: jsonl 항상 append, json 조건부 재작성', () => {
+    it('첫 번째 이벤트는 current-run.json 생성 (파일 없음 → 스로틀 없음)', () => {
+      runCounter({
+        payload: { tool_name: 'Bash', tool_input: { command: 'x' }, tool_response: {} },
+        projectDir,
+      });
+      expect(fs.existsSync(runJson)).toBe(true);
+      expect(readJson(runJson).steps).toBe(1);
+    });
+
+    it('10이벤트마다 강제 재작성: 10회 후 steps=jsonl라인수=10', () => {
+      for (let i = 0; i < 10; i++) {
+        runCounter({
+          payload: { tool_name: 'Edit', tool_input: { file_path: 'a.ts' }, tool_response: {} },
+          projectDir,
+        });
+      }
+      // 10번째 이벤트에서 강제 재작성 (10%10===0) — steps = jsonl 라인 수 = 10
+      const data = readJson(runJson);
+      expect(data.steps).toBe(10);
+      // jsonl 도 10줄
+      const lines = readJsonl(runJsonl);
+      expect(lines).toHaveLength(10);
+    });
+
+    it('jsonl 은 스로틀 무관 항상 즉시 append', () => {
+      for (let i = 0; i < 5; i++) {
+        runCounter({
+          payload: { tool_name: 'Bash', tool_input: { command: `cmd-${i}` }, tool_response: {} },
+          projectDir,
+        });
+      }
+      const lines = readJsonl(runJsonl);
+      expect(lines).toHaveLength(5);
+    });
+
+    it('3-fail 감지는 jsonl 기반 — json 스로틀 후에도 동작', () => {
+      const err = "TypeError: Cannot read properties of undefined (reading 'x')";
+      // 3회 실패 (jsonl에 즉시 기록되므로 감지 가능)
+      for (let i = 0; i < 3; i++) {
+        runCounter({
+          payload: {
+            tool_name: 'Bash',
+            tool_input: { command: `run-${i}` },
+            tool_response: { is_error: true, error: err },
+          },
+          projectDir,
+        });
+      }
+      const apDir = path.join(projectDir, '.vibe', 'anti-patterns');
+      const files = fs.existsSync(apDir) ? fs.readdirSync(apDir).filter(f => f.endsWith('.md')) : [];
+      expect(files).toHaveLength(1);
+    });
+  });
 });

package/hooks/scripts/__tests__/utils-npm-root.test.js

@@ -0,0 +1,98 @@
+/**
+ * utils.js — getGlobalNpmPath() 파일 캐시 테스트
+ *
+ * 검증 범위:
+ *  - L2 파일 캐시 히트 (TTL 내)
+ *  - L2 파일 캐시 만료 (TTL 초과)
+ *  - 캐시 파일 손상 시 fail-open (execSync 재실행)
+ *  - 캐시 파일 없음 시 execSync 실행 후 파일 저장
+ *
+ * 격리 전략: 각 테스트는 별도 임시 디렉토리를 캐시 경로로 사용한다.
+ * NPM_ROOT_CACHE_FILE 환경 변수를 통해 경로를 주입한다.
+ */
+import { describe, it, expect } from 'vitest';
+import { spawnSync } from 'child_process';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const UTILS_PATH = path.resolve(__dirname, '..', 'utils.js');
+
+function makeTempCacheFile() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'vibe-npm-root-test-'));
+  return path.join(dir, 'npm-root.json');
+}
+
+/**
+ * utils.js 의 getGlobalNpmPath() 를 별도 프로세스에서 실행.
+ * VIBE_NPM_ROOT_CACHE_FILE 환경 변수로 캐시 파일 경로를 주입한다.
+ */
+function runGetNpmRoot(cacheFilePath) {
+  return spawnSync('node', ['--input-type=module', '--eval',
+    `import { getGlobalNpmPath } from '${UTILS_PATH}';
+     process.stdout.write(getGlobalNpmPath() || '');`
+  ], {
+    encoding: 'utf-8',
+    timeout: 10000,
+    env: {
+      ...process.env,
+      VIBE_NPM_ROOT_CACHE_FILE: cacheFilePath,
+    },
+  });
+}
+
+describe('utils.js — getGlobalNpmPath() npm-root 파일 캐시', () => {
+  it('캐시 파일 없으면 execSync 실행 후 캐시 파일 생성', () => {
+    const cacheFile = makeTempCacheFile();
+    // 캐시 파일이 없는 상태에서 시작
+    expect(fs.existsSync(cacheFile)).toBe(false);
+
+    const result = runGetNpmRoot(cacheFile);
+    expect(result.status).toBe(0);
+    expect(result.stdout.trim()).toBeTruthy();
+
+    // 캐시 파일이 생성되어야 함
+    expect(fs.existsSync(cacheFile)).toBe(true);
+    const cached = JSON.parse(fs.readFileSync(cacheFile, 'utf-8'));
+    expect(cached.npmRoot).toBe(result.stdout.trim());
+    expect(typeof cached.savedAt).toBe('number');
+  });
+
+  it('유효한 캐시 파일이 있으면 execSync 없이 캐시값 반환', () => {
+    const cacheFile = makeTempCacheFile();
+    const fakeRoot = '/fake/npm/root/for/test';
+    // 유효한 캐시 미리 작성
+    fs.writeFileSync(cacheFile, JSON.stringify({ npmRoot: fakeRoot, savedAt: Date.now() }), { mode: 0o600 });
+
+    const result = runGetNpmRoot(cacheFile);
+    expect(result.status).toBe(0);
+    expect(result.stdout.trim()).toBe(fakeRoot);
+  });
+
+  it('TTL 초과 캐시는 무효화 — execSync 재실행', () => {
+    const cacheFile = makeTempCacheFile();
+    const staleRoot = '/stale/path/should/not/be/used';
+    const expiredAt = Date.now() - (25 * 60 * 60 * 1000); // 25시간 전
+    fs.writeFileSync(cacheFile, JSON.stringify({ npmRoot: staleRoot, savedAt: expiredAt }), { mode: 0o600 });
+
+    const result = runGetNpmRoot(cacheFile);
+    expect(result.status).toBe(0);
+    // stale 값이 아닌 실제 npm root 가 반환되어야 함
+    expect(result.stdout.trim()).not.toBe(staleRoot);
+    expect(result.stdout.trim()).toBeTruthy();
+  });
+
+  it('손상된 캐시 파일 — fail-open (execSync 실행)', () => {
+    const cacheFile = makeTempCacheFile();
+    fs.writeFileSync(cacheFile, '{ broken json :::');
+
+    const result = runGetNpmRoot(cacheFile);
+    expect(result.status).toBe(0);
+    expect(result.stdout.trim()).toBeTruthy(); // 실제 경로 반환
+    // 손상된 파일 때문에 프로세스가 crash 나지 않아야 함
+    const stderr = result.stderr || '';
+    expect(stderr).not.toMatch(/^Error:/m);
+  });
+});

package/hooks/scripts/auto-commit.js

@@ -13,12 +13,38 @@
  *   으로 롤백 가능. 최근 5개만 유지.
  */
 import { execSync } from 'child_process';
-import { PROJECT_DIR, readProjectConfig } from './utils.js';
+import { PROJECT_DIR, readProjectConfig, logHookDecision } from './utils.js';
+import { readLedger } from './lib/run-ledger.js';
 
 // Opt-in 가드 — 명시적으로 켜지 않았으면 아무것도 하지 않는다.
 const __autoCommitCfg = readProjectConfig();
 if (__autoCommitCfg?.hooks?.['auto-commit']?.enabled !== true) process.exit(0);
 
+// verify 게이트 — vibe.run 세션이 시작됐으면 verifyPassed가 true이고
+// verifyAt > runStarted 인 경우에만 커밋을 허용한다.
+const __ledger = readLedger(PROJECT_DIR);
+if (__ledger && __ledger.runStarted) {
+  const verifyOk = __ledger.verifyPassed === true
+    && __ledger.verifyAt
+    && __ledger.verifyAt > __ledger.runStarted;
+  if (!verifyOk) {
+    const reason = !__ledger.verifyPassed
+      ? 'vibe.verify not passed — run /vibe.verify before committing'
+      : 'verifyAt is not after runStarted — re-run /vibe.verify';
+    logHookDecision('auto-commit', 'git-commit', 'block', reason);
+    process.stderr.write(`[auto-commit] SKIP: ${reason}\n`);
+    process.exit(0);
+  }
+}
+
+// verifyRequired 게이트 — PostToolUse에서 P1 이슈가 발견되어 verify가 요구됨.
+if (__ledger && __ledger.verifyRequired === true) {
+  const reason = `P1 issue requires verification: ${__ledger.verifyRequiredReason || 'see code-check findings'}`;
+  logHookDecision('auto-commit', 'git-commit', 'block', reason);
+  process.stderr.write(`[auto-commit] SKIP: ${reason}\n`);
+  process.exit(0);
+}
+
 const PROTECTED_BRANCHES = ['main', 'master', 'develop', 'production'];
 const MAX_FILES_IN_MSG = 5;
 const MAX_CHECKPOINTS = 5;

package/hooks/scripts/auto-format.js

@@ -4,19 +4,33 @@
  * 프로젝트에 설치된 포매터를 감지하고 수정된 파일에 자동 실행.
  * Prettier(JS/TS), Black(Python), gofmt(Go) 지원.
  * 200ms 이내 완료 목표 — 단일 파일만 처리.
+ *
+ * 변경 감지: mtime 비교로 prettier가 실제 파일을 수정했는지 판단.
+ * 수정된 경우 finding을 반환 — 디스패처가 additionalContext에 포함시킨다.
  */
-import { execSync } from 'child_process';
-import { existsSync } from 'fs';
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+import { existsSync, statSync } from 'fs';
 import path from 'path';
 import { PROJECT_DIR } from './utils.js';
+import { buildCliCtx, isDirectRun } from './lib/hook-context.js';
+
+// WHY async execFile (not execSync): in-process 디스패처에서 다른 step과
+// Promise.all로 병렬 실행되므로, 동기 실행은 이벤트 루프를 막아 체인을 직렬화시킨다.
+const execFileAsync = promisify(execFile);
 
 const CODE_EXT_RE = /\.(ts|tsx|js|jsx|mjs|cjs|css|scss|json|md|html|vue|svelte)$/;
 const PYTHON_EXT_RE = /\.py$/;
 const GO_EXT_RE = /\.go$/;
+const FORMAT_TIMEOUT_MS = 5000;
 
-function getFilePath() {
-  const input = JSON.parse(process.env.TOOL_INPUT || '{}');
-  return input.file_path || input.path || '';
+function getFilePath(ctx) {
+  try {
+    const input = JSON.parse(ctx.toolInput || '{}');
+    return input.file_path || input.path || '';
+  } catch {
+    return '';
+  }
 }
 
 // PATH 직접 스캔 — `which` execSync는 매 파일 저장마다 자식 프로세스를 동기
@@ -37,33 +51,84 @@ function hasPrettier() {
   return existsSync(path.join(PROJECT_DIR, 'node_modules', '.bin', 'prettier'));
 }
 
-function formatFile(filePath) {
+/**
+ * mtimeMs 읽기 — stat 실패 시 0 반환 (fail-open).
+ * @param {string} resolvedPath
+ * @returns {number}
+ */
+function getMtime(resolvedPath) {
+  try {
+    return statSync(resolvedPath).mtimeMs;
+  } catch {
+    return 0;
+  }
+}
+
+/**
+ * 파일 포맷 실행. 실제 변경이 발생했으면 finding 문자열을 반환.
+ * @param {string} filePath
+ * @returns {Promise<string|null>} finding or null
+ */
+async function formatFile(filePath) {
   const resolved = path.resolve(filePath);
-  if (!existsSync(resolved)) return;
+  if (!existsSync(resolved)) return null;
 
   try {
     if (CODE_EXT_RE.test(filePath) && hasPrettier()) {
-      execSync(`npx prettier --write "${resolved}"`, {
+      const mtimeBefore = getMtime(resolved);
+      await execFileAsync('npx', ['prettier', '--write', resolved], {
         cwd: PROJECT_DIR,
-        stdio: 'ignore',
-        timeout: 5000,
+        timeout: FORMAT_TIMEOUT_MS,
+        // Windows에서 npx는 npx.cmd — shell 없이는 execFile이 찾지 못함
+        shell: process.platform === 'win32',
       });
-      console.log(`[AUTO-FORMAT] prettier: ${path.basename(resolved)}`);
+      const mtimeAfter = getMtime(resolved);
+      if (mtimeAfter > mtimeBefore) {
+        return `auto-format reformatted ${path.basename(resolved)} — re-read before further edits to avoid stale old_string`;
+      }
     } else if (PYTHON_EXT_RE.test(filePath) && hasBin('black')) {
-      execSync(`black --quiet "${resolved}"`, { stdio: 'ignore', timeout: 5000 });
-      console.log(`[AUTO-FORMAT] black: ${path.basename(resolved)}`);
+      const mtimeBefore = getMtime(resolved);
+      await execFileAsync('black', ['--quiet', resolved], { timeout: FORMAT_TIMEOUT_MS });
+      const mtimeAfter = getMtime(resolved);
+      if (mtimeAfter > mtimeBefore) {
+        return `auto-format reformatted ${path.basename(resolved)} — re-read before further edits to avoid stale old_string`;
+      }
     } else if (GO_EXT_RE.test(filePath) && hasBin('gofmt')) {
-      execSync(`gofmt -w "${resolved}"`, { stdio: 'ignore', timeout: 5000 });
-      console.log(`[AUTO-FORMAT] gofmt: ${path.basename(resolved)}`);
+      const mtimeBefore = getMtime(resolved);
+      await execFileAsync('gofmt', ['-w', resolved], { timeout: FORMAT_TIMEOUT_MS });
+      const mtimeAfter = getMtime(resolved);
+      if (mtimeAfter > mtimeBefore) {
+        return `auto-format reformatted ${path.basename(resolved)} — re-read before further edits to avoid stale old_string`;
+      }
     }
   } catch {
     // Format failure should never block — silently continue
   }
+  return null;
+}
+
+/**
+ * in-process 진입점 — 포맷 실행. finding 문자열 배열 반환.
+ * @param {{ toolInput: string }} ctx
+ * @returns {Promise<{ exitCode: number, findings: string[] }>}
+ */
+export async function run(ctx) {
+  const findings = [];
+  try {
+    const filePath = getFilePath(ctx);
+    if (filePath) {
+      const finding = await formatFile(filePath);
+      if (finding) findings.push(finding);
+    }
+  } catch {
+    // Silent fail
+  }
+  return { exitCode: 0, findings };
 }
 
-try {
-  const filePath = getFilePath();
-  if (filePath) formatFile(filePath);
-} catch {
-  // Silent fail
+// standalone CLI 모드
+if (isDirectRun(import.meta.url)) {
+  const { exitCode, findings } = await run(buildCliCtx());
+  if (findings.length > 0) process.stdout.write(findings.join('\n') + '\n');
+  process.exit(exitCode);
 }