@triflux/core 10.36.0 → 10.38.0

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)
@@ -45,13 +51,21 @@ export function toSessionPayload(payload) {
     typeof workspacePaths[0] === "string" && workspacePaths[0]
       ? workspacePaths[0]
       : process.cwd();
-  return JSON.stringify({ session_id: sessionId, cwd });
+  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 {
-        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/codex-session-hook.mjs

@@ -99,7 +99,7 @@ export async function runCodexSessionHook(stdinData, opts = {}) {
           await hubEnsureRun(stdinData);
         } catch {}
         try {
-          registerInteractiveSession(stdinData);
+          await Promise.resolve(registerInteractiveSession(stdinData));
         } catch {}
         try {
           await drainPendingSynapse(1000);

package/hooks/hooks.json

@@ -7,7 +7,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/hook-orchestrator.mjs\"",
+            "command": "node -e \"const fs=require('node:fs'),os=require('node:os'),path=require('node:path'),cp=require('node:child_process');const roots=[];try{roots.push(fs.readFileSync(path.join(os.homedir(),'.claude','scripts','.tfx-pkg-root'),'utf8').trim())}catch{}roots.push(process.env.PLUGIN_ROOT,process.env.CLAUDE_PLUGIN_ROOT);try{roots.push(cp.execFileSync('git',['rev-parse','--show-toplevel'],{encoding:'utf8',stdio:['ignore','pipe','ignore']}).trim())}catch{}roots.push(process.cwd());const root=roots.find(r=>r&&fs.existsSync(path.join(r,'hooks','hook-orchestrator.mjs')));if(!root){console.error('[triflux hook] cannot locate hooks/hook-orchestrator.mjs');process.exit(1)}const child=cp.spawnSync(process.execPath,[path.join(root,'hooks','hook-orchestrator.mjs')],{stdio:'inherit',env:process.env,windowsHide:true});process.exit(child.status??(child.signal?1:0));\"",
             "timeout": 15
           }
         ]
@@ -19,7 +19,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/hook-orchestrator.mjs\"",
+            "command": "node -e \"const fs=require('node:fs'),os=require('node:os'),path=require('node:path'),cp=require('node:child_process');const roots=[];try{roots.push(fs.readFileSync(path.join(os.homedir(),'.claude','scripts','.tfx-pkg-root'),'utf8').trim())}catch{}roots.push(process.env.PLUGIN_ROOT,process.env.CLAUDE_PLUGIN_ROOT);try{roots.push(cp.execFileSync('git',['rev-parse','--show-toplevel'],{encoding:'utf8',stdio:['ignore','pipe','ignore']}).trim())}catch{}roots.push(process.cwd());const root=roots.find(r=>r&&fs.existsSync(path.join(r,'hooks','hook-orchestrator.mjs')));if(!root){console.error('[triflux hook] cannot locate hooks/hook-orchestrator.mjs');process.exit(1)}const child=cp.spawnSync(process.execPath,[path.join(root,'hooks','hook-orchestrator.mjs')],{stdio:'inherit',env:process.env,windowsHide:true});process.exit(child.status??(child.signal?1:0));\"",
             "timeout": 5
           }
         ]
@@ -31,7 +31,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/hook-orchestrator.mjs\"",
+            "command": "node -e \"const fs=require('node:fs'),os=require('node:os'),path=require('node:path'),cp=require('node:child_process');const roots=[];try{roots.push(fs.readFileSync(path.join(os.homedir(),'.claude','scripts','.tfx-pkg-root'),'utf8').trim())}catch{}roots.push(process.env.PLUGIN_ROOT,process.env.CLAUDE_PLUGIN_ROOT);try{roots.push(cp.execFileSync('git',['rev-parse','--show-toplevel'],{encoding:'utf8',stdio:['ignore','pipe','ignore']}).trim())}catch{}roots.push(process.cwd());const root=roots.find(r=>r&&fs.existsSync(path.join(r,'hooks','hook-orchestrator.mjs')));if(!root){console.error('[triflux hook] cannot locate hooks/hook-orchestrator.mjs');process.exit(1)}const child=cp.spawnSync(process.execPath,[path.join(root,'hooks','hook-orchestrator.mjs')],{stdio:'inherit',env:process.env,windowsHide:true});process.exit(child.status??(child.signal?1:0));\"",
             "timeout": 10
           }
         ]
@@ -43,7 +43,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/hook-orchestrator.mjs\"",
+            "command": "node -e \"const fs=require('node:fs'),os=require('node:os'),path=require('node:path'),cp=require('node:child_process');const roots=[];try{roots.push(fs.readFileSync(path.join(os.homedir(),'.claude','scripts','.tfx-pkg-root'),'utf8').trim())}catch{}roots.push(process.env.PLUGIN_ROOT,process.env.CLAUDE_PLUGIN_ROOT);try{roots.push(cp.execFileSync('git',['rev-parse','--show-toplevel'],{encoding:'utf8',stdio:['ignore','pipe','ignore']}).trim())}catch{}roots.push(process.cwd());const root=roots.find(r=>r&&fs.existsSync(path.join(r,'hooks','hook-orchestrator.mjs')));if(!root){console.error('[triflux hook] cannot locate hooks/hook-orchestrator.mjs');process.exit(1)}const child=cp.spawnSync(process.execPath,[path.join(root,'hooks','hook-orchestrator.mjs')],{stdio:'inherit',env:process.env,windowsHide:true});process.exit(child.status??(child.signal?1:0));\"",
             "timeout": 3
           }
         ]
@@ -55,7 +55,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/hook-orchestrator.mjs\"",
+            "command": "node -e \"const fs=require('node:fs'),os=require('node:os'),path=require('node:path'),cp=require('node:child_process');const roots=[];try{roots.push(fs.readFileSync(path.join(os.homedir(),'.claude','scripts','.tfx-pkg-root'),'utf8').trim())}catch{}roots.push(process.env.PLUGIN_ROOT,process.env.CLAUDE_PLUGIN_ROOT);try{roots.push(cp.execFileSync('git',['rev-parse','--show-toplevel'],{encoding:'utf8',stdio:['ignore','pipe','ignore']}).trim())}catch{}roots.push(process.cwd());const root=roots.find(r=>r&&fs.existsSync(path.join(r,'hooks','hook-orchestrator.mjs')));if(!root){console.error('[triflux hook] cannot locate hooks/hook-orchestrator.mjs');process.exit(1)}const child=cp.spawnSync(process.execPath,[path.join(root,'hooks','hook-orchestrator.mjs')],{stdio:'inherit',env:process.env,windowsHide:true});process.exit(child.status??(child.signal?1:0));\"",
             "timeout": 10
           }
         ]
@@ -67,7 +67,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/hook-orchestrator.mjs\"",
+            "command": "node -e \"const fs=require('node:fs'),os=require('node:os'),path=require('node:path'),cp=require('node:child_process');const roots=[];try{roots.push(fs.readFileSync(path.join(os.homedir(),'.claude','scripts','.tfx-pkg-root'),'utf8').trim())}catch{}roots.push(process.env.PLUGIN_ROOT,process.env.CLAUDE_PLUGIN_ROOT);try{roots.push(cp.execFileSync('git',['rev-parse','--show-toplevel'],{encoding:'utf8',stdio:['ignore','pipe','ignore']}).trim())}catch{}roots.push(process.cwd());const root=roots.find(r=>r&&fs.existsSync(path.join(r,'hooks','hook-orchestrator.mjs')));if(!root){console.error('[triflux hook] cannot locate hooks/hook-orchestrator.mjs');process.exit(1)}const child=cp.spawnSync(process.execPath,[path.join(root,'hooks','hook-orchestrator.mjs')],{stdio:'inherit',env:process.env,windowsHide:true});process.exit(child.status??(child.signal?1:0));\"",
             "timeout": 5
           }
         ]
@@ -79,7 +79,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/hook-orchestrator.mjs\"",
+            "command": "node -e \"const fs=require('node:fs'),os=require('node:os'),path=require('node:path'),cp=require('node:child_process');const roots=[];try{roots.push(fs.readFileSync(path.join(os.homedir(),'.claude','scripts','.tfx-pkg-root'),'utf8').trim())}catch{}roots.push(process.env.PLUGIN_ROOT,process.env.CLAUDE_PLUGIN_ROOT);try{roots.push(cp.execFileSync('git',['rev-parse','--show-toplevel'],{encoding:'utf8',stdio:['ignore','pipe','ignore']}).trim())}catch{}roots.push(process.cwd());const root=roots.find(r=>r&&fs.existsSync(path.join(r,'hooks','hook-orchestrator.mjs')));if(!root){console.error('[triflux hook] cannot locate hooks/hook-orchestrator.mjs');process.exit(1)}const child=cp.spawnSync(process.execPath,[path.join(root,'hooks','hook-orchestrator.mjs')],{stdio:'inherit',env:process.env,windowsHide:true});process.exit(child.status??(child.signal?1:0));\"",
             "timeout": 5
           }
         ]
@@ -91,7 +91,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/hook-orchestrator.mjs\"",
+            "command": "node -e \"const fs=require('node:fs'),os=require('node:os'),path=require('node:path'),cp=require('node:child_process');const roots=[];try{roots.push(fs.readFileSync(path.join(os.homedir(),'.claude','scripts','.tfx-pkg-root'),'utf8').trim())}catch{}roots.push(process.env.PLUGIN_ROOT,process.env.CLAUDE_PLUGIN_ROOT);try{roots.push(cp.execFileSync('git',['rev-parse','--show-toplevel'],{encoding:'utf8',stdio:['ignore','pipe','ignore']}).trim())}catch{}roots.push(process.cwd());const root=roots.find(r=>r&&fs.existsSync(path.join(r,'hooks','hook-orchestrator.mjs')));if(!root){console.error('[triflux hook] cannot locate hooks/hook-orchestrator.mjs');process.exit(1)}const child=cp.spawnSync(process.execPath,[path.join(root,'hooks','hook-orchestrator.mjs')],{stdio:'inherit',env:process.env,windowsHide:true});process.exit(child.status??(child.signal?1:0));\"",
             "timeout": 35
           }
         ]
@@ -103,7 +103,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/hook-orchestrator.mjs\"",
+            "command": "node -e \"const fs=require('node:fs'),os=require('node:os'),path=require('node:path'),cp=require('node:child_process');const roots=[];try{roots.push(fs.readFileSync(path.join(os.homedir(),'.claude','scripts','.tfx-pkg-root'),'utf8').trim())}catch{}roots.push(process.env.PLUGIN_ROOT,process.env.CLAUDE_PLUGIN_ROOT);try{roots.push(cp.execFileSync('git',['rev-parse','--show-toplevel'],{encoding:'utf8',stdio:['ignore','pipe','ignore']}).trim())}catch{}roots.push(process.cwd());const root=roots.find(r=>r&&fs.existsSync(path.join(r,'hooks','hook-orchestrator.mjs')));if(!root){console.error('[triflux hook] cannot locate hooks/hook-orchestrator.mjs');process.exit(1)}const child=cp.spawnSync(process.execPath,[path.join(root,'hooks','hook-orchestrator.mjs')],{stdio:'inherit',env:process.env,windowsHide:true});process.exit(child.status??(child.signal?1:0));\"",
             "timeout": 5
           }
         ]
@@ -115,7 +115,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/hook-orchestrator.mjs\"",
+            "command": "node -e \"const fs=require('node:fs'),os=require('node:os'),path=require('node:path'),cp=require('node:child_process');const roots=[];try{roots.push(fs.readFileSync(path.join(os.homedir(),'.claude','scripts','.tfx-pkg-root'),'utf8').trim())}catch{}roots.push(process.env.PLUGIN_ROOT,process.env.CLAUDE_PLUGIN_ROOT);try{roots.push(cp.execFileSync('git',['rev-parse','--show-toplevel'],{encoding:'utf8',stdio:['ignore','pipe','ignore']}).trim())}catch{}roots.push(process.cwd());const root=roots.find(r=>r&&fs.existsSync(path.join(r,'hooks','hook-orchestrator.mjs')));if(!root){console.error('[triflux hook] cannot locate hooks/hook-orchestrator.mjs');process.exit(1)}const child=cp.spawnSync(process.execPath,[path.join(root,'hooks','hook-orchestrator.mjs')],{stdio:'inherit',env:process.env,windowsHide:true});process.exit(child.status??(child.signal?1:0));\"",
             "timeout": 5
           }
         ]
@@ -127,7 +127,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/hook-orchestrator.mjs\"",
+            "command": "node -e \"const fs=require('node:fs'),os=require('node:os'),path=require('node:path'),cp=require('node:child_process');const roots=[];try{roots.push(fs.readFileSync(path.join(os.homedir(),'.claude','scripts','.tfx-pkg-root'),'utf8').trim())}catch{}roots.push(process.env.PLUGIN_ROOT,process.env.CLAUDE_PLUGIN_ROOT);try{roots.push(cp.execFileSync('git',['rev-parse','--show-toplevel'],{encoding:'utf8',stdio:['ignore','pipe','ignore']}).trim())}catch{}roots.push(process.cwd());const root=roots.find(r=>r&&fs.existsSync(path.join(r,'hooks','hook-orchestrator.mjs')));if(!root){console.error('[triflux hook] cannot locate hooks/hook-orchestrator.mjs');process.exit(1)}const child=cp.spawnSync(process.execPath,[path.join(root,'hooks','hook-orchestrator.mjs')],{stdio:'inherit',env:process.env,windowsHide:true});process.exit(child.status??(child.signal?1:0));\"",
             "timeout": 5
           }
         ]
@@ -139,7 +139,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/hook-orchestrator.mjs\"",
+            "command": "node -e \"const fs=require('node:fs'),os=require('node:os'),path=require('node:path'),cp=require('node:child_process');const roots=[];try{roots.push(fs.readFileSync(path.join(os.homedir(),'.claude','scripts','.tfx-pkg-root'),'utf8').trim())}catch{}roots.push(process.env.PLUGIN_ROOT,process.env.CLAUDE_PLUGIN_ROOT);try{roots.push(cp.execFileSync('git',['rev-parse','--show-toplevel'],{encoding:'utf8',stdio:['ignore','pipe','ignore']}).trim())}catch{}roots.push(process.cwd());const root=roots.find(r=>r&&fs.existsSync(path.join(r,'hooks','hook-orchestrator.mjs')));if(!root){console.error('[triflux hook] cannot locate hooks/hook-orchestrator.mjs');process.exit(1)}const child=cp.spawnSync(process.execPath,[path.join(root,'hooks','hook-orchestrator.mjs')],{stdio:'inherit',env:process.env,windowsHide:true});process.exit(child.status??(child.signal?1:0));\"",
             "timeout": 5
           }
         ]

package/hooks/lib/resolve-root.mjs

@@ -43,6 +43,9 @@ export function resolvePluginRoot(callerUrl) {
   const breadcrumbRoot = readBreadcrumbRoot();
   if (isValidPluginRoot(breadcrumbRoot)) return breadcrumbRoot;
 
+  const pluginRoot = normalizeCandidate(process.env.PLUGIN_ROOT);
+  if (isValidPluginRoot(pluginRoot)) return pluginRoot;
+
   const envRoot = normalizeCandidate(process.env.CLAUDE_PLUGIN_ROOT);
   if (isValidPluginRoot(envRoot)) return envRoot;
 

package/hooks/session-start-fast.mjs

@@ -40,6 +40,98 @@ function parseStartPayload(stdinData) {
   }
 }
 
+function inferParticipantCli(payload) {
+  const direct = String(
+    payload?.actor_cli || payload?.cli || payload?.actor?.cli || "",
+  )
+    .trim()
+    .toLowerCase();
+  if (direct) return direct;
+
+  const eventName = String(payload?.hook_event_name || "").trim();
+  if (eventName === "SessionStart") return "claude";
+  if (eventName.toLowerCase().replace(/-/g, "_") === "session_start") {
+    return "codex";
+  }
+  return "participant";
+}
+
+async function defaultAppendParticipantCtoEvent(lakeRoot, event) {
+  const { appendCtoEvent } = await import("../cto/events.mjs");
+  return appendCtoEvent(lakeRoot, event, {
+    lockRetries: 1,
+    lockRetryDelayMs: 0,
+  });
+}
+
+async function defaultResolveParticipantLakeRoot(cwd) {
+  const { resolveLakeRootDir } = await import("../cto/lake-root.mjs");
+  const projectRoot = resolveLakeRootDir(cwd, {
+    execFileSync: (cmd, args, options = {}) =>
+      execFileSync(cmd, args, {
+        ...options,
+        timeout: 500,
+        killSignal: "SIGKILL",
+      }),
+  });
+  return {
+    projectRoot,
+    lakeRoot: projectRoot ? join(projectRoot, ".triflux", "lake") : "",
+  };
+}
+
+/**
+ * Append a compact CTO `session_started` event for participant hooks.
+ * This is intentionally observational only: no cleanup, reconciliation, or
+ * summarization policy is performed here. Callers may fire-and-forget it.
+ *
+ * @param {string} stdinData SessionStart-shaped stdin JSON
+ * @param {object} [seams] test seams
+ * @returns {Promise<object|null>}
+ */
+export async function emitParticipantSessionStarted(stdinData, seams = {}) {
+  try {
+    const payload = parseStartPayload(stdinData);
+    const sessionId = String(payload?.session_id || "").trim();
+    if (!sessionId) return null;
+    const cwd = typeof payload?.cwd === "string" ? payload.cwd : process.cwd();
+    const resolveLakeRoot =
+      seams.resolveLakeRoot || defaultResolveParticipantLakeRoot;
+    const resolved = await resolveLakeRoot(cwd);
+    const projectRoot =
+      typeof resolved === "string"
+        ? resolved
+        : String(resolved?.projectRoot || "");
+    const lakeRoot =
+      typeof resolved === "string"
+        ? join(resolved, ".triflux", "lake")
+        : String(resolved?.lakeRoot || "");
+    if (!lakeRoot) return null;
+
+    const event = {
+      event: "session_started",
+      source: "tfx_participant_hook",
+      session_id: sessionId,
+      project_root: projectRoot || cwd,
+      worktree_path: cwd,
+      branch: typeof payload?.branch === "string" ? payload.branch : "",
+      status: "active",
+      actor: {
+        cli: inferParticipantCli(payload),
+        session_id: sessionId,
+        host: typeof payload?.host === "string" ? payload.host : "local",
+      },
+      summary: `${inferParticipantCli(payload)} session_started ${sessionId}`,
+      now: seams.now,
+    };
+
+    const append = seams.ctoAppend || defaultAppendParticipantCtoEvent;
+    return await append(lakeRoot, event);
+  } catch {
+    return null;
+  }
+}
+
 function readAncestorCommands(pid = process.ppid, maxDepth = 6) {
   if (process.platform === "win32") return [];
   const commands = [];
@@ -146,17 +238,18 @@ function defaultGitRunner(cwd, args, cb) {
  * @param {Function} [seams.register]  registerSynapseSession 대체
  * @param {Function} [seams.heartbeat] heartbeatSynapseSession 대체
  * @param {Function} [seams.gitRunner] git runner 대체
- * @returns {void} (enrich 는 백그라운드에서 완료)
+ * @returns {Promise<object|null>|null} CTO append promise; enrich 는 백그라운드에서 완료
  */
 export function registerInteractiveSession(stdinData, seams = {}) {
+  let ctoEvent = null;
   const register = seams.register || registerSynapseSession;
   const heartbeat = seams.heartbeat || heartbeatSynapseSession;
   const gitRunner = seams.gitRunner || defaultGitRunner;
   try {
     const payload = parseStartPayload(stdinData);
     const sessionId = String(payload?.session_id || "").trim();
-    if (!sessionId) return;
-    if (shouldSkipInteractiveRegistration(payload, seams)) return;
+    if (!sessionId) return null;
+    if (shouldSkipInteractiveRegistration(payload, seams)) return null;
     const cwd = typeof payload?.cwd === "string" ? payload.cwd : process.cwd();
 
     // 1) cwd 만으로 즉시 minimal register (블로킹 git 없음, latency 0).
@@ -170,6 +263,10 @@ export function registerInteractiveSession(stdinData, seams = {}) {
       isRemote: false,
     });
 
+    ctoEvent = emitParticipantSessionStarted(stdinData, seams).catch(
+      () => null,
+    );
+
     // 2) worktree/branch 는 블로킹 경로 밖에서 비동기 enrich → heartbeat partial.
     gitContextAsync(cwd, gitRunner)
       .then(({ worktreePath, branch }) => {
@@ -180,6 +277,7 @@ export function registerInteractiveSession(stdinData, seams = {}) {
   } catch {
     /* best-effort — never affects session start */
   }
+  return ctoEvent;
 }
 
 /**
@@ -371,9 +469,10 @@ function runBackground(stdinData) {
     .catch(() => {}); // 완전 무시
 
   // Synapse: 인터랙티브 세션 self-register (fire-and-forget, hub 미응답 무시)
-  registerInteractiveSession(stdinData);
+  const ctoEvent = registerInteractiveSession(stdinData);
 
   // session-vault은 external source — hook-orchestrator가 execFile로 실행
+  return { ctoEvent };
 }
 
 /**
@@ -392,7 +491,7 @@ export async function execute(stdinData, externalHooks = []) {
 
   // DEFERRED + BACKGROUND: fire-and-forget
   runDeferred(stdinData);
-  runBackground(stdinData);
+  const background = runBackground(stdinData);
 
   // hook-orchestrator process.exit(0)s immediately after we return, which would
   // drop the just-fired Synapse register POST before it flushes to the loopback
@@ -401,7 +500,10 @@ export async function execute(stdinData, externalHooks = []) {
   // and the ceiling caps a hub stall so SessionStart never hangs. The async
   // git-enrich heartbeat stays best-effort (it may not have fired yet) — losing
   // it only drops worktree/branch enrichment, not the core registration.
-  await drainPendingSynapse(1000);
+  await Promise.allSettled([
+    drainPendingSynapse(1000),
+    background?.ctoEvent || Promise.resolve(null),
+  ]);
 
   const totalDur = performance.now() - totalStart;
   log.info(

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/routing/q-learning.mjs

@@ -164,6 +164,7 @@ export class QLearningRouter {
    * @param {number} [opts.epsilonMin=0.05] — 최소 엡실론
    * @param {number} [opts.minConfidence=0.6] — 최소 신뢰도 (이하면 폴백)
    * @param {string} [opts.modelPath] — Q-table 영속화 경로
+   * @param {() => number} [opts.random=Math.random] — 테스트/재현용 RNG seam
    */
   constructor(opts = {}) {
     this._lr = opts.learningRate ?? 0.1;
@@ -176,6 +177,8 @@ export class QLearningRouter {
     this._minConfidence = opts.minConfidence ?? 0.6;
     this._modelPath =
       opts.modelPath ?? join(homedir(), ".omc", "routing-model.json");
+    this._random =
+      typeof opts.random === "function" ? opts.random : Math.random;
 
     /** @type {Map<string, Map<string, number>>} state -> (action -> Q-value) */
     this._qTable = new Map();
@@ -223,12 +226,12 @@ export class QLearningRouter {
     const visits = this._visitCounts.get(state) || 0;
 
     // 엡실론-그리디: 탐색 vs 활용
-    const isExploration = Math.random() < this._epsilon;
+    const isExploration = this._random() < this._epsilon;
 
     let action;
     if (isExploration) {
       // 무작위 탐색
-      action = ACTIONS[Math.floor(Math.random() * ACTIONS.length)];
+      action = ACTIONS[Math.floor(this._random() * ACTIONS.length)];
     } else {
       // 최적 액션 선택 (최대 Q-value)
       let maxQ = -Infinity;

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

@@ -243,6 +243,7 @@ function candidateResultSummary(result) {
     ...summary,
     ok: result.ok === true,
     error: result.error ?? null,
+    errorCode: result.errorCode ?? null,
     sessionCount: Array.isArray(result.sessions) ? result.sessions.length : 0,
   };
 }
@@ -270,6 +271,14 @@ function buildProbeResponse({
     reason = "target-not-found";
     error = "Claude daemon target not found in reachable candidates";
   } else if (results.length > 0) {
+    const errorCodes = results
+      .map((result) => result.errorCode)
+      .filter(Boolean);
+    if (errorCodes.includes("stale-control-socket")) {
+      reason = "stale-control-socket";
+    } else if (errorCodes.includes("daemon-dir-missing")) {
+      reason = "daemon-dir-missing";
+    }
     error =
       results
         .map((result) => result.error)
@@ -341,6 +350,18 @@ export async function probeClaudeDaemonCandidates({
         error: ok ? null : list?.error || "Claude daemon list failed",
       });
     } catch (error) {
+      let errorCode = null;
+      if (error?.code === "ENOENT") {
+        try {
+          await fs.stat(candidate.daemonDir);
+          errorCode = "stale-control-socket";
+        } catch (statError) {
+          errorCode =
+            statError?.code === "ENOENT"
+              ? "daemon-dir-missing"
+              : "stale-control-socket";
+        }
+      }
       results.push({
         ok: false,
         candidate,
@@ -348,6 +369,7 @@ export async function probeClaudeDaemonCandidates({
         sessions: [],
         target: null,
         error: errorMessage(error),
+        errorCode,
       });
     }
   }
@@ -446,20 +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) {
-  const auth = await readDaemonControlKey(configDir);
+export async function buildDaemonControlAuth(configDir, opts = {}) {
+  if (!configDir) return {};
+  const auth = await readDaemonControlKey(configDir, opts);
   return auth ? { auth } : {};
 }
 
@@ -1223,7 +1254,7 @@ export function attachClaudeDaemonSession({
         cancelCompletionTimer();
       }
     });
-    socket.on("close", () => {
+    const finishClosed = () => {
       if (!settled) {
         if (pendingCompletion) {
           finish(pendingCompletion);
@@ -1231,7 +1262,9 @@ export function attachClaudeDaemonSession({
         }
         finish({ timedOut: false, matchedCompletion: false, closed: true });
       }
-    });
+    };
+    socket.on("end", finishClosed);
+    socket.on("close", finishClosed);
   });
 }
 

package/hud/hud-qos-status.mjs

@@ -177,8 +177,10 @@ async function main() {
   // 세션/누적 토큰 → context 대비 절약 배수 (개별 provider sv%)
   const ctxCapacity = deriveContextLimit(stdin);
   let codexSv = null;
+  let codexAccumulatorSv = null;
   if (svAccumulator?.codex?.tokens > 0) {
-    codexSv = svAccumulator.codex.tokens / ctxCapacity;
+    codexAccumulatorSv = svAccumulator.codex.tokens / ctxCapacity;
+    codexSv = codexAccumulatorSv;
   } else if (codexBuckets) {
     const main =
       codexBuckets.codex || codexBuckets[Object.keys(codexBuckets)[0]];
@@ -186,8 +188,10 @@ async function main() {
       codexSv = main.tokens.total_tokens / ctxCapacity;
   }
   let geminiSv = null;
+  let geminiAccumulatorSv = null;
   if (svAccumulator?.gemini?.tokens > 0) {
-    geminiSv = svAccumulator.gemini.tokens / ctxCapacity;
+    geminiAccumulatorSv = svAccumulator.gemini.tokens / ctxCapacity;
+    geminiSv = geminiAccumulatorSv;
   } else {
     const geminiTokens = geminiSession?.total || null;
     geminiSv = geminiTokens ? geminiTokens / ctxCapacity : null;
@@ -216,8 +220,15 @@ async function main() {
   const antigravitySlot1Bucket =
     antigravityModelFamily === "gemini" ? antigravityFamilyBucket : null;
 
-  // 합산 절약: Codex+Gemini sv% 합산 (컨텍스트 대비 위임 토큰 비율)
-  const combinedSvPct = Math.round(((codexSv ?? 0) + (geminiSv ?? 0)) * 100);
+  // 합산 절약은 svAccumulator 기반일 때만 표시한다.
+  // Codex bucket fallback은 account-window 누적 토큰이고 Gemini fallback은 latest
+  // session 토큰이라 서로 의미가 달라 합산하면 misleading cross-provider total이 된다.
+  const hasComparableSvAccumulator = Boolean(
+    codexAccumulatorSv != null || geminiAccumulatorSv != null,
+  );
+  const combinedSvPct = hasComparableSvAccumulator
+    ? Math.round(((codexAccumulatorSv ?? 0) + (geminiAccumulatorSv ?? 0)) * 100)
+    : null;
 
   // 인디케이터 인식 tier 선택 (stdin + Claude 사용량 기반)
   const CURRENT_TIER = selectTier(stdin, claudeUsageSnapshot.data);
@@ -230,7 +241,7 @@ async function main() {
       codexBuckets,
       antigravityReady ? null : geminiSession,
       antigravityReady ? null : geminiBucket,
-      antigravityReady ? Math.round((codexSv ?? 0) * 100) : combinedSvPct,
+      combinedSvPct,
       antigravityReady ? "a" : "g",
     );
     process.stdout.write(`\x1b[0m${microLine}\n`);

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/hud/renderers.mjs

@@ -326,7 +326,7 @@ export function getMicroLine(
   }
 
   // sv
-  const sv = formatSvPct(combinedSvPct || 0).trim();
+  const sv = formatSvPct(combinedSvPct).trim();
 
   const cols = getTerminalColumns() || 120;
   const line =
@@ -350,7 +350,7 @@ export function getClaudeRows(
   const ctxView = contextView || buildContextUsageView({}, null);
   const prefix = `${bold(claudeOrange("c"))}:`;
   // 절약 퍼센트
-  const svStr = formatSvPct(combinedSvPct || 0);
+  const svStr = formatSvPct(combinedSvPct);
   const svSuffix = `${dim("sv:")}${svStr}`;
 
   // API 실측 데이터

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@triflux/core",
-  "version": "10.36.0",
+  "version": "10.38.0",
   "description": "triflux core — CLI routing, pipeline, adapters. Zero native dependencies.",
   "type": "module",
   "main": "hub/index.mjs",

package/scripts/lib/cli-agy.mjs

@@ -10,6 +10,8 @@ export const id = "agy";
 export const cliType = "antigravity";
 export const command = "agy";
 
+// #310: agent-map.json normalizes upstream callers to antigravity,
+// but this adapter also accepts the direct `agy` route for compatibility.
 const AGENT_PROFILES = {
   antigravity: {
     profile: "agy_v1",

package/scripts/lib/codex-profile-config.mjs

@@ -0,0 +1,142 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+const PROFILE_SECTION_PREFIX = "profiles.";
+const SAFE_PROFILE_FILE_RE = /^[A-Za-z0-9_.-]+$/;
+
+function lineChunks(source = "") {
+  return String(source).match(/[^\n]*\n|[^\n]+$/g) || [];
+}
+
+function parseSectionHeader(line) {
+  const match = String(line)
+    .trimEnd()
+    .match(/^\s*\[([^\]]+)\]\s*(?:#.*)?$/);
+  return match ? match[1].trim() : null;
+}
+
+function profileNameFromSection(section) {
+  if (!section?.startsWith(PROFILE_SECTION_PREFIX)) return null;
+  return section.slice(PROFILE_SECTION_PREFIX.length).trim();
+}
+
+function isTopLevelProfileSelector(line) {
+  return /^\s*profile\s*=/.test(line);
+}
+
+function normalizeProfileBody(lines) {
+  const body = lines.join("").replace(/^\s+/, "").replace(/\s+$/, "");
+  return body ? `${body}\n` : "";
+}
+
+export function listLegacyCodexProfileSections(source = "") {
+  const names = [];
+  for (const line of lineChunks(source)) {
+    const name = profileNameFromSection(parseSectionHeader(line));
+    if (name && !names.includes(name)) names.push(name);
+  }
+  return names;
+}
+
+export function sanitizeCodexProfileConfig(
+  source = "",
+  { codexHome = null, migrateProfileFiles = true } = {},
+) {
+  const output = [];
+  const removedProfiles = [];
+  const migratedProfiles = [];
+  const skippedProfileFiles = [];
+  const captured = new Map();
+  let currentProfile = null;
+  let seenSection = false;
+  let removedTopLevelProfileSelector = false;
+
+  for (const line of lineChunks(source)) {
+    const section = parseSectionHeader(line);
+    if (section) {
+      seenSection = true;
+      const profileName = profileNameFromSection(section);
+      if (profileName) {
+        currentProfile = profileName;
+        if (!removedProfiles.includes(profileName))
+          removedProfiles.push(profileName);
+        if (!captured.has(profileName)) captured.set(profileName, []);
+        continue;
+      }
+      currentProfile = null;
+      output.push(line);
+      continue;
+    }
+
+    if (!seenSection && isTopLevelProfileSelector(line)) {
+      removedTopLevelProfileSelector = true;
+      continue;
+    }
+
+    if (currentProfile) {
+      captured.get(currentProfile)?.push(line);
+      continue;
+    }
+
+    output.push(line);
+  }
+
+  if (codexHome && migrateProfileFiles) {
+    mkdirSync(codexHome, { recursive: true });
+    for (const [profileName, bodyLines] of captured.entries()) {
+      if (!SAFE_PROFILE_FILE_RE.test(profileName)) {
+        skippedProfileFiles.push(profileName);
+        continue;
+      }
+      const body = normalizeProfileBody(bodyLines);
+      if (!body) {
+        skippedProfileFiles.push(profileName);
+        continue;
+      }
+      const profilePath = join(codexHome, `${profileName}.config.toml`);
+      if (existsSync(profilePath)) {
+        skippedProfileFiles.push(profileName);
+        continue;
+      }
+      writeFileSync(profilePath, body, "utf8");
+      migratedProfiles.push(profileName);
+    }
+  }
+
+  const toml = output.join("");
+  return {
+    changed: toml !== String(source),
+    toml,
+    removedProfiles,
+    migratedProfiles,
+    skippedProfileFiles,
+    removedTopLevelProfileSelector,
+  };
+}
+
+function stamp(now = () => new Date()) {
+  return now()
+    .toISOString()
+    .replace(/[-:]/g, "")
+    .replace(/\..*$/, "")
+    .replace("T", "-");
+}
+
+export function sanitizeCodexProfileConfigFile(
+  configPath,
+  {
+    codexHome = dirname(configPath),
+    backupPrefix = "bak-codex-profile-sanitize",
+    now = () => new Date(),
+  } = {},
+) {
+  if (!configPath || !existsSync(configPath)) {
+    return { changed: false, removedProfiles: [], migratedProfiles: [] };
+  }
+  const source = readFileSync(configPath, "utf8");
+  const sanitized = sanitizeCodexProfileConfig(source, { codexHome });
+  if (!sanitized.changed) return sanitized;
+  writeFileSync(`${configPath}.${backupPrefix}-${stamp(now)}`, source, "utf8");
+  writeFileSync(configPath, sanitized.toml, "utf8");
+  return sanitized;
+}

package/scripts/lib/mcp-guard-engine.mjs

@@ -182,6 +182,15 @@ function isAntigravityConfig(filePath) {
   return normalized.endsWith("/.gemini/config/mcp_config.json");
 }
 
+function isMigratedAntigravityConfig(filePath, raw = null) {
+  if (!isAntigravityConfig(filePath)) return false;
+  const resolvedPath = resolveFilePath(filePath);
+  const markerPath = join(dirname(resolvedPath), ".migrated");
+  if (!existsSync(markerPath)) return false;
+  const contents = raw === null ? readFileSync(resolvedPath, "utf8") : raw;
+  return String(contents || "").trim() === "";
+}
+
 function plaintextSecretHeaderClient(filePath) {
   const client = detectClient(filePath);
   return client === "gemini" || client === "antigravity" ? client : null;
@@ -970,7 +979,23 @@ function scanJsonConfig(filePath) {
   }
 
   try {
-    const parsed = readJsonFile(filePath);
+    const raw = readFileSync(filePath, "utf8");
+    if (isMigratedAntigravityConfig(filePath, raw)) {
+      return {
+        filePath,
+        client: detectClient(filePath),
+        label: detectLabel(filePath),
+        exists: true,
+        parseError: null,
+        servers: [],
+        stdioServers: [],
+        migrated: true,
+        message:
+          "Antigravity migrated MCP config; deprecated mcp_config.json left empty",
+      };
+    }
+
+    const parsed = JSON.parse(raw);
     const mcpServers = parsed?.mcpServers;
     const servers =
       !mcpServers || typeof mcpServers !== "object"
@@ -1705,6 +1730,8 @@ export function inspectRegistryStatus(registry = loadRegistryOrDefault()) {
         status = "missing-file";
       } else if (config.parseError) {
         status = "invalid-config";
+      } else if (config.migrated) {
+        status = "skipped";
       } else if (!actual) {
         status = "missing";
       } else if (expectedCommand) {
@@ -1733,6 +1760,8 @@ export function inspectRegistryStatus(registry = loadRegistryOrDefault()) {
         actualUrl: actual?.url || "",
         actualCommand: actual?.command || "",
         status,
+        migrated: Boolean(config.migrated),
+        message: config.message || "",
         headerStatus: currentHeaderStatus,
         expectedHeaderNames: headerNames(expectedHeaders),
         actualHeaderNames: headerNames(actualHeaders),
@@ -2015,6 +2044,19 @@ export function removeServerFromTargets(name, options = {}) {
     if (targetsFilter && !targetsFilter.has(target.client)) continue;
 
     const snapshot = scanConfig(target.filePath);
+    if (snapshot.migrated) {
+      actions.push({
+        type: "remove",
+        name: trimmedName,
+        filePath: target.filePath,
+        label: target.label,
+        status: "skipped",
+        migrated: true,
+        message: snapshot.message,
+      });
+      continue;
+    }
+
     if (snapshot.parseError) {
       actions.push({
         type: "remove",
@@ -2058,10 +2100,24 @@ export function syncRegistryTargets(options = {}) {
   );
   const actions = [];
   const invalidConfigs = new Set();
+  const skippedConfigs = new Set();
   const denylist = syncDenylistEntries(registry.policies);
 
   for (const target of syncTargets) {
     const snapshot = scanConfig(target.filePath);
+    if (snapshot.migrated) {
+      skippedConfigs.add(normalizeForMatch(target.filePath));
+      actions.push({
+        type: "sync",
+        filePath: target.filePath,
+        label: target.label,
+        status: "skipped",
+        migrated: true,
+        message: snapshot.message,
+      });
+      continue;
+    }
+
     if (snapshot.parseError) {
       invalidConfigs.add(normalizeForMatch(target.filePath));
       actions.push({
@@ -2097,6 +2153,10 @@ export function syncRegistryTargets(options = {}) {
   for (const target of primaryTargets) {
     const snapshot = scanConfig(target.filePath);
     const targetKey = normalizeForMatch(target.filePath);
+    if (snapshot.migrated || skippedConfigs.has(targetKey)) {
+      continue;
+    }
+
     if (snapshot.parseError) {
       if (!invalidConfigs.has(targetKey)) {
         actions.push({

package/scripts/lib/toml.mjs

@@ -1,5 +1,7 @@
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { createRequire } from "node:module";
+import { dirname } from "node:path";
+import { sanitizeCodexProfileConfig } from "./codex-profile-config.mjs";
 
 const require = createRequire(import.meta.url);
 let TOML = null;
@@ -100,14 +102,31 @@ export function patchMcpApprovalMode(source) {
 export function patchCodexConfigFile(path, { now = () => new Date() } = {}) {
   if (!path || !existsSync(path)) return { changed: false, count: 0 };
   const source = readFileSync(path, "utf8");
-  const patched = patchMcpApprovalMode(source);
-  if (!patched.changed) return patched;
+  const approvalPatched = patchMcpApprovalMode(source);
+  const profileSanitized = sanitizeCodexProfileConfig(approvalPatched.toml, {
+    codexHome: dirname(path),
+  });
+  const changed = approvalPatched.changed || profileSanitized.changed;
+  if (!changed) {
+    return {
+      changed: false,
+      count: 0,
+      removedProfiles: [],
+      migratedProfiles: [],
+    };
+  }
   const stamp = now()
     .toISOString()
     .replace(/[-:]/g, "")
     .replace(/\..*$/, "")
     .replace("T", "-");
   writeFileSync(`${path}.bak-${stamp}`, source);
-  writeFileSync(path, patched.toml);
-  return patched;
+  writeFileSync(path, profileSanitized.toml);
+  return {
+    changed: true,
+    count: approvalPatched.count,
+    removedProfiles: profileSanitized.removedProfiles,
+    migratedProfiles: profileSanitized.migratedProfiles,
+    toml: profileSanitized.toml,
+  };
 }