docs(agy): record 1.1.2 cross-platform validation

README.md

@@ -237,7 +237,7 @@ Override via `--engine` flag or the `GEMINI_ENGINE` environment variable.
 
 > `--model` and `--effort` are managed by the **gemini** engine only. `--engine agy` currently leaves model choice to AGY's configured/default behavior; the plugin does not translate Gemini aliases or effort tiers to AGY arguments.
 
-> **AGY transcript recovery remains authoritative.** Positional `agy --print` produced no piped response on older releases (upstream [google-gemini/gemini-cli#27466](https://github.com/google-gemini/gemini-cli/issues/27466); reproduced on macOS AGY 1.0.7). Plugin v0.7.1 uses the auto-print stdin path on AGY 1.1.2 or newer, but still takes the completed response, DONE status, thinking, and conversation ID from the on-disk transcript. Known brain roots are `~/.gemini/antigravity-cli/brain` (Windows/macOS) and `~/.antigravity-cli/brain` (Linux, reported). The 1.1.2 stdin path is live-verified on Windows and covered by a POSIX integration fixture; real macOS/Linux 1.1.2 verification remains pending. If no brain root is found, run `agy` once or open an issue with its actual location.
+> **AGY transcript recovery remains authoritative.** Positional `agy --print` produced no piped response on older releases (upstream [google-gemini/gemini-cli#27466](https://github.com/google-gemini/gemini-cli/issues/27466); reproduced on macOS AGY 1.0.7). Plugin v0.7.1 uses the auto-print stdin path on AGY 1.1.2 or newer, but still takes the completed response, DONE status, thinking, and conversation ID from the on-disk transcript. Known brain roots are `~/.gemini/antigravity-cli/brain` (verified on Windows, macOS AGY 1.0.7, and Linux AGY 1.1.2) and `~/.antigravity-cli/brain` (older Linux 1.0.2, reported). The 1.1.2 stdin path is live-verified on Windows and Ubuntu 24.04 WSL2, and covered by a POSIX integration fixture; real macOS 1.1.2 verification is intentionally optional and has not been run. If no brain root is found, run `agy` once or open an issue with its actual location.
 
 ---
 
@@ -262,7 +262,7 @@ Override via `--engine` flag or the `GEMINI_ENGINE` environment variable.
 | setup shows `… token expired` | OAuth token lapsed | Run `!gemini` again to refresh credentials |
 | `Status: partial (AGY fallback only …)` | Gemini CLI unavailable but AGY present | Install Gemini CLI, or use `--engine agy` (its auth cannot be verified) |
 | Windows: command resolves but fails | `.cmd` wrapper / PATH | Confirm `where gemini` resolves; the plugin spawns bare names through `shell: true` to find `.cmd` shims |
-| `--engine agy` reports no brain root | AGY has not created its brain directory yet, or it lives in an unknown location | Run `agy` once so it creates the brain dir. Known roots: `~/.gemini/antigravity-cli/brain` (Windows/macOS, verified) and `~/.antigravity-cli/brain` (Linux, reported); if yours differs, open an issue with its location |
+| `--engine agy` reports no brain root | AGY has not created its brain directory yet, or it lives in an unknown location | Run `agy` once so it creates the brain dir. Known roots: `~/.gemini/antigravity-cli/brain` (verified on Windows, macOS AGY 1.0.7, and Linux AGY 1.1.2) and `~/.antigravity-cli/brain` (older Linux 1.0.2, reported); if yours differs, open an issue with its location |
 
 To authenticate, run **`!gemini`** once — the plugin completes OAuth by invoking `gemini` itself. There is **no** `gemini login` subcommand. `setup` reports `ready: true` only when Node **and** the Gemini CLI are present **and** OAuth is valid; an installed-but-unauthenticated Gemini is reported as *not ready*.
 

README.zh-TW.md

@@ -235,7 +235,7 @@
 
 > `--model` 與 `--effort` 只由 **gemini** 引擎管理。`--engine agy` 目前讓 AGY 使用其 configured/default model；本外掛不會把 Gemini aliases 或 effort tiers 翻譯成 AGY 參數。
 
-> **AGY transcript recovery 仍是權威來源。** 舊版 positional `agy --print` 沒有 piped response（上游 [google-gemini/gemini-cli#27466](https://github.com/google-gemini/gemini-cli/issues/27466)，已於 macOS AGY 1.0.7 重現）。外掛 v0.7.1 對 AGY 1.1.2 以上改走自動 print 的 stdin 路徑，但完成回應、DONE 狀態、thinking 與 conversation ID 仍取自磁碟 transcript。已知 brain root 為 `~/.gemini/antigravity-cli/brain`（Windows／macOS）及 `~/.antigravity-cli/brain`（Linux，回報）。1.1.2 stdin 路徑已於 Windows live 驗證並有 POSIX integration fixture；macOS／Linux 真實 1.1.2 尚待驗證。若找不到 brain root，請先執行一次 `agy` 或開 issue 回報實際位置。
+> **AGY transcript recovery 仍是權威來源。** 舊版 positional `agy --print` 沒有 piped response（上游 [google-gemini/gemini-cli#27466](https://github.com/google-gemini/gemini-cli/issues/27466)，已於 macOS AGY 1.0.7 重現）。外掛 v0.7.1 對 AGY 1.1.2 以上改走自動 print 的 stdin 路徑，但完成回應、DONE 狀態、thinking 與 conversation ID 仍取自磁碟 transcript。已知 brain root 為 `~/.gemini/antigravity-cli/brain`（已於 Windows、macOS AGY 1.0.7 與 Linux AGY 1.1.2 驗證）及 `~/.antigravity-cli/brain`（較舊的 Linux 1.0.2，回報）。1.1.2 stdin 路徑已於 Windows 與 Ubuntu 24.04 WSL2 live 驗證，並有 POSIX integration fixture；真實 macOS 1.1.2 驗證刻意列為 optional，尚未執行。若找不到 brain root，請先執行一次 `agy` 或開 issue 回報實際位置。
 
 ---
 
@@ -260,7 +260,7 @@
 | setup 顯示 `… token expired` | OAuth token 已過期 | 再次執行 `!gemini` 以更新憑證 |
 | `Status: partial (AGY fallback only …)` | Gemini CLI 不可用但 AGY 存在 | 安裝 Gemini CLI，或使用 `--engine agy`（其認證無法驗證） |
 | Windows：命令可解析但執行失敗 | `.cmd` wrapper／PATH | 確認 `where gemini` 可解析；外掛以 `shell: true` 啟動裸命令名以尋得 `.cmd` shim |
-| `--engine agy` 回報找不到 brain 根目錄 | AGY 尚未建立 brain 目錄，或其位於未知位置 | 先執行一次 `agy` 讓其建立 brain 目錄。已知路徑：`~/.gemini/antigravity-cli/brain`（Windows/macOS，已驗證）與 `~/.antigravity-cli/brain`（Linux，回報）；若不同請開 issue 回報其位置 |
+| `--engine agy` 回報找不到 brain 根目錄 | AGY 尚未建立 brain 目錄，或其位於未知位置 | 先執行一次 `agy` 讓其建立 brain 目錄。已知路徑：`~/.gemini/antigravity-cli/brain`（已於 Windows、macOS AGY 1.0.7 與 Linux AGY 1.1.2 驗證）與 `~/.antigravity-cli/brain`（較舊的 Linux 1.0.2，回報）；若不同請開 issue 回報其位置 |
 
 如需認證，執行一次 **`!gemini`**——外掛即以呼叫 `gemini` 自身完成 OAuth。**並無** `gemini login` 子命令。唯有 Node **且** Gemini CLI 皆存在**且** OAuth 有效時，`setup` 方回報 `ready: true`；已安裝但未認證之 Gemini 將回報為 *not ready*。
 

docs/AGY_1.1.2_MACOS_LINUX_VALIDATION.md

@@ -0,0 +1,249 @@
+# AGY 1.1.2 macOS/Linux 驗證清單
+
+本清單驗證 `gemini-plugin-cc` v0.7.1 對真實 Antigravity CLI 1.1.2 的 stdin、stdout、transcript、背景工作、review、錯誤與 OAuth headless 行為。POSIX fake fixture 只能作為自動化基線，不能取代真實 AGY binary 與服務端回應。
+
+## 固定範圍與安全界線
+
+- 插件基準：tag `v0.7.1`，commit `6115ee184b02c429c3a220ade9ac7313c19a9283`。
+- AGY 基準：穩定版 `1.1.2`；unknown、prerelease 或其他版本不得記為通過。
+- 全程唯讀：不得使用 `--write`、`--dangerously-skip-permissions` 或修改專案檔案。
+- 不登出、不破壞日常憑證。未登入測試必須使用隔離的空白 `HOME`。
+- 每次 live call 使用唯一標記；執行期間不得同時啟動其他 AGY 工作，避免 transcript set-diff 配對歧義。
+- stdout 只驗證 transport；成功、`DONE`、conversation ID 與 thinking 仍以 transcript 為權威來源。
+
+官方依據：
+
+- [Antigravity CLI 1.1.2 changelog](https://github.com/google-antigravity/antigravity-cli/blob/main/CHANGELOG.md#112)
+- [Antigravity CLI 安裝說明](https://github.com/google-antigravity/antigravity-cli#installation)
+
+## 判定規則
+
+- **PASS**：實際在該 OS 執行，所有必要項目符合預期，並留下可核對的 exit code、marker、conversation ID 或 job ID。
+- **FAIL**：有實際執行，但任一必要行為不符合預期。
+- **BLOCKED**：沒有可用的該 OS 執行環境、AGY 1.1.2 binary 或安全的登入環境；不得以其他 OS 或 fake fixture 代替。
+
+## 前置檢查
+
+在 macOS 或 Linux 的 Bash/Zsh 執行：
+
+```sh
+uname -srm
+agy --version
+node --version
+git --version
+git rev-parse HEAD
+command -v agy
+
+for root in \
+  "$HOME/.gemini/antigravity-cli/brain" \
+  "$HOME/.antigravity-cli/brain"
+do
+  test -d "$root" && printf 'brain=%s\n' "$root"
+done
+```
+
+驗收：
+
+- `agy --version` 精確為 `1.1.2`。
+- Node.js 為專案支援的 `18` 以上。
+- Git commit 精確為上述 v0.7.1 commit。
+- 至少一個 brain root 存在；兩個候選路徑都要探測，不得只依 OS 猜測。
+
+若要隔離安裝 binary，先讀取官方平台 manifest，確認 `version`、下載 URL 與 SHA-512，再下載到暫存目錄。不得覆寫使用者現有 `agy`。2026-07-14 的官方 manifest 平台名稱為 `linux_amd64`、`linux_arm64`、`darwin_amd64` 與 `darwin_arm64`。
+
+## 必要 live 驗證
+
+下列範例以 `OS` 代表 `MACOS` 或 `LINUX`，日期改成實際執行日。
+
+### 1. 原生 stdin、stdout 與 transcript
+
+```sh
+MARKER="OS_AGY112_DIRECT_YYYYMMDD"
+printf 'Reply with exactly %s\n' "$MARKER" | agy --print-timeout 1m
+```
+
+驗收：
+
+- 90 秒內完成且 exit code 為 `0`。
+- stdout trim 後精確等於 marker。
+- argv 沒有 positional prompt；本項使用 stdin 自動進入 print mode。
+- 在其中一個 brain root 找到同一 marker，且同一 conversation 的 transcript 同時包含：
+  - `USER_INPUT status=DONE`
+  - `PLANNER_RESPONSE status=DONE`
+  - response content 精確等於 marker
+
+可用下列方式定位 transcript：
+
+```sh
+grep -R -l "$MARKER" \
+  "$HOME/.gemini/antigravity-cli/brain"/*/.system_generated/logs/transcript_full.jsonl \
+  "$HOME/.antigravity-cli/brain"/*/.system_generated/logs/transcript_full.jsonl \
+  2>/dev/null
+```
+
+### 2. 插件前景 task
+
+```sh
+node plugins/gemini/scripts/gemini-companion.mjs task \
+  --engine agy --fresh \
+  "Reply with exactly OS_AGY112_PLUGIN_FOREGROUND_YYYYMMDD"
+```
+
+驗收：exit `0`、使用者輸出為 marker、沒有 touched files，且新 conversation transcript 的 input、`DONE` response 與 marker 一致。
+
+### 3. 插件背景 task
+
+```sh
+node plugins/gemini/scripts/gemini-companion.mjs task \
+  --background --engine agy --fresh \
+  "Reply with exactly OS_AGY112_PLUGIN_BACKGROUND_YYYYMMDD"
+
+node plugins/gemini/scripts/gemini-companion.mjs status <job-id> --json
+node plugins/gemini/scripts/gemini-companion.mjs result <job-id> --json
+```
+
+驗收：
+
+- job 進入 `completed`，exit status 保持 `0`。
+- `status`、`result.rawOutput` 與 transcript marker 一致。
+- `threadId` 精確指向含 `PLANNER_RESPONSE status=DONE` 的 conversation。
+- `touchedFiles` 為空。
+
+### 4. 小型結構化 review
+
+使用小型、既有的唯讀 diff，避免把 transport 驗證混入大型 prompt 壓力測試。v0.7.1 歷史中的 `2a09e6d33528a58a7ab824a39a359b50ee94c198` 是單檔文件 commit，可作為固定 target。
+
+```sh
+PLUGIN_REPO="$(pwd)"
+TARGET="${TMPDIR:-/tmp}/agy112-review-target-YYYYMMDD"
+git clone "$PLUGIN_REPO" "$TARGET"
+git -C "$TARGET" checkout --detach 2a09e6d33528a58a7ab824a39a359b50ee94c198
+
+node "$PLUGIN_REPO/plugins/gemini/scripts/gemini-companion.mjs" review \
+  --wait --engine agy --cwd "$TARGET" \
+  --base HEAD~1 --scope branch
+```
+
+驗收：exit `0`、輸出可解析成插件 review 結構，且配對 transcript 的最終 `PLANNER_RESPONSE` 為 `DONE` 並包含同一份 JSON 結果。
+
+### 5. 無效 model 必須 fail-fast
+
+```sh
+AGY_BIN="$(command -v agy)" node - <<'NODE'
+const { spawnSync } = require("node:child_process");
+const result = spawnSync(process.env.AGY_BIN, [
+  "--model", "codex-invalid-model-validation",
+  "--print-timeout", "1m"
+], {
+  input: "This prompt must not run.\n",
+  encoding: "utf8",
+  timeout: 20_000
+});
+console.log(JSON.stringify({
+  status: result.status,
+  signal: result.signal,
+  stdout: result.stdout,
+  stderr: result.stderr,
+  spawnError: result.error?.message ?? null
+}, null, 2));
+NODE
+```
+
+驗收：20 秒內非零退出、signal 為空、stdout 為空、stderr 非空且同時說明 model 無效並列出可用模型。
+
+### 6. 真正 headless OAuth 必須 fail-fast
+
+Node 的 `detached: true` 會在 POSIX 建立沒有 controlling terminal 的新 session；空白暫存 `HOME` 隔離日常憑證。
+
+```sh
+AGY_BIN="$(command -v agy)" node - <<'NODE'
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const { spawnSync } = require("node:child_process");
+
+const home = fs.mkdtempSync(path.join(os.tmpdir(), "agy112-headless-"));
+const started = Date.now();
+const result = spawnSync(process.env.AGY_BIN, ["--print-timeout", "1m"], {
+  detached: true,
+  input: "This prompt must not run.\n",
+  encoding: "utf8",
+  timeout: 20_000,
+  env: {
+    ...process.env,
+    HOME: home,
+    XDG_CONFIG_HOME: path.join(home, ".config")
+  }
+});
+
+console.log(JSON.stringify({
+  elapsedMs: Date.now() - started,
+  status: result.status,
+  signal: result.signal,
+  stdout: result.stdout,
+  stderr: result.stderr,
+  spawnError: result.error?.message ?? null
+}, null, 2));
+NODE
+```
+
+驗收：20 秒內非零退出、沒有 timeout/kill signal、stdout 為空，stderr 明確要求先互動登入。若保留 controlling terminal，AGY 改從 `/dev/tty` 等待授權碼是另一條預期路徑，不能用來判定真正 headless fail-fast。
+
+### 7. 程序與自動化基線
+
+```sh
+pgrep -af agy
+npm test
+npm run check-version
+npm run verify-contracts
+git status --short
+```
+
+驗收：沒有本次測試遺留的 AGY/MCP 程序；完整測試、版本與契約檢查通過；正式 repo 保持乾淨。
+
+## 2026-07-14 執行結果
+
+### 平台結論
+
+| 平台 | 實際環境 | 結論 | 說明 |
+|---|---|---|---|
+| Linux x86_64 | Ubuntu 24.04.4 LTS，WSL2 kernel `6.18.33.2-microsoft-standard-WSL2` | **PASS（WSL2）** | 真實 Linux AGY 1.1.2 binary、服務端、OAuth、stdout 與 transcript 均已執行。WSL2 不等同 bare-metal Linux，若 v0.8.0 要承諾原生 distro，可再補一台非 WSL 主機。 |
+| macOS | 無可用主機；repository self-hosted runners 為 0 | **OPTIONAL / NOT RUN** | 只確認官方 Darwin x64/arm64 manifest 皆為 1.1.2；未執行 binary、登入、stdin 或 transcript。這不阻塞純 Node/plugin 邏輯或 v0.8.0；也不得宣稱 macOS 1.1.2 已 live verified。 |
+
+### Linux 證據
+
+- 隔離 binary：官方 Linux x64 tarball 的 SHA-512 驗證通過，`agy --version` 為 `1.1.2`；既有 `/root/.local/bin/agy` 仍為 `1.1.1`，未覆寫。
+- 正式插件：從公開 tag `v0.7.1` clone，commit 與版本分別為 `6115ee184b02c429c3a220ade9ac7313c19a9283`、`0.7.1`。
+- brain root：AGY 1.1.2 實際使用 `/root/.gemini/antigravity-cli/brain`；`/root/.antigravity-cli/brain` 不存在。
+- 原生 stdin：7.4 秒、exit `0`、stdout 精確為 `LINUX_AGY112_DIRECT_20260714`；conversation `81b6706c-56b9-49b3-8cdd-42af62f4a797` 的 transcript 含相同 marker。
+- 前景 task：6.6 秒、exit `0`；conversation `a877ac93-7de8-43c4-8a2f-63460d7c95c1` 的 `USER_INPUT` 與 `PLANNER_RESPONSE status=DONE` 配對成功。
+- 背景 task：job `task-mrke927m-d90f31a1b9` 於 4 秒完成；thread `6f006db2-ee2a-4522-bf2b-d4f7ad53aa45`、`result.rawOutput`、transcript marker 一致，`touchedFiles=[]`。
+- Review：7.3 秒、exit `0`、結構化 verdict `approve`；conversation `7d6d2927-caa7-4f19-9d07-d245aa29b616` 的最終 response 為 `DONE` 且包含同一 JSON。
+- 無效 model：3.2 秒內 exit `1`、無 signal、stdout 空；stderr 說明 model 無效並列出 8 個可用模型。
+- OAuth with TTY：隔離空白 `HOME` 時，AGY 顯示授權 URL 並宣告 60 秒等待，證實 prompt stdin 已占用時會改讀 controlling terminal；驗證 harness 於 20 秒上限終止。
+- OAuth truly headless：Node `detached: true`、隔離空白 `HOME`，745 ms 內 exit `1`；stderr 明確要求先執行互動登入，沒有 timeout 或 signal。
+- 程序清理：未發現本次 binary 的殘留 AGY 程序。
+- 自動化：Linux 完整測試 `237/237`；`npm run check-version` 與 `npm run verify-contracts` 通過。
+
+### 剩餘決策閘門
+
+- macOS 真實 1.1.2 全套驗證尚未執行，但它是額外平台信心，不是 v0.8.0 的必要進入條件。
+- 本次證明 Linux stdout 可用，但 transcript 仍提供 `DONE`、conversation ID、thinking 與可靠配對；不能據此移除 transcript recovery。
+- 本次只驗證 AGY 原生無效 model 的上游行為，未授權插件開始傳遞 `--model`；公開參數契約仍未改變。
+
+### 下一次租用 macOS 的觸發條件
+
+預設不租用 macOS。只有以下任一條件成立時，才建立 macOS live-validation issue，並在相關變更合併前執行本清單：
+
+- 修改 `agyBrainRoots()`、Darwin 路徑解析、transcript discovery/matching、mtime 或 conversation 配對邏輯。
+- 修改 POSIX process group、signal、timeout、stdio、detached session 或 controlling-terminal 行為。
+- 修改 OAuth code 的 stdin／`/dev/tty` 路徑，或 AGY 上游 changelog 明示 Darwin-specific 變更。
+- 準備對外宣稱「macOS + AGY 1.1.2（或後續指定版本）已 live verified」。
+- 收到可重現的 macOS-specific 安裝、執行、transcript 或清理缺陷。
+
+若以上條件均未成立，Windows live、真實 Linux AGY 與 POSIX integration tests 即為本 adapter 的必要驗證集合；不得僅為一般 Node/plugin 邏輯租用 Mac。
+
+### 本次暫存項目
+
+- WSL 驗證資料位於 `/tmp/agy112-verify-20260714-1`、`/tmp/gemini-plugin-cc-v071-verify`、`/tmp/agy112-linux-review-target` 與隔離 headless HOME。
+- 一次失敗的 PowerShell/Bash 變數傳遞將已校驗但未執行的 tarball 放在 WSL `/agy.tar.gz`。依刪除授權規範，本次未自行刪除。