@uzysjung/agent-harness 26.177.0 → 26.179.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -17,7 +17,7 @@ import {
17
17
  init_esm_shims,
18
18
  residentCost,
19
19
  resolveBundleRoot
20
- } from "./chunk-JIVFWRYB.js";
20
+ } from "./chunk-LRPCXEUU.js";
21
21
 
22
22
  // src/trust-tier-drift.ts
23
23
  init_esm_shims();
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@uzysjung/agent-harness",
3
- "version": "26.177.0",
3
+ "version": "26.179.0",
4
4
  "description": "Curate vetted AI-coding skills & plugins by your tech stack — install only what you need, across Claude Code, Codex, OpenCode & Antigravity",
5
5
  "type": "module",
6
6
  "publishConfig": {
@@ -2,7 +2,7 @@
2
2
 
3
3
  무엇으로 검증할지는 이 저장소가 정한다. **어느 정도까지**는 Testing 룰이, 그 결과가 **언제** 있어야 하는지는 이 룰이 정한다.
4
4
 
5
- - **검증의 리듬**: 구현 중에는 변경 부분의 빠른 검사만 한다. 사용자 씬의 수정분이 모였을 때가 독립 검토를 **판단하는** 시점이다 — 걸지는 아래 머지 전 기준으로 정한다. 수정이 끝난 뒤 통합 테스트 · 빌드 · 실제 사용자 흐름을 검증한다. 작은 수정마다 전체 검증을 반복하지 않고, 재검사는 영향받은 부분만 한다. 계획·위임문에 적었다는 것만으로는 검증을 넓히지 않는다.
5
+ - **검증의 리듬**: 구현 중에는 변경 부분의 빠른 검사만 한다. 사용자 씬의 수정분이 모였을 때가 독립 검토를 **판단하는** 시점이다 — 걸지는 아래 머지 전 기준으로 정한다. 수정이 끝난 뒤 영향받은 통합 테스트 · 빌드 · 바뀐 사용자 흐름을 검증한다(전체 스위트 · 전체 E2E 는 배포 몫). 작은 수정마다 전체 검증을 반복하지 않고, 재검사는 영향받은 부분만 한다. 계획·위임문에 적었다는 것만으로는 검증을 넓히지 않는다.
6
6
  - **머지 전 독립 검증**은 핵심 사용자 기능 · 되돌리기 어려운 변경 · 돈·권한처럼 틀리면 큰 사고인 것에만 건다. UX 의 큰 변경은 사용자 페르소나 리뷰(선택). 그 밖(테스트 하네스 · 문서 · 리팩터 · 문구 · UI · 리뷰어 처방)은 리그레션 테스트로 들어온다. 독립 검증의 판정은 만든 쪽이 아니라 검증자가 요구사항·변경분·결과를 직접 확인하고 내린다. 어느 쪽이든 변경 위험에 맞는 검증을 **실행하고 결과를 확인한다** — high risk 는 더 많은 증거를 갖고 들어오고, **실행하지 않은 상태는 통과가 아니다.** 필수 보안 · 데이터 보호 검사는 유지한다.
7
7
  - **배포**: 배포 전에 풀 테스트 · E2E 를 거친다(Testing 룰의 CI/CD 일정 몫). 독립 검증은 **단계가 아니라** 머지 전과 같은 기준(영향 · 불확실성 · 복구 비용 · 이미 있는 증거)으로 판단한다 — 배포라는 이유로 다시 걸지 않는다. 머지 전에 검증된 것과 **같은 artifact** 를 내보내고, 배포 뒤 실제 환경에서 smoke · health · 핵심 기능을 확인한다.
8
8
  - **머지·게시 경로가 위 기준대로 고른 검증과 저장소의 필수 체크 통과에 의존해야 한다.** 별개 경로면 아무도 우회하려 하지 않았는데 red 가 그대로 나간다. 의존하지 않는 상태를 발견하면 경로를 고치기 전에 먼저 보고한다.
@@ -3,10 +3,12 @@
3
3
  **How far** to verify scales with the risk of the change; **when** those results must exist
4
4
  belongs to the Delivery rule.
5
5
 
6
- - An ordinary change gets static checks and regression across the affected scope — not the whole
7
- suite merely because the repository's CI runs it; independent verification only where the
8
- Delivery rule requires it. A high-risk one widens that in proportion to what it touches and what
9
- its failure would cost.
6
+ - **Before running tests, name the affected scope** — what changed and which tests exercise it,
7
+ including the callers, data, and configuration it shares — and run that with static checks.
8
+ Widen only for a reason you can name: shared code or configuration changed, the scope cannot be
9
+ established (widen along what it shares, not to the whole suite), or a high-risk area below, in
10
+ proportion to what it touches and what failure would cost. Independent verification only where
11
+ the Delivery rule requires it.
10
12
  - Preserve required outcomes with the least burdensome reliable protection.
11
13
  Prefer fixing the cause and reusing or improving existing mechanisms within scope;
12
14
  no new guard is needed when those suffice. Judge safeguards by credible risk,
@@ -20,7 +22,7 @@ belongs to the Delivery rule.
20
22
  - High-risk includes at least authentication, authorization, payments and settlement, personal
21
23
  data, data integrity, concurrency, state transitions, and migrations.
22
24
  - Full regression, full E2E, full mutation, and periodic security scanning belong to the CI/CD
23
- schedule, not to a per-change decision.
25
+ schedule and the release step. For an ordinary change, ask before running them.
24
26
  - For a high-risk change, cover normal, boundary, failure, misuse, and recovery paths,
25
27
  omitting one only when failure on it is not plausible.
26
28
  - Use production-compatible dependencies when a substitute's behavioral differences could affect
@@ -30,6 +32,4 @@ belongs to the Delivery rule.
30
32
  adding indiscriminate retries. Correct or consolidate tests when their expectations are
31
33
  wrong, obsolete, or redundant; preserve coverage of the accepted contract and follow project
32
34
  policy for changes to mandatory gates.
33
- - If the affected scope cannot be established confidently, widen along what the change shares
34
- (callers, data, configuration), not to the whole suite by default. After an environment or CI
35
- fix, rerun what failed and what the fix could affect.
35
+ - After an environment or CI fix, rerun what failed and what the fix could affect.
@@ -2,7 +2,7 @@
2
2
  "_comment": "프로젝트 .claude/settings.json 템플릿. $CLAUDE_PROJECT_DIR 사용으로 절대 경로 제거. committable. 글로벌 ~/.claude/settings.json은 절대 건드리지 않음.",
3
3
  "statusLine": {
4
4
  "type": "command",
5
- "command": "npx -y @owloops/claude-powerline@1.32.1 --style=tui"
5
+ "command": "npx -y @owloops/claude-powerline@1.32.5 --style=tui"
6
6
  },
7
7
  "hooks": {
8
8
  "SessionStart": [
@@ -17,18 +17,18 @@ description: 한국어 답변·글쓰기·번역·퇴고에 사용한다. 뜻과
17
17
 
18
18
  1. **독자에게 익숙한 말을 쓴다.** 전문용어의 뜻은 보존하되, 설명문에서는 ‘스킬·규칙·프롬프트’처럼 익숙한 표기를 우선한다. 제품명·식별자·통용 약어는 유지한다. 낯선 용어는 필요할 때 짧게 설명하고, 원어 병기는 구분에 필요한 경우만 한다. 뜻이 불분명한 용어를 짐작으로 풀지 않는다.
19
19
  2. **누가 무엇을 하는지 분명히 쓴다.** 명사를 길게 잇기보다 동사로 직접 표현한다. 불필요한 대명사·명사화·간접 표현을 덜되, 주체와 논리관계는 남긴다. 긴 문장은 필요할 때 나누고, 짧게 쓰려고 조사·어미·필요한 설명을 빼지 않는다.
20
- 3. **반복과 군더더기를 줄인다.** 내용에 보탬이 없는 칭찬·예고·과장·결론 반복은 덜어낸다. 접속사·완곡 표현·같은 문형도 문맥상 불필요하거나 반복이 거슬릴 때만 고친다. 반복을 피하려고 같은 개념의 용어를 바꾸지는 않는다.
20
+ 3. **반복과 군더더기를 줄인다.** 내용에 보탬이 없는 칭찬·예고·과장·결론 반복은 덜어낸다. 접속사·완곡 표현·같은 문형도 문맥상 불필요하거나 반복이 거슬릴 때만 고친다. 반복을 피하려고 같은 개념의 용어를 바꾸지는 않는다. 연결어미(‘-고’, ‘-며’, ‘-지만’)와 ‘그리고·그러나’ 같은 접속어 뒤에 습관처럼 쉼표를 찍지 않는다. 끊어 읽지 않으면 뜻이 헷갈릴 때만 쓴다.
21
21
  4. **형식은 이해를 돕는 데 쓴다.** 비교·절차·기술 문서에 필요한 표·목록·제목은 살린다. 장식용 강조와 반복되는 문단 틀만 줄인다. 문장마다 줄을 바꾸거나, 모든 목록을 산문으로 만들거나, 문장 길이와 종결어미를 억지로 다양하게 만들지 않는다.
22
22
  5. **관용구는 어울릴 때만 쓴다.** ‘첫발을 떼다’, ‘손이 많이 가다’처럼 익숙한 표현도 뜻과 상황에 맞을 때 쓴다. 더 쉽게 전달되지 않으면 평이하게 쓴다. 사람처럼 보이려고 감탄·반문·유행어·꾸며 낸 경험을 넣지 않는다.
23
23
  6. **표현 하나만으로 문제 삼지 않는다.** ‘~를 통해’, ‘~할 수 있다’, 피동문·격식체·영어 자체는 수정 사유가 아니다. 문맥·반복·독자·목적을 기준으로 판단하고, 이미 자연스러운 문장은 그대로 둔다.
24
24
 
25
25
  ## 퇴고와 확인
26
26
 
27
- 의미 전달을 방해하는 구문부터 고치고, 반복과 군더더기는 그다음에 다듬는다. 표현·문장 단위로 고치되, 문제 해결에 필요하면 문장을 나누거나 문단을 조정한다. 단순한 취향 차이는 수정 사유로 삼지 않는다.
27
+ 의미 전달을 방해하는 구문부터 고치고, 반복과 군더더기는 그다음에 다듬는다. 표현·문장 단위로 고치되, 문제 해결에 필요하면 문장을 나누거나 문단을 조정한다. 고칠 이유를 한 문장으로 댈 수 없으면 고치지 않는다. 취향 차이는 이유가 아니다.
28
28
 
29
29
  원문이 있으면 결과와 대조한다. 정보·주장·수치·주체·인과·조건·부정·가능성·의무·현재 상태가 달라지지 않았는지 확인한다. 요청 없이 새 주장·근거·감정·비유를 보태지 않는다. 사실 오류를 발견하면 문체 수정과 구분해 알린다.
30
30
 
31
- 고유명사·직접 인용·코드·명령어·경로·옵션값·링크 주소는 별도 요청 없이 바꾸지 않는다. 의미가 달라진 수정만 되돌리거나 바로잡고, 새로운 반복과 마크다운 깨짐이 없는지 확인한다.
31
+ 고유명사·직접 인용·코드·명령어·경로·옵션값·링크 주소는 별도 요청 없이 바꾸지 않는다. 의미가 달라진 수정만 되돌리거나 바로잡고, 새로 생긴 반복·상투구·굵은 글씨·목록과 마크다운 깨짐이 없는지, 원문보다 눈에 띄게 길어지거나 말투 등급(합쇼체·해요체·한다체)이 바뀌지 않았는지 확인한다.
32
32
 
33
33
  ## 예시
34
34
 
@@ -37,6 +37,7 @@ description: 한국어 답변·글쓰기·번역·퇴고에 사용한다. 뜻과
37
37
  - “skill과 rule을 적용한다.” → “스킬과 규칙을 적용한다.” (설명문)
38
38
  - “해당 문제에 대한 검토를 수행합니다.” → “그 문제를 검토합니다.”
39
39
  - “프로젝트의 첫 번째 발걸음을 취했다.” → “프로젝트의 첫발을 뗐다.”
40
+ - “설정을 바꾸고, 다시 실행한다.” → “설정을 바꾸고 다시 실행한다.”
40
41
  - “예약이 취소되었습니다.” / “효과가 있을 수 있습니다.” → 그대로 둔다.
41
42
  - “하네스로 작동한다.” → “하네스를 목표로 한다.”로 바꾸지 않는다. 현재 상태를 목표로 바꾸면 뜻이 달라진다.
42
43
 
@@ -61,28 +61,28 @@ jobs:
61
61
 
62
62
  전 잡에 적용해야 한다. 하나라도 빠뜨리면 그 잡만 호스티드를 기다리다 영원히 큐에 남는다.
63
63
 
64
- ## Step 2 — 아키텍처를 **재고 나서** 정한다
64
+ ## Step 2 — Mac 에서는 네이티브 arm64 로 띄우고, 실제 실행으로 확인한다
65
65
 
66
- self-hosted 머신이 Apple Silicon 이면 arm64 다. 워크플로가 `ubuntu-latest`(x64)를 전제하고 쓴
67
- 것들이 여기서 깨진다. 두 선택지가 있고, **추측하지 말고 재라**:
66
+ Apple Silicon Mac 에서 amd64 컨테이너는 에뮬레이션으로 돈다. 같은 잡이 이만큼 차이 난다:
68
67
 
69
- ```bash
70
- for P in linux/arm64 linux/amd64; do
71
- docker run --rm --platform $P node:22-bookworm-slim node -e "
72
- const s=Date.now(); let h=0; for(let i=0;i<8e6;i++){h=(h*31+i)>>>0;}
73
- console.log('$P ms='+(Date.now()-s));"
74
- done
75
- ```
68
+ | 실측(M-series) | linux/arm64 | linux/amd64 |
69
+ |---|---|---|
70
+ | 정수 루프 마이크로벤치(Docker Desktop) | 127ms | 497ms |
71
+ | 실제 CI `checks` 잡 — npm ci · typecheck · lint · 테스트 685개(OrbStack, 2026-10-30) | **55~100초**(3회) | 3분 35초 |
76
72
 
77
- 실측 사례(M-series, Docker Desktop): arm64 **127ms** vs amd64 **497ms** — 에뮬레이션이 3.9배 느렸다.
73
+ 그래서 [`scripts/runner.sh`](scripts/runner.sh) 는 **호스트 아키텍처를 기본값**으로 쓴다(Apple
74
+ Silicon → `linux/arm64`). 다만 속도는 **의존성이 그 아키텍처에서 실제로 도는 다음**의 기준이다 —
75
+ 네이티브 모듈 하나만 prebuild 가 없어도 스위트가 통째로 죽는다. 그 확인을 추측이나 벤치마크가
76
+ 아니라 **실제 워크플로 1회**로 한다:
78
77
 
79
- **그런데 이 숫자로 고르지 마라.** 나도 이걸 보고 arm64 를 골랐다가 되돌렸다. 속도는 **의존성이
80
- 그 아키텍처에서 실제로 도는 다음**의 기준이다 — 돌지 않는 것이 빠를 수는 없다. 네이티브 모듈
81
- 하나만 prebuild 가 없어도 테스트 스위트가 통째로 죽는다.
78
+ - 첫 실행에서 설치·빌드·테스트가 통과하면 arm64 를 계속 쓴다. 위 실측 레포가 이 경우다.
79
+ - 네이티브 모듈·바이너리 실패가 나오면 코드 결함으로 읽기 전에 **같은 커밋을 `PLATFORM=linux/amd64`
80
+ 로 한 번 더 돌려 대조한다.** amd64 에서만 통과하면 아키텍처 문제다(아래 함정들). 대조 없이 고치기
81
+ 시작하면 "CI 환경이 달라서인가"를 끝내 지우지 못한다.
82
+ - **amd64 로 고정하는 경우**: 워크플로가 amd64 전용 바이너리를 받거나, 이 실행이 배포 산출물을
83
+ 만든다(산출물이 `ubuntu-latest` 의 것과 같아야 한다).
82
84
 
83
- **기본값은 `ubuntu-latest` 와 같은 amd64 로 두고**, arm64 는 "이 레포의 네이티브 의존성이 arm64
84
- prebuild 를 갖고 있다"를 확인한 뒤에 성능 최적화로 택하라. 아키텍처를 맞춰 두면 실패했을 때
85
- "CI 환경이 달라서인가"를 먼저 의심하지 않아도 된다 — 그 의심을 지우는 값이 3.9배보다 크다.
85
+ 보고에는 어느 아키텍처에서 돌았는지 적는다(§보고할 때).
86
86
 
87
87
  ### 흔히 깨지는 것: 아키텍처 하드코딩된 도구 설치
88
88
 
@@ -164,28 +164,40 @@ npm 캐시인가"로 몇 시간 쫓다가 결국 `ldd` 한 줄로 끝냈다.
164
164
  docker run --rm --entrypoint sh <이미지> -c 'grep PRETTY_NAME /etc/os-release; ldd --version | head -1'
165
165
  ```
166
166
 
167
- 띄우기·내리기·상태확인을 스크립트 하나로 묶어 두면 원복(Step 5)까지 한 곳에 남는다. 핵심은 이것이다:
167
+ 띄우기·내리기·상태 확인은 함께 들어 있는 스크립트 하나가 한다. 레포 루트에서 실행한다:
168
168
 
169
169
  ```bash
170
- TOKEN=$(gh api -X POST /repos/<owner>/<repo>/actions/runners/registration-token --jq .token)
171
-
172
- ENVFILE=$(mktemp); chmod 600 "$ENVFILE"
173
- cat > "$ENVFILE" <<EOF
174
- REPO_URL=https://github.com/<owner>/<repo>
175
- RUNNER_NAME=local-docker
176
- RUNNER_TOKEN=$TOKEN
177
- RUNNER_WORKDIR=/tmp/runner/work
178
- LABELS=<고유 라벨>
179
- EPHEMERAL=true
180
- EOF
181
-
182
- docker run -d --name ci-runner --env-file "$ENVFILE" \
183
- -v ci-runner-work:/tmp/runner myoung34/github-runner:latest
184
- rm -f "$ENVFILE"
185
-
186
- gh variable set CI_RUNNER_LABEL --body '<고유 라벨>' --repo <owner>/<repo>
170
+ bash <이 스킬 폴더>/scripts/runner.sh up --jobs 2 # 러너가 뜬 뒤 변수 설정 + 잡 2개를 차례로 처리
171
+ bash <이 스킬 폴더>/scripts/runner.sh status
172
+ bash <이 스킬 폴더>/scripts/runner.sh down # 원복(Step 5)
187
173
  ```
188
174
 
175
+ **`up` 은 N 개 잡이 끝날 때까지 터미널을 붙잡는다.** 백그라운드나 별도 셸에서 띄우고, `runner 1/N
176
+ listening` 이 찍힌 **뒤에** `gh run rerun` · `gh workflow run` 을 실행한다 — 변수는 그때 설정되므로,
177
+ 먼저 재실행하면 잡이 다시 호스티드로 가서 실패하고 `up` 은 오지 않을 잡을 기다린다. `up` 이 끝난 뒤
178
+ `down` 한다.
179
+
180
+ `<이 스킬 폴더>` 를 빼고 `scripts/runner.sh` 로 부르지 마라 — 레포 루트에서는 그 레포 자신의
181
+ `scripts/` 를 가리킨다. 스크립트가 출력하는 원복 명령은 자기 경로를 그대로 쓴다.
182
+
183
+ 기본값은 이렇다 — 레포는 `gh repo view`, 라벨은 `<레포 이름>-local`, 이미지는
184
+ `myoung34/github-runner:ubuntu-noble`(24.04), 아키텍처는 호스트 하드웨어 것(Rosetta 셸에서도 arm64).
185
+ `REPO` · `LABEL` · `IMAGE` · `PLATFORM` 환경변수로 바꾼다. 기본 라벨·이름은 이 레포에서 스크립트를
186
+ 쓰는 모든 사람에게 같으므로, 두 사람이 동시에 띄우지 말거나 서로 다른 `LABEL` 을 쓴다. 이럴 때는 아무것도 바꾸지 않고 멈춘다:
187
+ private 이 아닌 레포(public · internal) · fork PR 워크플로가 켜진 private 레포 · `CI_RUNNER_LABEL` 에 남의 값이 이미 있음 · 다른 이름의 러너가 이미 같은 라벨을 달고 있음(대소문자 무시 — 상시 러너의 라벨을 `LABEL` 로 빌려 쓰지 마라) · GitHub 상태를 읽지 못함(인증·네트워크 —
188
+ "없음"으로 읽지 않는다) · 러너가 뜨지 않음(변수는 러너가 `Listening for Jobs` 를 찍은 뒤에야 설정한다).
189
+ 스크립트는 아래 세 기본값을 그대로 구현한다 — 손으로 띄울 때도 같은 이유로 지킨다.
190
+
191
+ ### Mac 호스트에서 알아 둘 것
192
+
193
+ - OrbStack 에서 실측했다(2026-10-30). Docker Desktop · Colima 는 이 스크립트로 아직 돌려 보지 않았다.
194
+ 토큰 파일을 `$HOME` 아래에 만들어 마운트하므로, 엔진이 홈 디렉터리를 공유해야 한다(원격
195
+ `DOCKER_HOST` · 원격 context 는 안 된다). 자원은 §자원.
196
+ - 이미지를 받을 때 macOS 가 **키체인 접근 허용**을 물을 수 있다. `~/.docker/config.json` 의
197
+ `"credsStore": "osxkeychain"` 때문에 Docker CLI 가 레지스트리 자격증명을 키체인에서 찾는 것이다 —
198
+ OrbStack·러너 문제가 아니다. 거부하면 공개 이미지도 받기가 실패할 수 있다. 전역 Docker 설정이므로
199
+ 바꿀지는 사용자가 정한다.
200
+
189
201
  ### 안전한 기본값 세 가지 — 하나씩 이유가 있다
190
202
 
191
203
  **1. 라벨에 `self-hosted` 를 쓰지 마라.** GitHub 이 **모든** self-hosted 러너에 자동으로 붙이는
@@ -195,9 +207,26 @@ gh variable set CI_RUNNER_LABEL --body '<고유 라벨>' --repo <owner>/<repo>
195
207
  **2. `EPHEMERAL=true`.** 비-ephemeral 러너는 잡 사이에 작업 디렉터리와 프로세스 상태가 남는다 —
196
208
  한 잡이 심어 놓은 것이 다음 잡에서 실행된다(러너 오염). ephemeral 이면 잡 하나를 처리하고
197
209
  등록을 스스로 해제한다. **다음 잡을 돌리려면 다시 띄워야 해서 불편한데, 그 불편이 곧 격리다.**
198
-
199
- **3. 등록 토큰을 `-e` 로 넘기지 마라.** `docker inspect` 에 평문으로 남는다. 600 권한 임시 파일로
200
- 넘기고 곧바로 지운다. 토큰 자체는 1시간 유효·등록 시 1회 소비지만, 그 사이에 남길 이유가 없다.
210
+ 잡이 여럿인 워크플로(`checks` → `ci-gate` 처럼 `needs:` 로 이어진 것)는 `--jobs N` 으로 그 수만큼
211
+ 차례로 다시 띄운다. N 은 이 이벤트가 **실제로 돌릴** 잡 수다 — matrix 다리는 하나씩 세고, `if:` 로
212
+ 건너뛰는 잡은 세지 않는다. 많이 세면 `up` 이 마지막 잡을 영영 기다리고, 적게 세면 남은 잡이 큐에
213
+ 머문다. 중간에 Ctrl-C 로 끊었으면 `down` 을 실행한다(스크립트가 그 명령을 출력한다).
214
+
215
+ **3. 등록 토큰을 컨테이너 환경 설정에 넣지 마라.** `-e` 든 `--env-file` 이든 Docker 데몬에는 같은
216
+ `Config.Env` 로 가서 `docker inspect` 에 평문으로 남는다 — `--env-file` 은 명령줄·셸 기록만 피한다.
217
+ 스크립트는 토큰을 600 권한 파일에 쓰고 **읽기 전용 마운트**로 넘긴 뒤, 엔트리포인트 앞에서 그 파일을
218
+ 읽어 환경변수로 바꾸고, 러너가 등록되면 파일을 지운다(실측 2026-10-30: `docker inspect` 의 env 에
219
+ `RUNNER_TOKEN` 없음). 컨테이너 안에서 root 로 도는 잡 코드는 여전히 프로세스 환경에서 토큰을 읽을 수
220
+ 있다 — 그래서 ephemeral 과 짧은 수명이 함께 필요하다. 러너가 등록되면 파일을 **비운 뒤** 지운다 — 리눅스 Docker 엔진의 파일 bind mount 는 inode 를 쥐고
221
+ 있어서, 지우기만 하면 컨테이너 안에서는 그대로 읽힌다(OrbStack 은 지우는 것만으로 안에서도
222
+ 사라졌다 — 2026-10-30 대조 실측). 토큰은 1시간 동안 유효하고 그 안에 다른 러너를 등록하는 데
223
+ 쓰일 수 있다고 보고 다룬다. 그래서 `up` 은 시작할 때 다른 러너가 그 라벨을 달고 있지 않음을 확인하고
224
+ 이 머신에 "이 레포에서 이 라벨을 쓴다"는 기록을 남긴다(`${XDG_STATE_HOME:-~/.local/state}/self-hosted-github-runner/`,
225
+ 프로젝트 폴더 밖). `down` 은 우리 이름의 러너를 늘 등록 해제하고, **그 기록이 있을 때만** 같은 라벨을 단
226
+ 다른 이름의 러너까지 등록 해제하고 `CI_RUNNER_LABEL` 을 지운 뒤 기록을 지운다. 기록이 없으면 그런 러너와
227
+ 변수는 알리기만 하고 남긴다 — 그 라벨이 설치자의 상시 러너 것일 수 있어서다. 그래서 `up` 이 남의 러너
228
+ 때문에 거부하면 `down` 이 아니라 **다른 `LABEL`** 로 다시 띄운다(이 머신의 앞선 `up` 이 남긴 러너일 때만
229
+ `up` 이 `down` 을 권한다).
201
230
 
202
231
  ### `services:` 를 쓸 때만 docker.sock 을 붙인다 — 기본은 끈다
203
232
 
@@ -206,7 +235,7 @@ gh variable set CI_RUNNER_LABEL --body '<고유 라벨>' --repo <owner>/<repo>
206
235
 
207
236
  **이건 사실상 호스트 장악 권한이다** — 그 소켓에 닿는 코드는 호스트 파일시스템을 마운트한 root
208
237
  컨테이너를 띄울 수 있다. 필요 없는 잡까지 이 권한 아래 돌리지 마라. 워크플로에 `services:` 가
209
- 없으면 **빼라.**
238
+ 없으면 **빼라.** 스크립트는 `--docker` 를 줄 때만 붙인다.
210
239
 
211
240
  **소켓만 주면 반쯤만 동작한다 — `--network host` 가 같이 필요하다.** 러너가 컨테이너 안이면
212
241
  서비스 컨테이너는 **호스트 포트**에 게시되는데, 워크플로는 `localhost:5432` 를 본다. GitHub
@@ -235,6 +264,8 @@ docker rm -f probe
235
264
  의존성에 대한 것이 아니다.
236
265
 
237
266
  public 레포면 **하지 마라.** fork PR 이 임의 코드를 실행한다 — GitHub 이 명시적으로 말린다.
267
+ internal 레포와, fork PR 워크플로(`Settings → Actions → Fork pull request workflows`)를 켠 private
268
+ 레포도 같다. 스크립트는 `private` 이고 그 설정이 꺼져 있을 때만 띄운다.
238
269
 
239
270
  private 레포라면 착수 전에 실측해서 알린다:
240
271
 
@@ -260,6 +291,10 @@ gh workflow run <wf>.yml --ref <branch>
260
291
  # 잡이 실제로 시작하는지 본다 — queued 에서 안 움직이면 라벨이 안 맞는 것이다
261
292
  ```
262
293
 
294
+ **이미 실패한 PR 실행은 새 커밋 없이 `gh run rerun <run-id>` 로 옮긴다.** 다시 실행할 때 `vars` 를
295
+ 새로 읽으므로, 변수를 설정한 뒤 재실행하면 같은 PR 실행이 self-hosted 에 배정되고 PR 체크도 그
296
+ 결과로 갱신된다(2026-10-30 실측).
297
+
263
298
  **결제 실패 계정에서도 self-hosted 러너에는 잡이 배정된다** — 2026-08-20 실측. 같은 레포에서
264
299
  호스티드 잡은 `"The job was not started because recent account payments have failed…"` 로 2~4초 만에
265
300
  스텝 0개로 죽었는데, self-hosted 로 라벨을 옮기니 같은 워크플로가 정상적으로 스텝을 밟았다.
@@ -278,12 +313,10 @@ gh workflow run <wf>.yml --ref <branch>
278
313
 
279
314
  임시 조치는 **끝내는 방법이 있을 때만 임시**다. 없으면 그냥 새 영구 상태다.
280
315
 
281
- ```bash
282
- gh variable delete CI_RUNNER_LABEL --repo <owner>/<repo> # 호스티드로 복귀
283
- ID=$(gh api /repos/<owner>/<repo>/actions/runners --jq '.runners[]|select(.name=="local-docker")|.id')
284
- gh api -X DELETE /repos/<owner>/<repo>/actions/runners/$ID # 등록 해제
285
- docker rm -f ci-runner
286
- ```
316
+ `bash <이 스킬 폴더>/scripts/runner.sh down` 이 세 가지를 한다 — 변수 삭제(우리 라벨이고 이 머신의 `up`
317
+ 기록이 있을 때만 · 호스티드로 복귀) · 러너 등록 해제(우리 이름 + `up` 이후 우리 라벨로 붙은 것 — Step 3
318
+ 안전한 기본값 3) · 컨테이너 제거. 기록이 있으면 끝에 변수를 다시 읽어 아직 우리 라벨일 때 실패로
319
+ 끝난다. 마치면 `status` 로 셋 다 비었는지 확인한다.
287
320
 
288
321
  **등록 해제를 빼먹지 마라.** 컨테이너만 지우면 GitHub 에는 offline 러너가 남고, 그 라벨로 오는
289
322
  잡은 영영 큐에 머문다.
@@ -0,0 +1,205 @@
1
+ #!/usr/bin/env bash
2
+ # Temporary ephemeral self-hosted runner for the current GitHub repository, in a Linux container.
3
+ #
4
+ # Usage (from the repository root):
5
+ # bash <skill>/scripts/runner.sh up [--jobs N] [--docker] # serve N jobs, then set CI_RUNNER_LABEL
6
+ # bash <skill>/scripts/runner.sh down # restore hosted runners
7
+ # bash <skill>/scripts/runner.sh status # variable, registered runners, container
8
+ #
9
+ # Environment (all optional):
10
+ # REPO owner/name default: gh repo view
11
+ # LABEL runs-on label default: <name>-local (never a GitHub default label)
12
+ # PLATFORM linux/arm64|linux/amd64 default: the host hardware (Apple Silicon → arm64, even under Rosetta)
13
+ # IMAGE runner image default: myoung34/github-runner:ubuntu-noble (= ubuntu-latest's 24.04)
14
+ #
15
+ # --jobs N ephemeral runners serve one job each: N = the jobs this event will actually run
16
+ # (matrix legs count, jobs skipped by `if:` do not). Interrupted? run `down`.
17
+ # --docker mount the host Docker socket and use host networking — only for `services:` /
18
+ # Docker-based jobs. It gives jobs host-level control; leave it off otherwise.
19
+ # The registration token goes in through a 600 file mounted read-only, never through the
20
+ # container's environment config, so `docker inspect` does not show it.
21
+ # `up` refuses a LABEL another runner of this repository already carries, then claims the label
22
+ # on this machine (${XDG_STATE_HOME:-~/.local/state}/self-hosted-github-runner/). Only under that
23
+ # claim does `down` delete CI_RUNNER_LABEL or unregister other runners carrying the label; without
24
+ # it, it names them and leaves them.
25
+ # Exit codes: 2 usage · 3 refused or GitHub state unknown · 4 runner failed to start.
26
+ set -euo pipefail
27
+
28
+ SELF=$0
29
+ die() { echo "runner.sh: $1" >&2; exit "${2:-3}"; }
30
+ lower() { printf '%s' "$1" | tr '[:upper:]' '[:lower:]'; }
31
+ for bin in gh docker; do command -v "$bin" >/dev/null || die "$bin not found"; done
32
+
33
+ REPO=${REPO:-$(gh repo view --json nameWithOwner --jq .nameWithOwner)}
34
+ [ -n "$REPO" ] || die "cannot resolve the repository; set REPO=owner/name"
35
+ LABEL=${LABEL:-${REPO#*/}-local}
36
+ NAME="${REPO%/*}-${REPO#*/}-runner"
37
+ IMAGE=${IMAGE:-myoung34/github-runner:ubuntu-noble}
38
+ CLAIM="${XDG_STATE_HOME:-$HOME/.local/state}/self-hosted-github-runner/${REPO%/*}@${REPO#*/}"
39
+ if [ -z "${PLATFORM:-}" ]; then
40
+ arch=$(uname -m)
41
+ # A Rosetta shell on Apple Silicon reports x86_64; ask the hardware instead.
42
+ [ "$(uname -s)" = Darwin ] && [ "$(sysctl -n hw.optional.arm64 2>/dev/null || echo 0)" = 1 ] && arch=arm64
43
+ case "$arch" in
44
+ arm64|aarch64) PLATFORM=linux/arm64 ;;
45
+ x86_64|amd64) PLATFORM=linux/amd64 ;;
46
+ *) die "unknown host architecture $arch; set PLATFORM" ;;
47
+ esac
48
+ fi
49
+ case "$LABEL" in ''|*[!A-Za-z0-9._-]*) die "LABEL may contain only letters, digits, '.', '_' and '-'" 2 ;; esac
50
+ case "$(lower "$LABEL")" in
51
+ self-hosted|linux|macos|windows|x64|arm64|arm)
52
+ die "LABEL=$LABEL is a default label that any self-hosted runner matches" ;;
53
+ esac
54
+
55
+ # Prints the current CI_RUNNER_LABEL. Returns 1 only when GitHub says it does not exist;
56
+ # any other failure (auth, network, rate limit) stops the script rather than reading as unset.
57
+ label_var() {
58
+ local out
59
+ if out=$(gh api "/repos/$REPO/actions/variables/CI_RUNNER_LABEL" --jq .value 2>&1); then
60
+ printf '%s' "$out"; return 0
61
+ fi
62
+ case "$out" in *"HTTP 404"*) return 1 ;; esac
63
+ die "cannot read CI_RUNNER_LABEL: $out"
64
+ }
65
+ read_label() { # sets CURRENT; exits on an unknown state
66
+ local rc=0
67
+ CURRENT=$(label_var) || rc=$?
68
+ [ "$rc" -le 1 ] || exit "$rc"
69
+ }
70
+
71
+ # Prints "<id> <name>" of the runners named $NAME or carrying $LABEL (case-insensitive, as GitHub matches).
72
+ label_runners() {
73
+ gh api --paginate "/repos/$REPO/actions/runners" \
74
+ --jq ".runners[]|select(.name==\"$NAME\" or any(.labels[]; (.name|ascii_downcase)==\"$(lower "$LABEL")\"))|\"\(.id) \(.name)\""
75
+ }
76
+
77
+ # True when an earlier `up` on this machine claimed $LABEL for $REPO.
78
+ claimed() { [ "$(cat "$CLAIM" 2>/dev/null || true)" = "$(lower "$LABEL")" ]; }
79
+
80
+ TOKENFILE=""
81
+ VAR_SET=0
82
+ cleanup() {
83
+ local rc=$?
84
+ [ -z "$TOKENFILE" ] || { : > "$TOKENFILE"; rm -f "$TOKENFILE"; }
85
+ if [ "$rc" -ne 0 ] && [ "$VAR_SET" = 1 ]; then
86
+ echo "runner.sh: stopped with CI_RUNNER_LABEL=$LABEL still set; restore with: bash $SELF down" >&2
87
+ fi
88
+ }
89
+ trap cleanup EXIT
90
+ trap 'exit 130' INT TERM
91
+
92
+ launch() {
93
+ local -a extra=()
94
+ # Under $HOME, not $TMPDIR: engines like Colima share only the home directory with the VM.
95
+ TOKENFILE=$(mktemp "$HOME/.runner-token.XXXXXX"); chmod 600 "$TOKENFILE"
96
+ gh api -X POST "/repos/$REPO/actions/runners/registration-token" --jq .token > "$TOKENFILE"
97
+ [ "$DOCKER" = 1 ] && extra=(-v /var/run/docker.sock:/var/run/docker.sock --network host)
98
+ docker rm -f "$NAME" >/dev/null 2>&1 || true
99
+ docker run -d --name "$NAME" --platform "$PLATFORM" \
100
+ -e "REPO_URL=https://github.com/$REPO" -e "RUNNER_NAME=$NAME" -e "LABELS=$LABEL" \
101
+ -e RUNNER_WORKDIR=/tmp/runner/work -e EPHEMERAL=true \
102
+ -v "$TOKENFILE:/run/runner-token:ro" ${extra[@]+"${extra[@]}"} \
103
+ --entrypoint bash "$IMAGE" \
104
+ -c 'RUNNER_TOKEN=$(cat /run/runner-token); export RUNNER_TOKEN; exec /entrypoint.sh ./bin/Runner.Listener run --startuptype service' \
105
+ >/dev/null
106
+ for _ in $(seq 1 40); do
107
+ if docker logs "$NAME" 2>&1 | grep -q "Listening for Jobs"; then
108
+ # Empty it before unlinking: the container keeps the mounted inode, and job code runs as root.
109
+ : > "$TOKENFILE"; rm -f "$TOKENFILE"; TOKENFILE=""
110
+ return 0
111
+ fi
112
+ [ "$(docker inspect -f '{{.State.Running}}' "$NAME" 2>/dev/null)" = true ] || break
113
+ sleep 3
114
+ done
115
+ docker logs "$NAME" 2>&1 | tail -5 >&2
116
+ die "runner did not start listening" 4
117
+ }
118
+
119
+ cmd=${1:-}; shift || true
120
+ case "$cmd" in
121
+ up)
122
+ JOBS=1; DOCKER=0
123
+ while [ $# -gt 0 ]; do
124
+ case "$1" in
125
+ --jobs) [ $# -ge 2 ] || die "--jobs needs a number" 2; JOBS=$2; shift 2 ;;
126
+ --docker) DOCKER=1; shift ;;
127
+ *) die "unknown option $1" 2 ;;
128
+ esac
129
+ done
130
+ case "$JOBS" in ''|*[!0-9]*|0*) die "--jobs must be a positive integer" 2 ;; esac
131
+ visibility=$(gh api "/repos/$REPO" --jq .visibility) || die "cannot read $REPO visibility"
132
+ # Only private repositories, and only when fork PRs cannot start workflows: a fork PR's
133
+ # code would otherwise run on this machine. Anything unreadable counts as a refusal.
134
+ [ "$visibility" = private ] || die "$REPO visibility is '${visibility:-unknown}', not private"
135
+ fork_prs=$(gh api "/repos/$REPO/actions/permissions/fork-pr-workflows-private-repos" \
136
+ --jq .run_workflows_from_fork_pull_requests) || die "cannot read $REPO fork PR workflow setting"
137
+ case "$fork_prs" in
138
+ false) ;;
139
+ true) die "$REPO runs workflows from fork pull requests; disable that first" ;;
140
+ *) die "cannot confirm $REPO blocks fork pull request workflows (setting is '${fork_prs:-empty}')" ;;
141
+ esac
142
+ read_label
143
+ [ -z "$CURRENT" ] || [ "$CURRENT" = "$LABEL" ] || die "CI_RUNNER_LABEL is already '$CURRENT'; not overwriting"
144
+ # A runner we did not start already answers to this label: `down` must never be able to
145
+ # mistake it for one of ours, so refuse here instead.
146
+ held=$(label_runners) || die "cannot read $REPO runners"
147
+ others=$(while read -r _ rname; do [ -z "$rname" ] || [ "$rname" = "$NAME" ] || printf ' %s' "$rname"; done <<< "$held")
148
+ if [ -n "$others" ]; then
149
+ if claimed; then die "runner(s)$others carry label '$LABEL' since an earlier up on this machine; run down first"; fi
150
+ die "runner(s)$others already carry label '$LABEL'; choose another LABEL"
151
+ fi
152
+ mkdir -p "${CLAIM%/*}"
153
+ lower "$LABEL" > "$CLAIM"
154
+ echo "repo=$REPO label=$LABEL platform=$PLATFORM docker=$DOCKER jobs=$JOBS"
155
+ for i in $(seq 1 "$JOBS"); do
156
+ launch
157
+ echo "runner $i/$JOBS listening"
158
+ if [ "$VAR_SET" = 0 ]; then
159
+ # Route jobs here only once a runner is listening, so a failed start leaves CI as it was.
160
+ [ "$CURRENT" = "$LABEL" ] || gh variable set CI_RUNNER_LABEL --body "$LABEL" --repo "$REPO"
161
+ VAR_SET=1
162
+ fi
163
+ docker wait "$NAME" >/dev/null
164
+ docker logs "$NAME" 2>&1 | grep -E "Running job|completed with result" || true
165
+ docker rm -f "$NAME" >/dev/null 2>&1 || true
166
+ done
167
+ echo "served $JOBS job(s); restore hosted runners with: bash $SELF down"
168
+ ;;
169
+ down)
170
+ # Without this machine's claim the label may be the installer's own: change only what is ours by name.
171
+ ours=0
172
+ if claimed; then ours=1; fi
173
+ read_label
174
+ if [ "$CURRENT" = "$LABEL" ] && [ "$ours" = 1 ]; then
175
+ gh api -X DELETE "/repos/$REPO/actions/variables/CI_RUNNER_LABEL" >/dev/null
176
+ elif [ "$CURRENT" = "$LABEL" ]; then
177
+ echo "CI_RUNNER_LABEL is '$CURRENT' but no up on this machine claimed it; left as is" >&2
178
+ elif [ -n "$CURRENT" ]; then
179
+ echo "CI_RUNNER_LABEL is '$CURRENT', not '$LABEL'; left as is" >&2
180
+ fi
181
+ # Ours by name, always. Others carrying our label only under the claim: `up` refused the label
182
+ # while another runner held it, so they appeared afterwards (e.g. job code with the token).
183
+ ids=$(label_runners)
184
+ left=""
185
+ while read -r id rname; do
186
+ [ -n "$id" ] || continue
187
+ if [ "$rname" != "$NAME" ] && [ "$ours" = 0 ]; then left="$left $rname ($id)"; continue; fi
188
+ gh api -X DELETE "/repos/$REPO/actions/runners/$id"
189
+ echo "unregistered runner $rname ($id)"
190
+ done <<< "$ids"
191
+ [ -z "$left" ] || echo "runner.sh: left runner(s)$left carrying label '$LABEL': no up on this machine claimed it" >&2
192
+ [ "$ours" = 0 ] || rm -f "$CLAIM"
193
+ docker rm -f "$NAME" >/dev/null 2>&1 || true
194
+ read_label
195
+ [ "$ours" = 0 ] || [ "$CURRENT" != "$LABEL" ] || die "CI_RUNNER_LABEL is still '$LABEL'"
196
+ echo "restored: $NAME unregistered and removed; CI_RUNNER_LABEL is ${CURRENT:-unset}"
197
+ ;;
198
+ status)
199
+ read_label
200
+ echo "CI_RUNNER_LABEL=${CURRENT:-<unset>}"
201
+ gh api "/repos/$REPO/actions/runners" --jq '.runners[] | "\(.name) \(.status) " + ([.labels[].name]|join(","))'
202
+ docker ps -a --filter "name=^${NAME}$" --format '{{.Names}} {{.Status}}'
203
+ ;;
204
+ *) sed -n '2,25p' "$0" >&2; exit 2 ;;
205
+ esac