---
name: gremlins
description: Trains one headless implementer (the base) per build and spawns gremlins from it, one per complex block, by forking the base's session (`claude -p --resume --fork-session`). Owns the command line, the prompt-cache bookkeeping and the usage ledger. Windows-tested; other platforms fail closed until tested (see Platforms). Loaded by the Athanor.
allowed-tools: Bash(uv:*)
---
!`uv run "${CLAUDE_SKILL_DIR}/gremlins.py" where`

# Gremlins

## What and when

The Athanor's build path for complex blocks. One **base** per build, trained early: a headless `claude -p` session that reads the code the build touches, writes the trunk notes and changes nothing. One **gremlin** per complex block: `spawn` (method `fork`) forks the base's session, so the gremlin starts from the base's reading at cache-read prices. Mechanical or distant blocks still go to fresh Agent-tool agents with the trunk notes.

Words: `continue` gives a finished gremlin one more turn (it resumes, it does not fork); `rebase` forks the base to absorb what changed, and that session becomes a new base; a **ping** is a one-turn keep-warm call the helper launches by itself.

The helper `gremlins.py` owns every `claude -p` command line, the registry, the cache bookkeeping and the usage ledger. You write briefs and read its JSON.

Claude Code only. Codex loads this skill too; it does not apply there.

## Platforms

Windows-tested; other platforms fail closed until tested. On Linux, WSL and macOS `where` reports `ok: false` with the reason, `init` refuses, and on an existing state dir `train`, `spawn`, `continue`, `rebase` and `tick` refuse too (exit 2, `error: "platform not supported"`). Then use fresh agents for every block (the 0.2.2 shape). Do not try to work around it.

## Setup

- The report injected above is `where`'s. `script` is the helper's absolute path: use it in every call, `uv run "<script>" <command> …`. `ok: false` → Platforms, or the `reason`. No report above (the injection failed) → treat it as `ok: false`.
- The project needs an allow rule `Bash(uv run:*)` (or `Bash(uv:*)`): this skill's `allowed-tools` did not pre-approve the calls in a subagent (P0.8, untrusted dir). Call plain `uv`; use `$SCRIPTS_UV` only on a host without `uv` on PATH.
- `init --run <run log .md> --model <full id>` once per run, with `--effort` and `--agent <project agent>` where the plan names them. A successor never re-runs `init` to "reset": it runs `list` and adopts the active base.
- An `init` re-run changes only the flags given, except that it re-resolves the claude binary through the source it came from, unless it was pinned with `--binary` (N3). Its `warnings` say when the binary changed or could not be re-resolved; existing bases keep their own binary.
- `--warm-margin-s` must stay below the TTL (at 1 h, at most 1800 takes effect).
- `--tools` does not re-derive the allow rules: pass `--allowed-tools` together with it.

## Commands

Every command except `where` takes `--run <run log .md>`. stdout is one JSON object (`usage --format md`: one markdown fragment); a refusal is `{"error": …, …}`. Exit codes: `0` ok; `2` usage error or refused; `3` `wait` condition not met at its timeout; `4` `wait` condition met and a job in it did not end `ok`.

| Command | Key flags | Returns |
|---|---|---|
| `where` | `[--binary B]` | `{script, python, uv, binary, git, scrub, platform, warnings, ok}` (+ `reason`, `error` and exit 2 when not ok) |
| `init` | `--model`, `--effort`, `--agent`, `--cwd`, `--binary`, `--tools`, `--allowed-tools`, `--parallel-cap` (2), `--orphan-after` (1200), `--pings on\|off`, `--warm-margin-s`, `--max-minutes` (90), rebase thresholds | `{ok, state, registry, created, changed, changed_fields, bases, config, warnings}` |
| `train` | `--base B --brief F [--phase N] [--block X] [--supersedes OLD]…` | `{job, base, session_id}` |
| `spawn` | `--base B --block X --brief F --phase N [--method fork] [--mode sequential\|parallel] [--paths P…] [--delta-note PATH]… [--max-minutes M] [--max-budget-usd U] [--force]` | `{job, base, method, base_state, warm_until, rebase_due, retrain_due, reasons}` |
| `continue` | `--job J --brief F [--max-minutes M]` (J is a `spawn` job) | `{job}` |
| `rebase` | `--base B --as NEW --brief F --phase N [--delta-note PATH]…` | `{job, base, parent, session_id}` (`base` is NEW) |
| `wait` | `--all` or job ids, `[--any] [--timeout S]` (default 540, max 570) | `{done[], running[], pings[]}` |
| `list` | — | `{state, bases[], jobs[], running[], lost_now[]}`; base rows carry warmth, `trained_at` and the due flags |
| `usage` | `[--block X \| --phase N] [--format json\|md]` | tokens and cost per kind, cold starts, cache-hit ratio, priced total |
| `expire` | `--base B \| --all` | `{retired, bases, killed[], ok}` |
| `kill` | `--job J` | `{job, killed, status, ok, snapshot, survivors, tree_kill_rc}` |
| `tick` | — | one keep-warm pass `{state, pinged, bases}` (`wait` and the supervisors already tick) |

A first phase, in calls (`G` = `uv run "<script>"`, `R` = `--run <run log .md>`; every `wait` with Bash `timeout: 600000`):

```
G init R --model claude-opus-5-5[1m] --effort high
G train R --base B1 --phase 1 --brief <train brief>      → G wait R --all (until exit 0 or 4)
G spawn R --base B1 --block 1.1 --phase 1 --brief <delta brief> --delta-note <notes>…
G wait R --all                                           → read notes/1.1.md and the result
G continue R --job <job> --brief <fix brief>             (only on a red gate, once)
G usage R --block 1.1 --format md                        → the block's run-log row
G usage R --phase 1 --format md;  G list R               → phase close; nothing running
```

Next phase: `G rebase R --base B1 --as B2 --phase 2 --brief <delta> --delta-note <notes since trained_at>…`, `wait`, then spawn from `B2`.

The helper treats `--phase` as optional; always pass it on `spawn` and `rebase` (it drives `phase_boundary` and `usage --phase`). `spawn`, `continue` and `rebase` refuse (exit 2) while `parallel_cap` jobs of those kinds run: `wait` first. `spawn` and `rebase` refuse a base that is not active; `spawn --force` overrides that.

## Waiting

- Launches return at once; the job runs under a detached supervisor.
- Call `wait` from Bash with `timeout: 600000`; never omit it. The Bash tool **backgrounds** a call that passes its timeout instead of killing it (P0.1), and you are left without its output.
- Loop `wait --all` until exit 0 or 4. Exit 3 means "call again", and `done` may already hold finished results, failed ones too (C4). Each result comes back in exactly one `done`: read `done` on every call, not only the last.
- Pings come back in `pings`, never in `done`, and never set the exit code; a ping cannot be waited on. A ping belongs to its base's latest phase and is counted in that phase's `usage`.
- `running[]` rows (`job, block, elapsed_s, last_event_s_ago, messages`) count `messages` (stream messages so far); results and the ledger count `turns` (M16). They are different numbers.
- A failed detach of the supervisor (`detach_failed`) shows up as a failed result in the next `wait`, not in the launch return.

## Results

Each `done` entry (also `results/<job>.json`): `job, kind, method, base, block, phase, status, flags, fingerprint, session, parent_session, models_used, tokens{input, output, cache_creation, cache_creation_1h, cache_creation_5m, cache_read}, cost_delta_usd, cache, base_state, wall_s, turns, denials, note, raw, paths, reason, model_requested`.

- `kind` `train|spawn|continue|rebase|ping`; `method` is `"fork"` on a spawn, `null` on every other kind.
- `status` `ok|failed|timeout|killed|lost`. `reason`: for `failed` one of `model_refused, usage_limit, overloaded, prompt_too_long, api_error, is_error, exit_code, no_result, detach_failed, launch_error, supervisor_error`; for `killed` one of `kill, expire, orphaned`; for `lost` `supervisor_dead`; `null` otherwise, also for `timeout` (over `--max-minutes`).
- `flags`: `stalled, needs_attention` (permission denials: the allow rules may be short), `usage_mismatch, ttl_downgrade, cold_start, clock_jump, ping_missed, orphaned, expired, parent_inactive`.
- `cache` `hit|partial|miss`, from the first request against the base's context; `base_state` at launch `warm|expiring|cold`; `fingerprint` `ok` or `drift:<fields>`. A cold base usually shows `partial`, because the shared system prefix stays warm (C5).
- `note` is `notes/<block>.md` when the gremlin wrote it during this job, else `null`. `paths` echoes `--paths`.

What to do per failure reason:

- `model_refused` → the model id is not admitted (`availableModels`); the user must change settings. Flag it, hand back.
- `usage_limit` → plan usage is used up. Stop launching, flag it, hand back.
- `overloaded`, `api_error` → transient. `continue` once later, else flag it.
- `prompt_too_long` → the base is too large. Re-train or rebase smaller.
- `is_error`, `exit_code`, `no_result` → read `raw/<job>.err` and the note, `continue` once, else flag it.
- `detach_failed`, `launch_error`, `supervisor_error` → a helper or host problem (`raw/<job>.sup.log`). Flag it; do not retry blindly.
- Status `timeout` → read the note, `continue` once with what is left, else flag it. Status `lost` (the supervisor died) → flag it.

`continue` takes spawn jobs only. A failed `train` is trained again (a failed base's name is free); a failed `rebase` leaves the old base active.

`stalled` means no stream output for `stall_after_s` (900 s); the helper reports it and does nothing. Together with `clock_jump` it is a host suspend, not a hung gremlin. While a job runs, the same shows as a large `last_event_s_ago`: `wait` again before acting; still quiet after that → `kill` and flag it.

## Rules (flags, not judgment)

- `rebase_due` (reasons `phase_boundary`, `commits:N`, `lines:N`, `delta_tokens:N`, `binary_drift`, `runtime_drift:…`) → `rebase --as <new> --phase <n>` before the next spawn. **Always pass `--phase`.** `rebase` counts toward `parallel_cap`.
- `retrain_due` (`defining:…`, `max_base_tokens:N`, `rebases:N`, `binary_missing`) → `train` a new base with `--supersedes <old>`, else the old base keeps getting pings. `binary_missing` → launches refuse; train with the new binary (`train --binary`, or re-run `init --binary` first). A cold base is still spawnable; coldness never triggers a re-train.
- Delta: attach handoff notes with `spawn --delta-note PATH` (repeatable). A `## Changes since base` section in a brief holds this gremlin's delta only, and no line in it may start with `#`, also not inside fenced code: such a line ends the section (N1). When rebasing, attach every note written since the base's `trained_at` (shown by `list`): a note older than that counts as known to the base whether or not it was given to it (N2).
- `continue` sends the brief without a frame: put the commit rule and the note path into it (M16).
- Sequential gremlins run one at a time (Minor 13). Parallel only for disjoint blocks, with `--mode parallel --paths …`; parallel gremlins never commit, and the Athanor commits each block by the paths its note lists, one at a time.
- Nothing running at hand-back: `list` shows no running job other than pings (kind `ping`; a ping ends within 300 s and is not a leak, Minor 7). Otherwise `kill` it and flag it.
- `kill` and `expire` run long (each kill verifies for up to 10 s; `expire` kills its jobs one after another): call them from Bash with `timeout: 600000`, as `wait`.
- `kill`: key on `ok` and `status`, not on `killed` or the exit code (M12). `killed: true, status: ok` means the job finished first; `ok: false` lists `survivors` (exit still 0): flag it.
- Orphan watchdog (N1): a running job is killed (`orphaned`) after `orphan_after` (default 1200 s) without an orchestrator call (`wait`, `spawn`, `continue`, `train`, `rebase`, `list`, `usage`). `kill` and `expire` do not count (Phase 1 M3), and a gremlin's own calls never do. Keep looping `wait` while gremlins run.
- Inside a gremlin `SPIRE_GREMLIN_CHILD=1` is set, and `train`, `spawn`, `continue`, `rebase`, `kill`, `expire`, `init` and `tick` refuse (N3); `where`, `list`, `usage` and `wait` work.
- Models: full ids only; `spawn` takes the base's model (no `--model`). Admission is permissive at `init` and enforced at runtime (M15): a substituted model ends `failed`/`model_refused`.
- After `claude` exits, its leftover descendants are killed, including daemons a commit may have started (`gpg-agent`, `git fsmonitor--daemon`); they restart on demand (M16).
- A re-train that supersedes a base while a rebase of it runs: the rebase's new base arrives superseded, and its result carries `parent_inactive` (N4). Re-train first, or let the rebase finish.
- Never resume or fork a headless session by hand; never call `claude -p` yourself; never `SendMessage` or `TaskStop` a gremlin (`continue` and `kill` cover it).

## State

`<run log without .md>-gremlins/`, next to the run log: `registry.json`, `ledger.jsonl`, `jobs/`, `briefs/`, `notes/`, `results/`, `logs/`, `raw/`. Its `.gitignore` keeps out `raw/` and lock files; everything else is committed with the run log at phase close. The Athanor reads `notes/`, `results/` and `logs/`; `raw/<job>.err` and `raw/<job>.sup.log` only when a job failed.