triflux 10.59.2 → 10.61.0

package/adapters/codex/skills/tfx-live/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: tfx-live
 description: >
-  Claude·Codex 세션을 실시간으로 생성·질의·대기·압축·종료하거나,
+  Claude·Codex·agy 세션을 실시간으로 생성·질의·대기·압축·종료하거나,
   tmux/daemon UDS 연결과 peer 중계를 운영할 때 사용한다.
-argument-hint: "<start|ask|wait|queue|compact|stop|rename|interrupt|probe|list-sessions|peer|converse|goal-driven> ..."
+argument-hint: "<start|ask|wait|queue|compact|stop|rename|interrupt|probe|list-sessions|peer|converse|goal-driven> [--cli codex|claude|agy] ..."
 ---
 
 # tfx-live
@@ -12,7 +12,7 @@ argument-hint: "<start|ask|wait|queue|compact|stop|rename|interrupt|probe|list-s
 
 Codex에서는 `$tfx-live`로 호출한다. CLI의 `--cli`는 현재 호스트가 아니라 대상 세션을 선택한다.
 
-`tfx-live`는 Claude Code와 Codex 세션을 tmux 또는 daemon UDS로 제어한다.
+`tfx-live`는 Claude Code와 Codex 세션을 tmux 또는 daemon UDS로, agy 세션을 로컬 tmux로 제어한다.
 `tfx-live --help`와 `tfx-live <동사> --help`로 사용법을 확인한다.
 
 ## 전송 경로
@@ -29,7 +29,27 @@ tfx-live ask --cli codex --session cx1 --prompt "현재 변경사항을 요약
 tfx-live stop --cli codex --session cx1
 ```
 
-새 세션 이름은 `<월>.<일> <주제>`로 짓는다. `start --name`을 생략하면 자동으로 만들고 `nameGenerated: true`를 보고한다. `--resume` 또는 `--resume-last`는 `--name`을 명시한 경우에만 이름을 적용한다. 승계 세션에는 기존 이름 뒤에 ` 2`, 이후 ` 3`을 붙인다. 이름 적용을 요청한 경우 결과의 `nameApplied: false`는 적용 실패를 뜻한다. Codex `start`는 `/rename` 제출을 입력창이 빌 때까지 확인하고, 이름으로 찾은 thread UUID를 `threadId`로 돌려주며 tmux 세션 옵션 `@tfx_codex_thread`에 남긴다. 로컬 Codex `--resume-last`는 Codex가 고른 thread를 사후에 찾는다. 띄운 뒤 공유 app-server daemon에 로드된 같은 cwd의 thread 중 rollout에 그 시각 이후의 resume 기록(`thread_settings_applied`)이 생긴 것이 정확히 하나이고 1.5초 뒤에도 같을 때만 `threadId`로 쓴다. 이 확인은 5초 안에 끝난다. TUI가 daemon을 쓰지 않거나 같은 cwd에서 동시에 resume이 일어나면 `null`이다. 기존 Codex UDS thread는 `tfx-live rename --cli codex --transport uds --thread ID --name "<이름>"`으로 이름을 바꾼다.
+macOS의 iTerm2에서 로컬 tmux 세션을 `start`하면 리드가 있는 창에 attach 탭이나 패인을 연다. `LC_TERMINAL=iTerm2` 또는 `TERM_PROGRAM=iTerm.app`일 때만 적용하며, 원격과 tmux 세션이 없는 daemon 경로는 제외한다. 같은 `--group NAME`은 한 탭에서 세로로 나누고 다른 그룹은 새 탭을 연다. `--group`을 생략하면 대상 CLI인 `claude`, `codex`, `agy`를 그룹으로 쓴다. `stop --session`은 tmux 종료 뒤 남은 iTerm 패인도 닫는다. 연동이 실패해도 세션 시작과 종료는 계속하며 결과의 `itermWarning`에 원인을 남긴다. 탭 제목은 iTerm2 Python 런타임으로 고정하며 처음 쓸 때 iTerm2 Scripts 폴더에 스크립트 하나를 설치하고, 런타임이 없으면 제목만 바뀌지 않는다.
+
+새 세션 이름은 `<월>.<일> <주제>`로 짓는다. `start --name`을 생략하면 자동으로 만들고 `nameGenerated: true`를 보고한다. `--resume` 또는 `--resume-last`는 `--name`을 명시한 경우에만 이름을 적용한다. 승계 세션에는 기존 이름 뒤에 ` 2`, 이후 ` 3`을 붙인다. 이름 적용을 요청한 경우 결과의 `nameApplied: false`는 미적용을 뜻한다. agy의 `namePending: true`는 첫 일반 ask에서 적용할 이름이 보류됐다는 뜻이다. Codex `start`는 `/rename` 제출을 입력창이 빌 때까지 확인하고, 이름으로 찾은 thread UUID를 `threadId`로 돌려주며 tmux 세션 옵션 `@tfx_codex_thread`에 남긴다. 로컬 Codex `--resume-last`는 Codex가 고른 thread를 사후에 찾는다. 띄운 뒤 공유 app-server daemon에 로드된 같은 cwd의 thread 중 rollout에 그 시각 이후의 resume 기록(`thread_settings_applied`)이 생긴 것이 정확히 하나이고 1.5초 뒤에도 같을 때만 `threadId`로 쓴다. 이 확인은 5초 안에 끝난다. TUI가 daemon을 쓰지 않거나 같은 cwd에서 동시에 resume이 일어나면 `null`이다. 기존 Codex UDS thread는 `tfx-live rename --cli codex --transport uds --thread ID --name "<이름>"`으로 이름을 바꾼다.
+
+## agy 세션
+
+```bash
+tfx-live start --cli agy --session ag1 --cwd ~/Projects --name "10.11 구현 검토" --effort low --unset-env 'TOSSINVEST_*,PRIVATE_KEY'
+tfx-live ask --cli agy --session ag1 --prompt "현재 변경사항을 요약해줘" --no-wait
+tfx-live wait --cli agy --session ag1 --request-id <requestId> --timeout 120
+tfx-live list-sessions --cli agy --cwd ~/Projects
+tfx-live stop --cli agy --session ag1
+```
+
+`start`는 `--model ID`, `--effort low|medium|high|xhigh|max`, `--sandbox`를 agy에 넘긴다. `--sandbox`의 실효는 미검증이다. `--resume ID`와 `--resume-last 1`로 대화를 재개한다. 준비 뒤 `/rename <이름>`의 확인 문구가 보이면 `nameApplied: true`다. 새 대화는 첫 메시지 전 `/rename`이 실패하므로 이름을 tmux 옵션 `@tfx_agy_name`에 남기고 `nameApplied: false`, `namePending: true`로 보류한다. 첫 일반 ask는 제출 확인 뒤 현재 대화 DB에 사용자 step이 생길 때까지 최대 5초 기다리고, 유휴를 기다리지 않고 `/rename`을 보낸다. 확인 문구가 보이면 옵션을 지우고 `nameApplied: true`를 반환하며, 실패하면 옵션을 남기고 `nameApplied: false`를 반환한다. `--no-wait`에도 적용한다. 열린 presence lock에서 찾은 대화 ID는 `conversationId`로 보고한다.
+
+agy `ask`의 기본 `--if-busy queue`는 바쁜 턴에도 바로 전송한다. agy 자체 대기열에 쌓이며 앞 입력을 덮어쓰지 않는다. `wait|fail|interrupt`도 선택할 수 있다. `ask --no-wait`는 `inputSent: true`, `requestId`와 함께 유휴 시 `status: "submitted"`, 바쁠 때 `status: "queued"`를 반환한다. `queue` 정책은 agy 전용이다. 슬래시 명령은 중계 표식 없이 보내고 바빠도 즉시 실행한다. DB step을 만들지 않아 `wait`로 추적하지 않으며, `--no-wait` 여부와 무관하게 제출 확인 뒤 `status: "submitted"`, `slashCommand: true`로 반환한다. `/clear`는 대화 ID를 바꾼다.
+
+`wait`는 `node:sqlite`(Node 22.13+)로 대화 DB의 사용자 입력 표식과 뒤따르는 step 상태를 읽는다. 요청 뒤부터 다음 사용자 입력 전까지 모델 응답 step이 하나 이상 있고 그 구간의 모든 step이 끝났으며, pane이 유휴 상태이거나 다음 요청이 시작됐으면 완료다. 같은 구간의 마지막 비어 있지 않은 모델 텍스트를 응답으로 쓴다. Escape로 취소된 step도 완료 상태로 기록된다. `--timeout 0`은 한 번만 확인한다. `/clear`는 대화 ID를 바꾸며 진행 중 `wait`는 처음 연 DB를 계속 본다. agy 설정의 `toolPermission`에 따라 도구 승인 화면이 뜰 수 있다. 승인을 기다리는 동안 턴이 멈추고 `wait`는 `working`으로 남는다. `tfx-live`는 agy에 `--dangerously-skip-permissions`를 쓰지 않는다. agy에는 compact가 없으므로 `/clear` 또는 handoff를 쓴다. `--remote`, `peer`, `converse`, `goal-driven`은 지원하지 않는다.
+
+`start --unset-env 'PREFIX_*,EXACT_NAME'`은 모든 CLI에 쓸 수 있다. 쉼표로 구분한 환경변수 이름과 끝의 `*`로 지정한 접두만 허용한다. tmux pane 셸의 환경에서 변수를 지우고 CLI를 실행하며 resume에도 적용한다. 로컬에서는 준비 후 CLI 프로세스 환경을 확인한다. macOS는 `ps -E` 출력에 `PATH=`가 있고 Linux는 `/proc/PID/environ`이 비어 있지 않을 때만 환경을 읽은 것으로 판정한다. 일치하는 변수가 실제로 남은 경우에만 생성한 세션을 종료하고 오류를 낸다. 환경을 읽지 못하면 세션을 유지하고 `unsetEnvVerified: false`, `unsetEnvWarning: "CLI environment unreadable; removal not verified"`를 반환한다. 결과의 `unsetEnv`는 요청 목록이고 `unsetEnvVerified`는 확인 여부다. 원격에서는 확인하지 않아 `false`이고 Windows에서는 이 옵션을 지원하지 않는다.
 
 ## 리드 운영
 
@@ -74,7 +94,7 @@ tfx-live queue --cli codex --thread <UUID> --delete <queuedMessageId>
 | Codex | 15% | 18% | 20% | 22% |
 | agy | 12% | 없음 | 15% | 18% |
 
-Claude는 85% 도달 시 바로 handoff를 지시한다. agy 행은 운영 지침이며 `tfx-live` 전송 대상이 아니다. `model_context_window`와 `model_auto_compact_token_limit`은 올리지 않는다.
+Claude는 85% 도달 시 바로 handoff를 지시한다. agy 행은 운영 지침이며 agy도 `tfx-live` 전송 대상이지만 컨텍스트 비율은 자동으로 읽지 못해 `null`로 보고하고 가드를 건너뛴다. `model_context_window`와 `model_auto_compact_token_limit`은 올리지 않는다.
 
 결과에는 `estimatedContextTokens`, `contextLimitTokens`, `contextLimitSource`, `contextPct`가 포함된다. Claude 실행 한도는 `executionContextLimitTokens`로 별도 보고하며 `CLAUDE_CODE_DISABLE_1M_CONTEXT=1`이면 200,000이다. 판정에는 공식 창과 실행 한도 중 작은 값을 쓴다. 한도를 모르면 비율은 `null`로 두고 경고만 한다. 사용량이 없는 `probe`는 `context: null`이다. 컨텍스트를 확인하려면 직접 `tfx-live probe`를 실행한다. `interrupt`, 자동 `ask`의 daemon probe, `stop --short`는 transcript를 읽지 않는다.
 

package/bin/tfx-live.mjs

@@ -3,6 +3,7 @@ import { execFile } from "node:child_process";
 import { randomBytes } from "node:crypto";
 import { mkdirSync, realpathSync, statSync, writeFileSync } from "node:fs";
 import {
+  chmod,
   mkdir,
   open,
   readdir,
@@ -81,6 +82,7 @@ const BOOLEAN_FLAGS = new Set([
   "attach-b",
   "no-wait",
   "no-relay-tag",
+  "sandbox",
 ]);
 const PEER_HOP_DONE_MARKER = "<<<TFX_PEER_HOP_DONE>>>";
 // uds-fallback diagnostics land here, written async so a failed daemon attach
@@ -92,8 +94,8 @@ const BUG_REPORT_DIR =
 function usage(command) {
   const lines = [
     "Usage:",
-    "  tfx-live start --session NAME [--name NAME] [--cli codex|claude] [--model ID] [--effort TIER] [--cwd DIR] [--remote HOST] [--resume ID] [--resume-last 1] [--ready-timeout 30] [--poll-interval 1500]",
-    "  tfx-live ask --session NAME[:WINDOW.PANE] --prompt TEXT [--cli codex|claude] [--if-busy wait|fail|interrupt] [--busy-timeout 60] [--timeout 60] [--remote HOST] [--settle 1500] [--poll-interval 1500]",
+    "  tfx-live start --session NAME [--name NAME] [--group NAME] [--cli codex|claude|agy] [--sandbox] [--unset-env PATTERNS] [--model ID] [--effort TIER] [--cwd DIR] [--remote HOST] [--resume ID] [--resume-last 1] [--ready-timeout 30] [--poll-interval 1500]",
+    "  tfx-live ask --session NAME[:WINDOW.PANE] --prompt TEXT [--cli codex|claude|agy] [--if-busy wait|fail|interrupt|queue] [--busy-timeout 60] [--timeout 60] [--remote HOST] [--settle 1500] [--poll-interval 1500]",
     "  tfx-live ask --cli codex [--transport queue|tmux] (--session NAME[:WINDOW.PANE] | --thread UUID) --prompt TEXT [--from NAME] [--timeout 60] [--no-wait]",
     "    Codex ask defaults to the app-server queue (thread/queue/add, `codex queue --message` only when add is unavailable; delivered when the TUI picks it up); tmux paste is the reported fallback and the path for slash commands.",
     "  tfx-live ask --cli codex --transport uds --thread ID|auto --prompt TEXT [--codex-socket PATH|default] [--cwd DIR] [--if-busy wait|fail|steer] [--busy-timeout 60] [--timeout 60] [--max-turn SECONDS]",
@@ -102,16 +104,17 @@ function usage(command) {
     "  tfx-live compact --cli claude --session NAME [--instructions TEXT] [--if-busy fail|wait] [--timeout 60]",
     "  tfx-live wait --cli claude (--short SHORT | --session-id ID | --session NAME[:WINDOW.PANE]) [--request-id ID] [--config-dir DIR] [--bridge ABS] [--timeout 60] [--poll-interval 1500]",
     "  tfx-live wait --cli codex (--session NAME[:WINDOW.PANE] | --thread UUID) --request-id ID [--timeout 60] [--poll-interval 1500]",
+    "  tfx-live wait --cli agy --session NAME[:WINDOW.PANE] [--request-id ID] [--timeout 60] [--poll-interval 1500]",
     "  tfx-live queue --cli codex (--session NAME[:WINDOW.PANE] | --thread UUID) [--request-id ID] [--delete QUEUED_ID|all]",
     "    queue lists or deletes items the TUI has not picked up yet (official app-server thread/queue API); missing means already delivered or gone.",
     "  tfx-live rename --cli codex --transport uds --thread ID --name NAME [--codex-socket PATH|default]",
     "    transport: auto is the default for Claude when --short/--session-id is present; otherwise tmux. bridge path: --bridge > $TFX_BRIDGE > $TFX_REPO_ROOT/hub/bridge.mjs > bundled Triflux hub/bridge.mjs.",
-    "  tfx-live interrupt --session NAME [--cli codex|claude] [--transport tmux|uds|auto] [--short SHORT | --session-id ID] [--config-dir DIR] [--bridge ABS] [--timeout 5]",
-    "  tfx-live stop --session NAME [--cli codex|claude] [--remote HOST]",
+    "  tfx-live interrupt --session NAME [--cli codex|claude|agy] [--transport tmux|uds|auto] [--short SHORT | --session-id ID] [--config-dir DIR] [--bridge ABS] [--timeout 5]",
+    "  tfx-live stop --session NAME [--cli codex|claude|agy] [--remote HOST]",
     "  tfx-live stop --cli claude (--short SHORT | --session-id ID) [--config-dir DIR]",
     "  tfx-live probe [--short SHORT] [--session-id ID] [--config-dir DIR] [--bridge ABS] [--timeout 10]",
-    "  tfx-live list-sessions --cli codex|claude [--transport tmux|uds] [--codex-socket PATH|default] [--cwd DIR] [--remote HOST (codex tmux only)]",
-    "    Claude list-sessions supports local tmux only; --transport uds requires --cli codex.",
+    "  tfx-live list-sessions --cli codex|claude|agy [--transport tmux|uds] [--codex-socket PATH|default] [--cwd DIR] [--remote HOST (codex tmux only)]",
+    "    Claude and agy list-sessions support local tmux only; --transport uds requires --cli codex.",
     "  tfx-live converse --session NAME --prompts-file PATH [--cli codex|claude] [--remote HOST] [--cwd DIR] [--timeout 60] [--settle 1500]",
     "  tfx-live goal-driven --session NAME --goal TEXT [--cli codex|claude] [--remote HOST] [--cwd DIR] [--timeout 60] [--settle 1500] [--max-rounds 8] [--done-token DONE]",
     "  tfx-live peer [--cli-a codex] [--cli-b claude] [--model-a ID] [--model-b ID] [--effort-a TIER] [--effort-b TIER] [--session-a NAME[:WINDOW.PANE]] [--session-b NAME[:WINDOW.PANE]] [--attach-a] [--attach-b] [--transport-a tmux|uds|auto] [--transport-b tmux|uds|auto] [--short-a SHORT] [--short-b SHORT] [--session-id-a ID] [--session-id-b ID] [--thread-a ID|auto] [--thread-b ID|auto] [--codex-socket-a PATH|default] [--codex-socket-b PATH|default] [--bridge ABS] [--remote HOST] [--cwd DIR] [--if-busy wait|fail] [--if-busy-a POLICY] [--if-busy-b POLICY] [--busy-timeout 60] [--max-turn SECONDS] [--rounds 4] [--mode counting|freeform] [--seed TEXT] [--timeout 60]",
@@ -214,6 +217,7 @@ function contextPctFlag(flags, name, defaultValue) {
 }
 
 function contextOpts(flags, cli) {
+  if (cli === "agy") return {};
   return {
     warnContextPct: contextPctFlag(
       flags,
@@ -236,6 +240,12 @@ function selectAdapter(flags) {
       `--cli must be one of: ${Object.keys(ADAPTERS).join(", ")}`,
     );
   }
+  if (cli === "agy" && flags.remote)
+    throw new Error("agy supports local tmux only; --remote is unavailable");
+  if (flags.sandbox && cli !== "agy")
+    throw new Error("--sandbox is only supported with --cli agy");
+  if (flags["if-busy"] === "queue" && cli !== "agy")
+    throw new Error("--if-busy queue is only supported with --cli agy");
   return adapter;
 }
 
@@ -261,6 +271,270 @@ function shellQuote(args) {
     .join(" ");
 }
 
+function withUnsetEnv(command, patterns) {
+  if (!patterns.length) return command;
+  if (patterns.some((pattern) => !/^[A-Za-z_][A-Za-z0-9_]*\*?$/.test(pattern)))
+    throw new Error(
+      "--unset-env requires comma-separated environment names or prefixes ending in '*'",
+    );
+  if (process.platform === "win32")
+    throw new Error("--unset-env is unavailable on Windows");
+  const exact = patterns.filter((pattern) => !pattern.endsWith("*"));
+  const prefixes = patterns.filter((pattern) => pattern.endsWith("*"));
+  const expressions = prefixes.flatMap((pattern) => [
+    "-e",
+    `s/^\\(${pattern.slice(0, -1)}[A-Za-z0-9_]*\\)=.*/-u \\1/p`,
+  ]);
+  return [
+    "env",
+    ...exact.flatMap((name) => ["-u", name]),
+    ...(expressions.length
+      ? [`$(env | sed -n ${shellQuote(expressions)})`]
+      : []),
+    command,
+  ].join(" ");
+}
+
+function inspectUnsetEnv(environment, patterns, platform) {
+  const readable =
+    platform === "darwin"
+      ? /(?:^|\s)PATH=/.test(environment)
+      : environment.length > 0;
+  if (!readable) return { readable: false, remaining: [] };
+  const names =
+    platform === "darwin"
+      ? [...environment.matchAll(/(?:^|\s)([A-Za-z_][A-Za-z0-9_]*)=/g)].map(
+          (match) => match[1],
+        )
+      : environment.split("\0").map((entry) => entry.split("=", 1)[0]);
+  return {
+    readable,
+    remaining: names.filter((name) =>
+      patterns.some((pattern) =>
+        pattern.endsWith("*")
+          ? name.startsWith(pattern.slice(0, -1))
+          : name === pattern,
+      ),
+    ),
+  };
+}
+
+async function paneCliProcess(session, cli, panePid) {
+  if (!panePid) {
+    const { stdout } = await runTmux(null, [
+      "display-message",
+      "-p",
+      "-t",
+      session,
+      "#{pane_pid}",
+    ]);
+    panePid = Number(stdout.trim());
+  }
+  const { stdout } = await execFileAsync("ps", ["-eo", "pid=,ppid=,args="], {
+    timeout: 5000,
+    maxBuffer: MAX_BUFFER,
+  });
+  for (const line of stdout.split(/\r?\n/)) {
+    const match = line.match(/^\s*(\d+)\s+(\d+)\s+(.*)$/);
+    if (!match) continue;
+    const pid = Number(match[1]);
+    if (pid !== panePid && Number(match[2]) !== panePid) continue;
+    if (
+      cli === "codex"
+        ? isCodexProcessCommand(match[3])
+        : new RegExp(`^(?:\\S*/)?${cli}(?:\\s|$)`).test(match[3])
+    )
+      return { pid, command: match[3] };
+  }
+  return null;
+}
+
+async function agyConversation(pid) {
+  if (!pid) return null;
+  try {
+    const { stdout } = await execFileAsync("lsof", ["-Fn", "-p", String(pid)], {
+      timeout: 5000,
+      maxBuffer: MAX_BUFFER,
+    });
+    const match = stdout.match(
+      /^n(.*\/antigravity-cli)\/presence\/([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.lock$/im,
+    );
+    return match
+      ? {
+          conversationId: match[2],
+          dbPath: pathJoin(match[1], "conversations", `${match[2]}.db`),
+        }
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+async function discoverAgyTmuxSessions({ cwd = null } = {}) {
+  const result = { ok: true, cli: "agy", cwd: normalizeCwd(cwd), sessions: [] };
+  let stdout;
+  try {
+    ({ stdout } = await runTmux(null, [
+      "list-panes",
+      "-a",
+      "-F",
+      TMUX_DISCOVERY_FORMAT,
+    ]));
+  } catch (error) {
+    return {
+      ...result,
+      ok: false,
+      reason: "tmux-unavailable",
+      error: error.message,
+    };
+  }
+  for (const line of stdout.split(/\r?\n/)) {
+    const [session, , , window, pane, paneCwd, , , , pid, paneId] =
+      line.split("\t");
+    if (!paneId || (result.cwd && normalizeCwd(paneCwd) !== result.cwd))
+      continue;
+    const target = `${session}:${window}.${pane}`;
+    const agyProcess = await paneCliProcess(target, "agy", Number(pid));
+    if (!agyProcess) continue;
+    const conversation = await agyConversation(agyProcess.pid);
+    result.sessions.push({
+      session,
+      target,
+      paneId,
+      cwd: normalizeCwd(paneCwd),
+      ...agyProcess,
+      conversationId: conversation?.conversationId ?? null,
+    });
+  }
+  return result;
+}
+
+function agyStepText(payload, stepType) {
+  const fieldPath = stepType === 14 ? [19, 2] : [20, 1];
+  let bytes = Buffer.from(payload);
+  for (const wanted of fieldPath) {
+    let offset = 0;
+    let found = null;
+    const varint = () => {
+      let value = 0;
+      let factor = 1;
+      for (let count = 0; count < 10 && offset < bytes.length; count++) {
+        const byte = bytes[offset++];
+        value += (byte & 127) * factor;
+        if (!(byte & 128)) return value;
+        factor *= 128;
+      }
+      throw new Error("Invalid agy protobuf varint");
+    };
+    while (offset < bytes.length) {
+      const tag = varint();
+      const field = Math.floor(tag / 8);
+      const wire = tag % 8;
+      if (!field) throw new Error("Invalid agy protobuf field");
+      if (wire === 0) {
+        varint();
+      } else if (wire === 1 || wire === 5) {
+        offset += wire === 1 ? 8 : 4;
+        if (offset > bytes.length)
+          throw new Error("Invalid agy protobuf length");
+      } else if (wire === 2) {
+        const length = varint();
+        if (!Number.isSafeInteger(length) || offset + length > bytes.length)
+          throw new Error("Invalid agy protobuf length");
+        if (field === wanted) found = bytes.subarray(offset, offset + length);
+        offset += length;
+      } else {
+        throw new Error(`Unsupported agy protobuf wire type: ${wire}`);
+      }
+    }
+    if (!found) return "";
+    bytes = found;
+  }
+  return bytes.toString("utf8");
+}
+
+function agyWaitVerdict(steps, requestId, visible) {
+  const request = steps.findLastIndex(
+    (step) =>
+      step.step_type === 14 &&
+      (!requestId ||
+        agyStepText(step.step_payload, 14).includes(
+          `[tfx-live req=${requestId}]`,
+        )),
+  );
+  if (request < 0)
+    return {
+      status: isAgyQueuedCapture(visible) ? "queued" : "submitted",
+      done: false,
+      response: "",
+    };
+  const nextRequest = steps.findIndex(
+    (step, index) => index > request && step.step_type === 14,
+  );
+  // 다음 사용자 입력이 시작됐으면 그 턴의 진행 상태는 이 요청의 완료를 막지 않는다.
+  const turn = steps.slice(
+    request + 1,
+    nextRequest < 0 ? undefined : nextRequest,
+  );
+  let response = "";
+  for (const step of turn) {
+    if (step.step_type !== 15) continue;
+    const text = agyStepText(step.step_payload, 15);
+    if (text) response = text;
+  }
+  const done =
+    turn.some((step) => step.step_type === 15) &&
+    turn.every((step) => step.status === 3) &&
+    (nextRequest >= 0 || !ADAPTERS.agy.isBusy(visible));
+  return { status: done ? "completed" : "working", done, response };
+}
+
+async function waitAgy({
+  session,
+  requestId = null,
+  timeoutMs,
+  pollIntervalMs,
+}) {
+  let DatabaseSync;
+  try {
+    ({ DatabaseSync } = await import("node:sqlite"));
+  } catch {
+    throw new Error("agy wait requires node:sqlite (Node 22.13+)");
+  }
+  const agyProcess = await paneCliProcess(session, "agy");
+  if (!agyProcess)
+    throw new Error(`no live agy process in tmux target ${session}`);
+  const conversation = await agyConversation(agyProcess.pid);
+  if (!conversation)
+    throw new Error(`agy conversation unavailable in tmux target ${session}`);
+  // 처음 연 DB 를 고정해 대기 중 /clear 로 바뀐 대화를 따라가지 않는다.
+  const db = new DatabaseSync(conversation.dbPath, { readOnly: true });
+  const deadline = Date.now() + timeoutMs;
+  try {
+    const query = db.prepare(
+      "SELECT idx, step_type, status, step_payload FROM steps ORDER BY idx",
+    );
+    for (;;) {
+      const visible = await captureVisible(null, session);
+      const verdict = agyWaitVerdict(query.all(), requestId, visible);
+      const timedOut = !verdict.done && Date.now() >= deadline;
+      const result = {
+        ok: true,
+        cli: "agy",
+        ...verdict,
+        timedOut,
+        requestId,
+        conversationId: conversation.conversationId,
+        session,
+      };
+      if (verdict.done || timedOut) return result;
+      await sleep(Math.min(pollIntervalMs, deadline - Date.now()));
+    }
+  } finally {
+    db.close();
+  }
+}
+
 function buildTmuxCommand(remote, tmuxArgs) {
   if (!remote) {
     return { command: "tmux", args: tmuxArgs };
@@ -1139,7 +1413,8 @@ function promptLineIndex(lines, prompt) {
   return -1;
 }
 
-function isComposerPromptLine(line) {
+function isComposerPromptLine(line, cli) {
+  if (cli === "agy") return /^\s*>(?:\s|$)/.test(stripAnsi(line));
   return hasCodexComposerPrompt(line) || hasClaudeComposerPrompt(line);
 }
 
@@ -1156,21 +1431,21 @@ function promptComposerNeedle(prompt) {
   );
 }
 
-function composerLineMatchesPrompt(line, prompt) {
+function composerLineMatchesPrompt(line, prompt, cli) {
   const needle = promptComposerNeedle(prompt);
   return (
     Boolean(needle) &&
-    isComposerPromptLine(line) &&
+    isComposerPromptLine(line, cli) &&
     String(line).includes(needle)
   );
 }
 
-function composerShowsPrompt(text, prompt) {
+function composerShowsPrompt(text, prompt, cli) {
   const activeComposerLine = String(text)
     .split("\n")
-    .filter(isComposerPromptLine)
+    .filter((line) => isComposerPromptLine(line, cli))
     .at(-1);
-  return composerLineMatchesPrompt(activeComposerLine, prompt);
+  return composerLineMatchesPrompt(activeComposerLine, prompt, cli);
 }
 
 function nextComposerPromptIndex(lines, startIndex) {
@@ -1671,6 +1946,28 @@ async function dismissClaudeTourPrompt(remote, session) {
   return { dismissed: true, raw };
 }
 
+function isAgyTrustPrompt(text) {
+  return /Do you trust the contents of this project\?/.test(stripAnsi(text));
+}
+
+function isAgyQueuedCapture(text) {
+  return /Press up to edit queued messages/i.test(stripAnsi(text));
+}
+
+async function dismissAgyTrustPrompt(remote, session) {
+  let raw = await captureVisible(remote, session);
+  for (let attempt = 0; attempt < 4 && isAgyTrustPrompt(raw); attempt++) {
+    if (/^\s*>\s+Yes, I trust this folder\s*$/m.test(stripAnsi(raw))) {
+      await runTmux(remote, ["send-keys", "-t", session, "Enter"]);
+      return { dismissed: true, raw };
+    }
+    await runTmux(remote, ["send-keys", "-t", session, "Up"]);
+    await sleep(200);
+    raw = await captureVisible(remote, session);
+  }
+  return { dismissed: false, raw };
+}
+
 const ADAPTERS = {
   codex: {
     cli: "codex",
@@ -1774,12 +2071,36 @@ const ADAPTERS = {
       },
     ],
   },
+  agy: {
+    cli: "agy",
+    launchKeys: ["agy", "Enter"],
+    resumeById: (id) => shellQuote(["agy", "--conversation", id]),
+    resumeLast: () => shellQuote(["agy", "--continue"]),
+    isReady: (text) =>
+      !isAgyTrustPrompt(text) && /^\s*>(?:\s|$)/m.test(stripAnsi(text)),
+    isBusy: (text) =>
+      /esc to cancel/i.test(stripAnsi(text)) || isAgyQueuedCapture(text),
+    contextPct: () => null,
+    hasLoginGuard: () => false,
+    startupScreens: [
+      {
+        name: "trust",
+        isPresent: isAgyTrustPrompt,
+        dismiss: dismissAgyTrustPrompt,
+      },
+    ],
+  },
 };
 
-function buildLaunchKeys(adapter, { model, effort, name } = {}) {
+function buildLaunchKeys(adapter, { model, effort, name, sandbox } = {}) {
   const hasModel = model !== undefined;
   const hasEffort = effort !== undefined;
-  if (!hasModel && !hasEffort && !(adapter.cli === "claude" && name)) {
+  if (
+    !hasModel &&
+    !hasEffort &&
+    !sandbox &&
+    !(adapter.cli === "claude" && name)
+  ) {
     return adapter.launchKeys;
   }
 
@@ -1802,6 +2123,16 @@ function buildLaunchKeys(adapter, { model, effort, name } = {}) {
     if (hasEffort) {
       overrideArgs.push("--effort", effort);
     }
+  } else if (adapter.cli === "agy") {
+    if (hasModel) overrideArgs.push("--model", model);
+    if (hasEffort) {
+      if (!["low", "medium", "high", "xhigh", "max"].includes(effort))
+        throw new Error(
+          "agy --effort must be low, medium, high, xhigh, or max",
+        );
+      overrideArgs.push("--effort", effort);
+    }
+    if (sandbox) overrideArgs.push("--sandbox");
   } else {
     throw new Error(`Unsupported adapter: ${adapter.cli}`);
   }
@@ -2140,6 +2471,151 @@ async function resumedCodexThread(
   return matches.length === 1 ? matches[0] : null;
 }
 
+const ITERM_TITLE_SCRIPT_NAME = "com.triflux.live-title.py";
+const ITERM_TITLE_SCRIPT = String.raw`#!/usr/bin/env python3
+import sys
+
+import iterm2
+
+
+async def main(connection):
+    session_id, group, name = sys.argv[1:]
+    app = await iterm2.async_get_app(connection)
+    session = app.get_session_by_id(session_id)
+    if session is None:
+        raise RuntimeError(f"iTerm session not found: {session_id}")
+    update = iterm2.LocalWriteOnlyProfile()
+    update.set_allow_title_setting(False)
+    update.set_name(name)
+    await session.async_set_profile_properties(update)
+    await session.tab.async_set_variable("user.tfxLiveGroup", group)
+    await session.tab.async_set_title(r"\(user.tfxLiveGroup)")
+    await session.async_set_variable("user.tfxLiveTitleApplied", "1")
+
+
+iterm2.run_until_complete(main)
+`;
+
+function appleScriptString(value) {
+  if (/[\u0000-\u001f\u007f-\u009f\u2028\u2029]/u.test(value))
+    throw new Error("iTerm values must not contain control characters");
+  return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+
+function shouldUseIterm(
+  remote,
+  platform = process.platform,
+  env = process.env,
+) {
+  return (
+    !remote &&
+    platform === "darwin" &&
+    (env.LC_TERMINAL === "iTerm2" || env.TERM_PROGRAM === "iTerm.app")
+  );
+}
+
+async function openItermSession(session, group) {
+  const groupLiteral = appleScriptString(group);
+  const sessionLiteral = appleScriptString(session);
+  const leaderId = appleScriptString(
+    process.env.ITERM_SESSION_ID?.split(":")[1] ?? "",
+  );
+  // tmux 안의 리드는 ITERM_SESSION_ID 가 tmux 를 처음 띄운 터미널 값이라, 지금 붙어 있는 클라이언트 tty 로 창을 찾는다.
+  const clients = process.env.TMUX_PANE
+    ? await runTmux(null, [
+        "list-clients",
+        "-t",
+        process.env.TMUX_PANE,
+        "-F",
+        "#{client_activity} #{client_tty}",
+      ]).catch(() => ({ stdout: "" }))
+    : { stdout: "" };
+  const leaderTty = appleScriptString(
+    clients.stdout
+      .trim()
+      .split("\n")
+      .filter(Boolean)
+      .map((line) => line.split(" "))
+      .sort((a, b) => Number(b[0]) - Number(a[0]))[0]?.[1] ?? "",
+  );
+  const { stdout: tmuxPath } = await execFileAsync("which", ["tmux"], {
+    timeout: 2000,
+  });
+  const command = appleScriptString(
+    `${shellQuote([realpathSync(tmuxPath.trim()), "attach-session", "-t"])} '=${session.replace(/'/g, `'"'"'`)}'`,
+  );
+  const script = `tell application "iTerm2"
+  set leaderWindow to current window
+  set ttyWindow to missing value
+  set idWindow to missing value
+  repeat with candidateWindow in windows
+    repeat with candidateTab in tabs of candidateWindow
+      repeat with candidateSession in sessions of candidateTab
+        if ${leaderTty} is not "" and tty of candidateSession is ${leaderTty} then set ttyWindow to candidateWindow
+        if ${leaderId} is not "" and id of candidateSession is ${leaderId} then set idWindow to candidateWindow
+      end repeat
+    end repeat
+  end repeat
+  if ttyWindow is not missing value then
+    set leaderWindow to ttyWindow
+  else if idWindow is not missing value then
+    set leaderWindow to idWindow
+  end if
+  set groupSession to missing value
+  repeat with candidateTab in tabs of leaderWindow
+    repeat with candidateSession in sessions of candidateTab
+      try
+        tell candidateSession to set candidateGroup to variable named "user.tfx_group"
+        if candidateGroup is ${groupLiteral} then
+          set groupSession to candidateSession
+          exit repeat
+        end if
+      end try
+    end repeat
+    if groupSession is not missing value then exit repeat
+  end repeat
+  set didSplit to groupSession is not missing value
+  if didSplit then
+    tell groupSession to set newSession to split vertically with default profile command ${command}
+  else
+    tell leaderWindow to set newTab to create tab with default profile command ${command}
+    set newSession to current session of newTab
+  end if
+  tell newSession
+    set variable named "user.tfx_group" to ${groupLiteral}
+    set variable named "user.tfx_session" to ${sessionLiteral}
+  end tell
+  return (id of newSession) & linefeed & (didSplit as text)
+end tell`;
+  const { stdout } = await execFileAsync("/usr/bin/osascript", ["-e", script], {
+    timeout: 5000,
+    maxBuffer: 64 * 1024,
+  });
+  const [sessionId, split] = stdout.trim().split("\n");
+  if (!sessionId || !["true", "false"].includes(split))
+    throw new Error("iTerm did not return a session ID and split status");
+  return { sessionId, group, split: split === "true" };
+}
+
+async function closeItermSession(sessionId) {
+  const script = `tell application "iTerm2"
+  repeat with candidateWindow in windows
+    repeat with candidateTab in tabs of candidateWindow
+      repeat with candidateSession in sessions of candidateTab
+        if id of candidateSession is ${appleScriptString(sessionId)} then
+          tell candidateSession to close
+          return
+        end if
+      end repeat
+    end repeat
+  end repeat
+end tell`;
+  await execFileAsync("/usr/bin/osascript", ["-e", script], {
+    timeout: 5000,
+    maxBuffer: 64 * 1024,
+  });
+}
+
 async function doStart(adapter, opts) {
   const {
     session,
@@ -2164,11 +2640,27 @@ async function doStart(adapter, opts) {
     (!/^\d{1,2}\.\d{1,2} \S/u.test(name) || /[\r\n]/u.test(name))
   )
     throw new Error("--name must use '<month>.<day> <topic>' on one line");
-  const launchKeys = resume
-    ? [adapter.resumeById(resume), "Enter"]
-    : resumeLast
-      ? [adapter.resumeLast(), "Enter"]
-      : buildLaunchKeys(adapter, { model, effort, name });
+  const launchKeys = [
+    ...(resume
+      ? [adapter.resumeById(resume), "Enter"]
+      : resumeLast
+        ? [adapter.resumeLast(), "Enter"]
+        : buildLaunchKeys(adapter, {
+            model,
+            effort,
+            name,
+            sandbox: opts.sandbox,
+          })),
+  ];
+  if (resumed && adapter.cli === "agy") {
+    const overrides = buildLaunchKeys(adapter, {
+      model,
+      effort,
+      sandbox: opts.sandbox,
+    });
+    launchKeys[0] += overrides[0].slice("agy".length);
+  }
+  launchKeys[0] = withUnsetEnv(launchKeys[0], opts.unsetEnv ?? []);
   if (resumed && name && adapter.cli === "claude")
     launchKeys[0] += ` ${shellQuote(["-n", name])}`;
   const resumeTarget = resume ?? (resumeLast ? "last" : null);
@@ -2207,6 +2699,41 @@ async function doStart(adapter, opts) {
     readyTimeoutMs,
     pollIntervalMs,
   );
+  let unsetEnvVerified = false;
+  let unsetEnvWarning;
+  if (ready && !remote && opts.unsetEnv?.length) {
+    let environment = "";
+    try {
+      const target = await paneCliProcess(session, adapter.cli);
+      if (target)
+        environment =
+          process.platform === "darwin"
+            ? (
+                await execFileAsync(
+                  "ps",
+                  ["-E", "-ww", "-o", "command=", "-p", String(target.pid)],
+                  { timeout: 5000, maxBuffer: MAX_BUFFER },
+                )
+              ).stdout
+            : await readFile(`/proc/${target.pid}/environ`, "utf8");
+    } catch {
+      // 읽기 실패는 변수 잔존의 증거가 아니므로 세션을 유지한다.
+    }
+    const { readable, remaining } = inspectUnsetEnv(
+      environment,
+      opts.unsetEnv,
+      process.platform,
+    );
+    if (remaining.length) {
+      await runTmux(null, ["kill-session", "-t", session]);
+      throw new Error(
+        "--unset-env verification failed: matching variables remain in CLI environment",
+      );
+    }
+    unsetEnvVerified = readable;
+    if (!readable)
+      unsetEnvWarning = "CLI environment unreadable; removal not verified";
+  }
   let nameApplied = Boolean(name) && adapter.cli === "claude" && ready;
   let threadId =
     adapter.cli === "codex" && isCodexThreadId(resume) ? resume : null;
@@ -2248,6 +2775,25 @@ async function doStart(adapter, opts) {
       nameApplied = false;
     }
   }
+  if (name && adapter.cli === "agy" && ready) {
+    try {
+      nameApplied = await renameAgyConversation(
+        session,
+        name,
+        Math.min(readyTimeoutMs, 5000),
+        pollIntervalMs,
+      );
+    } catch {
+      nameApplied = false;
+    }
+  }
+  const namePending = adapter.cli === "agy" && Boolean(name) && !nameApplied;
+  if (namePending)
+    await runTmux(null, ["set-option", "-t", session, "@tfx_agy_name", name]);
+  const conversation =
+    adapter.cli === "agy" && ready
+      ? await agyConversation((await paneCliProcess(session, "agy"))?.pid)
+      : null;
   // ask 의 queue 전송이 레지스트리 없이도 thread 를 찾도록 세션에 남긴다.
   if (threadId && !remote)
     await runTmux(null, [
@@ -2257,6 +2803,66 @@ async function doStart(adapter, opts) {
       "@tfx_codex_thread",
       threadId,
     ]).catch(() => {});
+  let iterm;
+  let itermWarning;
+  if (ready && shouldUseIterm(remote)) {
+    try {
+      iterm = await openItermSession(session, opts.group || adapter.cli);
+      await runTmux(null, [
+        "set-option",
+        "-t",
+        session,
+        "@tfx_iterm_session",
+        iterm.sessionId,
+      ]);
+      const scriptsDir = pathJoin(
+        homedir(),
+        "Library",
+        "Application Support",
+        "iTerm2",
+        "Scripts",
+      );
+      const scriptPath = pathJoin(scriptsDir, ITERM_TITLE_SCRIPT_NAME);
+      await mkdir(scriptsDir, { recursive: true });
+      const installed = await readFile(scriptPath, "utf8").catch((error) => {
+        if (error.code === "ENOENT") return null;
+        throw error;
+      });
+      if (installed !== ITERM_TITLE_SCRIPT)
+        await writeFile(scriptPath, ITERM_TITLE_SCRIPT, { mode: 0o700 });
+      await chmod(scriptPath, 0o700);
+      const titleArgs = [iterm.sessionId, iterm.group, opts.name ?? session]
+        .map(appleScriptString)
+        .join(", ");
+      // 절대 경로는 최초 설치 직후의 메뉴 캐시 지연을 피하고, 적용 표식은 비동기 실패를 잡는다.
+      const titleScript = `tell application "iTerm2"
+  set titleSession to missing value
+  repeat with candidateWindow in windows
+    repeat with candidateTab in tabs of candidateWindow
+      repeat with candidateSession in sessions of candidateTab
+        if id of candidateSession is ${appleScriptString(iterm.sessionId)} then set titleSession to candidateSession
+      end repeat
+    end repeat
+  end repeat
+  if titleSession is missing value then error "iTerm title session not found"
+  launch API script named ${appleScriptString(scriptPath)} arguments {${titleArgs}}
+  repeat 30 times
+    try
+      tell titleSession to set titleApplied to variable named "user.tfxLiveTitleApplied"
+      if titleApplied is "1" then return
+    end try
+    delay 0.1
+  end repeat
+  error "iTerm title update was not confirmed; check the iTerm2 Python runtime and Script Console"
+end tell`;
+      await execFileAsync("/usr/bin/osascript", ["-e", titleScript], {
+        timeout: 5000,
+        maxBuffer: 64 * 1024,
+      });
+    } catch (error) {
+      itermWarning = error.message;
+    }
+  }
   return addLoginGuard(adapter, raw, {
     cli: adapter.cli,
     session,
@@ -2268,6 +2874,14 @@ async function doStart(adapter, opts) {
     nameGenerated: !resumed && opts.name === undefined,
     nameApplied,
     ...(adapter.cli === "codex" ? { threadId } : {}),
+    ...(adapter.cli === "agy"
+      ? { conversationId: conversation?.conversationId ?? null, namePending }
+      : {}),
+    unsetEnv: opts.unsetEnv ?? [],
+    unsetEnvVerified,
+    ...(iterm ? { iterm } : {}),
+    ...(itermWarning ? { itermWarning } : {}),
+    ...(unsetEnvWarning ? { unsetEnvWarning } : {}),
     ...(name && adapter.cli === "codex" && !nameApplied
       ? {
           nameWarning:
@@ -2287,21 +2901,43 @@ async function doStart(adapter, opts) {
 }
 
 // 빠른 입력 직후의 Enter 는 Codex 입력창이 버릴 수 있어 입력창이 빌 때까지 다시 누른다.
-async function submitComposerLine(remote, session, line) {
+async function submitComposerLine(remote, session, line, cli) {
   await sleep(300);
   for (let attempt = 1; attempt <= PROMPT_SUBMIT_MAX_ATTEMPTS; attempt += 1) {
     await runTmux(remote, ["send-keys", "-t", session, "Enter"]);
     await sleep(300);
-    if (!composerShowsPrompt(await captureVisible(remote, session), line))
+    if (!composerShowsPrompt(await captureVisible(remote, session), line, cli))
       return true;
   }
   return false;
 }
 
+async function renameAgyConversation(session, name, timeoutMs, pollIntervalMs) {
+  const command = `/rename ${name}`;
+  await runTmux(null, ["send-keys", "-t", session, "-l", "--", command]);
+  if (!(await submitComposerLine(null, session, command, "agy"))) return false;
+  const deadline = Date.now() + timeoutMs;
+  do {
+    const visible = stripAnsi(await captureVisible(null, session));
+    if (visible.includes(`Conversation renamed to: ${name}`)) return true;
+    await sleep(Math.min(pollIntervalMs, 200));
+  } while (Date.now() < deadline);
+  return false;
+}
+
 async function waitForTmuxIdle(adapter, opts) {
   const { session, remote, pollIntervalMs, busyTimeoutMs, ifBusy } = opts;
-  if (!["wait", "fail", "interrupt"].includes(ifBusy)) {
-    throw new Error("--if-busy must be wait, fail, or interrupt for tmux");
+  if (
+    ![
+      "wait",
+      "fail",
+      "interrupt",
+      ...(adapter.cli === "agy" ? ["queue"] : []),
+    ].includes(ifBusy)
+  ) {
+    throw new Error(
+      "--if-busy must be wait, fail, or interrupt for tmux (agy also supports queue)",
+    );
   }
   const startedAt = Date.now();
   let interrupted = false;
@@ -2309,9 +2945,9 @@ async function waitForTmuxIdle(adapter, opts) {
     const visible = await captureVisible(remote, session);
     const elapsedMs = Date.now() - startedAt;
     const busy =
-      isBusyByEsc(visible) ||
+      adapter.isBusy(visible) ||
       (adapter.cli === "codex" && isCodexLoadingCapture(visible));
-    if (!busy) return elapsedMs;
+    if (!busy || ifBusy === "queue") return elapsedMs;
     if (ifBusy === "fail") throw new Error("target busy (--if-busy fail)");
     if (elapsedMs >= busyTimeoutMs) {
       throw new Error(
@@ -2337,22 +2973,32 @@ async function doAskViaTmux(adapter, opts) {
     settleMs,
     pollIntervalMs,
     doneMarker,
-    ifBusy = "wait",
+    ifBusy = adapter.cli === "agy" ? "queue" : "wait",
     busyTimeoutMs = timeoutMs,
   } = opts;
+  const slashCommand = adapter.cli === "agy" && isSlashCommand(prompt);
   const busyWaitedMs = await waitForTmuxIdle(adapter, {
     session,
     remote,
     pollIntervalMs,
     busyTimeoutMs,
-    ifBusy,
+    ifBusy: slashCommand ? "queue" : ifBusy,
   });
+  const queued =
+    adapter.cli === "agy" &&
+    adapter.isBusy(await captureVisible(remote, session));
   const beforeRaw = await capturePane(remote, session);
   const contextPctBefore = adapter.contextPct(beforeRaw);
-  const context = opts.skipContextGuard ? {} : await tmuxContext(adapter, opts);
-  const guard = opts.skipContextGuard
-    ? {}
-    : contextGuard(adapter.cli, context, opts);
+  const context =
+    adapter.cli === "agy"
+      ? modelContext("agy", null)
+      : opts.skipContextGuard
+        ? {}
+        : await tmuxContext(adapter, opts);
+  const guard =
+    opts.skipContextGuard || adapter.cli === "agy"
+      ? {}
+      : contextGuard(adapter.cli, context, opts);
   if (guard.ok === false)
     return {
       ...guard,
@@ -2376,13 +3022,13 @@ async function doAskViaTmux(adapter, opts) {
   ]);
   await sleep(settleMs);
 
-  let promptSubmitted = !doneMarker;
-  if (doneMarker || opts.noWait) {
+  let promptSubmitted = adapter.cli === "agy" ? false : !doneMarker;
+  if (doneMarker || opts.noWait || adapter.cli === "agy") {
     for (let attempt = 1; attempt <= PROMPT_SUBMIT_MAX_ATTEMPTS; attempt += 1) {
       await runTmux(remote, ["send-keys", "-t", session, "Enter"]);
       await sleep(PROMPT_SUBMIT_RETRY_DELAY_MS);
       const submissionVisible = await captureVisible(remote, session);
-      if (!composerShowsPrompt(submissionVisible, prompt)) {
+      if (!composerShowsPrompt(submissionVisible, prompt, adapter.cli)) {
         promptSubmitted = true;
         break;
       }
@@ -2396,7 +3042,61 @@ async function doAskViaTmux(adapter, opts) {
     await runTmux(remote, ["send-keys", "-t", session, "Enter"]);
   }
 
-  if (opts.noWait) {
+  let nameApplied;
+  if (adapter.cli === "agy" && !slashCommand) {
+    const { stdout } = await runTmux(null, [
+      "show-options",
+      "-qv",
+      "-t",
+      splitTmuxTarget(session).session,
+      "@tfx_agy_name",
+    ]);
+    const pendingName = stdout.trim();
+    if (pendingName) {
+      nameApplied = false;
+      let db;
+      try {
+        const { DatabaseSync } = await import("node:sqlite");
+        const deadline = Date.now() + 5000;
+        while (Date.now() < deadline) {
+          if (!db) {
+            const agyProcess = await paneCliProcess(session, "agy");
+            const conversation = await agyConversation(agyProcess?.pid);
+            if (conversation)
+              db = new DatabaseSync(conversation.dbPath, { readOnly: true });
+          }
+          if (
+            db
+              ?.prepare("SELECT 1 FROM steps WHERE step_type = 14 LIMIT 1")
+              .get()
+          ) {
+            nameApplied = await renameAgyConversation(
+              session,
+              pendingName,
+              5000,
+              pollIntervalMs,
+            );
+            if (nameApplied)
+              await runTmux(null, [
+                "set-option",
+                "-u",
+                "-t",
+                splitTmuxTarget(session).session,
+                "@tfx_agy_name",
+              ]);
+            break;
+          }
+          await sleep(Math.min(pollIntervalMs, 200));
+        }
+      } catch {
+        nameApplied = false;
+      } finally {
+        db?.close();
+      }
+    }
+  }
+
+  if (opts.noWait || slashCommand) {
     return {
       ...context,
       ...guard,
@@ -2405,7 +3105,9 @@ async function doAskViaTmux(adapter, opts) {
       transport: "tmux",
       session,
       remote: remote ?? null,
-      status: "submitted",
+      status: queued && !slashCommand ? "queued" : "submitted",
+      ...(slashCommand ? { slashCommand: true } : {}),
+      ...(nameApplied !== undefined ? { nameApplied } : {}),
       inputSent: true,
       done: false,
       submittedAt: new Date().toISOString(),
@@ -2415,6 +3117,22 @@ async function doAskViaTmux(adapter, opts) {
     };
   }
 
+  if (adapter.cli === "agy") {
+    return {
+      ...context,
+      ...(await waitAgy({
+        session,
+        requestId: opts.noRelayTag ? null : opts.requestId,
+        timeoutMs,
+        pollIntervalMs,
+      })),
+      transport: "tmux",
+      inputSent: true,
+      ...(nameApplied !== undefined ? { nameApplied } : {}),
+      ifBusy,
+      busyWaitedMs,
+    };
+  }
   const startedAt = Date.now();
   let raw = "";
   let visible = "";
@@ -2512,7 +3230,8 @@ async function doAsk(adapter, opts) {
   // Codex 는 접힌 발신자 표시가 없어 첫 줄 머리말로 보낸 세션을 드러낸다.
   // 슬래시 명령은 첫 글자가 / 여야 실행되므로 표식을 붙이지 않는다.
   const bare =
-    opts.noRelayTag || (adapter.cli === "codex" && isSlashCommand(opts.prompt));
+    opts.noRelayTag ||
+    (["codex", "agy"].includes(adapter.cli) && isSlashCommand(opts.prompt));
   const from =
     adapter.cli === "codex" && !bare
       ? (opts.from ?? (await resolveSenderName()))
@@ -3056,17 +3775,48 @@ async function doStop(adapter, opts) {
     throw new Error(
       "stop --session accepts only a session name; pass the session name without a pane target",
     );
+  let itermSessionId;
+  let itermWarning;
+  if (shouldUseIterm(remote)) {
+    try {
+      const { stdout } = await runTmux(null, [
+        "show-options",
+        "-qv",
+        "-t",
+        session,
+        "@tfx_iterm_session",
+      ]);
+      itermSessionId = stdout.trim();
+    } catch (error) {
+      itermWarning = error.message;
+    }
+  }
   await runTmux(remote, ["kill-session", "-t", session]);
+  if (itermSessionId) {
+    try {
+      await closeItermSession(itermSessionId);
+    } catch (error) {
+      itermWarning = error.message;
+    }
+  }
   return {
     cli: adapter.cli,
     session,
     remote: remote ?? null,
     stopped: true,
+    ...(itermWarning ? { itermWarning } : {}),
   };
 }
 
 async function doInterruptViaTmux(adapter, opts) {
   await runTmux(opts.remote, ["send-keys", "-t", opts.session, "Escape"]);
+  if (adapter.cli === "agy")
+    await waitForTmuxIdle(adapter, {
+      ...opts,
+      ifBusy: "wait",
+      busyTimeoutMs: opts.timeoutMs,
+      pollIntervalMs: DEFAULT_POLL_INTERVAL_MS,
+    });
   return {
     cli: adapter.cli,
     session: opts.session,
@@ -3173,6 +3923,8 @@ async function doInterrupt(adapter, opts) {
 }
 
 function startOpts(flags) {
+  const unsetEnv =
+    flags["unset-env"] === undefined ? [] : flags["unset-env"].split(",");
   const session = requireFlag(flags, "session");
   if (session.includes(":"))
     throw new Error("start --session accepts only a session name without ':'");
@@ -3185,6 +3937,9 @@ function startOpts(flags) {
     model: flags.model,
     effort: flags.effort,
     name: flags.name,
+    group: flags.group,
+    sandbox: Object.hasOwn(flags, "sandbox"),
+    unsetEnv,
     readyTimeoutMs: secondsFlag(
       flags,
       "ready-timeout",
@@ -3243,6 +3998,8 @@ function askOpts(flags, adapter) {
     short,
     sessionId,
   );
+  if (adapter.cli === "agy" && transport !== "tmux")
+    throw new Error("agy ask supports local --transport tmux only");
   const codexUds = adapter.cli === "codex" && transport === "uds";
   const codexQueue = transport === "queue";
   if (adapter.cli === "codex" && transport === "auto")
@@ -3292,7 +4049,7 @@ function askOpts(flags, adapter) {
         ? resolveCodexDaemonSocket(flags["codex-socket"] ?? "default")
         : null,
     cwd: flags.cwd,
-    ifBusy: flags["if-busy"] ?? "wait",
+    ifBusy: flags["if-busy"] ?? (adapter.cli === "agy" ? "queue" : "wait"),
     busyTimeoutMs: secondsFlag(
       flags,
       "busy-timeout",
@@ -3343,6 +4100,8 @@ function interruptOpts(flags, adapter) {
   const short = flags.short;
   const sessionId = flags["session-id"];
   const transport = transportFlag(flags, adapter, short, sessionId);
+  if (adapter.cli === "agy" && transport !== "tmux")
+    throw new Error("agy interrupt supports local --transport tmux only");
   if (transport === "queue")
     throw new Error("interrupt uses tmux; queue cannot send keys");
   if (adapter.cli === "codex" && transport === "uds")
@@ -3464,6 +4223,26 @@ async function queue(flags) {
 }
 
 async function wait(flags) {
+  if (flags.cli === "agy") {
+    selectAdapter(flags);
+    if (flags.transport && flags.transport !== "tmux")
+      throw new Error("agy wait supports local --transport tmux only");
+    return printJson(
+      await waitAgy({
+        session: splitTmuxTarget(requireFlag(flags, "session")).target,
+        requestId: flags["request-id"] ?? null,
+        timeoutMs:
+          flags.timeout === "0"
+            ? 0
+            : secondsFlag(flags, "timeout", DEFAULT_ANSWER_TIMEOUT_MS),
+        pollIntervalMs: msFlag(
+          flags,
+          "poll-interval",
+          DEFAULT_POLL_INTERVAL_MS,
+        ),
+      }),
+    );
+  }
   if (flags.cli === "codex") return waitCodex(flags);
   if ((flags.cli ?? "claude") !== "claude")
     throw new Error("wait supports --cli claude or codex");
@@ -3568,6 +4347,8 @@ async function tmuxContext(adapter, opts) {
 }
 
 async function compact(flags) {
+  if (flags.cli === "agy")
+    throw new Error("agy has no compact; use /clear or a handoff");
   if (
     (flags.cli ?? "claude") !== "claude" ||
     flags.remote ||
@@ -3654,6 +4435,11 @@ async function probe(flags) {
 
 async function listSessions(flags) {
   const adapter = selectAdapter(flags);
+  if (adapter.cli === "agy") {
+    if (flags.transport && flags.transport !== "tmux")
+      throw new Error("agy list-sessions supports local --transport tmux only");
+    return printJson(await discoverAgyTmuxSessions({ cwd: flags.cwd }));
+  }
   if (adapter.cli === "claude") {
     if (flags.remote || flags.transport === "uds") {
       throw new Error(
@@ -3788,6 +4574,7 @@ function parseFirstInteger(response) {
 
 async function converse(flags) {
   const adapter = selectAdapter(flags);
+  if (adapter.cli === "agy") throw new Error("agy is unavailable for converse");
   const session = requireFlag(flags, "session");
   const promptsFile = requireFlag(flags, "prompts-file");
   const prompts = await readPromptsFile(promptsFile);
@@ -3823,6 +4610,8 @@ async function converse(flags) {
 
 async function goalDriven(flags) {
   const adapter = selectAdapter(flags);
+  if (adapter.cli === "agy")
+    throw new Error("agy is unavailable for goal-driven");
   const session = requireFlag(flags, "session");
   const goal = requireFlag(flags, "goal");
   const maxRounds = integerFlag(flags, "max-rounds", 8);
@@ -4317,6 +5106,8 @@ function addStopSpecOnce(stopSpecs, adapter, opts) {
 async function peer(flags) {
   const adapterA = selectAdapterName(flags["cli-a"] ?? "codex", "cli-a");
   const adapterB = selectAdapterName(flags["cli-b"] ?? "claude", "cli-b");
+  if (adapterA.cli === "agy" || adapterB.cli === "agy")
+    throw new Error("agy is unavailable for peer");
   peerSideBusyPolicy(
     flags,
     "a",
@@ -4587,12 +5378,16 @@ async function main() {
 
 export {
   ADAPTERS,
+  agyStepText,
+  agyWaitVerdict,
+  appleScriptString,
   buildLaunchKeys,
   buildPeerClosurePrompt,
   buildRemoteLiveCommand,
   buildTmuxCommand,
   callRemoteLive,
   classifyPeerExitReason,
+  composerShowsPrompt,
   createPeerSignalController,
   derivePeerStatus,
   discoverClaudeTmuxSessions,
@@ -4603,6 +5398,7 @@ export {
   extractResponseSinceMarker,
   hasClaudeCompletedTaskListResponse,
   inspectCodexTmuxPane,
+  inspectUnsetEnv,
   isCodexLoadingCapture,
   parseCodexTmuxSessions,
   parsePeerClosure,
@@ -4611,10 +5407,12 @@ export {
   resolveAskTransport,
   resolveCodexDaemonSocket,
   resumedCodexThread,
+  shouldUseIterm,
   splitTmuxTarget,
   stopOpts,
   tmuxBufferName,
   verifyAttachedPeerSide,
+  withUnsetEnv,
 };
 
 function isMainModule() {

package/package.json

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

package/skills/tfx-live/SKILL.md

@@ -1,14 +1,14 @@
 ---
 name: tfx-live
 description: >
-  Claude·Codex 세션을 실시간으로 생성·질의·대기·압축·종료하거나,
+  Claude·Codex·agy 세션을 실시간으로 생성·질의·대기·압축·종료하거나,
   tmux/daemon UDS 연결과 peer 중계를 운영할 때 사용한다.
-argument-hint: "<start|ask|wait|queue|compact|stop|rename|interrupt|probe|list-sessions|peer|converse|goal-driven> ..."
+argument-hint: "<start|ask|wait|queue|compact|stop|rename|interrupt|probe|list-sessions|peer|converse|goal-driven> [--cli codex|claude|agy] ..."
 ---
 
 # tfx-live
 
-`tfx-live`는 Claude Code와 Codex 세션을 tmux 또는 daemon UDS로 제어한다.
+`tfx-live`는 Claude Code와 Codex 세션을 tmux 또는 daemon UDS로, agy 세션을 로컬 tmux로 제어한다.
 `tfx-live --help`와 `tfx-live <동사> --help`로 사용법을 확인한다.
 
 ## 전송 경로
@@ -25,7 +25,27 @@ tfx-live ask --cli codex --session cx1 --prompt "현재 변경사항을 요약
 tfx-live stop --cli codex --session cx1
 ```
 
-새 세션 이름은 `<월>.<일> <주제>`로 짓는다. `start --name`을 생략하면 자동으로 만들고 `nameGenerated: true`를 보고한다. `--resume` 또는 `--resume-last`는 `--name`을 명시한 경우에만 이름을 적용한다. 승계 세션에는 기존 이름 뒤에 ` 2`, 이후 ` 3`을 붙인다. 이름 적용을 요청한 경우 결과의 `nameApplied: false`는 적용 실패를 뜻한다. Codex `start`는 `/rename` 제출을 입력창이 빌 때까지 확인하고, 이름으로 찾은 thread UUID를 `threadId`로 돌려주며 tmux 세션 옵션 `@tfx_codex_thread`에 남긴다. 로컬 Codex `--resume-last`는 Codex가 고른 thread를 사후에 찾는다. 띄운 뒤 공유 app-server daemon에 로드된 같은 cwd의 thread 중 rollout에 그 시각 이후의 resume 기록(`thread_settings_applied`)이 생긴 것이 정확히 하나이고 1.5초 뒤에도 같을 때만 `threadId`로 쓴다. 이 확인은 5초 안에 끝난다. TUI가 daemon을 쓰지 않거나 같은 cwd에서 동시에 resume이 일어나면 `null`이다. 기존 Codex UDS thread는 `tfx-live rename --cli codex --transport uds --thread ID --name "<이름>"`으로 이름을 바꾼다.
+macOS의 iTerm2에서 로컬 tmux 세션을 `start`하면 리드가 있는 창에 attach 탭이나 패인을 연다. `LC_TERMINAL=iTerm2` 또는 `TERM_PROGRAM=iTerm.app`일 때만 적용하며, 원격과 tmux 세션이 없는 daemon 경로는 제외한다. 같은 `--group NAME`은 한 탭에서 세로로 나누고 다른 그룹은 새 탭을 연다. `--group`을 생략하면 대상 CLI인 `claude`, `codex`, `agy`를 그룹으로 쓴다. `stop --session`은 tmux 종료 뒤 남은 iTerm 패인도 닫는다. 연동이 실패해도 세션 시작과 종료는 계속하며 결과의 `itermWarning`에 원인을 남긴다. 탭 제목은 iTerm2 Python 런타임으로 고정하며 처음 쓸 때 iTerm2 Scripts 폴더에 스크립트 하나를 설치하고, 런타임이 없으면 제목만 바뀌지 않는다.
+
+새 세션 이름은 `<월>.<일> <주제>`로 짓는다. `start --name`을 생략하면 자동으로 만들고 `nameGenerated: true`를 보고한다. `--resume` 또는 `--resume-last`는 `--name`을 명시한 경우에만 이름을 적용한다. 승계 세션에는 기존 이름 뒤에 ` 2`, 이후 ` 3`을 붙인다. 이름 적용을 요청한 경우 결과의 `nameApplied: false`는 미적용을 뜻한다. agy의 `namePending: true`는 첫 일반 ask에서 적용할 이름이 보류됐다는 뜻이다. Codex `start`는 `/rename` 제출을 입력창이 빌 때까지 확인하고, 이름으로 찾은 thread UUID를 `threadId`로 돌려주며 tmux 세션 옵션 `@tfx_codex_thread`에 남긴다. 로컬 Codex `--resume-last`는 Codex가 고른 thread를 사후에 찾는다. 띄운 뒤 공유 app-server daemon에 로드된 같은 cwd의 thread 중 rollout에 그 시각 이후의 resume 기록(`thread_settings_applied`)이 생긴 것이 정확히 하나이고 1.5초 뒤에도 같을 때만 `threadId`로 쓴다. 이 확인은 5초 안에 끝난다. TUI가 daemon을 쓰지 않거나 같은 cwd에서 동시에 resume이 일어나면 `null`이다. 기존 Codex UDS thread는 `tfx-live rename --cli codex --transport uds --thread ID --name "<이름>"`으로 이름을 바꾼다.
+
+## agy 세션
+
+```bash
+tfx-live start --cli agy --session ag1 --cwd ~/Projects --name "10.11 구현 검토" --effort low --unset-env 'TOSSINVEST_*,PRIVATE_KEY'
+tfx-live ask --cli agy --session ag1 --prompt "현재 변경사항을 요약해줘" --no-wait
+tfx-live wait --cli agy --session ag1 --request-id <requestId> --timeout 120
+tfx-live list-sessions --cli agy --cwd ~/Projects
+tfx-live stop --cli agy --session ag1
+```
+
+`start`는 `--model ID`, `--effort low|medium|high|xhigh|max`, `--sandbox`를 agy에 넘긴다. `--sandbox`의 실효는 미검증이다. `--resume ID`와 `--resume-last 1`로 대화를 재개한다. 준비 뒤 `/rename <이름>`의 확인 문구가 보이면 `nameApplied: true`다. 새 대화는 첫 메시지 전 `/rename`이 실패하므로 이름을 tmux 옵션 `@tfx_agy_name`에 남기고 `nameApplied: false`, `namePending: true`로 보류한다. 첫 일반 ask는 제출 확인 뒤 현재 대화 DB에 사용자 step이 생길 때까지 최대 5초 기다리고, 유휴를 기다리지 않고 `/rename`을 보낸다. 확인 문구가 보이면 옵션을 지우고 `nameApplied: true`를 반환하며, 실패하면 옵션을 남기고 `nameApplied: false`를 반환한다. `--no-wait`에도 적용한다. 열린 presence lock에서 찾은 대화 ID는 `conversationId`로 보고한다.
+
+agy `ask`의 기본 `--if-busy queue`는 바쁜 턴에도 바로 전송한다. agy 자체 대기열에 쌓이며 앞 입력을 덮어쓰지 않는다. `wait|fail|interrupt`도 선택할 수 있다. `ask --no-wait`는 `inputSent: true`, `requestId`와 함께 유휴 시 `status: "submitted"`, 바쁠 때 `status: "queued"`를 반환한다. `queue` 정책은 agy 전용이다. 슬래시 명령은 중계 표식 없이 보내고 바빠도 즉시 실행한다. DB step을 만들지 않아 `wait`로 추적하지 않으며, `--no-wait` 여부와 무관하게 제출 확인 뒤 `status: "submitted"`, `slashCommand: true`로 반환한다. `/clear`는 대화 ID를 바꾼다.
+
+`wait`는 `node:sqlite`(Node 22.13+)로 대화 DB의 사용자 입력 표식과 뒤따르는 step 상태를 읽는다. 요청 뒤부터 다음 사용자 입력 전까지 모델 응답 step이 하나 이상 있고 그 구간의 모든 step이 끝났으며, pane이 유휴 상태이거나 다음 요청이 시작됐으면 완료다. 같은 구간의 마지막 비어 있지 않은 모델 텍스트를 응답으로 쓴다. Escape로 취소된 step도 완료 상태로 기록된다. `--timeout 0`은 한 번만 확인한다. `/clear`는 대화 ID를 바꾸며 진행 중 `wait`는 처음 연 DB를 계속 본다. agy 설정의 `toolPermission`에 따라 도구 승인 화면이 뜰 수 있다. 승인을 기다리는 동안 턴이 멈추고 `wait`는 `working`으로 남는다. `tfx-live`는 agy에 `--dangerously-skip-permissions`를 쓰지 않는다. agy에는 compact가 없으므로 `/clear` 또는 handoff를 쓴다. `--remote`, `peer`, `converse`, `goal-driven`은 지원하지 않는다.
+
+`start --unset-env 'PREFIX_*,EXACT_NAME'`은 모든 CLI에 쓸 수 있다. 쉼표로 구분한 환경변수 이름과 끝의 `*`로 지정한 접두만 허용한다. tmux pane 셸의 환경에서 변수를 지우고 CLI를 실행하며 resume에도 적용한다. 로컬에서는 준비 후 CLI 프로세스 환경을 확인한다. macOS는 `ps -E` 출력에 `PATH=`가 있고 Linux는 `/proc/PID/environ`이 비어 있지 않을 때만 환경을 읽은 것으로 판정한다. 일치하는 변수가 실제로 남은 경우에만 생성한 세션을 종료하고 오류를 낸다. 환경을 읽지 못하면 세션을 유지하고 `unsetEnvVerified: false`, `unsetEnvWarning: "CLI environment unreadable; removal not verified"`를 반환한다. 결과의 `unsetEnv`는 요청 목록이고 `unsetEnvVerified`는 확인 여부다. 원격에서는 확인하지 않아 `false`이고 Windows에서는 이 옵션을 지원하지 않는다.
 
 ## 리드 운영
 
@@ -70,7 +90,7 @@ tfx-live queue --cli codex --thread <UUID> --delete <queuedMessageId>
 | Codex | 15% | 18% | 20% | 22% |
 | agy | 12% | 없음 | 15% | 18% |
 
-Claude는 85% 도달 시 바로 handoff를 지시한다. agy 행은 운영 지침이며 `tfx-live` 전송 대상이 아니다. `model_context_window`와 `model_auto_compact_token_limit`은 올리지 않는다.
+Claude는 85% 도달 시 바로 handoff를 지시한다. agy 행은 운영 지침이며 agy도 `tfx-live` 전송 대상이지만 컨텍스트 비율은 자동으로 읽지 못해 `null`로 보고하고 가드를 건너뛴다. `model_context_window`와 `model_auto_compact_token_limit`은 올리지 않는다.
 
 결과에는 `estimatedContextTokens`, `contextLimitTokens`, `contextLimitSource`, `contextPct`가 포함된다. Claude 실행 한도는 `executionContextLimitTokens`로 별도 보고하며 `CLAUDE_CODE_DISABLE_1M_CONTEXT=1`이면 200,000이다. 판정에는 공식 창과 실행 한도 중 작은 값을 쓴다. 한도를 모르면 비율은 `null`로 두고 경고만 한다. 사용량이 없는 `probe`는 `context: null`이다. 컨텍스트를 확인하려면 직접 `tfx-live probe`를 실행한다. `interrupt`, 자동 `ask`의 daemon probe, `stop --short`는 transcript를 읽지 않는다.