cloud-run-debug

Diagnose a broken Cloud Run service. This is a **Conductor / Executor** split: **you (Claude)
conduct** — confirm scope, reason about the root cause, and propose the fix — while the cheap,
high-volume work (pulling and clustering potentially hundreds of error log lines) is **offloaded
to agy (Gemini)** so your context stays lean. You ingest only agy's digest, never the raw logs.

Flags: $ARGUMENTS

Defaults: `--since 1h`, `--limit 200`, **read-only** (diagnosis only). `--apply` is the only
thing that writes anything, and only ever onto a branch for human review. For a chatty service,
narrowing `--since` tightens the digest (and cost) further.

Advanced (engine) flags also exist and can be passed through if the user asks: `--severity`
(minimum severity, default `ERROR`) and `--tier` (agy tier for the digest, default `flash`).

Do this:

1. **Resolve scope.** Parse the flags above.
   - `--service` is required. If it's missing, ask the user which Cloud Run service to diagnose
     (AskUserQuestion) — there is no "default service".
   - `--region` is optional; if omitted, logs across all regions are queried. If the user's
     `gcloud config` has a default region you can offer it.
   - `--project` is optional; when omitted the engine falls back to `gcloud config`'s default
     project. Multi-project users can easily read the **wrong** project's logs this way, so when
     `--project` isn't given, **surface the project the engine will use** (`gcloud config get-value
     project`) and confirm it before reading — or have the user pass `--project <id>` explicitly.
   - Never ask for or handle credentials/tokens — the engine uses the existing `gcloud` ADC.

2. **Fetch + digest (delegate to agy — one batch, not parallel).** Run the plugin's read-only
   engine, which pulls `severity>=ERROR` logs via `gcloud logging read` and hands them to agy for
   a structured digest (error clusters / representative stack traces / time distribution / likely
   root-cause candidates):
   `cloud-debug --service <name> [--region <r>] [--project <id>] [--since <dur>] [--limit <n>]`
   - **Ingest only the digest** it prints — do **not** re-fetch or paste the raw logs into your
     context (that lean handoff is where the cost saving comes from).
   - If it exits **3** (permission denied), relay the `roles/logging.viewer` guidance it printed
     and stop — the user must grant access first. Exit **4** means `gcloud` isn't installed.
   - If it reports no matching logs, widen `--since` / lower severity, or re-confirm the
     service/region with the user.

3. **Diagnose (you).** From the digest, infer the most likely root cause (e.g. a missing env var,
   an unhandled exception, bad config, a dependency timeout). State the reasoning and the evidence
   (which cluster / trace supports it). Then propose a **concrete fix** — the exact code, config,
   or environment change — and how to verify it.

4. **Apply only if `--apply` was passed.** Default is diagnosis-only; do **not** modify anything
   without `--apply`.
   - **Check the working tree first:** run `git status --short`. If it's **not clean**, stop and
     confirm with the user — branching now would fold their uncommitted changes into your fix's
     diff (and any commit). Offer to `git stash` them, or to work in a separate branch/worktree.
     Only proceed from a **clean base**.
   - Work on a **dedicated branch** (create/switch to one; never the user's working branch).
   - Apply the proposed fix, then **show the diff** and stop. Do **not** deploy and do **not**
     merge — a human reviews and merges.
   - Confirm before any destructive or hard-to-reverse step.

Keep it tight: the demo is Claude conducting the diagnosis while a cheaper model does the log
grunt-work. Report what you delegated, the root cause you landed on, and the fix (plus the diff
if `--apply`).