triflux 10.37.0 → 10.39.0

package/bin/triflux.mjs

@@ -499,13 +499,15 @@ const CLI_COMMAND_SCHEMAS = Object.freeze({
     },
   },
   cto: {
-    usage: "tfx cto <collect|status|dashboard|hygiene> [options]",
+    usage: "tfx cto <collect|status|dashboard|hygiene|event> [options]",
     description: "repo-local authority layer console",
     subcommands: {
       collect: "refresh .triflux/lake/current.json from authority sources",
       status: "print the current authority summary",
       dashboard: "render the CTO console dashboard, optionally with --watch",
       hygiene: "project CTO hygiene counts and actionable dry-run rows",
+      event:
+        "append wrapper lineage events: context-save, context-restore, pr-created, pr-merged-or-closed",
     },
   },
   multi: {

package/cto/events.mjs

@@ -6,6 +6,7 @@ import {
   unlinkSync,
 } from "node:fs";
 import { basename, join } from "node:path";
+import { resolveLakeRootDir } from "./lake-root.mjs";
 
 export const CTO_EVENT_SCHEMA_VERSION = "cto-event.v1";
 export const DEFAULT_CTO_EVENT_SOURCE = "tfx_cto_event";
@@ -41,6 +42,98 @@ export const CTO_HYGIENE_STATUSES = Object.freeze([
 const EVENT_TYPE_SET = new Set(CTO_EVENT_TYPES);
 const STATUS_SET = new Set(CTO_HYGIENE_STATUSES);
 
+const EVENT_PRESETS = Object.freeze({
+  "context-save": {
+    event: "checkpoint_saved",
+    source: "gstack_context_save",
+    actor: { cli: "gstack context-save" },
+    ownerSurface: "gstack context-save -> tfx cto event context-save",
+  },
+  "checkpoint-saved": {
+    event: "checkpoint_saved",
+    ownerSurface: "checkpoint wrapper -> tfx cto event checkpoint-saved",
+  },
+  "context-restore": {
+    event: "checkpoint_restored",
+    source: "gstack_context_restore",
+    actor: { cli: "gstack context-restore" },
+    ownerSurface: "gstack context-restore -> tfx cto event context-restore",
+  },
+  "checkpoint-restored": {
+    event: "checkpoint_restored",
+    ownerSurface: "checkpoint wrapper -> tfx cto event checkpoint-restored",
+  },
+  "pr-created": {
+    event: "pr_created",
+    source: "tfx_pr_lifecycle",
+    actor: { cli: "gh pr create" },
+    ownerSurface: "gh pr create/merge/close -> tfx cto event pr-created",
+  },
+  "pr-merged": {
+    event: "pr_merged_or_closed",
+    source: "tfx_pr_lifecycle",
+    status: "completed",
+    actor: { cli: "gh pr merge" },
+    ownerSurface:
+      "gh pr create/merge/close -> tfx cto event pr-merged-or-closed",
+  },
+  "pr-closed": {
+    event: "pr_merged_or_closed",
+    source: "tfx_pr_lifecycle",
+    status: "completed",
+    actor: { cli: "gh pr close" },
+    ownerSurface:
+      "gh pr create/merge/close -> tfx cto event pr-merged-or-closed",
+  },
+  "pr-merged-or-closed": {
+    event: "pr_merged_or_closed",
+    source: "tfx_pr_lifecycle",
+    actor: { cli: "gh pr merge/close" },
+    ownerSurface:
+      "gh pr create/merge/close -> tfx cto event pr-merged-or-closed",
+  },
+});
+
+const OPTION_KEYS = Object.freeze({
+  event: "event",
+  "event-type": "event",
+  source: "source",
+  summary: "summary",
+  now: "now",
+  ts: "ts",
+  status: "status",
+  "session-id": "session_id",
+  "parent-session-id": "parent_session_id",
+  "restored-from-session-id": "restored_from_session_id",
+  "checkpoint-id": "checkpoint_id",
+  "artifact-path": "artifact_path",
+  artifact: "artifact_path",
+  "task-id": "task_id",
+  branch: "branch",
+  "last-seen-at": "last_seen_at",
+  "stale-reason": "stale_reason",
+  "hygiene-key": "hygiene_key",
+  "hygiene-kind": "hygiene_kind",
+  "hygiene-id": "hygiene_id",
+  "hygiene-action": "hygiene_action",
+  "project-root": "project_root",
+  "worktree-path": "worktree_path",
+  worktree: "worktree_path",
+  issue: "issue_refs",
+  "issue-ref": "issue_refs",
+  "issue-refs": "issue_refs",
+  pr: "pr_refs",
+  "pr-ref": "pr_refs",
+  "pr-refs": "pr_refs",
+  "actor-cli": "actor.cli",
+  "actor-session-id": "actor.session_id",
+  "actor-agent-id": "actor.agent_id",
+  "actor-host": "actor.host",
+  "owner-surface": "owner_surface",
+});
+
+const COLLECTION_KEYS = new Set(["issue_refs", "pr_refs"]);
+
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -107,6 +200,124 @@ function normalizeActor(actor) {
   return Object.keys(normalized).length > 0 ? normalized : null;
 }
 
+function optionName(raw) {
+  return String(raw || "")
+    .replace(/^--?/u, "")
+    .trim();
+}
+
+function appendCollection(target, key, value) {
+  const values = String(value ?? "")
+    .split(",")
+    .map((item) => item.trim())
+    .filter(Boolean);
+  if (values.length === 0) return;
+  if (!Array.isArray(target[key])) target[key] = [];
+  target[key].push(...values);
+}
+
+function putPathValue(target, keyPath, value) {
+  if (keyPath.startsWith("actor.")) {
+    const key = keyPath.slice("actor.".length);
+    target.actor ||= {};
+    target.actor[key] = value;
+    return;
+  }
+  if (COLLECTION_KEYS.has(keyPath)) {
+    appendCollection(target, keyPath, value);
+    return;
+  }
+  target[keyPath] = value;
+}
+
+function parseEventArgs(args = []) {
+  const fields = {};
+  const positional = [];
+  let json = false;
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === "--json") {
+      json = true;
+      continue;
+    }
+    if (!arg?.startsWith?.("--")) {
+      positional.push(arg);
+      continue;
+    }
+
+    const eqIndex = arg.indexOf("=");
+    const rawName = eqIndex >= 0 ? arg.slice(0, eqIndex) : arg;
+    const name = optionName(rawName);
+    const mapped = OPTION_KEYS[name];
+    if (!mapped) {
+      throw new Error(`unknown tfx cto event option: --${name}`);
+    }
+
+    let value = eqIndex >= 0 ? arg.slice(eqIndex + 1) : null;
+    if (value === null) {
+      const next = args[i + 1];
+      if (typeof next === "string" && !next.startsWith("--")) {
+        value = next;
+        i += 1;
+      } else {
+        value = "true";
+      }
+    }
+    putPathValue(fields, mapped, value);
+  }
+
+  return {
+    presetName: positional[0] || null,
+    extraPositionals: positional.slice(1),
+    fields,
+    json,
+  };
+}
+
+function mergeActor(defaultActor, overrideActor) {
+  const actor = { ...(defaultActor || {}), ...(overrideActor || {}) };
+  return Object.keys(actor).length > 0 ? actor : undefined;
+}
+
+function defaultEventSummary(input) {
+  if (input.event === "checkpoint_saved") {
+    return `context-save checkpoint ${input.checkpoint_id}`;
+  }
+  if (input.event === "checkpoint_restored") {
+    return `context-restore checkpoint ${input.checkpoint_id}`;
+  }
+  if (input.event === "pr_created") {
+    const [pr] = normalizeNumericRefs(input.pr_refs);
+    return pr ? `PR #${pr} created` : "PR created";
+  }
+  if (input.event === "pr_merged_or_closed") {
+    const [pr] = normalizeNumericRefs(input.pr_refs);
+    return pr ? `PR #${pr} merged or closed` : "PR merged or closed";
+  }
+  return undefined;
+}
+
+function validateRunEventInput(input) {
+  if (!input.event) {
+    throw new Error("tfx cto event requires a preset or --event <event_type>");
+  }
+
+  if (
+    ["checkpoint_saved", "checkpoint_restored"].includes(input.event) &&
+    !maybeString(input.checkpoint_id)
+  ) {
+    throw new Error(`tfx cto event ${input.event} requires --checkpoint-id`);
+  }
+
+  if (
+    ["pr_created", "pr_merged_or_closed"].includes(input.event) &&
+    normalizeNumericRefs(input.pr_refs).length === 0
+  ) {
+    throw new Error(`tfx cto event ${input.event} requires --pr`);
+  }
+}
+
 function putString(target, key, value) {
   const normalized = maybeString(value);
   if (normalized) target[key] = normalized;
@@ -220,3 +431,59 @@ export async function appendCtoEvent(lakeRoot, input, opts = {}) {
     } catch {}
   }
 }
+
+export async function runEvent(args = [], opts = {}) {
+  const parsed = parseEventArgs(args);
+  if (parsed.extraPositionals.length > 0) {
+    throw new Error(
+      `unexpected tfx cto event argument: ${parsed.extraPositionals[0]}`,
+    );
+  }
+  const preset = parsed.presetName ? EVENT_PRESETS[parsed.presetName] : null;
+  if (parsed.presetName && !preset && !parsed.fields.event) {
+    throw new Error(`unknown tfx cto event preset: ${parsed.presetName}`);
+  }
+
+  const rootDir = opts.rootDir || resolveLakeRootDir(process.cwd());
+  const lakeRoot = opts.lakeRoot || join(rootDir, ".triflux", "lake");
+  const stdout = opts.stdout || process.stdout;
+  const jsonOut = opts.json === true || parsed.json;
+  const ownerSurface =
+    parsed.fields.owner_surface ||
+    preset?.ownerSurface ||
+    "external wrapper -> tfx cto event --event";
+
+  const input = {
+    ...(preset || {}),
+    ...parsed.fields,
+    actor: mergeActor(preset?.actor, parsed.fields.actor),
+  };
+  delete input.ownerSurface;
+  delete input.owner_surface;
+  if (!input.project_root) input.project_root = rootDir;
+  if (!input.summary) input.summary = defaultEventSummary(input);
+
+  validateRunEventInput(input);
+
+  const result = await appendCtoEvent(lakeRoot, input, {
+    stderr: opts.stderr,
+    lockRetries: opts.ledgerLockRetries,
+    lockRetryDelayMs: opts.ledgerLockRetryDelayMs,
+  });
+  const payload = {
+    appended: result.appended,
+    owner_surface: ownerSurface,
+    event: result.event,
+  };
+
+  if (jsonOut) {
+    stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+  } else {
+    const status = result.appended ? "appended" : "skipped";
+    stdout.write(
+      `[tfx cto event] ${status} ${result.event.event} via ${ownerSurface}\n`,
+    );
+  }
+
+  return payload;
+}

package/cto/index.mjs

@@ -1,4 +1,4 @@
-const SUBCOMMANDS = ["collect", "status", "dashboard", "hygiene"];
+const SUBCOMMANDS = ["collect", "status", "dashboard", "hygiene", "event"];
 
 function printUsage(subcommand) {
   if (subcommand) {
@@ -6,13 +6,14 @@ function printUsage(subcommand) {
   }
   console.log(`
 Usage
-  tfx cto <collect|status|dashboard|hygiene> [options]
+  tfx cto <collect|status|dashboard|hygiene|event> [options]
 
 Subcommands
   collect     Refresh .triflux/lake/current.json from repo-local authority sources
   status      Print the current authority summary
   dashboard   Render the CTO console dashboard, optionally with --watch
   hygiene     Project CTO hygiene counts and actionable dry-run rows
+  event       Append normalized wrapper lifecycle events to the CTO ledger
 `);
 }
 
@@ -36,6 +37,10 @@ export async function cmdCto(cmdArgs, opts = {}) {
       const { runHygiene } = await import("./hygiene.mjs");
       return runHygiene(rest, opts);
     }
+    case "event": {
+      const { runEvent } = await import("./events.mjs");
+      return runEvent(rest, opts);
+    }
     case undefined:
     case "":
       printUsage();

package/hooks/agy-session-hook.mjs

@@ -30,12 +30,18 @@ function parsePayload(stdinData) {
   }
 }
 
-// Antigravity hook payloads use camelCase system metadata (conversationId,
-// workspacePaths) rather than Codex's session_id/cwd. registerInteractiveSession
-// and heartbeatInteractiveSession parse the Codex shape, so we adapt the agy
-// payload into that shape before delegating. conversationId is the stable
-// per-conversation UUID (== session identity); the first mounted workspace path
-// is the effective cwd.
+/**
+ * Convert an Antigravity hook payload into the Codex-shaped session payload
+ * consumed by the shared fast session registration helpers.
+ *
+ * Antigravity hook payloads use camelCase system metadata (`conversationId`,
+ * `workspacePaths`) rather than Codex's `session_id`/`cwd`. The
+ * `conversationId` is the stable per-conversation UUID; the first mounted
+ * workspace path is the effective cwd.
+ *
+ * @param {Record<string, unknown> | null | undefined} payload
+ * @returns {string} JSON string with `{ session_id, cwd, actor_cli }`.
+ */
 export function toSessionPayload(payload) {
   const sessionId = String(payload?.conversationId || "").trim();
   const workspacePaths = Array.isArray(payload?.workspacePaths)
@@ -48,10 +54,18 @@ export function toSessionPayload(payload) {
   return JSON.stringify({ session_id: sessionId, cwd, actor_cli: "agy" });
 }
 
-// agy has no distinct SessionStart / UserPromptSubmit events. PreInvocation
-// fires before every model call, so the per-conversation invocationNum gates
-// register (first call == session start) vs heartbeat (subsequent calls).
-// An explicit argv mode (register|heartbeat) overrides, mirroring the codex hook.
+/**
+ * Decide whether a PreInvocation payload should register or heartbeat.
+ *
+ * agy has no distinct SessionStart/UserPromptSubmit events. PreInvocation fires
+ * before every model call, so per-conversation `invocationNum` gates register
+ * (first call) vs heartbeat (later calls). An explicit argv mode overrides this,
+ * mirroring the Codex hook.
+ *
+ * @param {string | null | undefined} argvMode
+ * @param {Record<string, unknown> | null | undefined} payload
+ * @returns {"register" | "heartbeat"}
+ */
 export function normalizeMode(argvMode, payload) {
   const direct = String(argvMode || "")
     .trim()
@@ -67,6 +81,50 @@ export function normalizeMode(argvMode, payload) {
   return "register";
 }
 
+function swallowStdoutWrite(_chunk, encodingOrCallback, callback) {
+  const done =
+    typeof encodingOrCallback === "function" ? encodingOrCallback : callback;
+  if (typeof done === "function") done();
+  return true;
+}
+
+async function runHookSideEffectsWithStdoutSuppressed(fn) {
+  const originalStdoutWrite = stdout.write;
+  const originalConsoleDebug = console.debug;
+  const originalConsoleInfo = console.info;
+  const originalConsoleLog = console.log;
+
+  stdout.write = swallowStdoutWrite;
+  console.debug = () => {};
+  console.info = () => {};
+  console.log = () => {};
+  try {
+    return await fn();
+  } finally {
+    stdout.write = originalStdoutWrite;
+    console.debug = originalConsoleDebug;
+    console.info = originalConsoleInfo;
+    console.log = originalConsoleLog;
+  }
+}
+
+/**
+ * Execute the observational Antigravity session hook.
+ *
+ * The hook always returns/writes an empty JSON object so hook stdout remains
+ * JSON-only and hook failures never block the user session.
+ *
+ * @param {string} stdinData
+ * @param {{
+ *   argvMode?: string,
+ *   writeStdout?: boolean,
+ *   hubEnsureRun?: (stdinData: string) => Promise<unknown> | unknown,
+ *   registerInteractiveSession?: (stdinData: string) => Promise<unknown> | unknown,
+ *   heartbeatInteractiveSession?: (stdinData: string) => Promise<unknown> | unknown,
+ *   drainPendingSynapse?: (timeoutMs?: number) => Promise<unknown> | unknown,
+ * }} [opts]
+ * @returns {Promise<string>}
+ */
 export async function runAgySessionHook(stdinData, opts = {}) {
   const output = "{}\n";
   const parsed = parsePayload(stdinData);
@@ -93,24 +151,26 @@ export async function runAgySessionHook(stdinData, opts = {}) {
     opts.drainPendingSynapse || defaultDrainPendingSynapse;
 
   try {
-    if (mode === "register") {
-      try {
-        await hubEnsureRun(sessionPayload);
-      } catch {}
-      try {
-        await Promise.resolve(registerInteractiveSession(sessionPayload));
-      } catch {}
-      try {
-        await drainPendingSynapse(1000);
-      } catch {}
-    } else if (mode === "heartbeat") {
-      try {
-        heartbeatInteractiveSession(sessionPayload);
-      } catch {}
-      try {
-        await drainPendingSynapse(500);
-      } catch {}
-    }
+    await runHookSideEffectsWithStdoutSuppressed(async () => {
+      if (mode === "register") {
+        try {
+          await hubEnsureRun(sessionPayload);
+        } catch {}
+        try {
+          await Promise.resolve(registerInteractiveSession(sessionPayload));
+        } catch {}
+        try {
+          await drainPendingSynapse(1000);
+        } catch {}
+      } else if (mode === "heartbeat") {
+        try {
+          heartbeatInteractiveSession(sessionPayload);
+        } catch {}
+        try {
+          await drainPendingSynapse(500);
+        } catch {}
+      }
+    });
   } catch {
     // agy session hooks are observational and must never block the session.
   }

package/hooks/subagent-tracker.mjs

@@ -16,7 +16,11 @@ import { dirname, join } from "node:path";
 const STATE_VERSION = 1;
 const DEFAULT_TTL_MS = 2 * 60 * 60 * 1000;
 const MAX_COMPLETED = 20;
-const DEFAULT_LOCK_TIMEOUT_MS = 750;
+// Lifecycle hooks are best-effort, but under CI/Linux process contention a
+// 30-way SubagentStart burst can legitimately take around a second to drain.
+// Keep this bounded so hooks do not hang indefinitely, while avoiding silent
+// lifecycle drops during normal high-concurrency fan-out.
+const DEFAULT_LOCK_TIMEOUT_MS = 3000;
 const LOCK_RETRY_MS = 20;
 
 function readStdin() {
@@ -96,6 +100,16 @@ function withStateLock(statePath, fn, timeoutMs = DEFAULT_LOCK_TIMEOUT_MS) {
   }
 }
 
+function lockTimeoutMsFromOptions(opts = {}) {
+  if (Number.isFinite(opts.lockTimeoutMs)) return opts.lockTimeoutMs;
+  const raw = opts.env?.TRIFLUX_SUBAGENT_LOCK_TIMEOUT_MS;
+  if (raw === undefined || raw === "") return DEFAULT_LOCK_TIMEOUT_MS;
+  const parsed = Number(raw);
+  return Number.isFinite(parsed) && parsed > 0
+    ? Math.trunc(parsed)
+    : DEFAULT_LOCK_TIMEOUT_MS;
+}
+
 function lifecycleKey(input) {
   if (typeof input.agent_id === "string" && input.agent_id.trim()) {
     return input.agent_id;
@@ -241,7 +255,7 @@ export function recordLifecycle(input, opts = {}) {
       writeState(statePath, state);
       return output;
     },
-    opts.lockTimeoutMs,
+    lockTimeoutMsFromOptions(opts),
   );
 }
 

package/hub/team/claude-daemon-control.mjs

@@ -468,21 +468,29 @@ export function sendClaudeControlRequest(
 // 인증 미강제 daemon 으로 보고 auth 필드를 생략한다 (fail-open — 구버전 호환).
 export async function readDaemonControlKey(
   configDir = resolveClaudeConfigDir(),
+  { diagnostics } = {},
 ) {
+  if (!configDir) return undefined;
+  const keyPath = path.join(configDir, "daemon", "control.key");
   try {
-    const key = await fs.readFile(
-      path.join(configDir, "daemon", "control.key"),
-      "utf8",
-    );
+    const key = await fs.readFile(keyPath, "utf8");
     return key.trim() || undefined;
-  } catch {
+  } catch (error) {
+    if (error?.code === "ENOENT") return undefined;
+    if (Array.isArray(diagnostics)) {
+      diagnostics.push({
+        code: error?.code || "UNKNOWN",
+        path: keyPath,
+        message: error?.message || String(error),
+      });
+    }
     return undefined;
   }
 }
 
-export async function buildDaemonControlAuth(configDir) {
+export async function buildDaemonControlAuth(configDir, opts = {}) {
   if (!configDir) return {};
-  const auth = await readDaemonControlKey(configDir);
+  const auth = await readDaemonControlKey(configDir, opts);
   return auth ? { auth } : {};
 }
 

package/hub/team/notify.mjs

@@ -54,12 +54,17 @@ function normalizeEvent(event, defaults = {}) {
   });
 }
 
-function defaultChannelConfig(name, env) {
+function defaultChannelConfig(name, env, platform = process.platform) {
   switch (name) {
     case "bell":
-      return { enabled: true };
+      return { enabled: envFlag(env?.TRIFLUX_NOTIFY_BELL, true) };
     case "toast":
-      return { enabled: true };
+      return {
+        // macOS `osascript display notification` can surface Script Editor
+        // authorization/UI prompts. Keep it opt-in there; Windows keeps the
+        // historical toast default, and other platforms skip as unsupported.
+        enabled: envFlag(env?.TRIFLUX_NOTIFY_TOAST, platform !== "darwin"),
+      };
     case "webhook": {
       const url = String(env?.TRIFLUX_NOTIFY_WEBHOOK || "");
       return { enabled: Boolean(url), url };
@@ -69,8 +74,13 @@ function defaultChannelConfig(name, env) {
   }
 }
 
-function normalizeChannelConfig(name, value, env) {
-  const base = defaultChannelConfig(name, env);
+function envFlag(value, fallback) {
+  if (value === undefined || value === null || value === "") return fallback;
+  return !["0", "false", "no", "off"].includes(String(value).toLowerCase());
+}
+
+function normalizeChannelConfig(name, value, env, platform) {
+  const base = defaultChannelConfig(name, env, platform);
   const patch =
     typeof value === "boolean"
       ? { enabled: value }
@@ -103,16 +113,21 @@ function normalizeChannelConfig(name, value, env) {
   return freezeRecord(next);
 }
 
-function normalizeChannels(channels, env) {
+function normalizeChannels(channels, env, platform) {
   const source = channels && typeof channels === "object" ? channels : {};
   const normalized = {};
   for (const name of NOTIFY_CHANNELS) {
-    normalized[name] = normalizeChannelConfig(name, source[name], env);
+    normalized[name] = normalizeChannelConfig(
+      name,
+      source[name],
+      env,
+      platform,
+    );
   }
   return Object.freeze(normalized);
 }
 
-function updateChannelConfig(channels, channel, config, env) {
+function updateChannelConfig(channels, channel, config, env, platform) {
   if (!NOTIFY_CHANNELS.includes(channel)) {
     throw new TypeError(`Unknown notify channel: ${channel}`);
   }
@@ -126,6 +141,7 @@ function updateChannelConfig(channels, channel, config, env) {
         ...(typeof config === "boolean" ? { enabled: config } : config || {}),
       },
       env,
+      platform,
     ),
   });
 }
@@ -322,7 +338,7 @@ function createNotifierInstance(channels, deps) {
 
   function setChannel(channel, config) {
     return createNotifierInstance(
-      updateChannelConfig(channels, channel, config, deps.env),
+      updateChannelConfig(channels, channel, config, deps.env, deps.platform),
       deps,
     );
   }
@@ -349,17 +365,21 @@ function createNotifierInstance(channels, deps) {
  */
 export function createNotifier(opts = {}) {
   const env = opts.env || process.env;
+  const platform = opts.platform || process.platform;
   const deps = Object.freeze({
     env,
     stdout: opts.stdout || process.stdout,
     execFile: opts.deps?.execFile || execFile,
     fetch: opts.deps?.fetch || globalThis.fetch?.bind(globalThis),
-    platform: opts.platform || process.platform,
+    platform,
     hostname: opts.hostname || os.hostname(),
     powerShellCandidates: Object.freeze(
       opts.deps?.powerShellCandidates || ["pwsh", "powershell.exe"],
     ),
   });
 
-  return createNotifierInstance(normalizeChannels(opts.channels, env), deps);
+  return createNotifierInstance(
+    normalizeChannels(opts.channels, env, platform),
+    deps,
+  );
 }

package/hud/providers/gemini.mjs

@@ -197,6 +197,8 @@ export function deriveGeminiFamilyBucket(buckets) {
 
 export function buildGeminiAuthContext(accountId) {
   let oauth = readJson(GEMINI_OAUTH_PATH, null);
+  let authSource = oauth?.access_token ? "gemini-file" : "none";
+  let expiryMissing = oauth?.access_token ? oauth.expiry_date == null : false;
   const fileExpired =
     oauth?.expiry_date != null && oauth.expiry_date < Date.now();
   // Preserve a valid Gemini file token; agy Keychain is only a missing/expired fallback.
@@ -209,13 +211,15 @@ export function buildGeminiAuthContext(accountId) {
         ...fileRest
       } = oauth || {};
       oauth = { ...fileRest, ...keychainOAuth };
+      authSource = "antigravity-keychain";
+      expiryMissing = keychainOAuth.expiry_date == null;
     }
   }
   const tokenSource =
     oauth?.refresh_token || oauth?.id_token || oauth?.access_token || "";
   const tokenFingerprint = tokenSource ? makeHash(tokenSource) : "none";
   const cacheKey = `${accountId || "gemini-main"}::${tokenFingerprint}`;
-  return { oauth, tokenFingerprint, cacheKey };
+  return { oauth, tokenFingerprint, cacheKey, authSource, expiryMissing };
 }
 
 function firstPresent(...values) {
@@ -305,12 +309,76 @@ function getAntigravityTokenFromKeychain() {
   }
 }
 
+export function classifyGeminiQuotaFailure(response, authContext = {}) {
+  if (!response) return "network";
+  const error = response?.error || {};
+  const code = Number(error.code ?? response.code ?? response.status);
+  const status = String(error.status || response.status || "").toUpperCase();
+  const message = String(
+    error.message || error.code || response.error || response.message || "",
+  );
+  if (
+    code === 401 ||
+    code === 403 ||
+    status === "UNAUTHENTICATED" ||
+    status === "PERMISSION_DENIED" ||
+    /(unauthorized|forbidden|invalid authentication|invalid credentials|oauth|token|credential|auth)/i.test(
+      message,
+    )
+  ) {
+    return "auth";
+  }
+  if (
+    authContext.authSource === "antigravity-keychain" &&
+    authContext.expiryMissing === true &&
+    /(expired|invalid|unauthenticated|permission denied)/i.test(message)
+  ) {
+    return "auth";
+  }
+  return "api";
+}
+
+function formatGeminiQuotaFailure(response, authContext = {}, stage = "quota") {
+  const error =
+    response?.error?.message ||
+    response?.error?.status ||
+    response?.error?.code ||
+    response?.error ||
+    response?.message ||
+    "no buckets in response";
+  const base = String(error);
+  if (
+    authContext.authSource === "antigravity-keychain" &&
+    authContext.expiryMissing === true
+  ) {
+    return `expiry-less Antigravity Keychain token failed bounded ${stage} freshness probe: ${base}`;
+  }
+  return base;
+}
+
+function writeGeminiQuotaErrorCache(cache, authContext, errorType, errorHint) {
+  const sameKey = cache?.cacheKey === authContext.cacheKey;
+  writeJsonSafe(GEMINI_QUOTA_CACHE_PATH, {
+    ...(sameKey ? cache || {} : {}),
+    timestamp: sameKey && cache?.timestamp ? cache.timestamp : Date.now(),
+    cacheKey: authContext.cacheKey,
+    accountId: authContext.accountId || "gemini-main",
+    tokenFingerprint: authContext.tokenFingerprint,
+    authSource: authContext.authSource,
+    expiryMissing: authContext.expiryMissing === true,
+    error: true,
+    errorType,
+    errorHint,
+  });
+}
+
 // ============================================================================
 // Gemini 쿼터 API 호출 (5분 캐시)
 // ============================================================================
 export async function fetchGeminiQuota(accountId, options = {}) {
   const authContext = options.authContext || buildGeminiAuthContext(accountId);
   const { oauth, tokenFingerprint, cacheKey } = authContext;
+  authContext.accountId = accountId || "gemini-main";
   const forceRefresh = options.forceRefresh === true;
 
   // 1. 캐시 확인 (계정/토큰별)
@@ -330,35 +398,34 @@ export async function fetchGeminiQuota(accountId, options = {}) {
 
   if (!oauth?.access_token) {
     // access_token 없음: 에러 힌트를 캐시에 기록하고 stale 캐시 반환
-    writeJsonSafe(GEMINI_QUOTA_CACHE_PATH, {
-      ...(cache || {}),
-      timestamp: cache?.timestamp || Date.now(),
-      error: true,
-      errorType: "auth",
-      errorHint: "no access_token in oauth_creds.json",
-    });
+    writeGeminiQuotaErrorCache(
+      cache,
+      authContext,
+      "auth",
+      "no access_token in oauth_creds.json",
+    );
     return cache;
   }
   if (oauth.expiry_date && oauth.expiry_date < Date.now()) {
     // OAuth 토큰 만료: 에러 힌트를 캐시에 기록 (refresh_token 갱신은 Gemini CLI 담당)
-    writeJsonSafe(GEMINI_QUOTA_CACHE_PATH, {
-      ...(cache || {}),
-      timestamp: cache?.timestamp || Date.now(),
-      error: true,
-      errorType: "auth",
-      errorHint: `token expired at ${new Date(oauth.expiry_date).toISOString()}`,
-    });
+    writeGeminiQuotaErrorCache(
+      cache,
+      authContext,
+      "auth",
+      `token expired at ${new Date(oauth.expiry_date).toISOString()}`,
+    );
     return cache;
   }
 
   // 3. projectId (캐시 or API)
+  let loadCodeAssistResponse = null;
   const fetchProjectId = async () => {
-    const loadRes = await httpsPost(
+    loadCodeAssistResponse = await httpsPost(
       "https://cloudcode-pa.googleapis.com/v1internal:loadCodeAssist",
       { metadata: { pluginType: "GEMINI" } },
       oauth.access_token,
     );
-    const id = loadRes?.cloudaicompanionProject;
+    const id = loadCodeAssistResponse?.cloudaicompanionProject;
     if (id)
       writeJsonSafe(GEMINI_PROJECT_CACHE_PATH, {
         cacheKey,
@@ -376,7 +443,19 @@ export async function fetchGeminiQuota(accountId, options = {}) {
   let projectId =
     projCache?.cacheKey === cacheKey ? projCache?.projectId : null;
   if (!projectId) projectId = await fetchProjectId();
-  if (!projectId) return cache;
+  if (!projectId) {
+    writeGeminiQuotaErrorCache(
+      cache,
+      authContext,
+      classifyGeminiQuotaFailure(loadCodeAssistResponse, authContext),
+      formatGeminiQuotaFailure(
+        loadCodeAssistResponse,
+        authContext,
+        "loadCodeAssist",
+      ),
+    );
+    return cache;
+  }
 
   // 4. retrieveUserQuota 호출
   let quotaRes = await httpsPost(
@@ -388,7 +467,19 @@ export async function fetchGeminiQuota(accountId, options = {}) {
   // projectId 캐시가 만료/변경된 경우 1회 재시도
   if (!quotaRes?.buckets && projCache?.projectId) {
     projectId = await fetchProjectId();
-    if (!projectId) return cache;
+    if (!projectId) {
+      writeGeminiQuotaErrorCache(
+        cache,
+        authContext,
+        classifyGeminiQuotaFailure(loadCodeAssistResponse, authContext),
+        formatGeminiQuotaFailure(
+          loadCodeAssistResponse,
+          authContext,
+          "loadCodeAssist",
+        ),
+      );
+      return cache;
+    }
     quotaRes = await httpsPost(
       "https://cloudcode-pa.googleapis.com/v1internal:retrieveUserQuota",
       { project: projectId },
@@ -398,18 +489,12 @@ export async function fetchGeminiQuota(accountId, options = {}) {
 
   if (!quotaRes?.buckets) {
     // API 응답에 buckets 없음: 에러 코드 또는 응답 내용을 캐시에 기록
-    const apiError =
-      quotaRes?.error?.message ||
-      quotaRes?.error?.code ||
-      quotaRes?.error ||
-      "no buckets in response";
-    writeJsonSafe(GEMINI_QUOTA_CACHE_PATH, {
-      ...(cache || {}),
-      timestamp: cache?.timestamp || Date.now(),
-      error: true,
-      errorType: "api",
-      errorHint: String(apiError),
-    });
+    writeGeminiQuotaErrorCache(
+      cache,
+      authContext,
+      classifyGeminiQuotaFailure(quotaRes, authContext),
+      formatGeminiQuotaFailure(quotaRes, authContext, "quota"),
+    );
     return cache;
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "triflux",
-  "version": "10.37.0",
+  "version": "10.39.0",
   "description": "CLI-first multi-model orchestrator for Claude Code — route tasks to Codex, Antigravity, and Claude",
   "type": "module",
   "bin": {

package/scripts/check-codex-config-stable.mjs

@@ -14,11 +14,15 @@
 //   사용자가 npm test 도중 다른 터미널에서 codex 를 활성 사용 중이면 이
 //   외부 mutation 이 false positive 로 잡힌다. 따라서 hooks.state-only
 //   churn 은 informational warning 으로 분류하고 exit 0 으로 통과시킨다.
+//   Codex plugin mode also auto-materializes OpenAI primary runtime plugin
+//   registry sections (for example pdf@openai-primary-runtime); those are
+//   likewise Codex-owned external churn, not triflux-owned MCP drift.
 //   triflux 자체 mutation (e.g. tfx-hub URL drift) 은 기존대로 exit 2.
 //
 // Exit codes:
 //   0  = config 안정. wrap 한 명령의 exit code 그대로 반환 (보통 0).
-//        hooks.state-only churn 도 여기 포함 (informational warning 만 출력).
+//        hooks.state/OpenAI runtime plugin churn 도 여기 포함
+//        (informational warning 만 출력).
 //   2  = triflux 가드가 잡아야 할 mutation 감지. wrap 한 명령의 exit code
 //        와 무관하게 강제 fail.
 //   N  = wrap 한 명령이 N 으로 끝남 (mutation 없음).
@@ -32,6 +36,10 @@ import { join } from "node:path";
 const CODEX_CONFIG = join(homedir(), ".codex", "config.toml");
 const EXPECTED_TFX_HUB_URL = "http://127.0.0.1:27888/mcp";
 const HOOKS_STATE_PREFIX = "hooks.state.";
+const OPENAI_PRIMARY_RUNTIME_MARKETPLACE =
+  "marketplaces.openai-primary-runtime";
+const OPENAI_PRIMARY_RUNTIME_PLUGIN_RE =
+  /^plugins\."[^"]+@openai-primary-runtime"$/u;
 
 function readTfxHubUrl(raw) {
   const headerMatch =
@@ -79,11 +87,23 @@ export function splitTomlSections(raw) {
 
 // Classify which sections drifted between before / after payloads.
 // Returns:
-//   { hooksStateOnly: bool, changedSections: string[] }
+//   { hooksStateOnly: bool, externalChurnOnly: bool, changedSections: string[] }
 //
 // hooksStateOnly = true means every changed section header starts with
 // "hooks.state." (the oh-my-codex managed area). Empty diff returns
 // hooksStateOnly=false so callers don't accidentally whitelist "no change".
+//
+// externalChurnOnly additionally permits Codex-owned OpenAI primary runtime
+// plugin registry sections. It remains false for empty diffs and for any
+// triflux-owned or unknown section drift.
+function isExternalChurnSection(header) {
+  return (
+    header.startsWith(HOOKS_STATE_PREFIX) ||
+    header === OPENAI_PRIMARY_RUNTIME_MARKETPLACE ||
+    OPENAI_PRIMARY_RUNTIME_PLUGIN_RE.test(header)
+  );
+}
+
 export function classifySectionDiff(beforeRaw, afterRaw) {
   const beforeSections = splitTomlSections(beforeRaw);
   const afterSections = splitTomlSections(afterRaw);
@@ -109,7 +129,9 @@ export function classifySectionDiff(beforeRaw, afterRaw) {
   const hooksStateOnly =
     changedSections.length > 0 &&
     changedSections.every((h) => h.startsWith(HOOKS_STATE_PREFIX));
-  return { hooksStateOnly, changedSections };
+  const externalChurnOnly =
+    changedSections.length > 0 && changedSections.every(isExternalChurnSection);
+  return { hooksStateOnly, externalChurnOnly, changedSections };
 }
 
 function snapshotConfig() {
@@ -145,13 +167,12 @@ export function describeChange(before, after) {
   if (before.sha !== after.sha) {
     const beforeRaw = typeof before.raw === "string" ? before.raw : "";
     const afterRaw = typeof after.raw === "string" ? after.raw : "";
-    const { hooksStateOnly, changedSections } = classifySectionDiff(
-      beforeRaw,
-      afterRaw,
-    );
+    const { hooksStateOnly, externalChurnOnly, changedSections } =
+      classifySectionDiff(beforeRaw, afterRaw);
     return {
       kind: "sha-changed",
       hooksStateOnly,
+      externalChurnOnly,
       changedSections,
       message: `sha256 differs (size: ${before.size} → ${after.size})`,
     };
@@ -205,18 +226,24 @@ if (isMain) {
   const portDrift = describePortDrift(after);
   const hooksStateOnly =
     change?.kind === "sha-changed" && change.hooksStateOnly === true;
+  const externalChurnOnly =
+    change?.kind === "sha-changed" && change.externalChurnOnly === true;
 
-  // hooksStateOnly + port drift 없음 = informational warning + pass.
+  // External Codex-owned churn + port drift 없음 = informational warning + pass.
   // port drift 가 같이 잡혔으면 그건 triflux-owned section mutation 이라
   // 기존 fail path 를 탄다.
-  if (hooksStateOnly && !portDrift) {
+  if (externalChurnOnly && !portDrift) {
     process.stderr.write(
       [
         "",
-        "[check-codex-config-stable] hooks.state-only churn (whitelist)",
+        hooksStateOnly
+          ? "[check-codex-config-stable] hooks.state-only churn (whitelist)"
+          : "[check-codex-config-stable] Codex external plugin churn (whitelist)",
         `Path:     ${CODEX_CONFIG}`,
         `Sections: ${(change.changedSections || []).join(", ") || "(none)"}`,
-        "Reason:   oh-my-codex 가 codex CLI hook trust state 를 자동 갱신.",
+        hooksStateOnly
+          ? "Reason:   oh-my-codex 가 codex CLI hook trust state 를 자동 갱신."
+          : "Reason:   Codex plugin runtime 이 OpenAI primary runtime registry 를 자동 갱신.",
         "          triflux 외부 mutation 이므로 #193 가드의 false positive 다.",
         "Action:   informational only — pass-through.",
         "",

package/scripts/lib/gemini-profiles.mjs

@@ -8,23 +8,49 @@ import {
 import { homedir } from "node:os";
 import { join } from "node:path";
 
+// 모델명 SSOT. 값은 agy 1.0.x `agy models` 가 출력하는 display name 형식이다
+// (`--model` 인자가 이 문자열을 받는다). 옛 `gemini-*-preview` ID 형식이 아님.
 const DEFAULT_GEMINI_PROFILES = {
-  model: "gemini-3.1-pro-preview",
+  model: "Gemini 3.5 Flash (Medium)",
   profiles: {
+    flash35_low: {
+      model: "Gemini 3.5 Flash (Low)",
+      hint: "3.5 Flash (Low) — 경량·저비용",
+    },
+    flash35: {
+      model: "Gemini 3.5 Flash (Medium)",
+      hint: "3.5 Flash (Medium) — 기본, 비용·속도 균형",
+    },
+    flash35_high: {
+      model: "Gemini 3.5 Flash (High)",
+      hint: "3.5 Flash (High) — 코드/추론 강화",
+    },
+    pro31_low: {
+      model: "Gemini 3.1 Pro (Low)",
+      hint: "3.1 Pro (Low) — 플래그십 경량",
+    },
     pro31: {
-      model: "gemini-3.1-pro-preview",
-      hint: "3.1 Pro — 플래그십 (1M ctx, 멀티모달)",
+      model: "Gemini 3.1 Pro (High)",
+      hint: "3.1 Pro (High) — 플래그십 최고 (긴 컨텍스트/복잡 추론)",
     },
     flash3: {
-      model: "gemini-3-flash-preview",
-      hint: "3.0 Flash — 빠른 응답, 비용 효율",
+      model: "Gemini 3 Flash",
+      hint: "3.0 Flash — 레거시 호환",
     },
-    pro25: { model: "gemini-2.5-pro", hint: "2.5 Pro — 안정 (추론 강화)" },
-    flash25: { model: "gemini-2.5-flash", hint: "2.5 Flash — 경량 범용" },
-    lite25: { model: "gemini-2.5-flash-lite", hint: "2.5 Flash Lite — 최경량" },
   },
 };
 
+// 1회 마이그레이션 테이블: 옛 ID 형식 모델값 → agy display name.
+// null = deprecated(2.5 계열) → 해당 프로필 제거 대상.
+const LEGACY_MODEL_MIGRATION = {
+  "gemini-3.1-pro-preview": "Gemini 3.1 Pro (High)",
+  "gemini-3-flash-preview": "Gemini 3 Flash",
+  "gemini-2.5-pro": null,
+  "gemini-2.5-flash": null,
+  "gemini-2.5-flash-lite": null,
+};
+const LEGACY_PROFILE_NAMES = ["pro25", "flash25", "lite25"];
+
 const DEFAULT_PROFILE_COUNT = Object.keys(
   DEFAULT_GEMINI_PROFILES.profiles,
 ).length;
@@ -80,6 +106,39 @@ function ensureGeminiProfiles({
     )
       cfg.profiles = {};
 
+    // ── 1회 마이그레이션: deprecated 2.5 프로필 prune + 옛 ID 형식 → display name ──
+    // merge-only 로직만으로는 기존 사용자 파일에 남은 stale 프로필/옛 모델 ID 가
+    // 정리되지 않으므로, 신규 default 를 채우기 전에 마이그레이션을 먼저 적용한다.
+    let migrated = false;
+    for (const legacy of LEGACY_PROFILE_NAMES) {
+      if (cfg.profiles[legacy]) {
+        delete cfg.profiles[legacy];
+        migrated = true;
+      }
+    }
+    for (const [pname, pval] of Object.entries(cfg.profiles)) {
+      const mid = typeof pval === "string" ? pval : pval?.model;
+      if (mid && Object.hasOwn(LEGACY_MODEL_MIGRATION, mid)) {
+        const repl = LEGACY_MODEL_MIGRATION[mid];
+        if (repl === null) {
+          delete cfg.profiles[pname];
+        } else if (typeof pval === "string") {
+          cfg.profiles[pname] = repl;
+        } else {
+          cfg.profiles[pname].model = repl;
+        }
+        migrated = true;
+      }
+    }
+    if (
+      typeof cfg.model === "string" &&
+      Object.hasOwn(LEGACY_MODEL_MIGRATION, cfg.model)
+    ) {
+      // 옛 ID 형식 기본값은 구버전 자동 생성값이므로 새 기본(DEFAULT)으로 정규화한다.
+      cfg.model = DEFAULT_GEMINI_PROFILES.model;
+      migrated = true;
+    }
+
     let added = 0;
     for (const [name, value] of Object.entries(
       DEFAULT_GEMINI_PROFILES.profiles,
@@ -91,7 +150,12 @@ function ensureGeminiProfiles({
     }
     if (!cfg.model) cfg.model = DEFAULT_GEMINI_PROFILES.model;
 
-    if (added > 0) {
+    if (added > 0 || migrated) {
+      if (migrated) {
+        try {
+          copyFileSync(profilesPath, profilesPath + `.bak.${Date.now()}`);
+        } catch {}
+      }
       writeFileSync(profilesPath, JSON.stringify(cfg, null, 2) + "\n", {
         encoding: "utf8",
         mode: 0o600,

package/scripts/test-lock.mjs

@@ -321,27 +321,7 @@ export function main(argv = process.argv.slice(2)) {
   const timeoutMs = parseTimeoutMs();
   const lock = acquireLock(timeoutMs);
   const testHubPidDir = mkdtempSync(join(tmpdir(), "tfx-test-hub-pid-"));
-
-  // forward args after -- to node --test
-  const args = preserveForceExitFailures(expandTestArgs(argv));
-  // stdio split (issue #192 F1): when prepare.mjs spawns this lock with
-  // ["ignore","pipe","pipe"], full inherit cascades the parent stdin=ignore
-  // to grand-child node --test, breaking ConPTY assumptions on Windows and
-  // surfacing as EXIT=1 (false-failed). Pipe stdin only — stdout/stderr stay
-  // inherited so the grand-child still streams to whoever attached to us.
-  const child = spawn(process.execPath, args, {
-    stdio: ["pipe", "inherit", "inherit"],
-    env: {
-      ...process.env,
-      TEST_LOCK_PID: String(process.pid),
-      TFX_HUB_PID_DIR: process.env.TFX_HUB_PID_DIR || testHubPidDir,
-      TFX_HUB_STATE_DIR: process.env.TFX_HUB_STATE_DIR || testHubPidDir,
-    },
-  });
-  updateChildPid(lock, child.pid);
-  // Close stdin immediately so node --test never blocks waiting for input.
-  child.stdin?.end();
-
+  let child = null;
   let finished = false;
   let requestedExitCode = null;
   let timeoutTimer = null;
@@ -390,14 +370,6 @@ export function main(argv = process.argv.slice(2)) {
     finish(requestedExitCode);
   }
 
-  timeoutTimer = setTimeout(() => {
-    console.error(
-      `\x1b[31m✗ test-lock child timed out after ${timeoutMs}ms (child PID ${child.pid})\x1b[0m`,
-    );
-    requestShutdown("SIGTERM", 124);
-  }, timeoutMs);
-  timeoutTimer.unref?.();
-
   process.once("exit", () => {
     if (!finished) terminateChild(child, "SIGTERM");
     releaseLock();
@@ -407,6 +379,27 @@ export function main(argv = process.argv.slice(2)) {
     process.once(signal, () => requestShutdown(signal));
   }
 
+  // Install termination handlers before spawning/advertising child state. The
+  // child can become ready before this wrapper reaches later setup lines on
+  // fast Linux CI; without early handlers an external SIGTERM can terminate the
+  // wrapper by signal instead of the controlled 128+signal exit path.
+  // forward args after -- to node --test
+  const args = preserveForceExitFailures(expandTestArgs(argv));
+  // stdio split (issue #192 F1): when prepare.mjs spawns this lock with
+  // ["ignore","pipe","pipe"], full inherit cascades the parent stdin=ignore
+  // to grand-child node --test, breaking ConPTY assumptions on Windows and
+  // surfacing as EXIT=1 (false-failed). Pipe stdin only — stdout/stderr stay
+  // inherited so the grand-child still streams to whoever attached to us.
+  child = spawn(process.execPath, args, {
+    stdio: ["pipe", "inherit", "inherit"],
+    env: {
+      ...process.env,
+      TEST_LOCK_PID: String(process.pid),
+      TFX_HUB_PID_DIR: process.env.TFX_HUB_PID_DIR || testHubPidDir,
+      TFX_HUB_STATE_DIR: process.env.TFX_HUB_STATE_DIR || testHubPidDir,
+    },
+  });
+
   child.on("error", (error) => {
     console.error(`test-lock failed to spawn child: ${error.message}`);
     finish(1);
@@ -419,6 +412,18 @@ export function main(argv = process.argv.slice(2)) {
     }
     finish(code ?? signalToExitCode(signal));
   });
+
+  updateChildPid(lock, child.pid);
+  // Close stdin immediately so node --test never blocks waiting for input.
+  child.stdin?.end();
+
+  timeoutTimer = setTimeout(() => {
+    console.error(
+      `\x1b[31m✗ test-lock child timed out after ${timeoutMs}ms (child PID ${child?.pid ?? "unknown"})\x1b[0m`,
+    );
+    requestShutdown("SIGTERM", 124);
+  }, timeoutMs);
+  timeoutTimer.unref?.();
 }
 
 if (process.argv[1] && resolve(process.argv[1]) === SCRIPT_PATH) {

package/scripts/tfx-route.sh

@@ -1121,11 +1121,12 @@ resolve_gemini_profile() {
     const primaryRaw = process.argv[2] || '{}';
     const settingsRaw = process.argv[3] || '{}';
     const defaults = {
-      pro31: 'gemini-3.1-pro-preview',
-      flash3: 'gemini-3-flash-preview',
-      pro25: 'gemini-2.5-pro',
-      flash25: 'gemini-2.5-flash',
-      lite25: 'gemini-2.5-flash-lite'
+      flash35_low: 'Gemini 3.5 Flash (Low)',
+      flash35: 'Gemini 3.5 Flash (Medium)',
+      flash35_high: 'Gemini 3.5 Flash (High)',
+      pro31_low: 'Gemini 3.1 Pro (Low)',
+      pro31: 'Gemini 3.1 Pro (High)',
+      flash3: 'Gemini 3 Flash'
     };
 
     if (typeof name === 'string' && name.startsWith('gemini-')) {
@@ -1193,9 +1194,9 @@ resolve_gemini_profile() {
       }
     }
 
-    process.stdout.write(defaults[name] || defaults[process.env.TFX_GEMINI_DEFAULT_PROFILE] || defaults.pro25);
+    process.stdout.write(defaults[name] || defaults[process.env.TFX_GEMINI_DEFAULT_PROFILE] || defaults.flash35);
   " "$profile" "$_GEMINI_PROFILE_CACHE" "$settings_cache" 2>/dev/null)
-  echo "${result:-gemini-2.5-pro}"
+  echo "${result:-Gemini 3.5 Flash (Medium)}"
 }
 
 # ── 라우팅 테이블 ──
@@ -1289,13 +1290,28 @@ route_agent() {
       CLI_EFFORT="gpt55_xhigh"; DEFAULT_TIMEOUT=3600; RUN_MODE="bg"; OPUS_OVERSIGHT="false" ;;
 
     # ─── Antigravity CLI 레인 (Gemini CLI 후속) ───
-    # 모델 선택 옵션 부재 (top-level), Antigravity 측 settings.json 으로 endemic.
+    # effort 차등: agent 별 GEMINI_PROFILE 을 설정하면 run_antigravity_exec() 가
+    # resolve_gemini_profile 로 해석해 `--model "<display name>"`을 agy_args 에
+    # 주입한다. 우선순위는 TFX_GEMINI_PROFILE(env) > GEMINI_PROFILE(agent) > flash35.
+    # CLI_ARGS 는 read -a 로 word-split 되므로 공백 포함 모델명을 여기 넣지 않는다.
     # #310: upstream callers are normalized through agent-map.json, but this
     # direct route entrypoint intentionally keeps agy as a compatibility alias.
-    designer|writer|gemini|antigravity|agy)
+    designer)
+      # 디자인 = 시각/UX 추론 → 3.5 Flash (High)
+      CLI_ARGS="--print --dangerously-skip-permissions"
+      GEMINI_PROFILE="flash35_high"
+      CLI_EFFORT="agy_v1"; DEFAULT_TIMEOUT=900; RUN_MODE="bg"; OPUS_OVERSIGHT="false" ;;
+    writer)
+      # 문서 작성 = 균형 → 3.5 Flash (Medium)
+      CLI_ARGS="--print --dangerously-skip-permissions"
+      GEMINI_PROFILE="flash35"
+      CLI_EFFORT="agy_v1"; DEFAULT_TIMEOUT=900; RUN_MODE="bg"; OPUS_OVERSIGHT="false" ;;
+    gemini|antigravity|agy)
+      # 직접 호출 alias — 기본 flash35. TFX_GEMINI_PROFILE 로 override 가능.
       # agy --print + --dangerously-skip-permissions 조합은 positional prompt에서
       # timeout이 재현되므로 wrapper 호출은 stdin pipe로 고정한다.
       CLI_ARGS="--print --dangerously-skip-permissions"
+      GEMINI_PROFILE="flash35"
       CLI_EFFORT="agy_v1"; DEFAULT_TIMEOUT=900; RUN_MODE="bg"; OPUS_OVERSIGHT="false" ;;
 
     # ─── 탐색 (Claude-native: Glob/Grep/Read 직접 접근) ───
@@ -1488,6 +1504,12 @@ apply_cli_mode() {
         CLI_TYPE="antigravity"
         CLI_CMD="agy"
         CLI_ARGS="--print --dangerously-skip-permissions"
+        # 주 라우팅(route_agent)과 동일하게 designer 만 effort 상향. 나머지는
+        # run_antigravity_exec 폴백(flash35) 또는 TFX_GEMINI_PROFILE override.
+        case "$AGENT_TYPE" in
+          designer) GEMINI_PROFILE="flash35_high" ;;
+          *)        GEMINI_PROFILE="flash35" ;;
+        esac
         CLI_EFFORT="agy_v1"
         DEFAULT_TIMEOUT=900
         echo "[tfx-route] TFX_CLI_MODE=antigravity: $AGENT_TYPE → antigravity($CLI_EFFORT)로 리매핑" >&2
@@ -2180,6 +2202,18 @@ run_antigravity_exec() {
   local -a agy_args=()
   read -r -a agy_args <<< "$CLI_ARGS"
 
+  # ── 프로필 기반 모델 주입 ──
+  # display name 에 공백/괄호가 있으므로(예: "Gemini 3.5 Flash (Medium)") CLI_ARGS
+  # 문자열이 아니라 agy_args 배열에 두 원소(--model, <display name>)로 append 해야
+  # "${agy_args[@]}" expand 시 단일 인자로 보존된다. 모델 SSOT 는 프로필 설정이다.
+  if [[ -z "${TFX_GEMINI_NO_MODEL:-}" ]]; then
+    local _agy_model
+    _agy_model="$(resolve_gemini_profile "${TFX_GEMINI_PROFILE:-${GEMINI_PROFILE:-flash35}}")"
+    if [[ -n "$_agy_model" ]]; then
+      agy_args+=("--model" "$_agy_model")
+    fi
+  fi
+
   if ! agy_supports_headless "$CLI_CMD"; then
     echo "[tfx-route] Antigravity CLI headless flags unsupported or missing: $CLI_CMD" >"$STDERR_LOG"
     return 127