@gaonjs/cli 0.41.6 → 0.42.0

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/commands/check.js

@@ -30,7 +30,7 @@ import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { generateTablesDts } from '@gaonjs/data';
 import { generateRoutesDts } from '@gaonjs/web';
-import { runDoctorCommand } from '../doctor.js';
+import { computeDoctorResult } from '../doctor.js';
 import { regenerateGaonOnce, resolveDevLayout } from '../dev.js';
 import { registerTsResolve } from '../tsResolve.js';
 import { listFrontendApps, verifyAppDist } from '../dev/build.js';
@@ -209,9 +209,11 @@ async function verifyBuildOutput(cwd) {
 /** doctor 는 이미 있는 명령을 재사용 — cwd 만 넘긴다. json 은 상위에서. */
 async function runDoctorStep(cwd) {
     try {
-        // runDoctorCommand 는 stdout 에 리포트를 그대로 찍는다. 결과 객체로
-        // 성공/실패를 판단한다.
-        const result = await runDoctorCommand({ cwd, json: false });
+        // computeDoctorResult 는 stdout 에 아무것도 쓰지 않고 결과만 돌려준다.
+        // runDoctorCommand 는 사람용 리포트를 stdout 에 직접 찍어 `gaon check --json`
+        // 의 순수 JSON 출력을 오염시켰다(mcp 의 parseJsonTail 우회가 방증). check 는
+        // 결과 객체만 필요하므로 무출력 경로를 쓴다(결정 269 · "--json = 파싱 안전").
+        const result = await computeDoctorResult({ cwd });
         const failed = !!result.fatal || result.errors.length > 0;
         return {
             step: 'doctor',

package/dist/commands/test.d.ts

@@ -3,6 +3,14 @@ export interface TestCommandOptions {
     readonly cwd?: string;
     readonly json?: boolean;
     readonly scope?: TestScope;
+    /**
+     * 프로그램 호출(MCP run_tests)용 출력 싱크. 지정되면 자식(vitest·test 스크립트)
+     * stdout/stderr 를 상속(inherit) 대신 파이프로 이 콜백에 흘린다 — 결과를 도구
+     * 응답에 담기 위함. CLI 경로(미지정)는 종전대로 `stdio:'inherit'`. 이 옵션으로
+     * MCP 가 `gaon test` 하네스(테스트 DB 프로비저닝·GAON_STREAM_PREFIX 격리·사용자
+     * test 스크립트 우선)를 그대로 거치게 한다(결정 270 · vitest 직접 spawn 우회 제거).
+     */
+    readonly onOutput?: (chunk: string) => void;
 }
 /**
  * `gaon test` 진입점. args 는 사용자가 넘긴 잔여 인자(필터 문자열 등).

package/dist/commands/test.js

@@ -67,7 +67,21 @@ function scopeArgs(scope) {
  * scope='unit' 은 실 인프라가 필요 없으므로 건너뛴다. config 가 없거나 db 커넥션이
  * 없으면 조용히 스킵(순수 vitest 위임). DB 접속 실패는 수리 안내와 함께 실패한다.
  */
-async function provisionTestDatabases(cwd, json) {
+async function provisionTestDatabases(cwd, json, onOutput) {
+    // capture(MCP) 모드는 stdio JSON-RPC 를 오염시키지 않도록 모든 출력을 싱크로
+    // 돌린다 — process.stdout 직접 쓰기 0(결정 270).
+    const writeOut = (s) => {
+        if (onOutput)
+            onOutput(s);
+        else
+            process.stdout.write(s);
+    };
+    const writeErr = (s) => {
+        if (onOutput)
+            onOutput(s);
+        else
+            process.stderr.write(s);
+    };
     registerTsResolve();
     let config;
     try {
@@ -93,7 +107,7 @@ async function provisionTestDatabases(cwd, json) {
             });
             if (res.exitCode !== 0) {
                 if (!json)
-                    process.stderr.write(`  ✗ 테스트 DB '${key}' 마이그레이션 실패\n${res.text}\n`);
+                    writeErr(`  ✗ 테스트 DB '${key}' 마이그레이션 실패\n${res.text}\n`);
                 return false;
             }
             prepared.push(key);
@@ -104,18 +118,18 @@ async function provisionTestDatabases(cwd, json) {
         const hint = `  ✗ 테스트 DB 준비 실패: ${msg}\n` +
             `  → DB 가 떠 있는지 확인하세요(docker compose up -d db). 테스트는 실 인프라가 필요합니다(§9).\n`;
         if (json)
-            process.stdout.write(JSON.stringify({ ok: false, kind: 'provision', error: msg }) + '\n');
+            writeOut(JSON.stringify({ ok: false, kind: 'provision', error: msg }) + '\n');
         else
-            process.stderr.write(hint);
+            writeErr(hint);
         return false;
     }
     finally {
         await destroyAllConnections();
     }
     if (json)
-        process.stdout.write(JSON.stringify({ kind: 'provisioned', dbs: prepared }) + '\n');
+        writeOut(JSON.stringify({ kind: 'provisioned', dbs: prepared }) + '\n');
     else
-        process.stdout.write(`  gaon test · 테스트 DB 준비 완료 (${prepared.join(', ')}) — <db>_test\n`);
+        writeOut(`  gaon test · 테스트 DB 준비 완료 (${prepared.join(', ')}) — <db>_test\n`);
     return true;
 }
 /**
@@ -127,9 +141,23 @@ export async function runTestCommand(args = [], opts = {}) {
     const cwd = opts.cwd ?? process.cwd();
     const scope = opts.scope ?? 'all';
     const json = opts.json ?? false;
+    const capture = typeof opts.onOutput === 'function';
+    // capture(MCP) 모드: 모든 출력을 싱크로. 미지정: 종전대로 process.std*.
+    const writeOut = (s) => {
+        if (opts.onOutput)
+            opts.onOutput(s);
+        else
+            process.stdout.write(s);
+    };
+    const writeErr = (s) => {
+        if (opts.onOutput)
+            opts.onOutput(s);
+        else
+            process.stderr.write(s);
+    };
     // 결정 111: unit 이 아니면 실행 전 테스트 DB 를 준비한다(생성 + 마이그레이션).
     if (scope !== 'unit') {
-        const ok = await provisionTestDatabases(cwd, json);
+        const ok = await provisionTestDatabases(cwd, json, opts.onOutput);
         if (!ok)
             return 1;
     }
@@ -151,10 +179,10 @@ export async function runTestCommand(args = [], opts = {}) {
             const msg = `vitest 가 설치돼 있지 않고 package.json 에 "test" 스크립트도 없습니다.\n` +
                 `→ pnpm add -D vitest 후 다시 실행하거나, package.json 에 "test": "vitest run" 을 추가하세요.`;
             if (json) {
-                process.stdout.write(JSON.stringify({ ok: false, error: msg }) + '\n');
+                writeOut(JSON.stringify({ ok: false, error: msg }) + '\n');
             }
             else {
-                process.stderr.write(`  ✗ ${msg}\n`);
+                writeErr(`  ✗ ${msg}\n`);
             }
             return 127;
         }
@@ -168,20 +196,25 @@ export async function runTestCommand(args = [], opts = {}) {
     // 값을 세팅했으면 존중한다(고급 · 다중 테스트 컨텍스트 분리).
     const testEnv = { ...process.env, GAON_STREAM_PREFIX: process.env.GAON_STREAM_PREFIX ?? 'test' };
     if (json) {
-        process.stdout.write(JSON.stringify({ kind: 'starting', cmd, args: spawnArgs, scope, streamPrefix: testEnv.GAON_STREAM_PREFIX }) + '\n');
+        writeOut(JSON.stringify({ kind: 'starting', cmd, args: spawnArgs, scope, streamPrefix: testEnv.GAON_STREAM_PREFIX }) + '\n');
     }
     else {
-        process.stdout.write(`  gaon test · ${cmd} ${spawnArgs.join(' ')} (scope=${scope})\n`);
+        writeOut(`  gaon test · ${cmd} ${spawnArgs.join(' ')} (scope=${scope})\n`);
     }
     const exitCode = await new Promise((resolvePromise) => {
+        // capture(MCP) 모드는 자식 출력을 파이프로 모아 싱크로 흘린다(도구 응답에 담기).
+        // CLI 경로(미지정)는 vitest 컬러 출력·리포터를 그대로 보이게 stdio 를 상속한다.
         const child = spawn(cmd, spawnArgs, {
             cwd,
             env: testEnv,
-            // vitest 컬러 출력·리포터를 그대로 보여주기 위해 stdio 를 상속한다.
-            stdio: 'inherit',
+            stdio: capture ? ['ignore', 'pipe', 'pipe'] : 'inherit',
         });
+        if (capture) {
+            child.stdout?.on('data', (d) => opts.onOutput(d.toString('utf8')));
+            child.stderr?.on('data', (d) => opts.onOutput(d.toString('utf8')));
+        }
         child.on('error', (err) => {
-            process.stderr.write(`  ✗ gaon test spawn 실패: ${String(err)}\n`);
+            writeErr(`  ✗ gaon test spawn 실패: ${String(err)}\n`);
             resolvePromise(127);
         });
         child.on('close', (code, signal) => {
@@ -195,7 +228,7 @@ export async function runTestCommand(args = [], opts = {}) {
         });
     });
     if (json) {
-        process.stdout.write(JSON.stringify({ kind: 'exited', exitCode }) + '\n');
+        writeOut(JSON.stringify({ kind: 'exited', exitCode }) + '\n');
     }
     return exitCode;
 }

package/dist/db/journal.d.ts

@@ -9,7 +9,14 @@ export interface JournalEntry {
     readonly down_sql: string | null;
     readonly applied_at: Date;
 }
-/** _gaon_migrations 존재 여부. information_schema 조회로 방언 무관. */
+/**
+ * _gaon_migrations 존재 여부. information_schema 조회로 방언 무관.
+ *
+ * count 는 캐스트 없이 뽑는다 — 이전 `count(*)::text` 는 postgres 전용 문법이라
+ * mysql/mariadb 에서 문법 에러를 내며 `gaon db migrate/status/down/reset` 을 전멸시켰다.
+ * pg 는 count 를 bigint(문자열)로, mysql 은 number 로 돌려주므로 `Number()` 로 통일한다
+ * (양 방언 공통 · 결정 268).
+ */
 export declare function journalExists(db: Kysely<any>): Promise<boolean>;
 /**
  * _gaon_migrations 를 만든다(존재하면 no-op). id/kind/applied_at/db_key/

package/dist/db/journal.js

@@ -9,10 +9,17 @@
 // 마이그레이션은 커넥션별로 돈다(§4.5) — 원장도 커넥션 DB 마다 따로 존재한다.
 import { sql } from 'kysely';
 import { MIGRATIONS_TABLE } from '@gaonjs/data';
-/** _gaon_migrations 존재 여부. information_schema 조회로 방언 무관. */
+/**
+ * _gaon_migrations 존재 여부. information_schema 조회로 방언 무관.
+ *
+ * count 는 캐스트 없이 뽑는다 — 이전 `count(*)::text` 는 postgres 전용 문법이라
+ * mysql/mariadb 에서 문법 에러를 내며 `gaon db migrate/status/down/reset` 을 전멸시켰다.
+ * pg 는 count 를 bigint(문자열)로, mysql 은 number 로 돌려주므로 `Number()` 로 통일한다
+ * (양 방언 공통 · 결정 268).
+ */
 export async function journalExists(db) {
     const rows = await sql `
-    select count(*)::text as n
+    select count(*) as n
     from information_schema.tables
     where table_name = ${MIGRATIONS_TABLE}
   `.execute(db);

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { type DevCommandOptions } from "./commands/dev.js";
 import { type ServeCommandOptions } from "./serve.js";
+import { type DbSubcommand, type DbCommandOptions } from "./commands/db.js";
 import { type DoctorRule } from "./doctor.js";
 export { startDev, resolveDevLayout, regenerateGaonOnce, type DevDeps, type DevLayout, type DevApp, type DevEvent, type DevHandle, type RegenDeps, type RegenResult, } from "./dev.js";
 export { runDevCommand, type DevCommandOptions } from "./commands/dev.js";
@@ -72,6 +73,16 @@ export interface ParsedNewArgs {
  * npm 이 프로젝트 이름으로 오인되지 않도록(결정 167 · O-1 근본 fix).
  */
 export declare function parseNewArgs(rest: readonly string[]): ParsedNewArgs;
+/**
+ * `gaon db <sub>` 의 인자를 파싱한다(argv = 전체 · argv[0]='db', argv[1]=sub).
+ *
+ * 방향 토큰 `down` 은 **위치 인자**다 — 값 플래그(`--db`/`--config <값>`)와 불리언
+ * 플래그를 건너뛰고 판별한다. 이전엔 `argv[2] === 'down'` 고정 위치로만 봐서
+ * `gaon db migrate --db X down` 처럼 플래그가 앞서면 down 을 놓치고 정방향 migrate 로
+ * 조용히 반전됐다(파괴 방향 오동작 · 결정 267). 위치로 훑어 순서와 무관하게
+ * 정확히 롤백으로 인식한다.
+ */
+export declare function parseDbArgs(sub: DbSubcommand, argv: readonly string[]): DbCommandOptions;
 /**
  * `--port <값>` 플래그를 읽어 검증한다(serve·dev 공용). 플래그가 없으면
  * undefined(기본 포트 폴백). 플래그는 있는데 값이 없거나(마지막 토큰) 다른

package/dist/index.js

@@ -197,6 +197,42 @@ export function parseNewArgs(rest) {
     }
     return { name, unknownPm: pmRaw === undefined || pmRaw === "" ? undefined : pmRaw };
 }
+/**
+ * `gaon db <sub>` 의 인자를 파싱한다(argv = 전체 · argv[0]='db', argv[1]=sub).
+ *
+ * 방향 토큰 `down` 은 **위치 인자**다 — 값 플래그(`--db`/`--config <값>`)와 불리언
+ * 플래그를 건너뛰고 판별한다. 이전엔 `argv[2] === 'down'` 고정 위치로만 봐서
+ * `gaon db migrate --db X down` 처럼 플래그가 앞서면 down 을 놓치고 정방향 migrate 로
+ * 조용히 반전됐다(파괴 방향 오동작 · 결정 267). 위치로 훑어 순서와 무관하게
+ * 정확히 롤백으로 인식한다.
+ */
+export function parseDbArgs(sub, argv) {
+    const dbIdx = argv.indexOf("--db");
+    const cfgIdx = argv.indexOf("--config");
+    const valueFlags = new Set(["--db", "--config"]);
+    const positionals = [];
+    for (let i = 2; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === undefined)
+            continue;
+        if (valueFlags.has(a)) {
+            i++; // 플래그 값 스킵
+            continue;
+        }
+        if (a.startsWith("--"))
+            continue; // 불리언 플래그
+        positionals.push(a);
+    }
+    return {
+        json: argv.includes("--json"),
+        db: dbIdx >= 0 ? argv[dbIdx + 1] : undefined,
+        config: cfgIdx >= 0 ? argv[cfgIdx + 1] : undefined,
+        yes: argv.includes("--yes"),
+        dryRun: argv.includes("--dry-run"),
+        // `gaon db migrate down` — 위치 인자로 롤백 지시(순서 무관).
+        down: sub === "migrate" && positionals.includes("down"),
+    };
+}
 /**
  * `--port <값>` 플래그를 읽어 검증한다(serve·dev 공용). 플래그가 없으면
  * undefined(기본 포트 폴백). 플래그는 있는데 값이 없거나(마지막 토큰) 다른
@@ -447,17 +483,7 @@ export function runCli(argv, opts = {}) {
             process.exitCode = 1;
             return;
         }
-        const dbIdx = argv.indexOf("--db");
-        const cfgIdx = argv.indexOf("--config");
-        const dbOpts = {
-            json: argv.includes("--json"),
-            db: dbIdx >= 0 ? argv[dbIdx + 1] : undefined,
-            config: cfgIdx >= 0 ? argv[cfgIdx + 1] : undefined,
-            yes: argv.includes("--yes"),
-            dryRun: argv.includes("--dry-run"),
-            // `gaon db migrate down` — 위치 인자로 롤백 지시.
-            down: sub === "migrate" && argv[2] === "down",
-        };
+        const dbOpts = parseDbArgs(sub, argv);
         void runDbCommand(sub, dbOpts)
             .then((code) => {
             process.exitCode = code;
@@ -616,6 +642,18 @@ export function runCli(argv, opts = {}) {
         });
         return;
     }
+    // 결정 266: 미지 명령은 로드맵 배너로 조용히 성공(exit 0)하지 않는다 — `gaon serv`·
+    // `gaon migrate` 같은 오타가 성공 종료로 오판되면 CI·AI 가 실패를 못 본다.
+    // argv[0] 가 있으면서 어떤 명령·플래그와도 안 맞으면(플래그는 `-` 접두라
+    // help/version/json 폴백이 처리) 여기서 fail-loud(§7.5.3). 인자 없는 `gaon`
+    // (argv[0] 미존재)은 종전대로 로드맵 배너를 낸다.
+    if (argv[0] !== undefined && !argv[0].startsWith("-")) {
+        process.stderr.write(`  ✗ 알 수 없는 명령: ${argv[0]}\n` +
+            `  → 지원 명령: dev · serve · check · gen · build · doctor · mcp · hub · work · jobs · db · g · new · console · test\n` +
+            `  → 전체 사용법: gaon --help\n`);
+        process.exitCode = 1;
+        return;
+    }
     if (argv.includes("--help") || argv.includes("-h")) {
         process.stdout.write(renderHelp(version) + "\n");
         return;

package/dist/mcp/tools.d.ts

@@ -54,10 +54,14 @@ export declare function getSchemaTool(args: ToolArgs, cwd: string): Promise<Tool
  */
 export declare function runMigrationTool(args: ToolArgs, cwd: string): Promise<ToolResult>;
 /**
- * `run_tests` — 프로젝트 테스트를 실 실행한다(§9 · vitest spawn).
+ * `run_tests` — 프로젝트 테스트를 정본 `gaon test` 하네스로 실행한다(§9).
  *
- * `gaon test` 와 같은 경로를 쓰되, MCP 컨텍스트에서는 stdout 을 파이프로
- * 캡처해서 결과를 도구 응답에 담아 돌려준다(자식이 종료할 때까지 대기).
+ * 결정 270: 이전엔 여기서 `vitest run` 을 **직접 spawn** 해 `gaon test`(runTestCommand)의
+ * 세 가지 필수 거동을 전부 우회했다 — ① `<db>_test` 프로비저닝(결정 111) ② NATS
+ * `GAON_STREAM_PREFIX` 격리(결정 130) ③ 사용자 `test` 스크립트 우선(결정 170). 주석은
+ * "같은 경로" 라 주장했으나 거짓이었다. 이제 runTestCommand 에 위임하고, MCP(stdio
+ * JSON-RPC) 컨텍스트라 자식·프로비저닝 출력을 `onOutput` 싱크로 모아 도구 응답에
+ * 담는다(process.stdout 오염 0 — 트랜스포트 보호).
  *
  * 인자:
  *   { scope?: 'unit'|'integration'|'all', filter?: string }
@@ -65,8 +69,8 @@ export declare function runMigrationTool(args: ToolArgs, cwd: string): Promise<T
  *      filter — vitest 위치 인자(파일 패턴 substring)
  *
  * 반환:
- *   data: { exitCode, scope, filter, output }
- *   text: vitest 자체 출력(사람 UI 그대로)
+ *   data: { ok, exitCode, scope, filter, output }
+ *   text: gaon test 출력(프로비저닝 + vitest · 사람 UI 그대로)
  */
 export declare function runTestsTool(args: ToolArgs, cwd: string): Promise<ToolResult>;
 /**

package/dist/mcp/tools.js

@@ -32,6 +32,7 @@ import { join, resolve as resolvePath } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { registerTsResolve } from '../tsResolve.js';
 import { runDbMigrate } from '../db/migrate.js';
+import { runTestCommand } from '../commands/test.js';
 import { scanSchemaDir, columns } from '@gaonjs/data';
 // ── 유틸 ────────────────────────────────────────────────────
 /** 문자열 옵션 안전 추출. */
@@ -276,10 +277,14 @@ export async function runMigrationTool(args, cwd) {
 }
 // ── 도구 4: run_tests ────────────────────────────────────────
 /**
- * `run_tests` — 프로젝트 테스트를 실 실행한다(§9 · vitest spawn).
+ * `run_tests` — 프로젝트 테스트를 정본 `gaon test` 하네스로 실행한다(§9).
  *
- * `gaon test` 와 같은 경로를 쓰되, MCP 컨텍스트에서는 stdout 을 파이프로
- * 캡처해서 결과를 도구 응답에 담아 돌려준다(자식이 종료할 때까지 대기).
+ * 결정 270: 이전엔 여기서 `vitest run` 을 **직접 spawn** 해 `gaon test`(runTestCommand)의
+ * 세 가지 필수 거동을 전부 우회했다 — ① `<db>_test` 프로비저닝(결정 111) ② NATS
+ * `GAON_STREAM_PREFIX` 격리(결정 130) ③ 사용자 `test` 스크립트 우선(결정 170). 주석은
+ * "같은 경로" 라 주장했으나 거짓이었다. 이제 runTestCommand 에 위임하고, MCP(stdio
+ * JSON-RPC) 컨텍스트라 자식·프로비저닝 출력을 `onOutput` 싱크로 모아 도구 응답에
+ * 담는다(process.stdout 오염 0 — 트랜스포트 보호).
  *
  * 인자:
  *   { scope?: 'unit'|'integration'|'all', filter?: string }
@@ -287,8 +292,8 @@ export async function runMigrationTool(args, cwd) {
  *      filter — vitest 위치 인자(파일 패턴 substring)
  *
  * 반환:
- *   data: { exitCode, scope, filter, output }
- *   text: vitest 자체 출력(사람 UI 그대로)
+ *   data: { ok, exitCode, scope, filter, output }
+ *   text: gaon test 출력(프로비저닝 + vitest · 사람 UI 그대로)
  */
 export async function runTestsTool(args, cwd) {
     const scope = (stringOpt(args, 'scope') ?? 'all');
@@ -296,39 +301,17 @@ export async function runTestsTool(args, cwd) {
     if (!['unit', 'integration', 'all'].includes(scope)) {
         return errorResult(`scope 는 'unit' | 'integration' | 'all' 중 하나여야 합니다. 입력값: '${scope}'`);
     }
-    // scopeArgs 는 test.ts 와 동일 규칙을 재구성한다 — 순환 import 를 피하려고
-    // 여기서 직접 계산한다(관례는 test.ts scopeArgs 와 정합).
-    const scopeExtras = scope === 'unit'
-        ? ['--exclude', '**/*.integration.test.ts']
-        : scope === 'integration'
-            ? ['integration.test']
-            : [];
-    const passthrough = [...scopeExtras, ...(filter ? [filter] : [])];
-    // 실행 경로: 로컬 vitest 바이너리 우선. 없으면 에러 안내.
-    const vitestBin = join(resolvePath(cwd), 'node_modules', '.bin', 'vitest');
-    if (!existsSync(vitestBin)) {
-        return errorResult(`vitest 가 설치돼 있지 않습니다: ${vitestBin}\n` +
-            `→ 프로젝트에서 \`pnpm add -D vitest\` 후 다시 시도하세요.`);
-    }
-    const child = spawn(vitestBin, ['run', ...passthrough], {
+    let output = '';
+    const exitCode = await runTestCommand(filter ? [filter] : [], {
         cwd,
-        env: process.env,
-        stdio: ['ignore', 'pipe', 'pipe'],
-    });
-    let stdout = '';
-    let stderr = '';
-    child.stdout.on('data', (d) => {
-        stdout += d.toString('utf8');
-    });
-    child.stderr.on('data', (d) => {
-        stderr += d.toString('utf8');
-    });
-    const exitCode = await new Promise((resolveExit) => {
-        child.on('close', (code) => resolveExit(code ?? 1));
+        scope,
+        json: false,
+        onOutput: (chunk) => {
+            output += chunk;
+        },
     });
-    const output = stdout + (stderr ? `\n[stderr]\n${stderr}` : '');
     return {
-        text: output || `(vitest 출력 없음 · exit ${exitCode})`,
+        text: output || `(gaon test 출력 없음 · exit ${exitCode})`,
         data: {
             ok: exitCode === 0,
             exitCode,

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/data.md.tpl

@@ -216,7 +216,7 @@ export const posts = table('posts', {
 | `having` | `('count', op, val)` · `('sum'\|'avg'\|'min'\|'max', col, op, val)` | `GroupChain` | groupBy 뒤 **집계값** 필터 (그룹 키 필터는 `where`). `.having('count', '>', 2)` · `.having('sum', 'price', '>=', 1000)` |
 | `distinct` | `()` · `(col \| col[])` | `Chain` · `SelectChain` | 인자 없으면 `SELECT DISTINCT` 전체 행(집계·벌크 쓰기 이어짐), 컬럼을 주면 그 컬럼만 뽑는 `SelectChain`. `distinct().count()` 는 `count(distinct id)` |
 | `withCount` | `(...rels)` | `IncludedChain` | 관계별 개수를 **상관 서브쿼리**로 얹는다 — `withCount('comments')` → 각 Rec 에 `commentsCount: bigint`. 조인이 아니라 행이 안 늘어 `limit` 과 함께 써도 개수가 정확. **hasMany·hasOne·belongsToMany 만**(belongsTo 는 항상 0/1 이라 throw). `include` 와 같은 체인에 실린다(`include('author').withCount('comments')`) |
-| `join` | `(table, 'table.col', 'self.col')` | `JoinChain` | INNER JOIN — **필터·정렬 수단**이고 반환은 **자기 테이블의 Rec**(조인 테이블 컬럼은 안 실림 → 뽑아야 하면 §5 `Post.query()`). 조인 테이블 조건은 한정 이름(`where('users.name', '=', ...)`), 1:N 부풀림은 `distinct()` 로 접는다. `join`/`leftJoin`·`where`·`orderBy`·`distinct`·`select`·`pluck`·`count`·`exists`·`first`·`all` 이어짐 |
+| `join` | `(table, 'table.col', 'self.col')` | `JoinChain` | INNER JOIN — **필터·정렬 수단**이고 반환은 **자기 테이블의 Rec**(조인 테이블 컬럼은 안 실림 → 뽑아야 하면 §5 `Post.query()`). **자기 테이블 컬럼은 한정 없이 그대로** 쓴다 — `t.timestamps()`·`t.id()` 로 양 테이블이 `createdAt`·`id` 를 공유해도 조인 시 자기 테이블로 자동 한정돼 `where('createdAt', ..)` 가 안전하다(ambiguous column 방지). **조인 테이블** 조건만 한정 이름(`where('users.name', '=', ...)`)으로 쓴다. 1:N 부풀림은 `distinct()` 로 접는다. `join`/`leftJoin`·`where`·`orderBy`·`distinct`·`select`·`pluck`·`count`·`exists`·`first`·`all` 이어짐 |
 | `leftJoin` | `(table, 'table.col', 'self.col')` | `JoinChain` | LEFT OUTER JOIN — 짝 없는 자기 행도 남는다. "짝 없는 것만" = `.where('posts.id', 'is null')` |
 
 > 조인 노출은 정본 결정 28 게이트 (f)(원안 = 기각·`Post.query()` 로만)를

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.42.0",
   "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.7",
     "@gaonjs/core": "0.2.4",
+    "@gaonjs/data": "0.17.2",
     "@gaonjs/i18n": "0.2.3",
-    "@gaonjs/data": "0.17.1",
     "@gaonjs/mail": "0.3.1",
-    "@gaonjs/web": "0.20.0"
+    "@gaonjs/web": "0.20.2"
   },
   "scripts": {
     "build": "node ../../node_modules/typescript/bin/tsc -p tsconfig.json && node -e \"require('fs').cpSync('src/templates','dist/templates',{recursive:true})\""