@gaonjs/cli 0.41.6 → 0.41.7

package/dist/cluster.d.ts

@@ -0,0 +1,38 @@
+export interface ReforkPolicy {
+    /** 이 시간 이상 산 워커의 죽음은 '정상 교체'로 보고 즉시 refork·streak 리셋. */
+    readonly minHealthyMs: number;
+    /** 첫 백오프(ms). 이후 연속 부팅 크래시마다 2배. */
+    readonly baseMs: number;
+    /** 백오프 상한(ms). */
+    readonly maxMs: number;
+}
+/** 연속 부팅 크래시 streak 에 대한 백오프 지연(ms). streak≤0 이면 0(즉시). */
+export declare function reforkDelayMs(streak: number, p: Pick<ReforkPolicy, 'baseMs' | 'maxMs'>): number;
+export interface ReforkDeps {
+    /** 새 워커를 fork 한다. */
+    fork(): void;
+    /** delayMs 후 fn 을 실행할 타이머를 건다. 취소 함수를 반환한다. */
+    schedule(fn: () => void, delayMs: number): () => void;
+    /** 현재 시각(ms). */
+    now(): number;
+    /** 백오프 결정 통지(로깅용). delayMs=0 은 즉시 refork. */
+    onBackoff?(info: {
+        delayMs: number;
+        streak: number;
+    }): void;
+}
+export interface ReforkSupervisor {
+    /** 워커가 예기치 않게 죽었을 때 호출. forkedAt = 그 워커를 fork 한 시각. */
+    onCrash(forkedAt: number): void;
+    /** 대기 중인 백오프 refork 타이머를 모두 취소한다(종료 시). */
+    cancelAll(): void;
+    /** 현재 연속 부팅 크래시 streak(테스트·진단). */
+    readonly streak: number;
+}
+/**
+ * 재fork 감독자를 만든다. cluster 를 직접 만지지 않아 결정적으로 테스트할 수 있다
+ * (fork·schedule·now 를 주입). runClusterPrimary 가 실제 cluster 이벤트를 여기 연결한다.
+ */
+export declare function createReforkSupervisor(policy: ReforkPolicy, deps: ReforkDeps): ReforkSupervisor;
+/** 환경변수에서 재fork 정책을 읽는다(비수치·비양수는 기본값으로 폴백). */
+export declare function reforkPolicyFromEnv(env?: NodeJS.ProcessEnv): ReforkPolicy;

package/dist/cluster.js

@@ -0,0 +1,68 @@
+// @gaonjs/cli · 클러스터 워커 재fork 백오프 (A5 · FINAL-AUDIT-2026-08-04 · 결정 261)
+//
+// `cluster.on('exit')` 가 무조건 즉시 refork 하면, 워커가 부팅 자체를 못 할 때
+// (무효 설정 → 결정 252 로 워커가 부팅 직후 exit1) 무한 고속 crash-loop 폭주가
+// 난다(실측: --workers 2 · 무효 PORT 로 5초에 refork 16회 · 평균 간격 236ms).
+// 정책: 워커가 **짧게 살고 죽으면**(부팅 크래시) 지수 백오프로 refork 를 늦추고,
+// **충분히 오래 산 뒤 죽으면**(정상 교체) 즉시 refork 한다 — 정상 워커 교체 지연 0.
+// 백오프는 상한(maxMs)에서 멈춘다. 253/252 의 단일 프로세스 확정 종료가 클러스터
+// 감독까지 미치지 못하던 공백을 메운다.
+/** 연속 부팅 크래시 streak 에 대한 백오프 지연(ms). streak≤0 이면 0(즉시). */
+export function reforkDelayMs(streak, p) {
+    if (streak <= 0)
+        return 0;
+    return Math.min(p.baseMs * 2 ** (streak - 1), p.maxMs);
+}
+/**
+ * 재fork 감독자를 만든다. cluster 를 직접 만지지 않아 결정적으로 테스트할 수 있다
+ * (fork·schedule·now 를 주입). runClusterPrimary 가 실제 cluster 이벤트를 여기 연결한다.
+ */
+export function createReforkSupervisor(policy, deps) {
+    let streak = 0;
+    const cancels = new Set();
+    return {
+        onCrash(forkedAt) {
+            const uptime = deps.now() - forkedAt;
+            let delayMs;
+            if (uptime >= policy.minHealthyMs) {
+                streak = 0; // 정상 교체 — 페널티 없음
+                delayMs = 0;
+            }
+            else {
+                streak += 1;
+                delayMs = reforkDelayMs(streak, policy);
+            }
+            deps.onBackoff?.({ delayMs, streak });
+            if (delayMs <= 0) {
+                deps.fork();
+                return;
+            }
+            let cancel = () => { };
+            cancel = deps.schedule(() => {
+                cancels.delete(cancel);
+                deps.fork();
+            }, delayMs);
+            cancels.add(cancel);
+        },
+        cancelAll() {
+            for (const c of cancels)
+                c();
+            cancels.clear();
+        },
+        get streak() {
+            return streak;
+        },
+    };
+}
+/** 환경변수에서 재fork 정책을 읽는다(비수치·비양수는 기본값으로 폴백). */
+export function reforkPolicyFromEnv(env = process.env) {
+    const num = (v, d) => {
+        const n = Number(v);
+        return Number.isFinite(n) && n > 0 ? n : d;
+    };
+    return {
+        minHealthyMs: num(env.GAON_WORKER_MIN_HEALTHY_MS, 10_000),
+        baseMs: num(env.GAON_WORKER_REFORK_BASE_MS, 1_000),
+        maxMs: num(env.GAON_WORKER_REFORK_MAX_MS, 30_000),
+    };
+}

package/dist/serve.js

@@ -20,6 +20,7 @@ import { loadGaonConfig, wireGaon, findConfigPath } from '@gaonjs/config';
 import { registerTsResolve } from './tsResolve.js';
 import { parsePort } from './port.js';
 import { computeHealth, DEV_HEALTH_PATH } from './dev/health.js';
+import { createReforkSupervisor, reforkPolicyFromEnv } from './cluster.js';
 /**
  * 워커 수를 결정한다: 옵션 > env `WEB_CONCURRENCY` > 1. `'auto'` = 코어 수
  * (availableParallelism). 0·음수·비수치는 1 로 떨어진다(안전 기본). 결정 84.
@@ -48,6 +49,8 @@ function humanEvent(e) {
             return `  gaon serve · 클러스터 — 워커 ${e.workers}개 fork (node:cluster)`;
         case 'worker-exit':
             return `  ⚠ 워커 종료(pid ${e.pid ?? '?'} · code ${e.code}${e.signal ? ` · ${e.signal}` : ''})${e.restarted ? ' — 교체 fork' : ''}`;
+        case 'worker-backoff':
+            return `  ⏳ 워커 부팅 크래시 반복(streak ${e.streak}) — ${Math.round(e.delayMs / 100) / 10}s 후 교체 fork (crash-loop 백오프)`;
         case 'stopping':
             return '  gaon serve · 종료 중 (graceful) ...';
         case 'stopped':
@@ -71,14 +74,36 @@ async function runClusterPrimary(workerCount, opts) {
     };
     emit({ kind: 'cluster', workers: workerCount });
     let shuttingDown = false;
+    // A5(결정 261): 재fork 백오프. 워커별 fork 시각을 추적해, 부팅 직후 죽는(짧은 수명) 크래시는
+    // 지수 백오프로 늦추고 정상 워커 교체는 즉시 처리한다. 감독 로직은 createReforkSupervisor 로
+    // 분리(cluster 미의존 · 결정적 테스트 가능). fork 는 이 감독자만 수행한다.
+    const forkedAt = new Map();
+    const doFork = () => {
+        const w = cluster.fork();
+        forkedAt.set(w.id, Date.now());
+    };
+    const supervisor = createReforkSupervisor(reforkPolicyFromEnv(), {
+        fork: doFork,
+        schedule: (fn, delayMs) => {
+            const timer = setTimeout(fn, delayMs);
+            return () => clearTimeout(timer);
+        },
+        now: () => Date.now(),
+        onBackoff: ({ delayMs, streak }) => {
+            if (delayMs > 0)
+                emit({ kind: 'worker-backoff', delayMs, streak });
+        },
+    });
     for (let i = 0; i < workerCount; i++)
-        cluster.fork();
+        doFork();
     cluster.on('exit', (worker, code, signal) => {
         if (shuttingDown)
             return;
-        // 예기치 않은 종료 → 교체 fork 로 워커 수를 유지한다.
+        const at = forkedAt.get(worker.id) ?? Date.now();
+        forkedAt.delete(worker.id);
+        // 예기치 않은 종료 → 교체 fork(백오프 정책에 따라 즉시 또는 지연)로 워커 수를 유지한다.
         emit({ kind: 'worker-exit', pid: worker.process.pid, code, signal, restarted: true });
-        cluster.fork();
+        supervisor.onCrash(at);
     });
     await new Promise((resolvePromise) => {
         const stop = () => {
@@ -88,6 +113,8 @@ async function runClusterPrimary(workerCount, opts) {
             signals.off('SIGINT', stop);
             signals.off('SIGTERM', stop);
             emit({ kind: 'stopping' });
+            // 대기 중인 백오프 refork 타이머를 취소한다 — 종료 중 새 워커가 뜨지 않게(결정 261).
+            supervisor.cancelAll();
             for (const w of Object.values(cluster.workers ?? {}))
                 w?.kill('SIGTERM');
             const killTimer = setTimeout(() => {

package/dist/templates/project/agents/async.md.tpl

@@ -86,6 +86,10 @@ await SendWelcomeMail.at(someDate, user.id) // 특정 시각 실행
   `curve`(백오프 곡선 ms) · `jitter` · `concurrency`.
 - **실패** — 재시도를 소진하면 DLQ 로 간다. `gaon jobs list --failed` ·
   `gaon jobs retry <id>` 로 조회·재적재한다.
+- **워커 복원력(결정 258)** — 재시도 재적재나 DLQ 이관을 하는 도중 NATS 가
+  순단해 발행 자체가 실패해도, 워커의 큐 소비 루프는 **멈추지 않는다**. 그 잡은
+  ack/DLQ 하지 않고 되돌려(재전달 백스톱) 유실을 막고, 실패는 로그로 남긴다 —
+  한 잡의 인프라 순단이 큐 전체를 조용히 세우지 않는다.
 - **실행 컨텍스트(결정 129)** — `gaon work` 는 `gaon serve` 와 **같은 도메인
   배선**(DB 커넥션 · 메일)을 태운다. 그래서 잡 핸들러에서 모델 조회(`User.find`),
   `Mail.deliver`, `broadcast`, 다른 잡 `.later()` 를 웹 컨트롤러에서와 똑같이 쓴다
@@ -413,4 +417,5 @@ async create() {
 | 결정 230 | 스케줄러/앱 시간대 = `gaon.config.ts` 의 `timezone` → `process.env.TZ`(config 가 런치 `TZ` 보다 우선 · 앱 전역 단일 타임존 · §5) |
 | 결정 233 | 크론 리더 페일오버 중복 발행 dedupe (결정론적 dedupe 키 + JetStream 중복 윈도우로 틱당 1회 발행 수렴 · §5) |
 | 결정 211 | `gaon dev` all-in-one — serve·work·hub 자동 기동 · dev 워커 동시성 4(`GAON_WORKER_CONCURRENCY`) · `--no-work`/`--no-hub` (§6) |
+| 결정 258 | 워커 소비 루프 복원력(§1) — 재시도/DLQ 발행이 NATS 순단으로 실패해도 큐 소비가 멈추지 않음(nak 재전달 백스톱 · 잡 유실 방지 · 실패 로그) |
 | §7 | 비동기 배터리 원문 (백오프 기본값 = M7 벤치마크 확정) |

package/dist/templates/project/agents/realtime.md.tpl

@@ -80,6 +80,12 @@ export default channel({
 
 멤버 식별자는 로그인 사용자면 `user:<id>`, 익명이면 `conn:<uuid>` 다.
 
+**핸들러가 throw 하면 그 연결만 닫힌다(결정 257).** `onMessage`/`onLeave` 안에서
+예외(코드 결함·DB 순단)가 나도 **서버는 죽지 않는다** — HTTP 액션이 500 으로
+마감되는 것과 대칭으로, 그 연결에 에러 프레임을 보내고 닫는다(다른 연결·서버는
+그대로 산다). 즉 `onMessage` 예외는 전역 장애가 아니라 연결 단위 장애다. 재시도가
+필요한 로직은 핸들러 안에서 try/catch 로 감싸 직접 통제한다.
+
 ### 2.5 서버 개시 broadcast (결정 126)
 
 `ctx.broadcast` 는 클라이언트 연결 훅(`onJoin`/`onMessage`/`onLeave`) **안에서만** 쓸 수 있다 —
@@ -233,6 +239,15 @@ export function useRoom(roomId: number) {
   겹친다 — 인스턴스마다 다른 `GAON_HUB_PORT` 를 주거나 호스트를 분리한다.
   `gaon dev` 는 내장 허브를 기본 포트로 띄우므로, 같은 호스트에서 별도
   `gaon hub` 를 돌릴 땐 포트를 바꾼다.
+- **디스커버리 endpoint 는 소유 리더만 지운다(결정 259).** standby 인스턴스의
+  정상 종료나 리더 교대가 **활성 리더의** 도달 주소(KV `gaon_hub/endpoint`)를
+  지우지 않는다 — 그렇지 않으면 재접속하는 웹서버가 허브를 못 찾고 무한
+  백오프에 빠진다. 삭제는 저장된 주소가 자기 것일 때 + revision CAS 로만
+  일어나, 롤링 재시작 중에도 디스커버리가 살아 있다.
+- **리스 TTL 은 역할별로 독립이다(결정 260).** 허브(`GAON_HUB_TTL_MS`)와
+  스케줄러(고정 5s)는 서로 다른 KV 버킷(`gaon_lease_<역할>`)을 써 각자 TTL 을
+  가진다 — 한 버킷을 공유하던 시절의 TTL 플래핑(부팅 순서 의존)이 없다.
+  허브 TTL 을 튜닝해도 스케줄러 failover 타이밍에 영향을 주지 않는다.
 
 ## 정본 예시
 
@@ -311,6 +326,9 @@ export default channel({
 | 결정 207 | 허브 fail-fast(§5) — 리스는 얻고 TCP 포트 bind 실패 시 좀비 리더 대신 리스 사임 + `process.exit(1)`(F-13 fix · `onFatal` 훅으로 주입 가능) |
 | 결정 225 | 프레즌스 연결 축 refcount(§3) — 같은 멤버의 멀티탭·멀티서버 연결을 refcount 해 마지막 연결에서만 이탈 · cleanupServer 는 그 서버 연결만 회수(타서버 불간섭) |
 | 결정 227 | 특정/다중 유저 타겟 발송(§2.6) — `sendToUsers(name, userIds, data)` · `broadcast` 와 대칭 · 대상 연결에만 전달(멀티서버·멀티탭) · 도달 유저 수 반환(오프라인=0) · 수정 1 연결 추적 위에 얹음 |
+| 결정 257 | 채널 `onMessage`/`onLeave` throw 는 그 연결만 마감(§2.4) — 사용자 핸들러 예외가 unhandledRejection 으로 serve 를 죽이지 않는다(HTTP 500 대칭 · 에러 프레임 + 연결 종료) |
+| 결정 259 | 허브 디스커버리 endpoint 는 소유 리더만 삭제(§5) — addr 일치 + revision CAS · standby 종료·리더 교대가 활성 endpoint 를 지우지 않음(재접속 서버 허브 발견 보존) |
+| 결정 260 | 리스 TTL 역할별 독립(§5) — 허브·스케줄러가 `gaon_lease_<역할>` 별도 버킷 · 공유 버킷 MaxAge 플래핑 제거 |
 
 ## `@gaonjs/seal` 켠 앱의 채널
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gaonjs/cli",
-  "version": "0.41.6",
+  "version": "0.41.7",
   "description": "Gaon CLI — 스캐폴딩·제너레이터·마이그레이션·dev/serve/work/hub·doctor·check (bin: gaon)",
   "type": "module",
   "license": "MIT",
@@ -27,13 +27,13 @@
     "@modelcontextprotocol/sdk": "^1.29.0",
     "typescript": "^5.9.0",
     "vite": "^7.0.0",
-    "@gaonjs/async": "0.15.1",
-    "@gaonjs/config": "0.17.5",
+    "@gaonjs/async": "0.15.2",
+    "@gaonjs/config": "0.17.6",
     "@gaonjs/core": "0.2.4",
-    "@gaonjs/i18n": "0.2.3",
     "@gaonjs/data": "0.17.1",
+    "@gaonjs/i18n": "0.2.3",
     "@gaonjs/mail": "0.3.1",
-    "@gaonjs/web": "0.20.0"
+    "@gaonjs/web": "0.20.1"
   },
   "scripts": {
     "build": "node ../../node_modules/typescript/bin/tsc -p tsconfig.json && node -e \"require('fs').cpSync('src/templates','dist/templates',{recursive:true})\""