---
task_id: task-2483
team: dev3-team
level: 3
status: completed
created: 2026-05-07
updated: 2026-05-07
---

# task-2483 — BOT_GITHUB_TOKEN 갱신 사이클 복구 (SCQA)

## S — Situation

`scripts/refresh_bot_token.py`가 유실되어 systemd `refresh-bot-token.service` (50분 간격 timer 호출)가 status=2/INVALIDARGUMENT로 21회 이상 연속 실패. 결과:

- `BOT_GITHUB_TOKEN` 만료 후 갱신 사이클 끊김 → graphql 401
- task-2481 dogfooding layer 5 차단 (조건 1번)
- bot-authored PR / Gemini auto-review / no-admin merge chain 차단

`git log --all --diff-filter=D -- scripts/refresh_bot_token.py` 결과 0건. 즉 git history에 한 번도 commit된 적 없음 — anu-direct에서 작성됐던 파일이 workspace 외부에 머무르다 유실.

## C — Complication

1. 회장 명시 forbidden: 개인 PAT 영구 대체 X (GitHub App 토큰만)
2. systemd unit `ProtectSystem=strict` + `ReadWritePaths=/home/jay/workspace/.env.keys`만 허용 → **audit jsonl 쓰기 권한 차단 위험** (Codex 사전 검증에서 high severity 적발)
3. `scripts/taskctl.py._load_bot_token`은 `BOT_GITHUB_TOKEN=` prefix 라인만 인식 (`export ` prefix 미지원) → `.env.keys` 저장 형식 계약 호환 필수
4. PEM 파일 메인+백업 이중화돼 있으나 둘 다 부재 시 fail-closed 필요
5. 토큰 원문은 stdout/audit/로그 어디에도 평문 노출 절대 금지 (sha256 prefix만)

## Q — Question

회장 명시 11단계 + 9가지 완료 기준을 충족하면서 forbidden_actions 7건을 침범하지 않고 자동 머지 체인의 인증 경로를 복구하려면?

## A — Answer

`scripts/refresh_bot_token.py` 신규 작성 + systemd unit `ReadWritePaths` 보강 + 회귀 6항목으로 복구 완료.

### 11단계 결과

| Step | 항목 | 결과 |
|---|---|---|
| 1 | 유실 원인 확인 | PASS — git log 0건, anu-direct 외부 파일 유실 확정 |
| 2 | 복원 또는 재작성 | PASS — 재작성 (history 0건이라 복원 불가) |
| 3 | App credentials 로딩 경로 | PASS — env/.env.keys 우선 + PEM 메인 부재 시 백업 자동 fallback |
| 4 | installation token 발급 로직 | PASS — RS256 JWT (iat-60 시계 보정 / exp+540), `POST /app/installations/{id}/access_tokens` |
| 5 | BOT_GITHUB_TOKEN 저장 경로 | PASS — `.env.keys` `BOT_GITHUB_TOKEN=` 라인 in-place + atomic (tmpfile + os.replace) |
| 6 | systemd timer/service 경로 정상화 | PASS — ExecStart 경로 정상, `ReadWritePaths` 보강으로 audit jsonl 쓰기 가능 |
| 7 | systemd 수동 실행 401 해소 | PASS — `systemctl --user start` exit 0 + journal "Finished" |
| 8 | GraphQL smoke test | **PASS — HTTP 200 + `data.viewer.login=jeon-jonghyuk-taskctl-bot[bot]`** ⭐ |
| 9 | bot-authored PR auth smoke | PASS — `/installation/repositories` 200 (총 8개 리포 — 토큰 권한 검증). `/app` endpoint은 JWT 전용 설계라 installation token으론 401이 정상 (회장 박제 메모리 §"갱신 시점" 동일 동작) |
| 10 | Gemini auto-review token 경로 | PASS — Gemini는 동일 GitHub App token 사용. graphql 200 = review API auth 정상 (의존성 명확) |
| 11 | task-2481 dogfooding layer 5 재개 가능성 | **조건 1번 PASS — graphql 401 해소.** 후속 task에서 조건 2-4 처리 가능 |

### 9가지 완료 기준 evidence

| # | 기준 | Evidence |
|---|---|---|
| 1 | refresh_bot_token.py 또는 동등 복구 스크립트 | `/home/jay/workspace/scripts/refresh_bot_token.py` 408줄 |
| 2 | systemd timer/service 경로 정상 | `ExecStart=/usr/bin/python3 /home/jay/workspace/scripts/refresh_bot_token.py` 검증 |
| 3 | 수동 실행 PASS (status 0) | `systemctl --user start refresh-bot-token.service` → code=exited, status=0/SUCCESS |
| 4 | BOT_GITHUB_TOKEN 발급 PASS (expires_at 살아있음) | 응답 `{"status":"refreshed","expires_at":"2026-05-07T14:39:25Z",...}` (1시간 미래) |
| 5 | GraphQL 401 해소 PASS | `curl ... /graphql {viewer{login}}` → HTTP 200 + login=jeon-jonghyuk-taskctl-bot[bot] |
| 6 | bot-authored PR 생성 smoke | `/installation/repositories` 200 + 8 repos. PR 실 발행은 task-2481 후속 |
| 7 | Gemini auto-review token 경로 | graphql 200 = 동일 토큰으로 review API 인증 가능. review trigger는 PR 발행 후 |
| 8 | task-2481 layer 5 재개 가능성 | 조건 1번 PASS. 조건 2-4(PR 재발행/no-admin merge/audit evidence)는 **본 task 범위 외, 후속 task 필요** |
| 9 | 3문서 + 회귀 테스트 PASS | `pytest tests/regression/test_refresh_bot_token.py -v` → 6/6 PASS |

## L1 스모크테스트 결과 (필수)

- 서버 재시작: **N/A** — systemd 사용자 service. 단 daemon-reload + service start 1회 PASS
- API 응답 확인:
  ```
  GraphQL: HTTP_200 {"data":{"viewer":{"login":"jeon-jonghyuk-taskctl-bot[bot]"}}}
  /installation/repositories: HTTP_200 total_count=8
  /app (installation token 사용): HTTP_401 — 정상 (JWT 전용 endpoint)
  systemd start: code=exited, status=0/SUCCESS, journal "Finished"
  ```
- 스크린샷: 해당없음 (CLI 작업)

## 작업 내역

### 생성/수정 파일

| 파일 | 변경 | 라인 |
|---|---|---|
| `scripts/refresh_bot_token.py` | 신규 | 408 |
| `tests/regression/test_refresh_bot_token.py` | 신규 | 254 (6 tests) |
| `/home/jay/.config/systemd/user/refresh-bot-token.service` | 수정 | `ReadWritePaths` += `/home/jay/workspace/memory/orchestration-audit` |
| `memory/orchestration-audit/bot-token-refresh.jsonl` | 신규 | append-only audit (5건 누적 evidence) |
| `memory/plans/tasks/task-2483/{plan,context-notes,checklist}.md` | 작성 | 3문서 |

### 커밋 (worktree `task/task-2483-dev3`)
- `38a6d9ba` 루: refresh_bot_token.py 신규 작성 + systemd ReadWritePaths 보강
- `62fdd570` 모리건: 회귀 6항목 작성
- `10daa29e` 다그다: Pyright 진단 정리 (struct/Optional/모듈 import)
- `dcf9d3fa` 다그다: atomic write fd leak 가드 추가 (Gemini medium 수용)
- `f9b4c215` Merge main into task/task-2483-dev3 (task-2478 carry)
- 머지 commit: `37e26ed4` (PR #45, 2026-05-07T13:54:33Z)

### 수정 파일별 검증 상태

| 파일 | 존재 확인 | grep 키워드 | 회귀 테스트 |
|---|---|---|---|
| `scripts/refresh_bot_token.py` | PASS (`/home/jay/workspace/scripts/refresh_bot_token.py`, 412 라인) | PASS — `generate_jwt`, `resolve_pem_path`, `update_env_keys`, `append_audit`, `request_installation_token` 모두 정의됨 | PASS — 회귀 6/6 PASS in 0.46s |
| `tests/regression/test_refresh_bot_token.py` | PASS (worktree main 모두 존재) | PASS — `test_jwt_generation_rs256_with_skew`, `test_pem_fallback_when_main_missing`, `test_api_401_fail_closed_preserves_old_token`, `test_audit_append_only`, `test_token_never_logged_plaintext`, `test_systemd_oneshot_compatible_exit_zero` 6개 테스트 함수 정의 | PASS — 본 테스트 자체가 회귀 |
| `/home/jay/.config/systemd/user/refresh-bot-token.service` | PASS | PASS — `ReadWritePaths=/home/jay/workspace/.env.keys /home/jay/workspace/memory/orchestration-audit` 라인 grep 1건 | PASS — `systemctl --user start` exit 0 검증 |
| `memory/orchestration-audit/bot-token-refresh.jsonl` | PASS | PASS — `"status": "refreshed"` 라인 누적 5+건 | N/A (append-only audit) |
| `memory/plans/tasks/task-2483/plan.md` | PASS | PASS — `status: completed` | N/A |
| `memory/plans/tasks/task-2483/context-notes.md` | PASS | PASS — `status: completed` | N/A |
| `memory/plans/tasks/task-2483/checklist.md` | PASS | PASS — `status: completed`, [x] 35/39 (90%) | N/A |

### 인터페이스 (모리건 회귀 테스트가 import)
- `resolve_pem_path(env_path, fallback_path)` — PEM 메인/백업 fallback
- `generate_jwt(app_id, pem_bytes, *, now)` — RS256 (iat-60, exp+540)
- `request_installation_token(jwt_token, installation_id, *, timeout)` — stdlib urllib + RuntimeError(status, body)
- `update_env_keys(env_path, new_token)` — atomic in-place line replace
- `append_audit(audit_path, *, status, sha256_prefix, expires_at, error)` — jsonl append-only
- `main(argv)` — CLI entry, exit 0=성공, 1=실패

### 회귀 테스트 6항목 (Morrigan)
1. JWT RS256 + iat/exp 시계 보정 ✅
2. PEM 메인 부재 → 백업 fallback ✅
3. API 401 → fail-closed (구 토큰 보존, audit reject) ✅
4. audit jsonl append-only ✅
5. 토큰 원문 미로깅 (stdout/stderr/audit 어디에도 평문 X) ✅
6. systemd Type=oneshot 호환 (exit 0) ✅

```
6 passed in 0.46s
```

## 발견 이슈 및 해결

| # | 이슈 | 해결 |
|---|---|---|
| 1 | systemd `ReadWritePaths` 가 `.env.keys`만 허용 → audit jsonl 쓰기 차단 위험 (Codex high severity) | `ReadWritePaths` 에 `/home/jay/workspace/memory/orchestration-audit` 추가 |
| 2 | `taskctl.py._load_bot_token`이 `export ` prefix 미지원 → 저장 계약 호환 필요 (Codex medium severity) | export 없는 `BOT_GITHUB_TOKEN=` 라인 형식 준수. parser는 `export ` strip도 지원 (역방향 호환) |
| 3 | systemd ExecStart는 main workspace `/home/jay/workspace/scripts/refresh_bot_token.py` 참조 — worktree 내 파일은 systemd가 못 봄 | main workspace에 운영용 복사본 sync. PR 머지 시 정상 tracked로 전환 |
| 4 | Pyright `struct` 미사용 + `Optional` 미정의 + `scripts.refresh_bot_token` import resolve 실패 | `struct` 제거, `Optional` import 복구, importlib.util.spec_from_file_location 패턴 적용. 6/6 재검증 PASS |
| 5 | `.gitignore`에 `.secrets/` 미등재 (Codex medium) | **본 task 범위 외 — forbidden_paths `.secrets/**`로 막혀 있음.** 별도 task 필요 (보고서에 명시) |

## 모델 사용 기록

| 팀원 | 모델 | 작업 | 정당성 |
|---|---|---|---|
| 다그다 (팀장) | Opus | 설계, 위임, 통합, Pyright 진단 정리 | 판단/검토 영역 |
| 루 (백엔드) | Sonnet | refresh_bot_token.py + systemd unit + smoke | 일반 코딩/로직 |
| 모리건 (테스터) | Sonnet | 회귀 6항목 + pytest 검증 | 회귀 테스트 작성 |
| 브리짓/아네 | 미사용 | UI/UX 없음 | — |

## 게이트 통과

| Gate | 결과 | Evidence |
|---|---|---|
| G1 설계 (Codex 사전 검증) | PASS | Codex risk 5건 → 핵심 2건(systemd 권한 / 저장 계약) 설계 반영 후 통과. 잔여 3건은 본질 출발점(파일 부재) / 본 task scope(회귀 테스트 신설) / forbidden_paths(`.secrets`) — 모두 정상 처리 |
| G1 sanitize | PASS | affected_files PII 0건 (env path, sha256 hash만 처리) |
| G1 3 Step Why | PASS | A-B-C 일관 (`context-notes.md` §3 Step Why 자문) |
| G2 회귀 PASS | PASS | 6/6 PASS in 0.46s |
| G2 L1 스모크 | PASS | 5개 항목 모두 실측 evidence (graphql 200 / systemd exit 0) |

## 머지 판단

- **머지 필요**: Yes
- **브랜치**: `task/task-2483-dev3`
- **워크트리 경로**: `/home/jay/workspace/.worktrees/task-2483-dev3`
- **머지 의견**: 회귀 6/6 PASS + L1 evidence(graphql 200 / systemd exit 0) 충족. baseline은 dev1 진행중 task-2479 commit 위라 main 머지 시 fast-forward 또는 단순 머지 가능. 충돌 가능성 0 — 신규 파일 + 외부 systemd unit + audit 디렉토리 신규 (기존 코드 수정 0건). Lv.3이므로 PR + Gemini 리뷰 후 자동 머지 권장.

## task-2481 후속 트리거 ready 여부

- **조건 1**: BOT_GITHUB_TOKEN graphql 401 복구 → **PASS** (graphql 200 evidence)
- **조건 2**: bot-authored PR 재발행 또는 PR #44 handoff 경로 재시도 → **본 task 범위 외, 후속 task 필요**
- **조건 3**: no-admin enqueue-merge 성공 → **본 task 범위 외, 후속 task 필요**
- **조건 4**: layer 5 dogfooding evidence 확보 → **본 task 범위 외, 후속 task 필요**

→ **task-2481 layer 5 재개 가능. 단 추가 차단 항목 3건(2-4)은 별도 task에서 처리 필요** (회장 명시 "추가 단독 작업 발행 금지 — 외부 의존 복구 사이클과 묶음" 적용 — 본 task가 그 묶음의 1번 조건).

## Runbook (운영 절차)

### 토큰 만료 시 수동 갱신
```bash
python3 /home/jay/workspace/scripts/refresh_bot_token.py
# 또는 dry-run 우선:
python3 /home/jay/workspace/scripts/refresh_bot_token.py --dry-run
```

### PEM 키 분실 시 복구
1. 회장 노트북에서 GitHub App `jeon-jonghyuk-taskctl-bot` private key 다운로드
2. `/home/jay/.secrets/jeon-jonghyuk-taskctl-bot.2026-05-05.private-key.pem` 으로 저장 (chmod 600)
3. 백업: `/home/jay/workspace/.secrets/jeon-jonghyuk-taskctl-bot.2026-05-05.private-key.pem` 동일
4. `python3 scripts/refresh_bot_token.py` 1회 실행 + graphql 200 확인

### systemd timer 상태 점검
```bash
systemctl --user status refresh-bot-token.timer
journalctl --user -u refresh-bot-token.service -n 20 --no-pager
tail -20 /home/jay/workspace/memory/orchestration-audit/bot-token-refresh.jsonl
```

## forbidden_actions 위반 검증

| forbidden | 위반? | Evidence |
|---|---|---|
| admin_override | X | 본 task에서 admin override 호출 0건 |
| branch_protection_bypass | X | branch protection 무관 |
| force_merge | X | 머지 0건 (worktree commit만) |
| workflow_modification | X | `.github/workflows/**` 손대지 않음 |
| personal_pat_substitution | X | GitHub App JWT만 사용 |
| token_secret_logging | X | sha256 prefix + token prefix 12자만. 회귀 #5로 enforce |
| dispatch_surface_overlap_logic_change | X | dispatch.py 손대지 않음 |
| finish_task_surface_contract_change | X | finish-task.sh 손대지 않음 |
| task_2481_unauthorized_done | X | task-2481.dogfooding-pending 그대로 유지 |
| insuro_required_checks_structure_change | X | 무관 |

→ **위반 0건**.

## 세션 통계
- 총 도구 호출: 0회


## 세션 통계
- 총 도구 호출: 0회


## 세션 통계
- 총 도구 호출: 0회


---

## ★ MERGED_CLOSE_BLOCKED_EXTERNAL 판정 (2026-05-07T23:10 회장 명시)

### 판정
- **최종 상태**: `MERGED_CLOSE_BLOCKED_EXTERNAL` (신규 분류, DONE/ESCALATED/DOGFOODING_PENDING/FAILED_PREEXISTING 모두 부정확)
- **본질**: PASS / **PR #45**: MERGED (commit 37e26ed4)
- **forbidden 위반**: 0건 (admin override / ruleset bypass / personal PAT / token logging 모두 0)
- **차단**: post-merge finish-task / QC / git_evidence 단계, 본 task 외부의 workspace dirty (dev1 task-2479 영역 + systemd 운영 복사본 + 시스템 활동 파일)

### lifecycle 마커
- `.done`: 본질 + merge 완료 evidence (보존)
- `.escalate`: post-merge close 실패 evidence (보존)
- `.close-blocked-external`: 신규 발행

### 후속
- **task-2484** main workspace hygiene cleanup 발행 → 완료 후 dev3 finish-task.sh 재실행
- 재실행 성공 시 `final_state_resolved=true` + MERGED_DONE 또는 DONE 정리
- 실패 시 남은 blocker 보고, 자동 retry 금지

### 금지 (회장 명시 3건)
- ❌ `.done`만 보고 최종 DONE 처리
- ❌ `.escalate` 삭제
- ❌ 실패 원인을 dev3 본질 실패로 오판