# v0.2.3 #2 AI retry / 수동 trigger 설계

**작성일:** 2026-05-01
**저자:** 김태현 (dlsrks0734@gmail.com)
**문서 성격:** v0.2.3 cut 7항목 중 5번째 항목 (#2 AI retry) 의 mini-brainstorm 결정 + design. roadmap §3 #2 의 In/Out 위에서 §8 미결정 3항목 (unreachable backoff cap / reason 분류 정밀도 / per-note retry) 결정.

**선행 문서:**
- `docs/superpowers/specs/2026-05-01-v023-feedback-roadmap-design.md` §3 #2, §8
- 선행 cut: #7 telemetry (PR #13), #4 trash (PR #14), #5 expiry (PR #15), #1 ollama 회복 (PR #16)

---

## 1. 결정 요약

| Q | 결정 | 근거 |
|---|------|------|
| Q1 unreachable backoff cap | **A 15분 exponential** | 30s → 60s → 120s → 240s → 480s → 900s cap. 회복 latency 짧으면서 오래 꺼지면 부하 미미. |
| Q2 timeout 분류 | **A unreachable 동일** (무한 retry) | timeout 99% 는 임시 (gemma cold start, 큰 입력). 영구 hang 케이스는 v0.2.4 dogfood 후 식별. roadmap §3 #2 In 과 deviation — 의식적. |
| Q3 per-note retry | **A retry-all 만** | UI 노이즈 회피. NoteCard 단건 버튼은 v0.2.4 dogfood 마찰 발생 시 추가. |

---

## 2. AiWorker.processJob 정책 변경

### 2.1 분기 로직

`classifyReason(err)` 결과로 분기:

```ts
const reason = classifyReason(err);
if (reason === 'unreachable' || reason === 'timeout') {
  // 무한 retry 경로: attempts 증가 안 함, in-job loop 안에서 sleep + retry
  const sleepMs = nextBackoffMs(this.unreachableBackoffStep);
  this.unreachableBackoffStep = Math.min(this.unreachableBackoffStep + 1, 5);
  this.repo.setNextRunAt(job.noteId, new Date(Date.now() + sleepMs).toISOString(), msg);
  await this.sleep(sleepMs);
  // for 루프의 attempt 인덱스 그대로 — 다음 try 도 같은 attempt 번호로 재시도
  attempt -= 1;  // for 루프의 attempt++ 상쇄
  continue;
} else {
  // schema / other: 기존 max 3 retry 정책 그대로
  this.repo.incrementJobAttempt(job.noteId, nextRunAt, msg);
  if (isLast) {
    this.repo.markAiFailed(job.noteId, msg);
    if (this.telemetry) {
      await this.telemetry.emit({ kind: 'ai_failed', payload: { ... } }).catch(() => {});
    }
    this.emit(job.noteId);
    return;
  }
  await this.sleep(this.backoffsMs[attempt + 1] ?? 0);
}
```

성공 시 `unreachableBackoffStep = 0` 으로 reset.

### 2.2 backoff schedule

```ts
private readonly UNREACHABLE_BACKOFFS_MS = [30_000, 60_000, 120_000, 240_000, 480_000, 900_000];
private nextBackoffMs(step: number): number {
  return this.UNREACHABLE_BACKOFFS_MS[Math.min(step, 5)];
}
```

기존 `backoffsMs = [0, 30_000, 120_000]` 은 schema/other 전용 그대로.

### 2.3 invariants

- unreachable/timeout: `markAiFailed` 절대 호출 안 함. `ai_failed` telemetry emit 안 함.
- schema/other: 기존 동작 (max 3 후 markAiFailed + emit).
- 결과: `ai_failed.reason` 통계에는 schema/other 만 누적 (Q2 = A 의 자연 결과).

---

## 3. NoteRepository 확장

```ts
// src/main/repository/NoteRepository.ts

findFailedIds(): string[];
  // SELECT id FROM notes WHERE ai_status='failed' AND deleted_at IS NULL ORDER BY updated_at DESC

countFailed(): number;
  // SELECT COUNT(*) FROM notes WHERE ai_status='failed' AND deleted_at IS NULL

retryAllFailed(now: string): { ids: string[] };
  // 단일 transaction 안에서:
  //   UPDATE notes SET ai_status='pending', ai_error=NULL, updated_at=now WHERE id IN (...)
  //   INSERT OR IGNORE INTO pending_jobs (note_id, attempts, next_run_at) VALUES (?, 0, now)
  //   (이미 pending_jobs row 가 있으면 OR IGNORE — race 가드)

setNextRunAt(noteId: string, nextRunAt: string, lastError: string): void;
  // UPDATE pending_jobs SET next_run_at=?, last_error=? WHERE note_id=?
  // attempts 변경 없음 — unreachable/timeout 무한 retry 용
```

---

## 4. CaptureService + IPC

### 4.1 CaptureService 메서드

```ts
async retryAllFailed(): Promise<{ count: number }> {
  const { ids } = this.repo.retryAllFailed(new Date().toISOString());
  for (const id of ids) {
    await this.deps.enqueue(id);
  }
  if (this.deps.telemetry && ids.length > 0) {
    await this.deps.telemetry.emit({
      kind: 'ai_retry_manual',
      payload: { failedCount: ids.length }
    }).catch(() => {});
  }
  return { count: ids.length };
}
```

빈 배열 시 telemetry emit 안 함 — 사용자가 "재시도" 클릭해도 N=0 이면 noise.

### 4.2 IPC 채널 신규 2

| 채널 | 입력 | 출력 |
|------|------|------|
| `inbox:retryAllFailed` | (없음) | `{ count: number }` |
| `inbox:failedCount` | (없음) | `number` |

confirm dialog 불필요 — destructive 아님 (단순 재처리 큐 등록, 데이터 손실 없음).

---

## 5. Tray + Banner UI

### 5.1 Tray 메뉴

기존 (#1 cut 후):
```
- 사용 로그 내보내기...
- Ollama 재확인 (status.ok=false 시 enabled)
```

신규 (본 cut):
```
- 사용 로그 내보내기...
- Ollama 재확인 (status.ok=false 시 enabled)
- 지금 AI 처리 (실패 N건) (failedCount > 0 시 enabled, label dynamic with N)
```

`refreshTrayFailedCount(count: number)` setter — `refreshTrayOllama` 와 동일 패턴. `_failedCount` module-level state + 메뉴 rebuild.

`createTray` 의 9번째 callback `runRetryAllFailed`. 8 → 9 positional. v0.2.4 backlog #4 (TrayCallbacks object refactor) trigger 더 강화.

AiWorker.onUpdate 시점에 `refreshTrayFailedCount(repo.countFailed())` 호출.

### 5.2 FailedBanner

`src/renderer/inbox/components/FailedBanner.tsx` (신규):

```tsx
import React from 'react';
import { useInbox } from '../store.js';

export function FailedBanner(): React.ReactElement | null {
  const count = useInbox((s) => s.failedCount);
  const retryAllFailed = useInbox((s) => s.retryAllFailed);
  if (count === 0) return null;
  return (
    <div className="banner warn" style={{ display: 'flex', alignItems: 'center', gap: 8 }}>
      <span style={{ flex: 1 }}>❌ AI 처리 실패 <b>{count}</b>건</span>
      <button onClick={() => { retryAllFailed().catch((e) => console.warn('retryAllFailed failed', e)); }}>
        재시도
      </button>
    </div>
  );
}
```

스타일: warn variant 색상은 PendingBanner 와 다른 차별 (#fff7e6 / #d99500 의 ExpiryBanner 와도 다름) — 본 banner 는 빨강 톤 (#fce4e4 / #a33). 사용자 주의 필요한 영구 실패 신호.

### 5.3 Inbox 상단 stack 갱신

```
1. OllamaBanner       (system - down)
2. RecoveryToast      (회복 toast)
3. PendingBanner      (AI 처리 N건 - 일시)
4. FailedBanner       (AI 실패 N건 - 영구 - 신규)
5. ExpiryBanner       (만료)
6. tagFilter chip
7. notes
```

위치 근거: system status > 진행 (transient) > 영구 실패 (actionable) > 트리아지 (expiry, also actionable but lower urgency) > filter > content.

---

## 6. zustand store

```ts
// InboxState 확장
failedCount: number;
retryAllFailed: () => Promise<void>;
```

initial: `failedCount: 0`.

`loadInitial` / `refreshMeta` 의 `Promise.all` 에 `inboxApi.getFailedCount()` 합류 → `set({ failedCount })`.

`retryAllFailed` action:
```ts
async retryAllFailed() {
  const r = await inboxApi.retryAllFailed();
  // 낙관적 갱신: failedCount = 0 으로 reset (worker 처리 진행 중)
  // 실제 카운트는 AiWorker.onUpdate 트리거된 refreshMeta 에서 자연 동기.
  // PendingBanner 가 처리 중 N 건 노출.
  set({ failedCount: 0 });
  // r.count 는 telemetry/log 정보용
}
```

---

## 7. Telemetry

### 7.1 신규 1 event

| event | payload | 발화 |
|-------|---------|------|
| `ai_retry_manual` | `{ failedCount: number }` (≥1) | retryAllFailed 시 ids.length>0 일 때만 |

빈 배열 시 emit 안 함 — sentinel.

### 7.2 zod schema

```ts
const AiRetryManualPayload = z.object({
  failedCount: z.number().int().positive()  // ≥1 enforced — 0 emit 자체가 invariant violation
}).strict();
```

### 7.3 stats.md 집계

신규 행 (수동 recheck 사용량 다음):
- AI 수동 재시도 사용량: `count` 회 / 누적 `Σfailedcount` 건

`DailyRow` 에 1 카운터 + sum 누적기 추가.

### 7.4 기존 `ai_failed` 영향

변경 없음. unreachable/timeout 가 markAiFailed 안 부르므로 자연히 reason 분포에서 제외. 결과: `ai_failed.reason` 분포 = schema + other 만. dogfood 통계 의미 명확화.

---

## 8. 테스트

| 영역 | 케이스 | 검증 |
|------|--------|------|
| AiWorker | unreachable 무한 retry | attempts 증가 안 함, markAiFailed 안 호출, ai_failed emit 안 함 |
| AiWorker | timeout 무한 retry (Q2=A) | unreachable 와 동일 경로 |
| AiWorker | schema fail max 3 | attempts 증가, 마지막에 markAiFailed + ai_failed emit |
| AiWorker | other fail max 3 | schema 와 동일 |
| AiWorker | unreachable backoff step | 1차 30s, 2차 60s, ..., 6차 900s cap |
| AiWorker | success 시 unreachableBackoffStep reset | 다음 unreachable 발생 시 30s 부터 |
| Repo | findFailedIds — failed + active 만 | trashed 또는 pending/done 제외 |
| Repo | countFailed | 정확 |
| Repo | retryAllFailed atomic | ai_status reset + pending_jobs 재투입 |
| Repo | retryAllFailed empty | `{ ids: [] }` |
| Repo | retryAllFailed pending_jobs 이미 존재 | OR IGNORE — race 안전 |
| Repo | setNextRunAt | attempts 변경 없이 next_run_at + last_error 만 |
| CaptureService | retryAllFailed — telemetry emit + worker.enqueue 호출 | per-id enqueue + ai_retry_manual emit |
| CaptureService | retryAllFailed 빈 결과 emit 없음 | count=0 sentinel |
| TelemetryEvents | zod parse `ai_retry_manual` | happy + extra field reject + 0 reject (≥1 invariant) |
| TelemetryStats | AI 수동 재시도 집계 | count + sum |
| Store | retryAllFailed action — failedCount=0 reset | 낙관적 갱신 |

총 ≥ 17 단위.

---

## 9. 작업 순서 (writing-plans 시 task 분할 가이드)

T1. Repo: findFailedIds + countFailed + retryAllFailed + setNextRunAt + 단위 5개
T2. AiWorker: unreachable/timeout 무한 retry 로직 + 단위 6개
T3. Telemetry: ai_retry_manual 1 event + stats + 단위 3개
T4. CaptureService.retryAllFailed + IPC 2 채널 + preload + 단위 2개
T5. shared/types InboxApi + store retryAllFailed + failedCount + 단위 1개
T6. FailedBanner 컴포넌트 + App.tsx mount
T7. Tray "지금 AI 처리 (실패 N건)" 메뉴 + 9th callback + refreshTrayFailedCount + main wiring
T8. closure (gates + roadmap mark + memory backlog)

---

## 10. roadmap In/Out 일치

### 10.1 roadmap §3 #2 In 매핑

| roadmap | design |
|---------|--------|
| AiWorker unreachable 무한 retry, attempts 증가 안 함 | §2 ✓ |
| schema fail / invalid response / timeout 만 attempts 증가 (max 3 유지) | §2 — **timeout 은 deviation (Q2=A)**, schema/other 만 attempts 증가 |
| markAiFailed 한 노트 수동 re-enqueue | §3 retryAllFailed |
| 트레이 + Inbox "지금 AI 처리 (실패 N건)" | §5 ✓ |
| FailedBanner | §5.2 ✓ |
| IPC `inbox:retryAllFailed`, `inbox:failedCount` | §4 ✓ |
| Telemetry `ai_retry_manual {failedCount}` | §7 ✓ |
| 단위 테스트 | §8 ≥ 17 |

### 10.2 Out 유지

- per-note retry 버튼 (Q3=A) — Out
- failed reason 별 차등 정책 — Out (모두 동일 max 3, telemetry 통계만 분리)
- retry progress UI — Out (PendingBanner 가 자연 표현)
- retry rate-limit — Out

### 10.3 roadmap deviation

§3 #2 In 의 "timeout 만 attempts 증가" 와 본 design 의 Q2=A "timeout 무한 retry" 가 충돌. 의식적 변경 — `ai_failed.reason='timeout'` 통계가 부족할 수 있음. dogfood 데이터로 검증 후 v0.2.4 에서 hang 케이스 분리 가능.

---

## 11. 위험 / 완화

| 위험 | 완화 |
|------|------|
| unreachable 무한 retry 큐 폭주 | sleep await sequential. 같은 job 안 in-place loop, 새 job 추가 0. cap 15분. |
| retryAllFailed 가 큰 N (예: 100+) | enqueue in-memory queue push. AiWorker 가 sequential 처리 — provider 호출 1개씩. 폭주 0. |
| timeout 분류 잘못 — 영구 hang 노트가 무한 retry | telemetry markAiFailed 시점만 emit → timeout 무한 retry 노트 stats 안 보임. v0.2.4 dogfood 시 ai_status='pending' 의 attempts 분포로 영구 hang 식별. 필요 시 timeout cap 도입. |
| unreachableBackoffStep 이 process restart 시 reset | 의도. next_run_at 가 미래면 sleep, 과거면 즉시 retry — 자연. |
| schema 후 unreachable 발생 — backoff step 이 unreachableBackoffStep 와 별개 인덱스 | unreachableBackoffStep 은 unreachable/timeout 전용. schema 의 attempts 와 독립. 단위 테스트 회귀 가드. |
| retryAllFailed 와 AiWorker 큐의 race (이미 처리 중인 노트 재투입) | retryAllFailed SQL 이 ai_status='failed' 만 → 처리 중 ('pending') 노트는 자연 제외. atomic transaction. |
| pending_jobs 재투입 시 이미 pending_jobs row 존재 (예: race) | INSERT OR IGNORE — duplicate ignored. attempts/next_run_at 그대로 유지. 안전. |

---

## 12. 게이트 (PR 머지 조건)

- `npm run typecheck` 0 errors
- `npm test` — 344 + 17 = 361+
- `npm run test:e2e` 1/1
- main 머지

머지 후:
- roadmap §3 #2 ✓ 완료 마커
- v0.2.4 backlog 누적

---

## 13. 변경 이력

| 일자 | 변경 |
|------|------|
| 2026-05-01 | 초안 — Q1=A (15분 cap), Q2=A (timeout=unreachable), Q3=A (retry-all only). AiWorker unreachable/timeout 무한 retry + retryAllFailed atomic + FailedBanner + tray "지금 AI 처리" + ai_retry_manual telemetry. roadmap §3 #2 deviation 1건 (timeout) 의식적. |
