agy-sidecar-scheduled-tick

What this skill does

# agy-sidecar-scheduled-tick

Drive a **recurring** AgentOps loop tick on the **Antigravity image** (AGY) using a **sidecar** — AGY's
long-lived headless server — with the **`schedule` builtin** for the cadence and **`agentapi`** as the
runtime the tick talks to. Each fire leaves a durable, inspectable **agentapi evidence** surface so a
separate-context validator can confirm the tick ran and did real work after the fact. This closes the
AGY proof child that requires *sidecar scheduling* plus *agentapi runtime evidence* (`cp-c6k.3.2`):
a one-shot `agy -p` (see `agy-headless-evidence`) proves a single headless run; this skill proves the
**daemon-style recurring** path. **Configure the sidecar; never cold-start `agy` on a timer by hand.**

## Overview / When to Use

`agy -p` cold-starts the harness on every call. For a loop that ticks on a cadence (claim a ready bead,
do one scoped unit, persist, repeat) you want a **persistent brain and warm conversation state** instead
of a cold start per fire. AGY provides this through a **sidecar**: a long-lived process described by a
`sidecar.json`, driven by the **`schedule` builtin** (the AGY-native cron/interval cadence) and reachable
over the **agentapi** runtime (AGY's headless server API). Per `IMAGE-AGY.md`, the control-plane
"scheduled tick" role maps to *"Antigravity sidecars with the `schedule` builtin plus `agentapi` for
daemon-style recurring ticks."*

Use this skill when:

- a loop must fire **repeatedly without a human re-invoking it** (overnight burndown, periodic validate
  sweeps, a warm worker that picks up newly-ready beads);
- you need the cadence to be **AGY-native** (the `schedule` builtin) rather than an external `cron`/launchd
  wrapper around `agy -p`;
- a downstream validator must **trust the recurring tick** — so every fire must drop agentapi runtime
  evidence, not just print to a log nobody reads back.

Do **not** use this for a single headless run — that is `agy-headless-evidence` (`agy -p`, one shot). Use
the sidecar only when the *recurrence* is the point.

### AGY surfaces this skill uses

- **Sidecar** — a long-lived AGY process declared by `sidecar.json` (under the workspace or plugin), the
  daemon that hosts the recurring tick. Validate/list with `agy --help` surface checks (Door-9: discovery
  commands only).
- **`schedule` builtin** — the AGY-native cadence inside the sidecar (cron expression or interval). This
  is the scheduling source of truth, not an external timer.
- **agentapi** — AGY's headless server runtime the sidecar drives each fire; its **event stream** and a
  **health probe** are the runtime evidence.
- **Brain / knowledge** — durable memory + userFacing artifacts under `~/.gemini/antigravity-cli/{brain,knowledge}/`;
  mirror each fire's verdict here so a *different* context can consume it (author != judge).

## ⚠️ Critical Constraints

- **Rule 1 — The cadence lives in the sidecar's `schedule` builtin, not an external timer.** Encode the
  cron/interval in `sidecar.json`'s `schedule` builtin and record it in `schedule.txt`. **Why:** the
  whole point of this proof child is *AGY-native sidecar scheduling*; wrapping `agy -p` in host `cron`
  is the thing this skill exists to replace, and it leaves no AGY-side schedule to inspect.
- **Rule 2 — Every fire must produce agentapi runtime evidence.** Capture the agentapi **event stream**
  (`events.jsonl`) and a **health probe** (`agentapi-health.json`) per fire. **Why:** a sidecar that
  "is scheduled" but leaves no per-fire runtime trace cannot be distinguished from one that silently
  stopped firing — evidence over comfort.
- **Rule 3 — One fire, one timestamped directory.** Never append unrelated fires into the same evidence
  files. **Why:** a verdict must bind to exactly one event stream, one exit code, one command; fires
  otherwise clobber each other and the proof surface lies.
- **Rule 4 — Capture the exit code immediately.** `echo "$?" > exit-code` on the line right after the
  fire returns. **Why:** a plausible message with a non-zero exit is still a failed tick; the validator
  keys off process reality, not self-report.
- **Rule 5 — The sidecar tick does not close its own beads.** A scheduled author tick claims and works;
  an **independent context** judges and only the orchestrator closes. **Why:** author != judge holds on
  AGY exactly as on the Claude/Codex images (`IMAGE-AGY.md`, single-writer seam).
- **Rule 6 — Scope the sidecar; sandbox by default.** Bound the tick with `--add-dir` to one
  worktree/repo and keep project/worktree-scoped, sandboxed execution. **Why:** a long-lived recurring
  process with broad write scope is a standing hazard; the image path has no break-glass permission
  bypass.
- **Rule 7 — `dcg` BeforeTool guard stays on.** Keep the `dcg` `BeforeTool` hook on `run_shell_command`
  in `~/.gemini/settings.json` even for the sidecar. **Why:** a recurring auto-driven process is exactly
  where a destructive command would slip through unattended — `dcg` is the floor.
- **Rule 8 — This is the AGY lane only (LAW 0).** Never reach for `claude -p` / `claude --print` to make
  a "Claude sidecar." **Why:** `claude -p` bills the API per-token and is banned for worker dispatch;
  AGY runtime is `agy` + the agentapi sidecar. Door-9: do not use `agy --print` as the scheduled executor
  until it is proven subscription-safe; `agy --help`/`--version`/`models` are allowed surface checks.

## Distribution — where the sidecar lives

A sidecar is declared by a `sidecar.json` carried in the **workspace** (`.agents/` / Antigravity config)
or bundled in an **AGY plugin** alongside `plugin.json`, `skills/`, `hooks.json`, and `mcp_config.json`
(per `IMAGE-AGY.md` N=1 step 1). Prefer the plugin bundle so the recurring tick ships and validates with
the rest of the AgentOps laws (`agy plugin validate` / `agy plugin list`).

## Workflow / Methodology

### Phase 1: Declare the sidecar + cadence
Author a `sidecar.json` with the `schedule` builtin (cron or interval) and the scoped command the fire
runs. Record the cadence so it is inspectable.
```bash
RUN_ROOT="$(pwd)/.agy-evidence/sidecar"
mkdir -p "$RUN_ROOT"
{
  printf 'sidecar=%s\n' "agentops-tick"
  printf 'builtin=schedule\n'
  printf 'cadence=%s\n' "${AGY_SCHEDULE:-*/30 * * * *}"   # cron or interval
  printf 'runtime=agentapi\n'
  printf 'scopes=%s\n' "${REPO:-$PWD}"
} > "$RUN_ROOT/schedule.txt"
```
**Checkpoint:** `schedule.txt` records the sidecar name, the `schedule` builtin, the cadence, and that
the runtime is agentapi — and the cadence is in `sidecar.json`, not host `cron`.

### Phase 2: Bring the sidecar up on agentapi
Register/start the sidecar so agentapi hosts it; probe liveness before trusting any fire.
```bash
# agy surface checks only (Door-9: discovery, not the print executor)
agy --version > "$RUN_ROOT/agy-version.txt" 2>&1 || true
# Probe the agentapi runtime the sidecar drives; persist the liveness proof.
curl -fsS "${AGENTAPI_URL:-http://127.0.0.1:3284}/status" \
  > "$RUN_ROOT/agentapi-health.json" 2> "$RUN_ROOT/agentapi-health.err" \
  || printf '{"status":"unreachable"}\n' > "$RUN_ROOT/agentapi-health.json"
```
**Checkpoint:** `agentapi-health.json` exists and shows the runtime reachable (not `unreachable`) before
counting any fire as real.

### Phase 3: Capture one scheduled fire as evidence
Each time the sidecar fires, the tick runs scoped and drops a fresh timestamped evidence dir. (Driven by
the sidecar's `schedule` builtin; shown here as the per-fire command the sidecar invokes.)
```bash
FIRE_DIR="$RUN_ROOT/$(date -u +%Y%m%dT%H%M%SZ)-tick"
mkdir -p "$FIRE_DIR"
{
  printf 'cwd=%s\n' "$PWD"
  printf 'mode=sidecar\n'
  printf 'runtime=agentapi\n'
  printf 'scopes=%s\n' "${REPO:-$PWD}"
  printf 'cmd=%s\n' 'agentapi-driven tick: claim 1 ready bead, do it scoped, evidence to brain, DO NOT close'
} > "$FIRE_DIR/command.txt"

# The sidecar drives the tick through the agentapi runtime; capture its event stream.
agy -p "Claim one ready