feat(cli): detect Gemini managed-agent sandbox in detectAgentRuntime

[jrusso1020]

What

Adds Gemini managed-agent sandbox detection to the CLI's existing agent-runtime telemetry. Returns "gemini_managed_agent" from detectAgentRuntime() when the CLI is invoked inside a Google Gemini managed-agent sandbox; null elsewhere.

Why

The CLI already classifies invocations from Claude Code, Cursor, Codex, Replit, Hermes, openclaw, Pi, GitHub Copilot Agent (the existing VENDOR_RULES array in agent_runtime.ts). A Gemini managed-agent template is now using the hyperframes CLI internally for local renders (the dual-mode work in heygen-com/hyperframes-gemini-agent#1), and the team wants the same adoption signal for that surface.

How

Two changes in packages/cli/src/telemetry/agent_runtime.ts:

1. Add "gemini_managed_agent" to the AgentRuntime type union.
2. Add isGeminiManagedAgent() — a filesystem-based detector that returns true when both signals are present:
   • existsSync('/.agents/AGENTS.md') — the uniqueness anchor. Definitionally a managed-agent artifact (the platform injects it per-run; its mtime tracks the interaction). Nothing in the generic Google-Cloud-on-gVisor universe (Cloud Run gen2, GKE Sandbox, Fly.io) mounts /.agents/. This single check carries essentially all uniqueness.
   • isGVisor() — a guard, not a second uniqueness signal. gVisor itself is shared with GKE Sandbox + Cloud Run gen2 — it does not discriminate Antigravity. Its job here is to rule out a stray user-created /.agents/AGENTS.md on a non-sandbox host.
3. detectAgentRuntime() checks isGeminiManagedAgent() ahead of the env-var-only VENDOR_RULES loop, since the Gemini signal is filesystem + kernel, not env.

GEMINI_API_KEY is deliberately NOT keyed on — it's user-settable on any host. Other signals explicitly excluded with documented reasons: gVisor alone, Google Compute Engine DMI (entire GCP reports this), job cgroup (Google-internal but broadly present), the egress-proxy env cluster (any MITM container sets these), /.google/ base-image overlay.

Empirical verification

Two independent verification passes by gemini-agent (introspection-based — env, /proc/version, /proc/1/cgroup, /proc/net/tcp, ip route, ip link, ls -la /, DMI, PID-1):

Stability — 3 independent fresh sandbox spins (the original spike, b9db4e56, d59d6361) all show both signals present. Full 3-spin matrix posted as a comment on this PR.

Uniqueness — FS-root + cgroup + netns + DMI + PID-1 introspection of d59d6361 to discriminate Antigravity-unique markers from the broader Google-Cloud-on-gVisor universe. Verdict:

• /.agents/AGENTS.md carries essentially all uniqueness (definitional managed-agent mount).
• gVisor is shared with GKE Sandbox + Cloud Run gen2 — guard only, not a discriminator.
• Several hoped-for stronger markers don't exist in the empirical environment: no antigravity/managed-agent in any cgroup path; no ANTIGRAVITY_* / MANAGED_AGENT_* env var; no :8081 listener in /proc/net/tcp (proxy is the veth /30 gateway, not a local socket); no /credentials or service-account path.

Stability ≠ uniqueness; both are required for a correct detection rule. The 3-spin work confirms the signals are reliably present; the uniqueness analysis confirms they discriminate Antigravity from neighboring gVisor surfaces.

Test plan

4 new vitest cases in agent_runtime.test.ts:

• Positive: /.agents/AGENTS.md exists + kernel is 4.19.0-gvisor → gemini_managed_agent
• Negative: gVisor alone (no /.agents/) → null (generic gVisor surface fallthrough)
• Negative: /.agents/AGENTS.md exists on a non-gVisor kernel → null (dev-box false-positive guard)
• Precedence: Gemini signal wins over a coincident CLAUDECODE env var
• All 24 tests in agent_runtime.test.ts pass under vitest run (the CI runner)
• bun run lint + bun run format:check repo-wide clean
• Commit signed (GitHub verified)
• Cross-spin empirical verification (stability)
• Uniqueness empirical verification
• Documentation updated — detectAgentRuntime()'s docstring updated inline; no separate docs surface

🤖 Signed off by Jerrai (hyperframes specialist)

[jrusso1020]

Cross-spin confirmation for the detection rule — 3 independent fresh sandbox spins, all consistent with the conjunction this PR keys on:

Spin	/.agents/AGENTS.md	/proc/version
spike (original)	present	4.19.0-gvisor
b9db4e56 (verification batch)	present (+ skills/, workspace/)	Linux version 4.19.0-gvisor
d59d6361 (heavy-render env)	-rw-r--r-- … 4328 … /.agents/AGENTS.md	gvisor

So the primary signal (exists('/.agents/AGENTS.md') AND isGVisor()) held on all three — the single-spin caveat in the PR body can be treated as closed for v1 adoption. — gemini-agent

[jrusso1020]

Generalizability fix pushed (52d1947)

Re-examined whether the detection generalizes across all Gemini managed agents, not just our own template. It did not, as originally written.

Finding: the detector keyed on existsSync('/.agents/AGENTS.md'), but Google's Managed Agents docs are explicit that AGENTS.md is optional — an agent can declare its instructions inline via system_instruction in agent.yaml and ship no AGENTS.md file ("the system_instruction and AGENTS.md are additive; both apply when present"). The platform auto-discovers the agent under the /.agents/ directory; skills mount at /.agents/skills/, workspace at /workspace/, and AGENTS.md at /.agents/AGENTS.md only when shipped.

So the file-based check generalized only to templates that happen to bundle an AGENTS.md — like our own hyperframes-gemini-agent and Thor's reference. A managed agent defined with inline instructions, or a skills-only definition, was a silent false-negative. All three verification spins used our AGENTS.md-bearing template, so this gap was never exercised — stability across spins ≠ generalizability across agent definitions.

Fix: key on the /.agents/ directory mount instead of the AGENTS.md file. Still gVisor-guarded, so the false-positive surface is unchanged (/.agents/ at filesystem root doesn't exist on Cloud Run gen2 / GKE Sandbox / Fly.io). Added a regression test for the skills-but-no-AGENTS.md case.

Residual gap (documented in-code): an agent defined with only inline system_instruction — no skills, no AGENTS.md — may not materialize a /.agents/ mount at all. That tail can't be closed from the docs; it needs an empirical spin of such an agent to confirm. The common case (skills and/or AGENTS.md present) is now covered.

Sources: Building Managed Agents, Managed Agents Quickstart.