@cartanova/qgrid-cli 2.10.10 → 2.11.0

package/bundle/src/utils/providers/anthropic/anthropic-constants.ts

@@ -11,12 +11,16 @@
 // claude-api 스킬 확인: Sonnet 4.6 official id = "claude-sonnet-4-6" (날짜 suffix 없음).
 // model-cost 테이블에도 "claude-sonnet-4-6" 키 존재
 export const ANTHROPIC_DEFAULT_MODEL = "claude-sonnet-4-6";
+
 // OpenAI provider 기본값(openai-dispatcher DEFAULT_EFFORT)과 맞춘다. 클라가 effort 미지정 시 안전망.
 export const ANTHROPIC_DEFAULT_EFFORT = "low";
+
 // project scope cwd (settings.json 격리). 토큰별 격리는 CLAUDE_CONFIG_DIR 로 한다.
 export const ANTHROPIC_CLAUDE_CWD = "/tmp/qgrid-anthropic";
+
 // per-token CLAUDE_CONFIG_DIR 의 베이스. 실제 경로는 `${BASE}/${tokenId}` (R10 격리).
 export const ANTHROPIC_CONFIG_DIR_BASE = "/tmp/qgrid-anthropic-config";
+
 // CC 가 자동 활성화하는 deferred 도구 — 토큰 최적화 위해 dispatcher 경로에서 차단.
 export const ANTHROPIC_DISALLOWED_TOOLS = ["Monitor", "PushNotification", "RemoteTrigger"] as const;
 const ONE_MILLION_SUFFIX_RE = /\[1m\]$/i;
@@ -35,6 +39,7 @@ export function anthropicConfigDir(tokenId: number): string {
 export function canonicalAnthropicModel(model?: string): string {
   const raw = model || ANTHROPIC_DEFAULT_MODEL;
   const withoutProvider = raw.includes("/") ? raw.split("/").pop()! : raw;
+
   return withoutProvider.replace(ONE_MILLION_SUFFIX_RE, "");
 }
 
@@ -58,6 +63,7 @@ const ONE_MILLION_CONTEXT_MODELS = new Set([
 ]);
 
 const CLI_ONE_MILLION_SUFFIX_MODELS = new Set(["claude-sonnet-4-6", "claude-opus-4-6"]);
+
 // Preserve these defaults when thinking is omitted. This is not an off-capability list:
 // explicit false supports Opus 5, and native extra-body delivery supports Haiku 5.5
 // (disabled) and Sonnet 5.5 (between_tools). See anthropic-thinking.ts.
@@ -84,6 +90,7 @@ for (const model of CLI_ONE_MILLION_SUFFIX_MODELS) {
     throw new Error(`[invariant] CLI 1M suffix model not in context set: ${model}`);
   }
 }
+
 // Fable 계열은 공식 사양상 1M 기본 컨텍스트 + adaptive thinking 필수다. 새 Fable 버전을 계열 Set
 // 에만 넣고 나머지를 빠뜨리는 실수를 같은 방식으로 모듈 로드 시점에 잡는다.
 for (const model of FABLE_FAMILY_MODELS) {
@@ -114,6 +121,7 @@ export function isFableFamilyModel(model?: string): boolean {
 export function assertSupportedOneMillionSuffix(model?: string): void {
   if (!hasOneMillionSuffix(model)) return;
   const canonical = canonicalAnthropicModel(model);
+
   if (!supports1MContext(canonical)) {
     throw new Error(`Unsupported Anthropic 1M model suffix: ${model}`);
   }

package/bundle/src/utils/providers/anthropic/anthropic-dispatcher.ts

@@ -7,7 +7,7 @@ import { getLogger } from "@logtape/logtape";
 
 import { QuotaThresholdExceededError } from "../../../application/qgrid/qgrid.types";
 import { TokenModel } from "../../../application/token/token.model";
-import { type AnthropicCredentials } from "../../../application/token/token.types";
+import { AnthropicCredentials } from "../../../application/token/token.types";
 import { getExpiresAt, getRefreshToken } from "../common/credentials";
 import {
   type GenerateRequest,
@@ -45,10 +45,18 @@ export class AnthropicDispatcher implements ProviderDispatcher {
     // NOTIFY는 기존 토큰을 재전송하지 않으므로 시작 시 DB에서 읽는다.
     const tokens = await TokenModel.findActiveByProvider("A", "anthropic");
     tokens.forEach((t) => {
+      const credentials = AnthropicCredentials.safeParse(t.credentials);
+
+      if (!credentials.success) {
+        logger.warn(`skipping token ${t.name}: credentials are not Anthropic OAuth credentials`);
+
+        return;
+      }
+
       this.tokenPool.set(t.id, {
         id: t.id,
         name: t.name,
-        credentials: t.credentials as AnthropicCredentials,
+        credentials: credentials.data,
         quotaThreshold: t.quota_threshold,
         weight: t.weight,
       });
@@ -121,13 +129,16 @@ export class AnthropicDispatcher implements ProviderDispatcher {
   async selectToken(model: string, preferredTokenId?: number): Promise<PooledToken | null> {
     const preferred =
       preferredTokenId === undefined ? undefined : this.tokenPool.get(preferredTokenId);
+
     if (preferredTokenId !== undefined && !preferred) {
       throw new Error(`Preferred anthropic token ${preferredTokenId} is not available`);
     }
 
     const rows = preferred ? [preferred] : [...this.tokenPool.values()];
+
     if (rows.length === 0) return null;
     const { eligible, overThresholdTokens } = await this.filterEligibleTokens(rows, model);
+
     if (eligible.length === 0) {
       logger.warn("quota_threshold gate: all_exceeded", {
         provider: "anthropic",
@@ -136,9 +147,11 @@ export class AnthropicDispatcher implements ProviderDispatcher {
         overThresholdTokens,
         reason: "all_exceeded",
       });
+
       const details = overThresholdTokens
         .map((token) => `${token.tokenName} (threshold ${token.threshold}%)`)
         .join(", ");
+
       throw new QuotaThresholdExceededError(
         details
           ? `All anthropic tokens exceeded quota threshold: ${details}`
@@ -149,7 +162,9 @@ export class AnthropicDispatcher implements ProviderDispatcher {
     if (preferred) return preferred;
 
     const selectedId = this.weightedSelector.select(new Set(eligible.map((token) => token.id)));
+
     if (selectedId === null) return null;
+
     return this.tokenPool.get(selectedId) ?? null;
   }
 
@@ -161,12 +176,15 @@ export class AnthropicDispatcher implements ProviderDispatcher {
     overThresholdTokens: Array<{ tokenName: string; threshold: number }>;
   }> {
     const thresholded = rows.filter((token) => this.hasQuotaThreshold(token));
+
     if (thresholded.length === 0) return { eligible: rows, overThresholdTokens: [] };
 
     const eligibleIds = new Set(
-      rows.filter((token) => !this.hasQuotaThreshold(token)).map((token) => token.id),
+      rows.flatMap((token) => (this.hasQuotaThreshold(token) ? [] : [token.id])),
     );
+
     const overThresholdTokens: Array<{ tokenName: string; threshold: number }> = [];
+
     const checks = await Promise.allSettled(
       thresholded.map(async (token) => ({
         token,
@@ -176,11 +194,14 @@ export class AnthropicDispatcher implements ProviderDispatcher {
 
     checks.forEach((check, index) => {
       const token = check.status === "rejected" ? thresholded[index] : check.value.token;
+
       if (!token) return;
+
       const result =
         check.status === "fulfilled"
           ? check.value.result
           : { kind: "lookup_failed" as const, reason: String(check.reason) };
+
       if (result.kind === "lookup_failed") {
         logger.warn("quota_threshold gate: lookup_fail_open", {
           tokenId: token.id,
@@ -191,6 +212,7 @@ export class AnthropicDispatcher implements ProviderDispatcher {
           lookupReason: result.reason,
         });
         eligibleIds.add(token.id);
+
         return;
       }
 
@@ -205,6 +227,7 @@ export class AnthropicDispatcher implements ProviderDispatcher {
           reason: "over_threshold",
         });
         overThresholdTokens.push({ tokenName: token.name, threshold: token.quotaThreshold });
+
         return;
       }
 
@@ -228,7 +251,7 @@ export class AnthropicDispatcher implements ProviderDispatcher {
       cb.onThreadId?.(result.threadCoord.threadId);
       cb.onComplete(result);
     } catch (e) {
-      cb.onError(e as Error);
+      cb.onError(e instanceof Error ? e : new Error(String(e)));
     }
   }
 
@@ -238,10 +261,12 @@ export class AnthropicDispatcher implements ProviderDispatcher {
     opts?: { includePartialMessages?: boolean },
   ): Promise<GenerateResult> {
     this.inFlight++;
+
     try {
       if (req.imageGeneration) {
         throw new Error("image generation is not supported on the Anthropic route");
       }
+
       assertSupportedOneMillionSuffix(req.model);
       const model = canonicalAnthropicModel(req.model);
       const thinking = resolveAnthropicThinking(model, req.thinking, req.effort);
@@ -249,11 +274,13 @@ export class AnthropicDispatcher implements ProviderDispatcher {
       const jsonSchema = serializeAndValidateDispatchSchema(req.outputSchema, "anthropic");
 
       const token = await this.selectToken(model, req.preferredTokenId);
+
       if (!token) throw new Error("No anthropic tokens available");
 
       // 만료 직전에 갱신하되 실패하면 기존 토큰으로 진행한다.
       let accessToken = token.credentials.accessToken;
       const expiresAt = getExpiresAt(token.credentials);
+
       if (
         expiresAt &&
         expiresAt - Date.now() < REFRESH_SAFETY_MS &&
@@ -267,13 +294,16 @@ export class AnthropicDispatcher implements ProviderDispatcher {
             provider: "anthropic",
             name: token.name,
             credentials: token.credentials,
-          } as Parameters<typeof QgridFrame.refreshToken>[0]);
+          });
         } catch (e) {
-          logger.warn(`refresh failed for ${token.name}: ${(e as Error).message}`);
+          logger.warn(
+            `refresh failed for ${token.name}: ${e instanceof Error ? e.message : String(e)}`,
+          );
         }
       }
 
       logger.info(`→ ${token.name} (model: ${model})`);
+
       const session = await runClaudeSession(
         {
           tokenId: token.id,
@@ -294,20 +324,25 @@ export class AnthropicDispatcher implements ProviderDispatcher {
 
       if (session.quotaExhausted) {
         invalidateAnthropicQuotaUsage(token.credentials.accessToken);
+
         if (accessToken !== token.credentials.accessToken) {
           invalidateAnthropicQuotaUsage(accessToken);
         }
+
         throw new Error(`quota exhausted (${token.name})`);
       }
+
       if (session.isError) {
         // 종료 사유를 먼저 표시하고 응답 본문은 진단에 필요한 만큼만 남긴다.
         const reason =
           session.subtype ?? session.terminalReason ?? (session.isError ? "is_error" : "unknown");
+
         const body = session.text
           ? session.text.length > 500
             ? `${session.text.slice(0, 500)}…(${session.text.length} chars)`
             : session.text
           : `empty text, outputTokens=${session.usage.outputTokens}`;
+
         const refusal = session.refusal ? ` refusal=${JSON.stringify(session.refusal)}` : "";
         throw new Error(`claude error (${token.name}) [${reason}]: ${body}${refusal}`);
       }

package/bundle/src/utils/providers/anthropic/anthropic-quota.ts

@@ -16,19 +16,23 @@ export async function readAnthropicQuotaUsage(
 ): Promise<AnthropicQuotaUsageResult> {
   try {
     const { data, cachedAt } = await fetchUsageWithMeta(accessToken);
+
     if (data.error) return { kind: "lookup_failed", reason: data.error };
 
     const utilizations = [data.five_hour?.utilization];
+
     // Fable 계열(5, 5.1)은 5시간 창과 별개로 usage credits 기반 7일 버킷도 소진될 수 있다.
     if (isFableFamilyModel(model)) {
       utilizations.push(data.seven_day_overage_included?.utilization);
     }
+
     const utilization = Math.max(
       ...utilizations.filter(
-        (value): value is number => typeof value === "number" && Number.isFinite(value),
+        (value): value is number => value !== null && value !== undefined && Number.isFinite(value),
       ),
     );
-    if (typeof utilization !== "number" || !Number.isFinite(utilization)) {
+
+    if (!Number.isFinite(utilization)) {
       return { kind: "lookup_failed", reason: "five_hour utilization unavailable" };
     }
 
@@ -38,6 +42,6 @@ export async function readAnthropicQuotaUsage(
       cacheAgeMs: Math.max(Date.now() - cachedAt, 0),
     };
   } catch (e) {
-    return { kind: "lookup_failed", reason: (e as Error).message };
+    return { kind: "lookup_failed", reason: e instanceof Error ? e.message : String(e) };
   }
 }

package/bundle/src/utils/providers/anthropic/anthropic-thinking.ts

@@ -27,6 +27,7 @@ let extraBodyRuntimeSupported: boolean | undefined;
 /** These modes were verified through native extra-body delivery on Claude Code 2.1.295. */
 export function assertAnthropicThinkingRuntime(extraBody: string | undefined): void {
   if (!extraBody) return;
+
   if (extraBodyRuntimeSupported === undefined) {
     try {
       const version = execFileSync("claude", ["--version"], {
@@ -35,6 +36,7 @@ export function assertAnthropicThinkingRuntime(extraBody: string | undefined): v
         stdio: ["ignore", "pipe", "pipe"],
         env: { PATH: process.env.PATH, TMPDIR: process.env.TMPDIR },
       }).match(/^(\d+)\.(\d+)\.(\d+)/);
+
       const [major, minor, patch] = version?.slice(1).map(Number) ?? [];
       extraBodyRuntimeSupported =
         major !== undefined &&
@@ -45,6 +47,7 @@ export function assertAnthropicThinkingRuntime(extraBody: string | undefined): v
       extraBodyRuntimeSupported = false;
     }
   }
+
   if (!extraBodyRuntimeSupported) {
     throw new ThinkingValidationError(
       "thinking:false for Haiku 5.5 and Sonnet 5.5 requires Claude Code 2.1.295 or later; runtime version could not be verified",
@@ -54,14 +57,17 @@ export function assertAnthropicThinkingRuntime(extraBody: string | undefined): v
 
 export function resolveAnthropicThinking(model: string, thinking?: boolean, effort?: string) {
   const canonical = canonicalAnthropicModel(model);
+
   if (thinking === false && !THINKING_OFF_MODELS.has(canonical)) {
     const reason = usesAdaptiveThinking(canonical)
       ? "this model requires thinking"
       : "thinking-off support has not been verified for this model";
+
     throw new ThinkingValidationError(
       `thinking:false is not supported for anthropic/${canonical}: ${reason}`,
     );
   }
+
   return {
     // Never accept caller-provided extra body data or inherit it from the host environment.
     extraBody:

package/bundle/src/utils/providers/anthropic/claude-session.ts

@@ -52,13 +52,16 @@ export async function withSessionLock<T>(sessionId: string, fn: () => Promise<T>
   const prev = sessionChains.get(sessionId) ?? Promise.resolve();
   // 이전 turn 의 성패와 무관하게 직렬 체인을 잇는다.
   const next = prev.then(fn, fn);
+
   // tail: 성패 무관 settle 되는 핸들. 이걸 맵에 두고, finally 에서 "여전히 내가 끝"일 때만 삭제.
   // (set 직후 undefined 검사로 하면 절대 삭제 안 돼 세션 id 가 누수됨 — tail 일치 검사로 회피.)
   const tail = next.then(
     () => {},
     () => {},
   );
+
   sessionChains.set(sessionId, tail);
+
   try {
     return await next;
   } finally {
@@ -127,10 +130,12 @@ export function ensureConfigDir(tokenId: number): string {
   mkdirSync(dir, { recursive: true });
   writeFileSync(`${dir}/.claude.json`, "{}");
   writeFileSync(`${dir}/settings.json`, "{}");
+
   return dir;
 }
 
 let cwdEnsured = false;
+
 function ensureCwd(): void {
   if (cwdEnsured) return;
   mkdirSync(`${ANTHROPIC_CLAUDE_CWD}/.claude`, { recursive: true });
@@ -141,6 +146,7 @@ function ensureCwd(): void {
 // spawn args 구성. 멀티턴/격리/structured 모드 반영.
 export function applyOneMillionSuffix(model: string, needsSuffix: boolean): string {
   const base = canonicalAnthropicModel(model);
+
   return needsSuffix ? `${base}[1m]` : base;
 }
 
@@ -152,12 +158,18 @@ export function oneMillionEnv(supported: boolean): { CLAUDE_CODE_DISABLE_1M_CONT
 // `{rejected}{accepted}` 누적이 AI-SDK 의 JSON.parse 를 깨뜨리므로, retry 자체를 막아 그 경로를
 // 원천 차단한다. `0` 은 CC query loop(`callsThisQuery >= maxRetries`)가 첫 attempt emit 전에
 // 실패시키므로(`error_max_structured_output_retries`) 외부 값이 1 미만이어도 1 로 클램프한다.
-export function structuredOutputRetriesEnv(raw = process.env.MAX_STRUCTURED_OUTPUT_RETRIES): {
+export interface StructuredOutputRetriesEnv {
   MAX_STRUCTURED_OUTPUT_RETRIES: string;
-} {
+}
+
+export function structuredOutputRetriesEnv(
+  raw = process.env.MAX_STRUCTURED_OUTPUT_RETRIES,
+): StructuredOutputRetriesEnv {
   if (!raw) return { MAX_STRUCTURED_OUTPUT_RETRIES: "1" };
   const parsed = Number.parseInt(raw, 10);
+
   if (!Number.isFinite(parsed)) return { MAX_STRUCTURED_OUTPUT_RETRIES: "1" };
+
   return { MAX_STRUCTURED_OUTPUT_RETRIES: String(Math.max(parsed, 1)) };
 }
 
@@ -201,7 +213,9 @@ export function buildClaudeArgs(opts: {
 }): Array<string> {
   const thinking = resolveAnthropicThinking(opts.model, opts.thinking, opts.effort);
   const useStructured = Boolean(opts.jsonSchema && opts.jsonSchema.length > 0);
+
   if (useStructured) assertAnthropicSchemaArgvSize(opts.jsonSchema!);
+
   // --tools "" 로 전체 차단, structured(jsonSchema 있음) 면 StructuredOutput 만 허용.
   const toolArgs = useStructured
     ? ["--tools", "", "--allowed-tools", "StructuredOutput"]
@@ -241,7 +255,9 @@ export function buildClaudeArgs(opts: {
     "--session-id",
     opts.sessionId,
   ];
+
   if (useStructured) args.push("--json-schema", opts.jsonSchema!);
+
   return args;
 }
 
@@ -274,6 +290,7 @@ export function runClaudeSession(
     // 실제 파일 쓰기는 abort 체크 이후(Promise 안)로 미뤄, 이미 취소된 요청엔 쓰지 않는다.
     const system = req.system ?? "";
     const useSystemPromptFile = Buffer.byteLength(system, "utf8") > SYSTEM_PROMPT_ARGV_MAX_BYTES;
+
     const systemPromptFile = useSystemPromptFile
       ? `${configDir}/system-prompt-${sessionId}.txt`
       : undefined;
@@ -294,44 +311,53 @@ export function runClaudeSession(
       coldHistory: req.coldHistory,
       input: req.input,
     });
+
     const stdinPayload = decorateAndSerialize(inputLines, sessionId);
 
     return new Promise<ClaudeSessionResult>((resolve, reject) => {
       if (req.abortSignal?.aborted) {
         reject(new Error("aborted"));
+
         return;
       }
 
       // 대형 시스템 프롬프트는 spawn 직전에 파일로 기록(argv E2BIG 회피). 종료 시 정리한다.
       if (systemPromptFile) writeFileSync(systemPromptFile, system);
 
+      const env: NodeJS.ProcessEnv = {
+        PATH: process.env.PATH,
+        TMPDIR: process.env.TMPDIR,
+        CLAUDE_CODE_OAUTH_TOKEN: req.token,
+        CLAUDE_CONFIG_DIR: configDir,
+      };
+
+      if (thinking.extraBody) env.CLAUDE_CODE_EXTRA_BODY = thinking.extraBody;
+
+      env.CLAUDE_CODE_DISABLE_AUTO_MEMORY = "1";
+      Object.assign(env, oneMillionEnv(supportsOneMillion));
+      env.CLAUDE_CODE_DISABLE_CLAUDE_MDS = "1";
+      env.CLAUDE_CODE_DISABLE_TERMINAL_TITLE = "1";
+      env.CLAUDE_CODE_DISABLE_BUNDLED_SKILLS = "1";
+      env.CLAUDE_CODE_DISABLE_WORKFLOWS = "1";
+      env.CLAUDE_CODE_ATTRIBUTION_HEADER = "0";
+
+      // structured + 스트리밍일 때만 retry 를 고정한다(SON-495). text 모드와 논스트림
+      // generate 는 CC 기본 retry 를 그대로 쓴다.
+      if (
+        shouldPinStructuredRetries({
+          useStructured,
+          includePartialMessages: req.includePartialMessages,
+        })
+      ) {
+        Object.assign(env, structuredOutputRetriesEnv());
+      }
+
       const child = spawn("claude", args, {
         // stderr 도 캡처: invalid OAuth / 잘못된 플래그 / CLI 검증 실패가
         // "closed without result" 로 뭉개지지 않게 close/error 에 stderr 를 실어 보낸다.
         stdio: ["pipe", "pipe", "pipe"],
         cwd: ANTHROPIC_CLAUDE_CWD,
-        env: {
-          PATH: process.env.PATH,
-          TMPDIR: process.env.TMPDIR,
-          CLAUDE_CODE_OAUTH_TOKEN: req.token,
-          CLAUDE_CONFIG_DIR: configDir,
-          ...(thinking.extraBody ? { CLAUDE_CODE_EXTRA_BODY: thinking.extraBody } : {}),
-          CLAUDE_CODE_DISABLE_AUTO_MEMORY: "1",
-          ...oneMillionEnv(supportsOneMillion),
-          CLAUDE_CODE_DISABLE_CLAUDE_MDS: "1",
-          CLAUDE_CODE_DISABLE_TERMINAL_TITLE: "1",
-          CLAUDE_CODE_DISABLE_BUNDLED_SKILLS: "1",
-          CLAUDE_CODE_DISABLE_WORKFLOWS: "1",
-          CLAUDE_CODE_ATTRIBUTION_HEADER: "0",
-          // structured + 스트리밍일 때만 retry 를 고정한다(SON-495). text 모드와 논스트림
-          // generate 는 CC 기본 retry 를 그대로 쓴다.
-          ...(shouldPinStructuredRetries({
-            useStructured,
-            includePartialMessages: req.includePartialMessages,
-          })
-            ? structuredOutputRetriesEnv()
-            : {}),
-        },
+        env,
       });
 
       let settled = false;
@@ -346,18 +372,22 @@ export function runClaudeSession(
         stderrBuf = (stderrBuf + d.toString()).slice(-STDERR_CAP);
       });
       const stderrSuffix = () => (stderrBuf.trim() ? ` — stderr: ${stderrBuf.trim()}` : "");
+
       // spawn 시 쓴 임시 시스템 프롬프트 파일 정리(한 번만). 모든 종료 경로에서 호출한다.
       // 누락돼도 다음 ensureConfigDir 가 디렉토리를 재사용할 뿐이지만, sessionId 별 파일이라
       // 쌓이면 디스크가 차므로 settle 시 즉시 지운다.
       const cleanupSpawnFiles = () => {
         if (!systemPromptFile) return;
+
         try {
           unlinkSync(systemPromptFile);
         } catch {
           // 이미 없거나 권한 문제면 무시 — 정리는 best-effort.
         }
       };
+
       let cleanupAbort: (() => void) | undefined;
+
       const timer = setTimeout(() => {
         if (settled) return;
         settled = true;
@@ -385,6 +415,7 @@ export function runClaudeSession(
         child.kill();
         reject(new Error("aborted"));
       };
+
       cleanupAbort = () => req.abortSignal?.removeEventListener("abort", onAbort);
       req.abortSignal?.addEventListener("abort", onAbort, { once: true });
 
@@ -393,13 +424,16 @@ export function runClaudeSession(
         buffer += d.toString();
         const lines = buffer.split("\n");
         buffer = lines.pop() ?? "";
+
         for (const line of lines) {
           const result = handleStreamJsonLine(line, onTrackedDelta, {
             structuredOutput: useStructured,
             state: streamState,
           });
+
           if (result) {
             finish(result);
+
             return;
           }
         }

package/bundle/src/utils/providers/anthropic/fence-strip.ts

@@ -47,18 +47,22 @@ export function createFenceStripTransform(): FenceStripTransform {
   return {
     push(delta: string): string {
       full += delta;
+
       if (bodyStart < 0) {
         bodyStart = resolveLeadingOffset(full);
+
         if (bodyStart < 0) return "";
       }
 
       const body = full.slice(bodyStart);
       const unemitted = body.slice(emitted);
       const safe = unemitted.length - trailingHoldLength(unemitted);
+
       if (safe <= 0) return "";
 
       const out = unemitted.slice(0, safe);
       emitted += safe;
+
       return out;
     },
 
@@ -76,19 +80,25 @@ export function createFenceStripTransform(): FenceStripTransform {
  */
 function resolveLeadingOffset(text: string): number {
   const trimmedStart = text.trimStart();
+
   if (trimmedStart === "") return -1; // 아직 공백뿐 — flush 가 정리한다
   const ws = text.length - trimmedStart.length;
 
   if (!trimmedStart.startsWith("`")) return ws;
+
   if (/^`{1,2}$/.test(trimmedStart)) return -1; // "```" 로 자랄 수 있음
 
   const fence = /^```(?:json)?/i.exec(trimmedStart);
+
   if (!fence) return ws; // "`x", "``x" — 펜스가 아니라 본문
+
   if (/^```(?:j|js|jso)$/i.test(trimmedStart)) return -1; // "json" 태그가 자라는 중
 
   const afterFence = trimmedStart.slice(fence[0].length);
   const afterFenceBody = afterFence.trimStart();
+
   if (afterFenceBody === "") return -1; // 펜스 뒤 공백만 — 본문 첫 글자 대기
+
   return ws + fence[0].length + (afterFence.length - afterFenceBody.length);
 }
 
@@ -101,5 +111,6 @@ function resolveLeadingOffset(text: string): number {
  */
 function trailingHoldLength(unemitted: string): number {
   const match = /(?:\n?`{1,3})?[\s]*$/.exec(unemitted);
+
   return match ? match[0].length : 0;
 }