aiskillstore/marketplace / pending/cagdasyurekli/agy-worker
agy-worker
UnverifiedUse when Codex or Claude Code should delegate repository exploration or implementation to Google Antigravity CLI (agy), then review, verify, repair, and deliver the result.
references/TROUBLESHOOTING.md
View on GitHub# Troubleshooting
Classify the first failure; preserve the candidate and caller choices. Do not silently
retry, change models or weaken checks.
For the normal command sequence, read
[Project lifecycle and verification](PROJECT_LIFECYCLE_AND_VERIFICATION.md). For
provider, environment, and verifier limits, read
[Security and compatibility](SECURITY_AND_COMPATIBILITY.md).
## The runtime does not resolve
**Symptom:** `resolve-pipeline.sh` reports that the pipeline or complete bundle is
missing.
**Action:** Reinstall or recopy the whole `skills/agy-worker/` package, including
`runtime/`, `scripts/`, `references/`, and `agents/`. Do not point the resolver at a
partial runtime or edit `.pipeline-root` by hand. A standalone marker must be an
absolute path to a complete installation.
## Doctor reports `not-ready`
Fix the named local prerequisite or missing AGY capability, then rerun the read-only
doctor. Version drift does not require activation or help-SHA approval. A `ready`
result does not test authentication, provider availability, native containment, or
task quality.
## Transmission preview fails
The preview requires a real canonical branch-backed linked Git worktree. Common
causes are an ordinary directory copy, a detached or unregistered worktree, a root
`.git` layout that does not match the contract, an outward/broken symlink, a special
node, path drift between scans, or a configured enumeration limit.
Create or repair the disposable worktree using Git, remove unapproved content, and
rerun the provider-free preview. Do not bypass the preview or interpret a preview
failure as provider rejection. If using a narrow provider-scope policy, recompute and
review its unified transmission SHA after any content or policy change.
The scope policy itself must be a current-user, regular, unlinked `0600` file at its
resolved path. Recreate it if it is group/world-readable, read-only, a symlink,
hardlinked, replaced, or changed during the bound read; do not weaken the policy-file
boundary to recover a preview.
## Preflight fails before provider launch
Tell the user the task was not sent to AGY. Missing capabilities, malformed help or a
changed executable reject before launch. Version text is diagnostic; approval flags
cannot bypass readiness. Resolve the actual prerequisite without changing model,
effort, authentication, scope, permissions or task.
Lifecycle status reports `selection_preflight_failed` (exit 26). Inspect the existing
private `stderr_path` for fixed missing-capability names, not raw help. Initial CLI
preflight reports those names directly.
## agy exits zero but ordinary output is empty
This can be valid CLI behavior. Parse `result.structured_output`; do not treat the
echoed schema or empty display text as the worker result. If the structured report is
missing or invalid, preserve the sanitized failure and do not invent an envelope.
A command-permission denial can also produce empty output in headless mode;
`accept-edits` grants no shell permission. Keep the selected model and authority
unchanged, retain the actual controller failure, and do not silently retry or widen
permissions. A file-tool-only prompt does not guarantee the worker avoids commands.
## Authentication, quota, timeout, or provider failure
Classify only from reviewed, bounded evidence. Do not infer account health, billing,
model acceptance, or provider availability from local controller state.
There is no version-specific quota countdown or automatic retry. A strict terminal
`denied_actions` field, including an empty or malformed value, stops provider reuse.
A valid candidate remains reviewable; a missing report does not become a candidate.
An exact duration-bound partial-timeout signal or nonzero provider exit also prevents
successful completion. Follow the recorded reason and available actions.
There is no separate quota reason. A valid, unambiguous `AGY_ERROR` terminal payload
with provider exit 3 maps to `provider_terminal_error` (worker exit 25); other
nonzero shapes can map to `agy_failed_unclassified`, including a marker with exit
1 or 2. Inspect the bounded `short_error` / `error_code` diagnostic to distinguish
quota, rate-limit or credit exhaustion; the reason alone does not establish which
occurred. Do not retry automatically; use only the recovery action authorized by
the owner and offered in `available_actions`. Falsifier: `static_agy_error_metadata_offline_parser_contracts` in
`tests/test-agy-worker-remediation.py` tests metadata and classification.
For a candidate-free failure, consult `available_actions`. A mechanically eligible
`resume` keeps the exact stored conversation; a fresh `restart` requires explicit user
direction. Both require the current state SHA and a new provider notice.
## hard_deadline_exceeded
Use the [driver's task-sizing guidance](../SKILL.md#choose-and-run-the-workflow).
Observation (2026-10-16, agy 1.4.0,
`gemini-4-argon-medium`, native scoped mode): a 157-file read scope reached its
30-minute maximum runtime after 147 file views and two write events, without a
report or recognized candidate; the private stage was absent afterward. This is
one observed run, not a task-capacity guarantee.
The `source guard preserves stage workdir dirty-source and ignored-output controls`
check in `tests/agy_worker_remediation_runtime_boundary_cases.py` tests the
narrow cleanup claim: after a scoped provider writes partially and reaches maximum
runtime without a report, its owned stage is removed and the candidate worktree
stays unchanged. It does not prove remote provider cancellation or recoverability
of those partial writes. A timeout with a valid report has a separate candidate
review path; inspect status before choosing recovery.
## A provider error or cancellation still has a candidate
A structurally valid `ERROR` candidate is reviewable. Retrieve `result`, inspect the
diff, create Verification v2 from driver-owned evidence, then choose an eligible
same-conversation `continue` or `finalize`. Do not use `resume`.
A structurally valid `CANCELED` or `CANCELLED` candidate is preserved for review and
finalization, or an explicitly directed fresh restart. It is never resumed or
continued. Local cancellation proves local process closure only; report remote
cancellation as unverified unless independently established.
## Model selection rejected or source checkout guard stop
`model_selection_rejected` (exit 26): AGY rejected the caller's `--model`/`--effort`
pair. Check `agy models` and start a new job; the controller never substitutes a model.
`source_checkout_changed` (28) / `source_checkout_guard_unavailable` (29): the main
source checkout changed since the job baseline, or could not be observed within limits.
No candidate or repair reuse is available; inspect the source checkout and start a new job.
## Scoped native launch is unavailable
Explicit `--provider-isolation native` requires supported macOS scoped containment.
`session` isolation (never defaulted; the caller must name it) uses the existing AGY session. A general
`doctor` readiness result does not qualify that native launch or authentication.
An outer host sandbox can prohibit nested Seatbelt: Codex `workspace-write` produced
`sandbox_apply: Operation not permitted` in a live native attempt. Treat that as a
host containment prerequisite failure, not as an unclassified provider failure.
If launch reports `status_unavailable`, inspect the host and bound executable/profile
before changing the task. Do not retry a provider call or silently switch execution
or transmission modes: that changes the exposure approved by the user. Keep the
candidate and identify the failed prerequisite in the handoff. Exit 27 (native host
prerequisite) also covers a missing or locked dedicated keychain; see
[Dedicated agy keychain](#dedicated-agy-keychain-for-native-isolation).
## Dedicated agy keychain for native isolation
Native isolation uses only `~/Library/Keychains/agy-worker-provider.keychain-db`
(under the home directory from the password database), never your login keychain.
Set it up once, in your own terminal:
```bash
security create-keychain ~/Library/Keychains/agy-worker-provider.keychain-db
security set-keychain-settings -l -u -t 28800 ~/Library/Keychains/agy-worker-provider.keychain-db
"$PIPELINE/agy-worker.sh" native-keychain-login
```
`create-keychain` prompts for a keychain password and may also add the file to your
keychain search list; native runs ignore that list. `set-keychain-settings -l -u -t
28800` locks the keychain on sleep and after 8 idle hours. Do not run it without
options: that turns auto-lock off and leaves the credential readable after you walk
away. A shorter timeout is safer but makes multi-cycle jobs stop for an unlock; each
native launch and repair fails closed with exit 27 while it is locked. If it locks
mid-run, agy cannot write a refreshed token back and falls back to a file in the job's
private provider HOME. `native-keychain-login` runs `agy -p "Reply with OK"` in a
temporary HOME holding only a preference that names the dedicated keychain, so agy's
browser sign-in stores its credential there; it then deletes the temporary tree. It
never creates the keychain or handles its password.
After a reboot, unlock it before native launches:
```bash
security unlock-keychain ~/Library/Keychains/agy-worker-provider.keychain-db
```
A missing or locked keychain stops a new native launch with exit 27 before the task is
read and before any job exists; a repair or resume that finds it locked ends that
job with `native_host_sandbox_unavailable` (27). Unlock or create it and start the
documented recovery; do not switch isolation mode.
## State approval is stale
Mutating lifecycle commands require the current `state_sha256`; `wait` uses
`--after-state-sha`. Read `status` again, understand what changed, rebuild any
candidate-bound evidence, and use the newly reported approval only if the intended
action remains available. Never copy a stale digest forward blindly.
Refreshing a binding does not itself require new approval. Reuse covered authority;
changed exposure, scope, destination, isolation, permissions or budget needs approval.
For facade finalization of a bound dispatch, use `dispatch.state_sha256` as
`--approve-dispatch-sha`. It is distinct from a convenient current facade state hash.
The former facade `--approve-state-sha` alias is rejected; advanced dispatcher and
job lifecycle commands still use their own `--approve-state-sha` flag.
## Unsupported job schema or removed flag
Use the creating release to finish or discard old-format jobs. Preserve their artifacts;
do not rewrite schema numbers or use removed options to bypass rejection. There is no
in-place migration, including for ordinary old jobs without removed features.
Use current explicit transmission approvals and `--approve-dispatch-sha` for facade
finalization. See [controller state and actions](PROJECT_LIFECYCLE_AND_VERIFICATION.md#controller-state-and-actions).
## Candidate drift or verification-copy failure
Tracked, untracked, deleted, and ignored paths participate in candidate binding. A
cache file, bytecode file, generated artifact, or manual cleanup can invalidate the
snapshot. Do not delete or regenerate files to force equality. Stop writes to the
candidate, inspect it read-only, and create a new isolated verification copy.
The copy fails closed for source drift, an existing or non-private destination,
outward/broken/Git-administration symlinks, or an invalid destination boundary. A
failed copy is not usable evidence. A non-`0700` immediate-parent diagnostic is emitted
only when its bounded inspection is small enough; otherwise the failure stays an invalid
destination boundary. Preserve the original candidate and report the unresolved failure.
## The gate rejects scope or verifier input
- A declared-path mismatch means Git found changes outside the envelope declaration.
- `--only` rejects every changed path outside its repeatable policy; `--allow` only
permits known undeclared artifacts and does not override `--only`.
- A no-op with `--expect-edits` is a rejection, not a verified result.
- Non-empty worker `commands_run` or `tests_run` fields are untrusted claims and cause
rejection; choose commands independently.
- `--verify-argv` must be a canonical JSON array and cannot smuggle an implicit shell.
- A verifier that mutates the candidate invalidates the exercised state.
Fix a real candidate defect through a bounded same-conversation repair when budget
remains. Fix a driver invocation error locally. Never weaken the gate simply to make
it green.
## A verifier needs environment or network access
The default verifier baseline excludes `HOME`. Add an ordinary variable only by exact
name with `--verify-env NAME`. Credential-like names, including `HOME`, require
`--verify-credential-env NAME` and the credential-access acknowledgement. Explicit
shell verification separately requires network and credential-access
acknowledgements.
Acknowledgements do not provide a value or network isolation and do not authorize an
external write. Candidate code can import unreviewed code, so expose no credential
merely to reproduce an ambient shell setup. Prefer a narrower offline verifier.
## The repair budget ends with failed or missing checks
Keep the useful candidate and report `partially_verified` with the exact failed,
missing, or unavailable checks and unresolved gaps. Do not erase the candidate,
silently start a new conversation, or call it verified. A fresh restart is a separate
explicit user decision.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |