부하가 높은 desktop에서 시험이 가끔 떨어진다. 총괄 지시로 두 가지를 고치고, 검증 중 찾은 하나를 더 고친다.
자식 프로세스 시험 timeout.tests/unit/documentation-readiness.test.ts가 FE-GATE-020 drill 사본에서 기본 timeout 10초를 넘겼다. 평소 0.4~1.2초인 시험이 10.6초 걸렸다. 같은 모양의 시험을 repo 전체에서 찾았다. 그 결과 자식 프로세스를 띄우면서 기본 10초에 기대는 Vitest 시험이 91개(24파일) 나왔다. 가장 위험한 tests/architecture/app-build-input.test.ts는 평소에도 5.7초까지 걸렸다. 문서 시험 자체에는 PR #15가 이미 60초를 줬다.
guardian lease.tests/integration/provider-guardian-transaction.test.ts에서 guardian이 lease 만료로 스스로 SIGKILL한다. FE-GATE-007·020에서 났고 FE-B 실행에서는 load 28에 2건 났다. 다시 돌리면 통과한다.
artifacts 복사 경합. 이 PR의 첫 최종 실행에서 FE-GATE-007이 실패했다. tests/integration/security-followup-archive.test.ts가 artifacts/를 복사하는 동안, 다른 시험이 쓰던 임시 파일이 rename되어 ENOENT가 났다.
desktop에서 test:coverage 묶음(maxWorkers=4)과 test:unit을 세 번씩 돌렸다.
시험마다 띄운 자식 프로세스는 child_process 함수를 감싸 기록했고, 소요 시간은 JSON reporter로 받았다.
실제 timeout은 task.timeout으로 받았다.
자식 프로세스를 띄우는 시험 140개 중 88개가 기본값이었다.
tests/system은 아래 검사가 잡은 셋을 따로 세 번 쟀다.
tests/helpers/child-process-timeout.ts의 childProcessTimeout(<잰 최대 ms>)가 timeout을 정한다.
잰 최대의 15배를 30초 단위로 올린 값이다.
15배는 위 문서 시험의 0.7초 → 10.6초에서 왔다.
시험마다 자기가 잰 값을 인자로 적어서, 근거가 호출 자리에 남는다.
describe 안의 기본값 시험이 모두 자식 프로세스를 띄우면 describe에, 일부만 띄우면 그 시험에 준다. 프로세스 안에서 도는 시험의 hang을 늦게 잡지 않으려는 것이다.
tests/setup.ts가 child_process 함수를 감싼다.
기본 timeout인 시험이 자식 프로세스를 띄우면 그 호출에서 실패시키고, helper 이름을 알린다.
시험이 import한 helper나 스크립트가 띄워도 잡는다.
util.promisify가 읽는 속성은 원래 함수에서 옮긴다.
이 검사의 시험은 tests/unit/child-process-timeout.test.ts다.
docs/work/reference/testing.md 2절에 값 정하는 법과 이 검사를 적었다.
버린 것:
전역 testTimeout 올리기: 프로세스 안 시험의 hang을 늦게 잡는다.
시험마다 손으로 정한 숫자: 근거가 남지 않는다. 이미 있던 60_000·120_000에도 근거가 없었다.
자식 프로세스 없이 검사하게 바꾸기: 검사 스크립트를 CLI 그대로 시험하는 것이 이 시험들의 목적이라 범위가 커진다.
파일에 timeout 선언이 있는지만 보는 정적 검사: helper가 띄우는 경우와, 같은 파일의 다른 시험을 놓친다.
77c01b03 guardian 시험의 lease가 시험 대상이 아니면 시험 timeout만큼 준다.
원인은 두 가지다.
startProviderGuardian은 guardian을 띄우자마자 절대 deadline을 찍는다. 그래서 client 경로 시험의 2~3초 lease가 node 시작 시간까지 낸다.
직접 프로토콜 시험은 guardian이 load를 마친 뒤 가드를 보낸다(c8620042). 그래도 가드 → READY 처리는 실제 시계로 돈다. desktop CPU 25% 제한에서 이 구간이 17ms에서 334ms로 늘었다. 350ms lease로 만료를 보는 시험은 여유가 거의 없다.
lease가 시험 대상이 아닌 15곳(client 경로 10, 직접 경로 5)은 LEASE_NOT_UNDER_TEST_MS다.
값은 시험 timeout과 같다.
그래서 lease가 시험보다 먼저 끝날 수 없고, guardian이 멈추면 시험 timeout이 잡는다.
lease를 보는 두 시험은 잰 값으로 정했다.
만료 시험은 350ms → 2초다. 가드 → READY의 CPU 25% 최대 334ms의 여섯 배다.
near-deadline 시험은 직접 프로토콜로 옮겨 node 시작 시간이 lease에서 빠진다.
sendGuard가 보낸 deadline을 돌려준다.
near-deadline 시험은 lease 4초의 마지막 2초 안에 publish·commit을 보내고, 그 구간에 있었는지 단언한다.
2초는 publish·commit의 CPU 25% 최대 104ms의 약 스무 배다.
client의 publish·commit은 「owns raw and sealed publication」이 그대로 본다.
버린 것:
guardian에 가짜 시계 주입: 운영 스크립트에 시험용 훅을 넣어야 한다.
client가 guardian load 뒤에 deadline을 찍게 바꾸기: 운영 프로토콜에 준비 신호를 더해야 한다.
모든 lease를 늘리기: 만료와 near-deadline 시험은 lease가 대상이다.
db4c632d archive 시험이 다른 시험이 쓰는 중인 임시 파일을 복사하지 않는다.
같은 integration 실행에서 tests/integration/http-scenario-catalog.test.ts가 artifacts/tests/http-scenario-executions.json을 임시 파일에 쓰고 rename한다.
복사 filter가 원자적 쓰기의 임시 파일(.<이름>.<무작위>.tmp)을 건너뛴다. fs.cp는 filter를 stat보다 먼저 부르므로, 건너뛴 파일은 사라져도 오류가 없다.
버린 것: 필요한 증거 경로만 복사하기(공급망 생성이 artifacts의 .gitkeep까지 추적 파일을 모두 lstat하고 build가 읽는 증거가 여러 곳이라 목록을 따로 관리해야 한다), 두 시험을 직렬로 돌리기(integration 층 전체가 느려진다).
a593feb2 CHANGELOG 정리 단계 절: 범위, 먼저 할 일 17, 옮긴 뒤 확인 1, 계약 표 한 줄, 그 밖의 수정 두 줄.
위험과 영향
다운스트림: 자기 Vitest 시험이 기본 timeout으로 자식 프로세스를 띄우면 test:unit 등이 실패한다. 메시지가 helper를 알린다(CHANGELOG 먼저 할 일 17).
검사가 보지 않는 곳:
hook(beforeAll 등)에서 띄우는 프로세스는 보지 않는다. 계측에서 hook이 띄운 곳은 둘이고, 둘 다 180초를 선언했다.
Playwright spec은 tests/setup.ts를 쓰지 않는다.
같은 파일 안에서 it.concurrent로 도는 시험이 섞이면 어느 시험의 timeout인지 틀릴 수 있다. 지금은 그런 시험이 없다.
guardian 시험이 실패하면 guardian이 lease 끝까지(최대 30초) 남을 수 있다. 전에는 2~3초였다.
near-deadline 시험에는 실제 시계 구간이 남는다. publish·commit이 2초를 넘으면 실패한다.
운영 client가 lease에 node 시작 시간을 포함하는 것은 그대로다. 운영 lease는 분 단위다.
archive 시험: 임시 파일이 아닌 파일을 다른 시험이 지우는 경합은 남는다. 지금 artifacts/ 아래에서 그렇게 하는 시험은 찾지 못했다.
시험 파일 24개를 건드려 W2-FE 브랜치와 겹칠 수 있다. W2-FE에 D를 여기서 고쳤다고 알렸다.
검증
모두 desktop에서 돌렸다. workflow env(CI=true, 40자리 VITE_COMMIT_SHA, VITE_BUILD_ID, RELEASE_ID, CI_RUNNER_IMAGE digest)를 썼고, job마다 깨끗한 트리에서 설치를 한 번 하고 게이트를 차례로 corepack pnpm ci:gate <ID>로 돌렸다. 로그는 desktop /tmp/claude-gates/ 아래에 있다. 계측은 fea-m1·fea-m2·fea-m3·fea-gp, 재현은 fea-t2·fea-gg·fea-gg2·fea-ar2, 최종은 fea-f3이다.
판정(docs/work/reference/gates.md 3절): merge 단계 중 FE-GATE-013 밖 전부 통과, FE-GATE-013은 desktop 호스트 제약(user namespace)이라 판정에서 뺌(뒤 명령 결과 첨부, 모두 rc=0). FE-GATE-005·020은 깨끗한 트리에서 3회 연속 통과했다.
커밋별(fea-f3, 2026-11-12 11:49~11:55)
다섯 검사(test:unit, check:types, check:ci, lint, verify:documentation)가 네 커밋 모두 rc=0이다.
커밋
test:unit
check:types
check:ci
lint
verify:documentation
91962e24
0 (47s)
0
0
0
0
77c01b03
0 (65s)
0
0
0
0
db4c632d
0 (48s)
0
0
0
0
a593feb2
0 (71s)
0
0
0
0
게이트 — 끝 커밋 a593feb2(fea-f3, 11:5512:57, load 526)
job
게이트
결과
merge_static
001 · 002 · 003 · 010 · 011 · 012
모두 0 (4s · 24s · 15s · 67s · 12s · 7s)
merge_test
004 · 006 · 007
모두 0 (2s · 13s · 30s)
merge_test
013
1 (2s). 사전 점검이 user namespace 제한 하나만 댄다. 뒤 명령은 아래
merge_test, 1회
005 · 020
0 (162s) · 0 (902s)
깨끗한 트리 2회
005 · 020
0 (145s) · 0 (1,034s)
깨끗한 트리 3회
005 · 020
0 (171s) · 0 (1,009s)
main_gate
029
0 (34s)
—
017
0 (2s)
FE-GATE-005: 세 번 모두 test:unit 3,166개, coverage 4,102개 통과.
FE-GATE-020: 세 번 모두 제거 drill 다섯이 실패 0(browser-file-storage 7, feature-scaffold 38, optional-recipe 6, realtime 7, sample-removal 목록 비어 SKIP).
FE-GATE-013 뒤 명령: verify:reproducible-build·build:release-candidate·verify:local-evidence·check:browser-security 모두 0. tests/system은 115개 중 18개 실패, 97개 통과다. 실패는 모두 candidate archive and provider upload boundaries(bwrap)이고, 새 검사 위반은 0이다.
FE-GATE-008·009(Playwright)는 돌리지 않았다. 이 PR은 Playwright가 쓰는 파일을 바꾸지 않는다.
결정적 재현
무엇
조건
고치기 전
고친 뒤
1번 timeout
CPU 10% 제한, app-build-input·registry-governance·hosting-probe·design-system-rules
main 650d22fa: 11개 「Test timed out in 10000ms」
71개 통과, 가장 긴 시험 17.7초
2번 guardian
CPU 20% 제한, guardian 파일 5회
main d2239c67: 5회 모두 1~6개 실패(가드 처리 중 deadline 지남 126, READY·PUBLISHED 대기 초과, EPIPE)
5회 모두 22개 통과
3번 archive
옆 프로세스가 artifacts/tests에 임시 파일 10개를 계속 만들고 rename
main 6b4f703c: 3회 중 2회 FE-GATE-007과 같은 ENOENT(.tmp)
3회 모두 통과
guardian 파일은 고친 뒤 평소 상태로 30회(load 3.6~21), CPU 20% 제한으로 5회 더 돌려 모두 통과했다.
검사의 검출력(변이)
tests/setup.ts의 검사를 끄면 tests/unit/child-process-timeout.test.ts가 실패한다.
tests/unit/tracked-artifacts.test.ts describe의 timeout을 지우면 그 시험이 검사 메시지로 실패한다.
tests/system을 처음 돌렸을 때 검사가 기본 timeout으로 자식 프로세스를 띄우던 시험 셋(ci-evidence-freshness 둘, provider-process-group 하나)을 잡았다. 따로 세 번 재서 timeout을 줬다.
처음 최종 실행에서 고친 것
near-deadline 시험의 「마지막 2초 안」 단언이 남은 2,001ms로 실패했다(FE-GATE-007). 타이머가 Date.now()보다 1ms 일찍 깼다. 목표 시각에 닿을 때까지 다시 기다리게 고쳐 2번 커밋에 합쳤다.
다음 실행에서 FE-GATE-007이 archive 시험의 ENOENT로 실패했다. 3번 커밋이다.
## 무엇을, 왜
부하가 높은 desktop에서 시험이 가끔 떨어진다. 총괄 지시로 두 가지를 고치고, 검증 중 찾은 하나를 더 고친다.
- **자식 프로세스 시험 timeout.** `tests/unit/documentation-readiness.test.ts`가 FE-GATE-020 drill 사본에서 기본 timeout 10초를 넘겼다. 평소 0.4~1.2초인 시험이 10.6초 걸렸다. 같은 모양의 시험을 repo 전체에서 찾았다. 그 결과 자식 프로세스를 띄우면서 기본 10초에 기대는 Vitest 시험이 91개(24파일) 나왔다. 가장 위험한 `tests/architecture/app-build-input.test.ts`는 평소에도 5.7초까지 걸렸다. 문서 시험 자체에는 PR #15가 이미 60초를 줬다.
- **guardian lease.** `tests/integration/provider-guardian-transaction.test.ts`에서 guardian이 lease 만료로 스스로 SIGKILL한다. FE-GATE-007·020에서 났고 FE-B 실행에서는 load 28에 2건 났다. 다시 돌리면 통과한다.
- **artifacts 복사 경합.** 이 PR의 첫 최종 실행에서 FE-GATE-007이 실패했다. `tests/integration/security-followup-archive.test.ts`가 `artifacts/`를 복사하는 동안, 다른 시험이 쓰던 임시 파일이 rename되어 ENOENT가 났다.
## 고른 방법과 버린 대안
커밋 넷이다. 커밋마다 desktop에서 test:unit·check:types·check:ci·lint·verify:documentation을 돌렸다(아래 검증).
1. `91962e24` 자식 프로세스 시험이 잰 시간으로 timeout을 정한다.
- 무엇을 고칠지는 계측으로 정했다.
- desktop에서 test:coverage 묶음(maxWorkers=4)과 test:unit을 세 번씩 돌렸다.
- 시험마다 띄운 자식 프로세스는 `child_process` 함수를 감싸 기록했고, 소요 시간은 JSON reporter로 받았다.
- 실제 timeout은 `task.timeout`으로 받았다.
- 자식 프로세스를 띄우는 시험 140개 중 88개가 기본값이었다.
- tests/system은 아래 검사가 잡은 셋을 따로 세 번 쟀다.
- `tests/helpers/child-process-timeout.ts`의 `childProcessTimeout(<잰 최대 ms>)`가 timeout을 정한다.
- 잰 최대의 15배를 30초 단위로 올린 값이다.
- 15배는 위 문서 시험의 0.7초 → 10.6초에서 왔다.
- 시험마다 자기가 잰 값을 인자로 적어서, 근거가 호출 자리에 남는다.
- describe 안의 기본값 시험이 모두 자식 프로세스를 띄우면 describe에, 일부만 띄우면 그 시험에 준다. 프로세스 안에서 도는 시험의 hang을 늦게 잡지 않으려는 것이다.
- `tests/setup.ts`가 `child_process` 함수를 감싼다.
- 기본 timeout인 시험이 자식 프로세스를 띄우면 그 호출에서 실패시키고, helper 이름을 알린다.
- 시험이 import한 helper나 스크립트가 띄워도 잡는다.
- `util.promisify`가 읽는 속성은 원래 함수에서 옮긴다.
- 이 검사의 시험은 `tests/unit/child-process-timeout.test.ts`다.
- `docs/work/reference/testing.md` 2절에 값 정하는 법과 이 검사를 적었다.
- 버린 것:
- 전역 testTimeout 올리기: 프로세스 안 시험의 hang을 늦게 잡는다.
- 시험마다 손으로 정한 숫자: 근거가 남지 않는다. 이미 있던 60_000·120_000에도 근거가 없었다.
- 자식 프로세스 없이 검사하게 바꾸기: 검사 스크립트를 CLI 그대로 시험하는 것이 이 시험들의 목적이라 범위가 커진다.
- 파일에 timeout 선언이 있는지만 보는 정적 검사: helper가 띄우는 경우와, 같은 파일의 다른 시험을 놓친다.
2. `77c01b03` guardian 시험의 lease가 시험 대상이 아니면 시험 timeout만큼 준다.
- 원인은 두 가지다.
- `startProviderGuardian`은 guardian을 띄우자마자 절대 deadline을 찍는다. 그래서 client 경로 시험의 2~3초 lease가 node 시작 시간까지 낸다.
- 직접 프로토콜 시험은 guardian이 load를 마친 뒤 가드를 보낸다(c8620042). 그래도 가드 → READY 처리는 실제 시계로 돈다. desktop CPU 25% 제한에서 이 구간이 17ms에서 334ms로 늘었다. 350ms lease로 만료를 보는 시험은 여유가 거의 없다.
- lease가 시험 대상이 아닌 15곳(client 경로 10, 직접 경로 5)은 `LEASE_NOT_UNDER_TEST_MS`다.
- 값은 시험 timeout과 같다.
- 그래서 lease가 시험보다 먼저 끝날 수 없고, guardian이 멈추면 시험 timeout이 잡는다.
- lease를 보는 두 시험은 잰 값으로 정했다.
- 만료 시험은 350ms → 2초다. 가드 → READY의 CPU 25% 최대 334ms의 여섯 배다.
- near-deadline 시험은 직접 프로토콜로 옮겨 node 시작 시간이 lease에서 빠진다.
- `sendGuard`가 보낸 deadline을 돌려준다.
- near-deadline 시험은 lease 4초의 마지막 2초 안에 publish·commit을 보내고, 그 구간에 있었는지 단언한다.
- 2초는 publish·commit의 CPU 25% 최대 104ms의 약 스무 배다.
- client의 publish·commit은 「owns raw and sealed publication」이 그대로 본다.
- 버린 것:
- guardian에 가짜 시계 주입: 운영 스크립트에 시험용 훅을 넣어야 한다.
- client가 guardian load 뒤에 deadline을 찍게 바꾸기: 운영 프로토콜에 준비 신호를 더해야 한다.
- 모든 lease를 늘리기: 만료와 near-deadline 시험은 lease가 대상이다.
3. `db4c632d` archive 시험이 다른 시험이 쓰는 중인 임시 파일을 복사하지 않는다.
- 같은 integration 실행에서 `tests/integration/http-scenario-catalog.test.ts`가 `artifacts/tests/http-scenario-executions.json`을 임시 파일에 쓰고 rename한다.
- 복사 filter가 원자적 쓰기의 임시 파일(`.<이름>.<무작위>.tmp`)을 건너뛴다. `fs.cp`는 filter를 stat보다 먼저 부르므로, 건너뛴 파일은 사라져도 오류가 없다.
- 버린 것: 필요한 증거 경로만 복사하기(공급망 생성이 artifacts의 `.gitkeep`까지 추적 파일을 모두 lstat하고 build가 읽는 증거가 여러 곳이라 목록을 따로 관리해야 한다), 두 시험을 직렬로 돌리기(integration 층 전체가 느려진다).
4. `a593feb2` CHANGELOG 정리 단계 절: 범위, 먼저 할 일 17, 옮긴 뒤 확인 1, 계약 표 한 줄, 그 밖의 수정 두 줄.
## 위험과 영향
- 다운스트림: 자기 Vitest 시험이 기본 timeout으로 자식 프로세스를 띄우면 test:unit 등이 실패한다. 메시지가 helper를 알린다(CHANGELOG 먼저 할 일 17).
- 검사가 보지 않는 곳:
- hook(`beforeAll` 등)에서 띄우는 프로세스는 보지 않는다. 계측에서 hook이 띄운 곳은 둘이고, 둘 다 180초를 선언했다.
- Playwright spec은 `tests/setup.ts`를 쓰지 않는다.
- 같은 파일 안에서 `it.concurrent`로 도는 시험이 섞이면 어느 시험의 timeout인지 틀릴 수 있다. 지금은 그런 시험이 없다.
- guardian 시험이 실패하면 guardian이 lease 끝까지(최대 30초) 남을 수 있다. 전에는 2~3초였다.
- near-deadline 시험에는 실제 시계 구간이 남는다. publish·commit이 2초를 넘으면 실패한다.
- 운영 client가 lease에 node 시작 시간을 포함하는 것은 그대로다. 운영 lease는 분 단위다.
- archive 시험: 임시 파일이 아닌 파일을 다른 시험이 지우는 경합은 남는다. 지금 `artifacts/` 아래에서 그렇게 하는 시험은 찾지 못했다.
- 시험 파일 24개를 건드려 W2-FE 브랜치와 겹칠 수 있다. W2-FE에 D를 여기서 고쳤다고 알렸다.
## 검증
모두 desktop에서 돌렸다. workflow env(`CI=true`, 40자리 `VITE_COMMIT_SHA`, `VITE_BUILD_ID`, `RELEASE_ID`, `CI_RUNNER_IMAGE` digest)를 썼고, job마다 깨끗한 트리에서 설치를 한 번 하고 게이트를 차례로 `corepack pnpm ci:gate <ID>`로 돌렸다. 로그는 desktop `/tmp/claude-gates/` 아래에 있다. 계측은 `fea-m1`·`fea-m2`·`fea-m3`·`fea-gp`, 재현은 `fea-t2`·`fea-gg`·`fea-gg2`·`fea-ar2`, 최종은 `fea-f3`이다.
**판정**(`docs/work/reference/gates.md` 3절): merge 단계 중 FE-GATE-013 밖 전부 통과, FE-GATE-013은 desktop 호스트 제약(user namespace)이라 판정에서 뺌(뒤 명령 결과 첨부, 모두 rc=0). FE-GATE-005·020은 깨끗한 트리에서 3회 연속 통과했다.
### 커밋별(fea-f3, 2026-11-12 11:49~11:55)
다섯 검사(test:unit, check:types, check:ci, lint, verify:documentation)가 네 커밋 모두 rc=0이다.
| 커밋 | test:unit | check:types | check:ci | lint | verify:documentation |
|---|---|---|---|---|---|
| `91962e24` | 0 (47s) | 0 | 0 | 0 | 0 |
| `77c01b03` | 0 (65s) | 0 | 0 | 0 | 0 |
| `db4c632d` | 0 (48s) | 0 | 0 | 0 | 0 |
| `a593feb2` | 0 (71s) | 0 | 0 | 0 | 0 |
### 게이트 — 끝 커밋 `a593feb2`(fea-f3, 11:55~12:57, load 5~26)
| job | 게이트 | 결과 |
|---|---|---|
| merge_static | 001 · 002 · 003 · 010 · 011 · 012 | 모두 0 (4s · 24s · 15s · 67s · 12s · 7s) |
| merge_test | 004 · 006 · 007 | 모두 0 (2s · 13s · 30s) |
| merge_test | 013 | 1 (2s). 사전 점검이 user namespace 제한 하나만 댄다. 뒤 명령은 아래 |
| merge_test, 1회 | 005 · 020 | 0 (162s) · 0 (902s) |
| 깨끗한 트리 2회 | 005 · 020 | 0 (145s) · 0 (1,034s) |
| 깨끗한 트리 3회 | 005 · 020 | 0 (171s) · 0 (1,009s) |
| main_gate | 029 | 0 (34s) |
| — | 017 | 0 (2s) |
- FE-GATE-005: 세 번 모두 test:unit 3,166개, coverage 4,102개 통과.
- FE-GATE-020: 세 번 모두 제거 drill 다섯이 실패 0(browser-file-storage 7, feature-scaffold 38, optional-recipe 6, realtime 7, sample-removal 목록 비어 SKIP).
- FE-GATE-013 뒤 명령: `verify:reproducible-build`·`build:release-candidate`·`verify:local-evidence`·`check:browser-security` 모두 0. tests/system은 115개 중 18개 실패, 97개 통과다. 실패는 모두 `candidate archive and provider upload boundaries`(bwrap)이고, 새 검사 위반은 0이다.
- FE-GATE-008·009(Playwright)는 돌리지 않았다. 이 PR은 Playwright가 쓰는 파일을 바꾸지 않는다.
### 결정적 재현
| 무엇 | 조건 | 고치기 전 | 고친 뒤 |
|---|---|---|---|
| 1번 timeout | CPU 10% 제한, app-build-input·registry-governance·hosting-probe·design-system-rules | main `650d22fa`: 11개 「Test timed out in 10000ms」 | 71개 통과, 가장 긴 시험 17.7초 |
| 2번 guardian | CPU 20% 제한, guardian 파일 5회 | main `d2239c67`: 5회 모두 1~6개 실패(가드 처리 중 deadline 지남 126, READY·PUBLISHED 대기 초과, EPIPE) | 5회 모두 22개 통과 |
| 3번 archive | 옆 프로세스가 `artifacts/tests`에 임시 파일 10개를 계속 만들고 rename | main `6b4f703c`: 3회 중 2회 FE-GATE-007과 같은 ENOENT(.tmp) | 3회 모두 통과 |
guardian 파일은 고친 뒤 평소 상태로 30회(load 3.6~21), CPU 20% 제한으로 5회 더 돌려 모두 통과했다.
### 검사의 검출력(변이)
- `tests/setup.ts`의 검사를 끄면 `tests/unit/child-process-timeout.test.ts`가 실패한다.
- `tests/unit/tracked-artifacts.test.ts` describe의 timeout을 지우면 그 시험이 검사 메시지로 실패한다.
- tests/system을 처음 돌렸을 때 검사가 기본 timeout으로 자식 프로세스를 띄우던 시험 셋(`ci-evidence-freshness` 둘, `provider-process-group` 하나)을 잡았다. 따로 세 번 재서 timeout을 줬다.
### 처음 최종 실행에서 고친 것
- near-deadline 시험의 「마지막 2초 안」 단언이 남은 2,001ms로 실패했다(FE-GATE-007). 타이머가 `Date.now()`보다 1ms 일찍 깼다. 목표 시각에 닿을 때까지 다시 기다리게 고쳐 2번 커밋에 합쳤다.
- 다음 실행에서 FE-GATE-007이 archive 시험의 ENOENT로 실패했다. 3번 커밋이다.
## 리뷰어가 볼 곳
- `tests/setup.ts`의 검사와 `tests/helpers/child-process-timeout.ts`, `tests/unit/child-process-timeout.test.ts`.
- `tests/integration/provider-guardian-transaction.test.ts`: lease 상수 셋, `sendGuard`의 반환값, near-deadline 시험.
- `tests/integration/security-followup-archive.test.ts`의 복사 filter.
- 나머지 시험 파일은 timeout 인자만 더했다. 인자의 ms는 desktop에서 잰 그 시험의 최대다.
## 관련
- 총괄 지시(2026-11-12), PR #18(이 문제가 처음 보인 곳), PR #15(문서 시험의 60초)
- `.claude/rules/tests.md` 9, `docs/work/reference/testing.md` 2·5절
자식 프로세스를 띄우는 Vitest 시험 91개(24파일)가 기본 timeout 10초에
기대고 있었다. 셋은 FE-GATE-013에서만 도는 tests/system 시험이다.
기본값은 프로세스 안에서 도는 시험에 맞춘 값이다. 부하가 높은
desktop에서는 자식 프로세스 시험이 평소보다 크게 느려진다.
FE-GATE-020 drill 사본에서 평소 0.4~1.2초인 문서 시험이 10.6초 걸려
실패했다(2026-11-12). 가장 위험한 것은 tests/architecture/app-build-input
.test.ts로, desktop에서 이미 5.7초까지 걸렸다.
무엇을 고칠지는 desktop 계측으로 정했다.
- test:coverage 묶음(maxWorkers=4)과 test:unit을 세 번씩 돌렸다. 시험마다
띄운 자식 프로세스는 child_process 함수를 감싸 기록했고, 소요 시간은
JSON reporter로 받았다.
- 시험마다 실제 timeout은 task.timeout으로 기록했다.
- 자식 프로세스를 띄우는 시험 140개 중 88개가 기본값이었다. tests/system은
그 묶음에 없어서, 아래 검사가 잡은 셋을 따로 세 번 쟀다.
고친 것:
- tests/helpers/child-process-timeout.ts의 childProcessTimeout(<잰 최대
ms>)는 그 15배를 30초 단위로 올린 값이다. 15배는 위 0.7초 → 10.6초에서
왔다. 시험마다 자기가 잰 최대값을 인자로 적어 근거가 호출 자리에 남는다.
- describe 안의 기본값 시험이 모두 자식 프로세스를 띄우면 describe에,
일부만 띄우면 그 시험에 준다. 프로세스 안에서 도는 시험의 hang을 늦게
잡지 않으려는 것이다.
- tests/setup.ts가 child_process 함수를 감싼다. 기본 timeout인 시험이
자식 프로세스를 띄우면 그 호출에서 실패시키고, helper 이름을 알린다.
helper나 시험이 import한 스크립트가 띄워도 잡는다. util.promisify가
읽는 속성은 원래 함수에서 옮긴다.
- docs/work/reference/testing.md 2절에 값 정하는 법과 이 검사를 적었다.
버린 것:
- 전역 testTimeout 올리기: 프로세스 안 시험의 hang을 늦게 잡는다.
- 시험마다 손으로 정한 숫자: 근거가 남지 않고, 이미 있는 값도
60_000·120_000처럼 근거가 없었다.
- 자식 프로세스를 띄우지 않게 바꾸기: 검사 스크립트를 CLI 그대로 시험하는
것이 이 시험들의 목적이라 범위가 커진다.
- 파일에 timeout 선언이 있는지만 보는 정적 검사: helper가 띄우는 경우와
같은 파일의 다른 시험을 놓친다.
위험:
- hook(beforeAll 등)에서 띄우는 프로세스는 검사하지 않는다. 계측에서
hook이 띄운 곳은 둘이고, 둘 다 180초를 선언했다.
- 같은 파일 안에서 it.concurrent로 도는 시험이 섞이면 어느 시험의
timeout인지 틀릴 수 있다. 지금은 그런 시험이 없다.
- 다운스트림 시험이 기본값으로 자식 프로세스를 띄우면 test:unit 등이
실패한다. 메시지가 helper를 알린다.
검증(desktop):
- 다섯 검사(test:unit·check:types·check:ci·lint·verify:documentation)
rc=0.
- 자식 프로세스를 띄우는 시험 파일 40개와 tests/scale: rc=0, 검사 위반 0.
- tests/system: 115개 중 18개 실패. 모두 bwrap 호스트 제약이고 검사
위반은 0이다.
- 변이: 검사를 끄면 tests/unit/child-process-timeout.test.ts가 실패한다.
tracked-artifacts describe의 timeout을 지우면 그 시험이 검사 메시지로
실패한다.
- 재현: CPU 10% 제한에서 app-build-input·registry-governance·hosting-probe
·design-system-rules를 돌렸다. main 650d22fa는 11개가 10초 timeout으로
실패했다. 이 커밋은 71개 모두 통과했고, 가장 긴 시험은 17.7초였다.
tests/integration/provider-guardian-transaction.test.ts가 부하 때 lease
만료로 실패한다. guardian이 스스로 SIGKILL한 것이다. desktop 기록 둘:
- FE-GATE-007: 「still publishes near the lease deadline」
- FE-GATE-020 drill: 「owns raw and sealed publication through the
authenticated client lease」
FE-B 실행에서도 load 28에 같은 실패가 2건 났다. 다시 돌리면 통과한다.
원인은 두 가지다.
- startProviderGuardian은 guardian을 띄우자마자 절대 deadline
(Date.now() + leaseMs)을 찍는다. 그래서 client 경로 시험의 2~3초
lease가 node 시작 시간까지 낸다. 부하 때 시작에는 상한이 없다.
- 직접 프로토콜 시험은 guardian이 load를 마친 뒤 가드를 보낸다
(c8620042). 그래도 가드 → READY 처리는 실제 시계로 돈다. desktop에서
CPU 25%로 제한하면 이 구간이 17ms에서 334ms로 늘어나, 350ms lease로
만료를 보는 시험의 여유가 거의 없다.
lease가 시험 대상인지로 나눠 고쳤다.
- lease가 대상이 아닌 15곳(client 경로 10, 직접 경로 5)은
LEASE_NOT_UNDER_TEST_MS다. 값은 시험 timeout과 같아서, lease가 시험보다
먼저 끝날 수 없다. guardian이 멈추면 시험 timeout이 잡는다.
- lease 만료를 보는 시험은 350ms → 2초다. 가드 → READY의 CPU 25% 최대
334ms의 여섯 배다.
- near-deadline 시험은 client 경로에서 직접 프로토콜로 옮겼다.
- deadline이 guardian load 뒤에 시작해서 시작 시간이 빠진다.
- sendGuard가 보낸 deadline을 돌려준다.
- 시험은 lease 4초의 마지막 2초 안에 publish·commit을 보내고, 그
구간에 있었는지 단언한다.
- 2초는 publish·commit의 CPU 25% 최대 104ms의 약 스무 배다.
- client의 publish·commit은 「owns raw and sealed publication」이 그대로
본다.
버린 것:
- guardian에 가짜 시계 주입: 운영 스크립트에 시험용 훅을 넣어야 한다
(c8620042와 같은 이유).
- client가 guardian load 뒤에 deadline을 찍게 바꾸기: 운영 프로토콜에
준비 신호를 더해야 한다. 이 PR 범위를 넘는다.
- 모든 lease를 늘리기: 만료와 near-deadline 시험은 lease가 대상이라
늘리면 보는 것이 흐려진다.
위험:
- 시험이 실패하면 guardian이 lease 끝까지(최대 30초) 남을 수 있다.
전에는 2~3초였다.
- near-deadline 시험에는 실제 시계 구간이 남는다. publish·commit이 2초를
넘으면 실패한다. 잰 최대의 약 스무 배다.
- 운영 client가 lease에 node 시작 시간을 포함하는 것은 그대로다. 운영
lease는 분 단위라 시험만큼 빠듯하지 않다.
검증(desktop):
- 이 파일을 10회 돌려 22개 모두 통과했다(load 3~4).
- CPU 20% 제한에서 main d2239c67은 5회 모두 1~6개 실패했다. 원인은 가드
처리 중 deadline 지남(126), READY·PUBLISHED 대기 시간 초과, EPIPE였다.
같은 조건에서 이 커밋은 5회 모두 통과했다.
- 시험 timeout은 잰 최대로 고쳤다. near-deadline 3.2초, 만료 2.1초.
- 첫 최종 실행에서 FE-GATE-007이 near-deadline 시험의 「마지막 2초 안」
단언으로 실패했다(남은 2,001ms). 타이머가 Date.now()보다 1ms 일찍 깼다.
목표 시각에 닿을 때까지 다시 기다리게 고쳤다. 고친 뒤 이
파일을 30회(load 3.6~21), CPU 20% 제한으로 5회 돌려 모두 통과했다.
tests/integration/security-followup-archive.test.ts는 후보 빌드에 쓸
증거를 얻으려고 checkout의 artifacts/를 통째로 사본에 복사한다. 같은
integration 실행에서 tests/integration/http-scenario-catalog.test.ts가
artifacts/tests/http-scenario-executions.json을 임시 파일에 쓰고
rename한다. 복사가 목록을 읽은 뒤 그 임시 파일이 rename되면 ENOENT로
실패한다. desktop FE-GATE-007(2026-11-12, load 9)에서 났다.
복사 filter가 원자적 쓰기의 임시 파일(.<이름>.<무작위>.tmp)을 건너뛴다.
그런 파일은 쓰는 중이라 증거가 아니다. fs.cp는 filter를 stat보다 먼저
부르므로, 건너뛴 파일은 사라져도 오류가 없다.
버린 것:
- 필요한 증거 경로만 복사: 공급망 생성이 추적 파일(artifacts의 .gitkeep
포함)을 모두 lstat하고 build가 읽는 증거가 여러 곳이라, 목록을 따로
관리해야 한다.
- 두 시험을 같이 돌지 않게 하기: integration 층 전체를 직렬로 돌려야 한다.
위험: 임시 파일이 아닌 파일을 다른 시험이 지우는 경합은 남는다. 지금
artifacts/ 아래에서 그렇게 하는 시험은 찾지 못했다.
검증(desktop):
- 다른 프로세스가 artifacts/tests에 임시 파일 10개를 계속 만들고
rename하는 동안 이 시험을 돌렸다. main 6b4f703c는 3회 중 2회가 같은
ENOENT(.tmp)로 실패했고, 이 커밋은 3회 모두 통과했다.
- test:unit, check:types, check:ci, lint, verify:documentation.
정리 단계 절에 이 브랜치의 범위를 넣었다. 먼저 할 일 17을 더했다:
기본 timeout인 Vitest 시험이 자식 프로세스를 띄우면 실패하니,
다운스트림은 자기 시험에 childProcessTimeout(<잰 ms>)을 준다. 옮긴 뒤
확인 1에는 test:integration과 17단계를 더했다. 계약 표 한 줄과, 그 밖의
수정에 guardian lease 고침과 archive 시험의 임시 파일 경합 고침을
한 줄씩 적었다.
검증(desktop): verify:documentation, test:unit.
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
무엇을, 왜
부하가 높은 desktop에서 시험이 가끔 떨어진다. 총괄 지시로 두 가지를 고치고, 검증 중 찾은 하나를 더 고친다.
tests/unit/documentation-readiness.test.ts가 FE-GATE-020 drill 사본에서 기본 timeout 10초를 넘겼다. 평소 0.4~1.2초인 시험이 10.6초 걸렸다. 같은 모양의 시험을 repo 전체에서 찾았다. 그 결과 자식 프로세스를 띄우면서 기본 10초에 기대는 Vitest 시험이 91개(24파일) 나왔다. 가장 위험한tests/architecture/app-build-input.test.ts는 평소에도 5.7초까지 걸렸다. 문서 시험 자체에는 PR #15가 이미 60초를 줬다.tests/integration/provider-guardian-transaction.test.ts에서 guardian이 lease 만료로 스스로 SIGKILL한다. FE-GATE-007·020에서 났고 FE-B 실행에서는 load 28에 2건 났다. 다시 돌리면 통과한다.tests/integration/security-followup-archive.test.ts가artifacts/를 복사하는 동안, 다른 시험이 쓰던 임시 파일이 rename되어 ENOENT가 났다.고른 방법과 버린 대안
커밋 넷이다. 커밋마다 desktop에서 test:unit·check:types·check:ci·lint·verify:documentation을 돌렸다(아래 검증).
91962e24자식 프로세스 시험이 잰 시간으로 timeout을 정한다.child_process함수를 감싸 기록했고, 소요 시간은 JSON reporter로 받았다.task.timeout으로 받았다.tests/helpers/child-process-timeout.ts의childProcessTimeout(<잰 최대 ms>)가 timeout을 정한다.tests/setup.ts가child_process함수를 감싼다.util.promisify가 읽는 속성은 원래 함수에서 옮긴다.tests/unit/child-process-timeout.test.ts다.docs/work/reference/testing.md2절에 값 정하는 법과 이 검사를 적었다.77c01b03guardian 시험의 lease가 시험 대상이 아니면 시험 timeout만큼 준다.startProviderGuardian은 guardian을 띄우자마자 절대 deadline을 찍는다. 그래서 client 경로 시험의 2~3초 lease가 node 시작 시간까지 낸다.c8620042). 그래도 가드 → READY 처리는 실제 시계로 돈다. desktop CPU 25% 제한에서 이 구간이 17ms에서 334ms로 늘었다. 350ms lease로 만료를 보는 시험은 여유가 거의 없다.LEASE_NOT_UNDER_TEST_MS다.sendGuard가 보낸 deadline을 돌려준다.db4c632darchive 시험이 다른 시험이 쓰는 중인 임시 파일을 복사하지 않는다.tests/integration/http-scenario-catalog.test.ts가artifacts/tests/http-scenario-executions.json을 임시 파일에 쓰고 rename한다..<이름>.<무작위>.tmp)을 건너뛴다.fs.cp는 filter를 stat보다 먼저 부르므로, 건너뛴 파일은 사라져도 오류가 없다..gitkeep까지 추적 파일을 모두 lstat하고 build가 읽는 증거가 여러 곳이라 목록을 따로 관리해야 한다), 두 시험을 직렬로 돌리기(integration 층 전체가 느려진다).a593feb2CHANGELOG 정리 단계 절: 범위, 먼저 할 일 17, 옮긴 뒤 확인 1, 계약 표 한 줄, 그 밖의 수정 두 줄.위험과 영향
beforeAll등)에서 띄우는 프로세스는 보지 않는다. 계측에서 hook이 띄운 곳은 둘이고, 둘 다 180초를 선언했다.tests/setup.ts를 쓰지 않는다.it.concurrent로 도는 시험이 섞이면 어느 시험의 timeout인지 틀릴 수 있다. 지금은 그런 시험이 없다.artifacts/아래에서 그렇게 하는 시험은 찾지 못했다.검증
모두 desktop에서 돌렸다. workflow env(
CI=true, 40자리VITE_COMMIT_SHA,VITE_BUILD_ID,RELEASE_ID,CI_RUNNER_IMAGEdigest)를 썼고, job마다 깨끗한 트리에서 설치를 한 번 하고 게이트를 차례로corepack pnpm ci:gate <ID>로 돌렸다. 로그는 desktop/tmp/claude-gates/아래에 있다. 계측은fea-m1·fea-m2·fea-m3·fea-gp, 재현은fea-t2·fea-gg·fea-gg2·fea-ar2, 최종은fea-f3이다.판정(
docs/work/reference/gates.md3절): merge 단계 중 FE-GATE-013 밖 전부 통과, FE-GATE-013은 desktop 호스트 제약(user namespace)이라 판정에서 뺌(뒤 명령 결과 첨부, 모두 rc=0). FE-GATE-005·020은 깨끗한 트리에서 3회 연속 통과했다.커밋별(fea-f3, 2026-11-12 11:49~11:55)
다섯 검사(test:unit, check:types, check:ci, lint, verify:documentation)가 네 커밋 모두 rc=0이다.
91962e2477c01b03db4c632da593feb2게이트 — 끝 커밋
a593feb2(fea-f3, 11:5512:57, load 526)verify:reproducible-build·build:release-candidate·verify:local-evidence·check:browser-security모두 0. tests/system은 115개 중 18개 실패, 97개 통과다. 실패는 모두candidate archive and provider upload boundaries(bwrap)이고, 새 검사 위반은 0이다.결정적 재현
650d22fa: 11개 「Test timed out in 10000ms」d2239c67: 5회 모두 1~6개 실패(가드 처리 중 deadline 지남 126, READY·PUBLISHED 대기 초과, EPIPE)artifacts/tests에 임시 파일 10개를 계속 만들고 rename6b4f703c: 3회 중 2회 FE-GATE-007과 같은 ENOENT(.tmp)guardian 파일은 고친 뒤 평소 상태로 30회(load 3.6~21), CPU 20% 제한으로 5회 더 돌려 모두 통과했다.
검사의 검출력(변이)
tests/setup.ts의 검사를 끄면tests/unit/child-process-timeout.test.ts가 실패한다.tests/unit/tracked-artifacts.test.tsdescribe의 timeout을 지우면 그 시험이 검사 메시지로 실패한다.ci-evidence-freshness둘,provider-process-group하나)을 잡았다. 따로 세 번 재서 timeout을 줬다.처음 최종 실행에서 고친 것
Date.now()보다 1ms 일찍 깼다. 목표 시각에 닿을 때까지 다시 기다리게 고쳐 2번 커밋에 합쳤다.리뷰어가 볼 곳
tests/setup.ts의 검사와tests/helpers/child-process-timeout.ts,tests/unit/child-process-timeout.test.ts.tests/integration/provider-guardian-transaction.test.ts: lease 상수 셋,sendGuard의 반환값, near-deadline 시험.tests/integration/security-followup-archive.test.ts의 복사 filter.관련
.claude/rules/tests.md9,docs/work/reference/testing.md2·5절