agy_cli_onboarding_lessons

AGY onboarding lessons and manual test log

This is the running record of what was easy to miss while adding Antigravity CLI (agy-cli). Use the general CLI onboarding checklist for the full cross-repository implementation map and the AGY setup guide for user setup. Add a row here whenever a manual test finds a gap: what was observed, the underlying contract, the fix or open follow-up, and the test that will catch it for the next CLI. Do not mark a case verified from code inspection alone.

Gaps found during AGY integration

What we initially missed	Contract to carry forward	Evidence or follow-up
Treating terminal text as proof that AGY accepted or finished a turn.	Keep tmux for launch, typing, live steering, and terminal display. Match the submitted user message to a new AGY conversation SQLite user step; read progress, tool trail, and the settled final assistant step from that same turn. A pane echo is not an acknowledgement and early assistant prose is not necessarily the final answer.	Turn signals, PLAT-352, PLAT-354. AGY 1.2.12 provider and app P0 were run in API-key mode.
Assuming a successful tmux send proves a retained live-input delivery.	Give every send its own receipt. Confirm the exact message in a new SQLite user step after the pre-send index, including repeated identical text; preserve an uncertain outcome when confirmation times out.	Durable ACK contract; TestAgyCLIRealDurableAckContract passed on two retained turns.
Adding the adapter without all product lifecycle paths.	Audit provider identity and options in multi-llm-provider-go, bridge/agent lifecycle in mcpagent, and classification, retained policy, isolation, manifest, setup, model defaults, and release selection in AgentWorks. Run a real workflow and a retained chat, not only an adapter smoke test.	Implementation map; AGY app P0 and isolation changes landed in 05b038d5d.
Assuming an API key in .env automatically authenticates AGY.	Verify the CLI's actual auth mode. AGY does not read .env; API-key mode requires exported GEMINI_API_KEY and modelProvider: "gemini" in its settings. AgentWorks now sets that provider in a private per-run settings copy when the backend has the key. Interactive Google sign-in is a separate path. agy models can exit 0 while saying sign-in is required, so inspect its output.	AGY setup guide. Private-home key-mode live probe passed on 2026-09-28; stored-login and missing-auth regression checks remain on the acceptance list.
Enabling native tools without an AGY-specific policy and visible switch.	Verify both Native agent tools settings. Off uses the MCP bridge. On (hybrid) permits AGY's native file read/search and web read/search. Local Full CLI (full_unconfined) also permits native edits, commands and subagents alongside MCP. Confirm the temporary .gemini/hooks.json is restored after the session. See AGY Full CLI; RTS and excellence remain excluded.	AGY setup guide; UI and isolation work in 05b038d5d.
A working backend provider remained invisible in the UI.	Check the server manifest, supported-provider list, frontend fallback list, Providers panel, workflow model picker, runtime label, and Alpha copy. Verify in the running app, because an old checkout or pre-merge bundle can hide a correctly merged provider.	UI exposure landed in 9ae369a03 and Alpha copy in 749e13dd0. On 2026-09-28 the active port 51733 belonged to the older mcp-gateway checkout; merged main at 51734 visibly showed Antigravity CLI (Alpha) as Connected.
AGY appeared in Providers and workflow models but was absent from product model pickers.	Audit every product profile's runtime.provider_options when onboarding a CLI. The shared provider manifest alone does not add an option. For each product that offers coding CLI choice, open its picker, choose the CLI, and confirm the saved provider and model. Record intentional single-provider products separately.	Crew's product.yaml omitted agy-cli; SparkQuill's parent and child profiles also omitted it. Added AGY to all three picker profiles and extended their manifest tests on 2026-09-28. Dominion and Video Studio deliberately curate a single provider; AgentWorks uses the shared catalog.
The Crew picker saved AGY with high reasoning effort, but sending a message returned HTTP 422.	A product option must offer any effort that its picker saves. Declare supported reasoning_efforts and an options.reasoning_effort default in the product profile. The picker must use a default from that offered set, even when the shared provider manifest suggests another default. Submit a real message after selecting the CLI.	Crew's new AGY option had no reasoning_efforts, while the frontend used the manifest's high default. Added AGY's low/medium/high levels and high default, guarded the picker and chat submission against the running profile, and extended the release tests. A live Crew message succeeded without interrupting scheduled jobs.
An AGY model switch could retain the previous reasoning effort.	AGY encodes effort in the model ID (-low, -medium, -high). Keep the selector and chat payload aligned with that suffix; changing the effort control must choose the corresponding model variant. Test a model switch followed by a message.	The shared product composer and Crew Models panel now synchronize the pair; chat submission derives the effort from the selected AGY model. Frontend tests cover the outgoing payload; live model-switch check remains open.
A later AGY Crew turn failed after its tmux pane needed recovery.	Prove launch-only native resume separately from a normal turn: the restored agent must re-enable persistent interactive mode, and the adapter must boot the TUI without requiring a human prompt. Then send the pending user message exactly once.	StartAgentTransportSession ran before ContinueConversation enabled AGY's interactive mode, so AGY routed the promptless warmup to its JSON exec lane. Added the interactive launch setup in mcpagent and a launch-only path in the SDK. Deterministic tests and a live restored Crew turn passed on 2026-09-28.
Restarting a second backend did not update the open test page.	Verify the browser origin's proxy target, backend start time, and workspace directory before declaring a live retest. Keep the same workspace for retained-conversation recovery.	The new backend on 18743 used a different workspace while port 51734 still proxied to the old 18842 process. Restarted the original stack on 18842/18843 with the project workspace and verified the recovered turn there.
Shared-server readiness was inferred from a single-user alpha pass.	Track security, concurrency and capacity review findings separately from desktop acceptance. For H1, replace foreign workspace hooks during a turn and guard .agents writes in every coding-agent session. For H2/H3, keep MCP credentials in private 0600 per-run config, sweep dead legacy mounts, expire bridge tokens, and prove two users can call different bridges concurrently. For M1, return a typed quota error.	Issue #235 records the review. Local fixes and macOS live AGY 1.2.12 bridge tests passed on 2026-09-28; Linux and shared deployment verification remain open.
The follow-up review found scrollback, environment, prompt-argv, alpha-gate, isolation, hook-failure, and lifecycle gaps after the first pass.	For every new CLI, test pane markers against quoted old output; pass prompts on stdin or a private file; scrub the tmux server environment at the child boundary; require an explicit alpha gate; prevent shared-server use until per-user credentials and conversations are isolated; test slow and crashed safety hooks; and cover orphan sweep, steer readiness, cost metadata, terminal labels, multiline input, atomic settings, and races.	Issue #235 M2–M7 and Low. Deterministic fixes were started on 2026-09-28; live hook-failure and per-user isolation proofs remain open.
Treating an in-process mutex as exclusive ownership of AGY workspace hooks.	Hold a cross-process lock for the entire AGY session, save the original hooks on disk before replacing them, restore after a crashed process, and reject symlinked hook paths. Test a second process and a simulated crash.	SDK #38 adds the lock, backup, and regression tests. Parent-directory hook discovery and live timeout/crash behavior remain open.
Classifying quota from all CLI output, or guarding every bridge session before it has workspace grants.	Read quota only from explicit error carriers; never scan assistant text or the full NDJSON transcript. Enforce an alpha gate where the provider is executed and hide unavailable product options. Adding blocked-write paths must not create an empty allowlist; isolated delegated sessions need their own grants.	SDK #38 and AgentWorks #237 carry focused fixes. A real quota wall and per-user AGY isolation remain open.
A parent AGY hook blocked delegated AGY runs, and the sub-agent lost its CDP host Downloads read grant.	Exercise nested and background sessions while a parent CLI is still live. Permit an ancestor hook only when its file exactly matches the managed gate, keep rejecting foreign hooks, and copy browser read grants to the isolated sub-agent session ID. Match quota text from explicit stderr/TUI error lines, including the interactive timeout path.	SDK #38 and AgentWorks #237 include focused tests and fixes. A live delegated AGY run, real quota wall, and Linux hook behavior still need verification.
Assuming the installed CLI version remains certified after an upgrade.	Record the exact agy --version, compare it with scripts/p0-certified-cli-versions.json and the SDK minimum, then rerun the required live proofs on version changes. Quota exhaustion is a failed or incomplete live run, never a pass.	Certified version recorded as 1.2.12. The Providers panel on 2026-09-28 reported 1.2.12.

Repeatable acceptance pass for AGY and the next CLI

Record the date, app/agent/SDK commits, CLI version, auth mode, selected model, transport, and whether each result came from a real CLI, deterministic test, or manual UI check. Keep incomplete checks open.

• Fresh setup: install/version floor, login and API-key modes, missing auth, trust prompt for the exact working directory, model discovery, and quota failure surfaced to the user.
• Turn evidence: exact user intake, slow tool progress, tool receipts, final answer after the last tool, no replay of older assistant text, and one canonical completion. Use structured CLI records for correctness and tmux for interactive transport and display.
• Retained chat: second turn in the same conversation, live input while busy, repeated identical messages with distinct acknowledgements, cancel, tmux loss/recovery, promptless launch-only resume, and page refresh/history restoration. Retry the user message after a dead pane and verify one answer.
• Tools and workspace: MCP bridge call in chat and a workflow step; native tools off/on; disallowed native command/write/subagent attempts; exact cwd, temporary config cleanup, and parallel session isolation.
• Safety and lifecycle edges: old quoted pane markers, scoped secrets inside a tmux sidecar, prompt outside process arguments, explicit alpha flag, per-user account and conversation separation, slow/crashed hook behavior, orphan sweep, steer readiness, terminal/cost labels, multiline live input, atomic settings writes, and race detection.
• Product surfaces: Providers panel with correct Alpha label and status; workflow model picker; every applicable product Models picker and saved selection; model/effort alignment after selecting another AGY variant; send a real message in each product to verify the selected model and reasoning effort pass server validation; normal chat, workflow step, background/sub-agent run; terminal progress separated from the formatted final reply.
• Release environment: default and explicit provider test selection, certified version file, fresh frontend build, correct API/runtime-config ports, and the actual app window or browser tab the tester is using. When another checkout runs locally, set separate AGENT_PORT and WORKSPACE_PORT; the launcher otherwise claims its default workspace port.

Manual findings to append

Date and CLI version	Surface and exact action	Observed vs expected	Reproduction/evidence	Fix or issue	Regression test and status
2026-09-28 · 1.2.12	Open Providers in the active local app	Older gateway checkout did not show AGY; merged main showed Antigravity CLI (Alpha) as Connected	Ports 51733 (gateway) and 51734 (main); live Providers UI check	Use the merged app for AGY testing; retain the running-checkout check above	UI manifest/panel tests exist; local running-app check verified
2026-09-28 · 1.2.12	Create a blank Crew from the AGY test app in the in-app browser	The UI showed Network Error even though the API was healthy	The browser blocked direct requests to API port 18842; page on 51734 loaded. No hello123 project files were written by the failed attempt.	Route local /api through the Vite origin and write that origin to runtime config (frontend/vite.config.ts, agent_go/run_server_with_logging.sh).	Proxy /api/health returned 200. Retrying the blank form created hello123 once, showed it in the Crew UI, and wrote its project files.
2026-09-28 · 1.2.12	Open hello123 → Setup → Identity → Models	AGY was missing while the Providers panel showed it connected	Crew's runtime.provider_options listed five CLIs and omitted agy-cli	Added AGY to Crew's product.yaml with the certified model and extended the manifest contract test.	Focused Go tests passed. After restarting the local app, the picker showed Antigravity CLI (Alpha); selecting it saved gemini-3.8-flash-high, and both provider and model remained selected after a page reload. Live AGY conversation in Crew remains unchecked.
2026-09-28 · 1.2.12	Audit all product profiles with coding CLI pickers	SparkQuill parent and child also offered only Claude Code and Codex	Both profiles curate runtime.provider_options in SparkQuill's product.yaml; the picker reads these options.	Added AGY with the supported Gemini 3.8 Flash models and high effort default to both profiles.	Focused manifest tests passed. Live SparkQuill picker and conversation remain unchecked until the running backend loads the new embedded manifest.
2026-09-28 · 1.2.12	Send a message in hello123 after choosing AGY	HTTP 422: reasoning effort "high" is not offered for engine "agy-cli"	Crew saved the shared manifest's high effort, but its AGY provider_options entry declared no reasoning_efforts; the server rejects any undeclared effort.	Declared AGY low/medium/high and high default in Crew; constrained the picker and chat request to the running profile's offered levels.	Product manifest, server chat-request, and frontend submission tests pass. Retrying hi in the current app on 2026-09-28 was accepted; AGY completed a reply in hello123. The Go manifest update still awaits a server restart.
2026-09-28 · 1.2.12	Continue hello123 after earlier AGY turns and terminal loss	can you also.. check mcps you have access to showed Not delivered; the next turn failed with parent_transport_unavailable and agy-cli exec lane needs a human prompt, got none	Server log at 12:21:31 shows the restored handle entering StartAgentTransportSession before the pending user prompt.	Enable interactive launch mode on restored agents and make AGY launch-only boot the sidecar without a prompt.	SDK and agent focused tests pass. After restarting the original stack, one resend at 12:52 prelaunched the restored native session in 3.7s, completed in 1.1m, and rendered the answer in Crew. AGY's conversation DB has exactly one matching user step (idx 34) and a settled assistant step (idx 48, status 3).
2026-09-28 · 1.2.12	Restart the same 18842/18843/51734 stack again, then continue hello123	The saved AGY provider and gemini-3.8-flash-high model remained selected; the user's what all can you do turn completed in 43.3s with a visible reply	Backend and workspace health endpoints were healthy; no 422 or parent_transport_unavailable appeared in the new server log; AGY's native conversation DB contains one matching user step (idx 49).	Keep a second restart and retained-chat turn in the basic smoke pass.	SDK recovery, mcpagent recovery, server reasoning, and frontend chat-submit focused tests passed locally.
2026-09-28 · 1.2.12	Review issue #235 H1–H3 and M1	Foreign workspace hooks were executable; bridge tokens appeared in global MCP config and argv; different session fingerprints serialized all mounted turns; quota walls were generic errors.	Own the active hook file exclusively, install the write guard at every coding-agent bridge, use private AGY homes and expiring tokens, and type quota failures.	Added deterministic hook, private-home, legacy-sweep, quota, token-expiry, and write-guard tests.	SDK package tests and app guard tests passed; live key-mode private-home, MCP canary, two concurrent bridges, and persistent sidecar bridge passed on macOS. The original global-mount test assertion was updated to respect another live backend's mount. Linux and shared deployment tests remain open.
2026-09-28 · 1.2.12	Follow up issue #235 M2–M7 and low findings	Pane checks scanned old replies, prompts and keys reached process arguments, and missing provider mappings and global trust entries survived onboarding.	Use terminal rows only for current pane status, AGY stream JSON on stdin, a scoped sidecar launch script, private-home trust, AGY_ALPHA=1 for single-user testing, and complete the missing provider mappings.	SDK and app branch fix/agy-review-remaining; M6 per-user accounts and M7 live hook-failure behavior remain open.	Focused SDK race tests and app Go tests passed. The live exec check is blocked: stored login is unavailable and local key candidates return API_KEY_INVALID.

When a manual result has no automated guard yet, leave its regression-test cell open and link the issue. This file is a test log, not a claim that every case in the acceptance pass has already been certified.