Add cost-control deep-dive report

[Copilot]

Deep-dive report on cost-control possibilities for the harnesses Autoloop runs on (gh-aw + Copilot/Claude/Codex/Gemini engines): what levers exist today, what we use, and what to add to express $/token budgets per iteration / day / week / month and to default to cheaper models.

Changes

• docs/cost-control.md (new): the report itself.
  • §1 — where cost is incurred per iteration (inference dominates; program eval can dwarf the agent)
  • §2 — full catalogue of gh-aw cost levers per engine: engine.model, max-turns (claude), max-continuations (copilot), COPILOT_PROVIDER_MAX_* (BYOK), timeout-minutes, stop-after, concurrency, rate-limit, skip-if-match, safe-outputs.*.max, plus gh aw logs --json / gh aw audit for measurement
  • §3 — gap analysis vs. what workflows/autoloop.md uses today (only engine: copilot + timeout-minutes: 45)
  • §4 — proposed cost: frontmatter for program.md (per-iteration.max-{tokens,usd} + budget.{window,max-*,on-exceeded}), enforced scheduler-side by reading historical spend from gh aw logs --json. Covers per-iteration / per-program / repo-wide / per-account scopes, distinguishing hard vs soft caps
  • §5 — three cheaper-model strategies: (A) cheap default + opt-in frontier escalation, (B) per-phase routing, (C) quality-aware auto-downgrade driven by iteration history already in the state file
  • §6 — prioritized P0–P3 implementation plan (P0: add engine.model, concurrency, stop-after, and a per-program attribution key so gh aw logs can be grouped by program)
  • §7 — single-table summary of the proposed final surface
• AGENTS.md: link to the report from the Reference section.

Key finding

gh-aw exposes no portable per-run token-budget: knob — only Claude's max-turns and Copilot-BYOK's COPILOT_PROVIDER_MAX_*. Real $/week caps therefore have to be enforced by the Autoloop scheduler reading gh aw logs --json and refusing to schedule over-budget programs. The natural extension point is parse_program_frontmatter in workflows/scripts/autoloop_scheduler.py, which would benefit from being refactored from its current 5-tuple return into a dataclass before adding a cost_config field.

Documentation only; no behaviour change.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• github.github.com
  • Triggering command: /home/REDACTED/work/_temp/ghcca-node/node/bin/node /home/REDACTED/work/_temp/ghcca-node/node/bin/node --enable-source-maps /home/REDACTED/work/_temp/copilot-developer-action-main/dist/index.js (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)