@caddis/cli 0.4.91 → 0.4.92

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (32) hide show
  1. package/bundles/antigravity-plugin/plugin.json +1 -1
  2. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_exit.cpython-311.pyc +0 -0
  3. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_file_lock.cpython-311.pyc +0 -0
  4. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_frontmatter.cpython-311.pyc +0 -0
  5. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_redact.cpython-311.pyc +0 -0
  6. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_roadmap.cpython-311.pyc +0 -0
  7. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_rows.cpython-311.pyc +0 -0
  8. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_status.cpython-311.pyc +0 -0
  9. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_tidy.cpython-311.pyc +0 -0
  10. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_todo.cpython-311.pyc +0 -0
  11. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_workstreams.cpython-311.pyc +0 -0
  12. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_worktree_safety.cpython-311.pyc +0 -0
  13. package/bundles/antigravity-plugin/scripts/caddis_gate.py +8 -8
  14. package/bundles/antigravity-plugin/scripts/caddis_guide.json +2 -2
  15. package/bundles/antigravity-plugin/scripts/caddis_lanes.py +17 -17
  16. package/bundles/antigravity-plugin/scripts/caddis_review.py +1 -1
  17. package/bundles/antigravity-plugin/scripts/caddis_roadmap_run.py +16 -36
  18. package/bundles/antigravity-plugin/scripts/caddis_routing.py +1 -1
  19. package/bundles/antigravity-plugin/scripts/caddis_spend.py +121 -138
  20. package/bundles/antigravity-plugin/scripts/oss_review.py +15 -13
  21. package/bundles/antigravity-plugin/scripts/roadmap-recheck.ps1 +4 -2
  22. package/bundles/antigravity-plugin/scripts/schemas/hub-collect.schema.json +6 -0
  23. package/bundles/antigravity-plugin/scripts/schemas/hub-spend.schema.json +6 -0
  24. package/bundles/antigravity-plugin/skills/cross-review/SKILL.md +1 -1
  25. package/bundles/antigravity-plugin/skills/feature-plan/SKILL.md +1 -1
  26. package/bundles/antigravity-plugin/skills/implement/SKILL.md +7 -6
  27. package/bundles/antigravity-plugin/skills/roadmap/SKILL.md +6 -6
  28. package/bundles/antigravity-plugin/skills/roadmap/assets/plan-resume-prompt.md +2 -2
  29. package/bundles/codex/.codex/skills/workflow/roadmap/SKILL.md +6 -6
  30. package/bundles/codex/.codex/skills/workflow/roadmap/assets/plan-resume-prompt.md +2 -2
  31. package/bundles/manifest.json +2 -2
  32. package/package.json +1 -1
@@ -1,5 +1,5 @@
1
1
  {
2
2
  "name": "caddis",
3
- "version": "1.3.175",
3
+ "version": "1.3.176",
4
4
  "description": "caddis — agent-agnostic dev harness as an Antigravity (agy) plugin: TDD skills + commands, single-sourced with the Claude Code plugin."
5
5
  }
@@ -90,7 +90,7 @@ def launch_command(block: str) -> str:
90
90
  """The literal command for a non-claude lane, if the phase names one.
91
91
 
92
92
  Also matches a caddis_lanes.py run command, a direct codex/agy command, and an agy command
93
- wrapped in the spend cap (`python .../caddis_spend.py run --caller X -- agy ...`).
93
+ wrapped in the spend wrapper (`python .../caddis_spend.py run --caller X -- agy ...`).
94
94
  """
95
95
  m = re.search(
96
96
  r'`((?:claude-(?:glm|oss|deepseek)\b|' + _LANES_RUN + r'\b|' + _SPEND_RUN
@@ -101,13 +101,13 @@ def launch_command(block: str) -> str:
101
101
 
102
102
 
103
103
  _LANES_RUN = r'python\s+"?\$\{CLAUDE_PLUGIN_ROOT\}/scripts/caddis_lanes\.py"?\s+run'
104
- # Every agy lane goes through the global spend cap (caddis-next Phase 4). Any path that ends in
104
+ # Every agy lane goes through `caddis_spend.py run` (usage log, timeout, depth guard; no EUR cap). Any path that ends in
105
105
  # scripts/caddis_spend.py: `${CLAUDE_PLUGIN_ROOT}/...`, an expanded plugin-cache path (the codex bundle
106
106
  # rewrites the variable), or the bare repo-relative `scripts/caddis_spend.py` - which gate_lane accepts
107
107
  # only in the caddis source repo, because in an app repo that path is a file the agent can write.
108
108
  _SPEND_RUN = r'python3?\s+"?[^"\s`]*scripts/caddis_spend\.py"?\s+run'
109
109
  _SPEND_PATH = re.compile(r'python3?\s+"?([^"\s`]*scripts/caddis_spend\.py)"?\s+run')
110
- # Shell control characters outside the quoted prompt would chain a second, uncapped command.
110
+ # Shell control characters outside the quoted prompt would chain a second, unwrapped command.
111
111
  _SHELL_CHAIN = re.compile(r"[;&|`\n]|\$\(")
112
112
 
113
113
 
@@ -155,7 +155,7 @@ def gate_lane(plan: Path, phase: int) -> int:
155
155
  return EXIT_MALFORMED
156
156
  if re.match(r"agy\b", cmd):
157
157
  sys.stderr.write(
158
- f"[caddis-gate] phase {phase}'s agy command is not wrapped in the spend cap: {cmd}\n"
158
+ f"[caddis-gate] phase {phase}'s agy command is not wrapped in caddis_spend.py run: {cmd}\n"
159
159
  " agy lanes must go through caddis_spend.py run --caller <name> -- agy ... Refusing to run it.\n")
160
160
  return EXIT_MALFORMED
161
161
  inner = cmd
@@ -163,7 +163,7 @@ def gate_lane(plan: Path, phase: int) -> int:
163
163
  wrapped = re.match(_SPEND_RUN + r'\s+--caller\s+\S+\s+--\s+(agy\b.*)$', cmd, re.S)
164
164
  if not wrapped:
165
165
  sys.stderr.write(
166
- f"[caddis-gate] phase {phase}'s spend-cap command is malformed: {cmd}\n"
166
+ f"[caddis-gate] phase {phase}'s caddis_spend command is malformed: {cmd}\n"
167
167
  " Expected: caddis_spend.py run --caller <name> -- agy ... Refusing to run it.\n")
168
168
  return EXIT_MALFORMED
169
169
  inner = wrapped.group(1)
@@ -173,13 +173,13 @@ def gate_lane(plan: Path, phase: int) -> int:
173
173
  or "${" in inner):
174
174
  sys.stderr.write(
175
175
  f"[caddis-gate] phase {phase}'s agy command chains another command: {cmd}\n"
176
- " A second command after the wrapped agy would run outside the spend cap. Refusing to run it.\n")
176
+ " A second command after the wrapped agy would run outside caddis_spend.py run. Refusing to run it.\n")
177
177
  return EXIT_MALFORMED
178
178
  formats = re.findall(r"--output-format(?:\s+|=)(\S+)", _QUOTED.sub('""', inner))
179
179
  if formats != ["json"]:
180
180
  sys.stderr.write(
181
181
  f"[caddis-gate] phase {phase}'s agy command must have exactly one --output-format json: {cmd}\n"
182
- " Without JSON output the spend cap cannot read the token counts. Refusing to run it.\n")
182
+ " Without JSON output the usage log cannot read the token counts. Refusing to run it.\n")
183
183
  return EXIT_MALFORMED
184
184
  path = _SPEND_PATH.match(cmd).group(1)
185
185
  norm = path.replace("\\", "/")
@@ -608,7 +608,7 @@ _STEERING_FILENAMES = {"conftest.py", "pytest.ini", "pyproject.toml", "setup.cfg
608
608
  def is_review_steering_file(path: str) -> bool:
609
609
  """True for config that steers reviews, merges or tests: never tier 0, and never a 0-reviewer "1-small".
610
610
 
611
- `.caddis/*.toml` (review/implement routing, merge-chain checks, spend cap), any `conftest.py`, the pytest and
611
+ `.caddis/*.toml` (review/implement routing, merge-chain checks), any `conftest.py`, the pytest and
612
612
  packaging config, and `.github/workflows/**`. A fix diff that changes these can turn a gate off, so it is reviewed.
613
613
  """
614
614
  norm = path.replace("\\", "/").lower().removeprefix("./")
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "schema": 1,
3
- "version": "1.3.174",
4
- "generated": "2026-11-01 00:26 UTC",
3
+ "version": "1.3.175",
4
+ "generated": "2026-11-01 21:34 UTC",
5
5
  "commands": [
6
6
  {
7
7
  "name": "add-rules",
@@ -127,9 +127,8 @@ BUDGET_PATTERNS: dict[str, tuple[str, ...]] = {
127
127
  r"Quota exceeded\. Check your plan",
128
128
  r"workspace is out of credits",
129
129
  ),
130
- # caddis_spend refusing over the global EUR cap: the chain moves on, like a provider quota.
131
- "agy": (r"RESOURCE_EXHAUSTED.*quota", r"Individual quota reached", r"(?m)^caddis_spend: over cap",
132
- r"(?m)^caddis_spend: could not lock"),
130
+ # caddis_spend could not lock its usage log (another launch holds it): the chain moves on, like a provider quota.
131
+ "agy": (r"RESOURCE_EXHAUSTED.*quota", r"Individual quota reached", r"(?m)^caddis_spend: could not lock"),
133
132
  }
134
133
  CONFIG_PATTERNS: dict[str, tuple[str, ...]] = {
135
134
  "claude": (),
@@ -147,8 +146,7 @@ CONFIG_PATTERNS: dict[str, tuple[str, ...]] = {
147
146
  r"Model metadata for .* not found",
148
147
  ),
149
148
  "agy": (r"invalid model selection", r"is not recognized as a known model",
150
- r"(?m)^caddis_spend: spend cap not configured",
151
- r"(?m)^caddis_spend: could not check the spend cap"),
149
+ r"(?m)^caddis_spend: could not write the spend log"),
152
150
  }
153
151
  LOAD_WORDING = (
154
152
  r"(?i)\bcpu\s+burner",
@@ -613,7 +611,7 @@ def _windows_process_names(pids: list[int]) -> dict[int, str]:
613
611
 
614
612
 
615
613
  def _refused_run(returncode: int, message: str) -> LaneRun:
616
- """A lane that never started: the spend cap refused it. pid 0, no time spent."""
614
+ """A lane that never started: the spend log could not be locked or written. pid 0, no time spent."""
617
615
  return LaneRun(returncode=returncode, output=message + "\n", timed_out=False, duration_s=0.0,
618
616
  pid=0, started=time.time())
619
617
 
@@ -631,23 +629,18 @@ def run_lane(
631
629
  probe=default_probe,
632
630
  spend_caller: str = "lane",
633
631
  ) -> LaneRun:
634
- # Every agy launch is booked against the global spend cap first (caddis_spend). ci_watch reaches
635
- # agy through here too, so each call is booked exactly once. Any spend problem refuses the lane
636
- # (fail closed) and never crashes the unattended chain.
632
+ # Every agy launch is written to the usage log first (caddis_spend; there is no cap). ci_watch reaches
633
+ # agy through here too, so each call is logged exactly once. A log that cannot be locked or written
634
+ # refuses the lane (the spend would go unseen) and never crashes the unattended chain.
637
635
  spend_id = None
638
636
  if Path(argv[0]).stem.lower() == "agy":
639
637
  spend_home = Path.home()
640
638
  try:
641
639
  spend_id = caddis_spend.reserve(spend_home, spend_caller, datetime.now(timezone.utc))
642
- except caddis_spend.NotConfigured:
643
- return _refused_run(3, caddis_spend.NOT_CONFIGURED_MESSAGE)
644
640
  except TimeoutError as exc:
645
641
  return _refused_run(3, str(exc))
646
- except Exception as exc: # an unreadable log or file error: refuse, never crash
647
- return _refused_run(3, f"caddis_spend: could not check the spend cap: {exc!r}")
648
- if spend_id is None:
649
- return _refused_run(1, "caddis_spend: over cap: agy refused ("
650
- + caddis_spend.status_line(spend_home, datetime.now(timezone.utc)) + ")")
642
+ except Exception as exc: # a file error on the log: refuse, never crash
643
+ return _refused_run(3, f"caddis_spend: could not write the spend log: {exc!r}")
651
644
  argv = caddis_spend.hidden_argv(argv, env) # agy's tool consoles open on a hidden desktop, not on screen
652
645
  job_name = f"Local\\caddis-governor-{os.getpid()}-{secrets.token_hex(8)}" if sys.platform == "win32" else None
653
646
  full = governed_argv(argv, job_name)
@@ -781,8 +774,15 @@ def run_lane(
781
774
  try:
782
775
  caddis_spend.settle(spend_home, spend_id, counts, datetime.now(timezone.utc),
783
776
  duration_s=clock() - monotonic_started)
784
- except Exception as exc: # the pending reserve keeps counting; never lose the lane's result
777
+ except Exception as exc: # the pending line stays unsettled; never lose the lane's result
785
778
  output += f"\ncaddis_spend: could not settle {spend_id}: {exc!r}\n"
779
+ try: # advice only: at or above the advise level the lane's output says so; nothing is refused
780
+ committed = caddis_spend.committed_last_24h(spend_home, datetime.now(timezone.utc))
781
+ level = caddis_spend.advise_eur()
782
+ if committed >= level:
783
+ output += "\n" + caddis_spend.advisory_line(committed, level) + "\n"
784
+ except Exception:
785
+ pass
786
786
  return LaneRun(
787
787
  returncode=proc.returncode,
788
788
  output=output,
@@ -685,7 +685,7 @@ def launch_claude(prompt: str, worktree: Path, out: Path) -> str:
685
685
  # No `--allowedTools`: unscoped, it approves files outside the worktree (smoke run 18 Oct 2026: without it a
686
686
  # Read in the worktree ran, a Read of ~/.caddis/spend-cap.toml was refused).
687
687
  try:
688
- import caddis_spend # the recursion guard lives beside the spend cap (robustness #19)
688
+ import caddis_spend # the recursion guard lives beside the agy usage log (robustness #19)
689
689
  env_depth = caddis_spend.bump_headless_depth(os.environ)
690
690
  except ImportError:
691
691
  env_depth = None
@@ -4,8 +4,8 @@ the next batches of a roadmap.
4
4
  Design: programme-method-design.md sections 8.1 to 8.5 and 9.2; caddis-next Phases 7 and 9. `roadmap-run.ps1` is a
5
5
  thin shim over this file. The programme layer (programme folders, ledger, budget block) is gone (caddis-next Phase 7).
6
6
 
7
- One session: stop checks (STOP file, session, hour and dollar caps); for agy, a reservation under the global spend cap
8
- (`caddis_spend.py`, settled after the session); read the relay hash; launch ONE session through the governor with the
7
+ One session: stop checks (STOP file, session, hour and dollar caps); for agy, a pending line in the usage log
8
+ (`caddis_spend.py`, settled after the session; there is no EUR cap, only an ADVISORY line); read the relay hash; launch ONE session through the governor with the
9
9
  resume prompt and `CADDIS_HEADLESS=1` in its environment; parse its JSON result (cost, error); read the relay status
10
10
  line; decide. A relay the session did not change (same hash as before it, any status line) is `FAILED no relay
11
11
  written`, so a status an earlier session wrote is never acted on again; three sessions in a row with no newly closed
@@ -101,10 +101,10 @@ Session output, relay text and every log line, printed stop line, toast and push
101
101
  The runner never passes an owner gate, never raises a cap and never deletes a STOP file.
102
102
 
103
103
  Exit codes: 0 stopped at a status the session wrote (plan mode: OWNER-GATE, BLOCKED), or at a STOP file after a
104
- session; 1 a FAILED stop, a cap, the agy spend cap, a usage limit, `BLOCKED stuck`, `BLOCKED nothing ready`,
104
+ session; 1 a FAILED stop, a cap, an agy spend log error, a usage limit, `BLOCKED stuck`, `BLOCKED nothing ready`,
105
105
  `BLOCKED waiting for merge`, `BLOCKED review`, `BLOCKED review not run`, `BLOCKED rollup not run` (a rollup exit 3,
106
106
  for example an exit check that cannot run in the merged checkout; not restartable by the recheck task), or the
107
- snapshot guard; 3 never started (lock, STOP file, no governor, agy spend cap not configured, another host, a plan a roadmap runner holds); 4 bad input (no plan or roadmap, both, a bad slug, no prompt template,
107
+ snapshot guard; 3 never started (lock, STOP file, no governor, another host, a plan a roadmap runner holds); 4 bad input (no plan or roadmap, both, a bad slug, no prompt template,
108
108
  bad engine).
109
109
 
110
110
  Engines: `claude` is built and live-tested. `agy` and `codex` are command-line adapters with unit tests only (not
@@ -912,7 +912,7 @@ def _one_session(ctx: _Ctx, prompt: str, relay_slug: str, n: int, spent: float,
912
912
  usd = min(caps.max_usd_per_session, caps.max_usd_total - spent)
913
913
  cmd = build_command(ctx.engine, ctx.model, prompt, usd=usd, timeout_min=remaining_s / 60, governor=ctx.governor,
914
914
  engine_cmd=ctx.engine_cmd, worktree=cwd)
915
- rid = _spend_reserve(ctx.home, spend_slug, ctx.now(), n > 1) if ctx.engine == "agy" else None
915
+ rid = _spend_reserve(ctx.home, spend_slug, ctx.now()) if ctx.engine == "agy" else None
916
916
  if ctx.engine == "agy": # agy's tool consoles open on a hidden desktop, not on the owner's screen
917
917
  g = len(ctx.governor)
918
918
  cmd = [*cmd[:g], *caddis_spend.hidden_argv(cmd[g:], session_env())]
@@ -1318,8 +1318,6 @@ def _run_plan(ctx: _Ctx, template: Path, dry_run: bool, after_session: Callable[
1318
1318
  raise held
1319
1319
  _dry_lock_check(lock.path)
1320
1320
  ctx.checks(0, 0.0, 0.0)
1321
- if ctx.engine == "agy":
1322
- _spend_preview(ctx.home, ctx.now())
1323
1321
  except _Stop as stop:
1324
1322
  print(f"would stop: {caddis_redact.redact(stop.reason, masks)}")
1325
1323
  return caddis_exit.NOT_RUN
@@ -1855,8 +1853,6 @@ def _run_roadmap(ctx: _Ctx, template: Path, dry_run: bool, after_session: Callab
1855
1853
  try:
1856
1854
  _dry_lock_check(lock.path)
1857
1855
  ctx.checks(0, 0.0, 0.0)
1858
- if ctx.engine == "agy":
1859
- _spend_preview(ctx.home, ctx.now())
1860
1856
  try:
1861
1857
  batch, snap = caddis_roadmap.next_with_snapshot(repo, slug)
1862
1858
  except caddis_roadmap.RoadmapError as exc:
@@ -2332,28 +2328,25 @@ def _publish_and_wait(ctx: _Ctx, repo: Path, slug: str, mid: str, plan: str, pha
2332
2328
  raise _Stop(f"{WAITING_PREFIX} {ref} {url}", caddis_exit.BLOCKED)
2333
2329
 
2334
2330
 
2335
- def _spend_reserve(home: Path, slug: str, moment: datetime, started: bool) -> str:
2336
- """Book one agy session under the global spend cap (caddis_spend.py); _Stop when the cap refuses it or cannot be
2337
- read (a file error never crashes the runner: the stop is logged and notified, redacted, like any other).
2338
- The caller name in the spend log is `runner-<slug>`."""
2331
+ def _spend_reserve(home: Path, slug: str, moment: datetime) -> str:
2332
+ """Write the pending line of one agy session to the usage log (caddis_spend.py; there is no cap). _Stop only when
2333
+ the log cannot be locked or written (a file error never crashes the runner: the stop is logged and notified,
2334
+ redacted, like any other). The caller name in the spend log is `runner-<slug>`. At or above the advise level it
2335
+ prints the ADVISORY line and goes on."""
2339
2336
  try:
2340
2337
  rid = caddis_spend.reserve(home, f"runner-{slug}", moment)
2341
- except caddis_spend.NotConfigured:
2342
- code = caddis_exit.BLOCKED if started else caddis_exit.NOT_RUN
2343
- raise _Stop("FAILED spend cap not configured", code) from None
2344
2338
  except TimeoutError:
2345
- raise _Stop("BLOCKED spend cap lock busy", caddis_exit.BLOCKED) from None
2339
+ raise _Stop("BLOCKED spend log lock busy", caddis_exit.BLOCKED) from None
2346
2340
  except Exception as exc:
2347
- raise _Stop(f"FAILED spend cap error: {exc!r}", caddis_exit.BLOCKED) from None
2348
- if rid is None:
2349
- raise _Stop("BLOCKED spend cap", caddis_exit.BLOCKED)
2341
+ raise _Stop(f"FAILED spend log error: {exc!r}", caddis_exit.BLOCKED) from None
2342
+ caddis_spend.advise(home, moment)
2350
2343
  return rid
2351
2344
 
2352
2345
 
2353
2346
  def _spend_settle(home: Path, rid: str, cmd: Sequence[str], outcome: "_Outcome | None", moment: datetime,
2354
2347
  duration_s: float) -> None:
2355
- """Record the session's real cost: (0, 0) when it never started, its reserve (estimated) when there is no outcome
2356
- (an exception) or no readable token counts."""
2348
+ """Record the session's real cost: (0, 0) when it never started, estimated when there is no outcome (an
2349
+ exception) or no readable token counts."""
2357
2350
  try:
2358
2351
  if outcome is None:
2359
2352
  usage_counts = None
@@ -2364,23 +2357,10 @@ def _spend_settle(home: Path, rid: str, cmd: Sequence[str], outcome: "_Outcome |
2364
2357
  else:
2365
2358
  usage_counts = None
2366
2359
  caddis_spend.settle(home, rid, usage_counts, moment, duration_s=duration_s)
2367
- except Exception as exc: # the pending reserve keeps counting for 24 h; never lose the session's result
2360
+ except Exception as exc: # the pending line stays unsettled; never lose the session's result
2368
2361
  print(f"caddis_roadmap_run: could not settle spend {rid}: {exc}", file=sys.stderr)
2369
2362
 
2370
2363
 
2371
- def _spend_preview(home: Path, moment: datetime) -> None:
2372
- """The dry run's read-only spend check: the same stops as _spend_reserve, with no pending line written."""
2373
- try:
2374
- cap = caddis_spend.load_cap(home)
2375
- over = caddis_spend.committed_last_24h(home, moment) + cap.reserve > cap.eur_per_24h
2376
- except caddis_spend.NotConfigured:
2377
- raise _Stop("FAILED spend cap not configured", caddis_exit.NOT_RUN) from None
2378
- except Exception as exc:
2379
- raise _Stop(f"FAILED spend cap error: {exc!r}", caddis_exit.NOT_RUN) from None
2380
- if over:
2381
- raise _Stop("BLOCKED spend cap", caddis_exit.BLOCKED)
2382
-
2383
-
2384
2364
  @dataclass
2385
2365
  class _Outcome:
2386
2366
  code: int
@@ -22,7 +22,7 @@ DEFAULT_ROUTING: dict[str, list[str]] = {
22
22
  "critical": ["opus"],
23
23
  "light": ["sonnet"],
24
24
  "coding": ["agy"],
25
- "review": ["deepseek", "glm"], # owner order 2026-10-16; an agy review runs through caddis_spend.py
25
+ "review": ["deepseek", "glm"], # owner order 2026-10-16; an agy review runs through caddis_spend.py run (no cap)
26
26
  "consult": ["agy", "glm"],
27
27
  "ci-watch": ["agy"],
28
28
  "mechanical": ["haiku"],
@@ -1,47 +1,39 @@
1
1
  #!/usr/bin/env python3
2
- """caddis_spend - one global spend cap for agy, in EUR per rolling 24 hours, on this machine.
2
+ """caddis_spend - the agy usage log and the `run` wrapper for every agy launch caddis makes.
3
3
 
4
- Why: on 7 Oct 2026 two unsupervised overnight agy runs cost EUR 793 in one billing day. Nothing in
5
- caddis capped money (caddis_governor caps CPU and memory only). Every agy launch that caddis makes
6
- through a lane (`caddis_lanes.run_lane`, which ci-watch also uses) or a plan Lane line
7
- (`caddis_spend.py run -- agy ...`) goes through `reserve()` before it starts and `settle()` after it ends.
8
- The roadmap/plan runner (`caddis_roadmap_run.py --engine agy`) reserves before each agy session and settles after it.
4
+ History: on 7 Oct 2026 two unattended overnight agy runs cost EUR 793 in one billing day. caddis then
5
+ had a spend cap here (EUR per rolling 24 h). The owner removed the cap on 1 Nov 2026. The usage log stays,
6
+ so agy spend stays visible, and the owner's rule "cost-heavy runs need approval first" stays as text.
7
+ Nothing in this file refuses an agy launch because of money. Instead, at or above an advise level (EUR 300
8
+ committed in 24 h, or CADDIS_SPEND_ADVISE_EUR), `run` prints one `caddis_spend: ADVISORY:` line to stderr before
9
+ the launch and after the settle, and `status` / `check` add ` - ADVISORY (>= EUR <level>)`. Exit codes do not
10
+ change. The committed EUR comes from the prices below, so with no prices it stays 0 and no advisory shows.
9
11
 
10
- Config `~/.caddis/spend-cap.toml` (the owner writes it; caddis never does):
12
+ Every agy launch that caddis makes through a lane (`caddis_lanes.run_lane`, which ci-watch also uses), a
13
+ plan Lane line (`caddis_spend.py run -- agy ...`) or the roadmap/plan runner (`caddis_roadmap_run.py
14
+ --engine agy`) calls `reserve()` before it starts and `settle()` after it ends.
11
15
 
12
- [agy]
13
- eur_per_24h = 200
14
- reserve_eur_per_call = 10 # what a call still running, or killed, is assumed to cost
15
- eur_per_million_input_tokens = 0 # from Google Cloud billing; 0 = unset
16
- eur_per_million_output_tokens = 0
16
+ Log `~/.caddis/spend/agy.jsonl`, append-only. A `pending` line is written under a file lock before the
17
+ launch and a `settled` line with the same id after it. A settled line holds the token counts and an EUR
18
+ estimate. A pending line with no settled line (a crash) counts its `reserve_eur` (now 0) for 24 h.
17
19
 
18
- Every value must be a finite number above 0. Anything else means NOT CONFIGURED, and every agy launch is
19
- refused (fail closed).
20
+ Prices (optional): when `~/.caddis/spend-cap.toml` has an `[agy]` table with
21
+ `eur_per_million_input_tokens` and `eur_per_million_output_tokens` (finite numbers above 0), a settled
22
+ line records EUR from the token counts. Every other key in that file (an old `eur_per_24h`, a reserve) is
23
+ ignored, and with no valid prices EUR is recorded as 0 with `estimated: true`. caddis never writes the file.
20
24
 
21
- Log `~/.caddis/spend/agy.jsonl`, append-only. A `pending` line is written under a file lock before the
22
- launch and a `settled` line with the same id after it. A pending line with no valid settled line keeps
23
- counting its reserve for 24 h, so a killed or crashed call is never free, and two callers cannot both
24
- pass the check with the last EUR of the cap.
25
-
26
- Limits (by design, see .caddis/plans/caddis-next.md Phase 4):
27
- - The cap is per machine. The only cap across machines is a Google Cloud budget alert.
28
- - agy started by hand, or by a script outside caddis, is not covered.
29
- - The cap file and the log are plain files of this user: any process of this user, including an agy
30
- session started with --dangerously-skip-permissions, can edit them. The cap stops accidents and
31
- runaway loops; it is not a security boundary against a hostile local process.
32
- - The check runs at launch. A long call can cost more than its reserve before it is settled; an
33
- estimated settle records its duration so the overshoot is visible.
25
+ Limits:
26
+ - The log is per machine. agy started by hand, or by a script outside caddis, is not logged.
34
27
  - EUR is an estimate from token counts and the owner's prices, not the real bill.
35
28
 
36
29
  CLI:
37
- python caddis_spend.py check exit 0 allowed, 1 over cap, 3 not configured
38
- python caddis_spend.py status prints the committed spend of the last 24 h
30
+ python caddis_spend.py check always exit 0; prints the status line
31
+ python caddis_spend.py status [--json] prints the logged spend of the last 24 h
39
32
  python caddis_spend.py run --caller X -- agy ...
40
- reserve, run, settle. Returns agy's own exit code, or 75 over the cap / could not lock,
41
- or 78 not configured, or 124 when the command ran past its time limit (--timeout-s, else
42
- CADDIS_SPEND_RUN_TIMEOUT_S, else 3600 s) and its process tree was killed. 75 and 78 are never
43
- agy's own codes for a refusal, so a caller can tell "the cap refused" from "agy failed". Each
44
- refusal also prints a `caddis_spend:` line.
33
+ log, run, settle. Returns agy's own exit code, or 75 when the headless depth is at its limit or the
34
+ log could not be locked or written, or 124 when the command ran past its time limit (--timeout-s,
35
+ else CADDIS_SPEND_RUN_TIMEOUT_S, else 3600 s) and its process tree was killed. Each refusal also
36
+ prints a `caddis_spend:` line.
45
37
  On Windows the command runs on a hidden desktop (caddis_hidden_desktop.py), so the console windows agy opens
46
38
  for its tools never show; CADDIS_AGY_VISIBLE=1 runs it on the normal desktop.
47
39
  """
@@ -58,30 +50,43 @@ import sys
58
50
  import time
59
51
  import uuid
60
52
  from contextlib import contextmanager
61
- from dataclasses import dataclass
62
53
  from datetime import datetime, timedelta, timezone
63
54
  from pathlib import Path
64
55
 
65
56
  EXIT_OK = 0
66
- EXIT_OVER_CAP = 1 # `check` only
67
- EXIT_NOT_CONFIGURED = 3 # `check` only
68
- RUN_REFUSED = 75 # `run`: over the cap, or could not lock (EX_TEMPFAIL)
69
- RUN_NOT_CONFIGURED = 78 # `run`: not configured (EX_CONFIG)
57
+ EXIT_LOG_ERROR = 1 # `status` only: the log could not be read
58
+ RUN_REFUSED = 75 # `run`: headless depth at its limit, or the log could not be locked or written (EX_TEMPFAIL)
70
59
  RUN_TIMEOUT = 124 # `run`: the child ran past its time limit and its process tree was killed (as timeout(1))
71
60
  DEFAULT_RUN_TIMEOUT_S = 3600.0 # one hour: a run over about 1 hour needs the owner's approval anyway
72
61
  # No console window for the child on Windows (robustness #19; see no_window.py: never DETACHED_PROCESS).
73
62
  _NO_WINDOW_KW = {"creationflags": 0x08000000} if os.name == "nt" else {}
74
63
  LOCK_TIMEOUT_S = 10.0
75
- NOT_CONFIGURED_MESSAGE = ("caddis_spend: spend cap not configured: set eur_per_24h, reserve_eur_per_call and both "
76
- "token prices (finite, above 0) in ~/.caddis/spend-cap.toml; every agy launch is refused "
77
- "until then")
64
+ # Advisory, never a refusal: at or above this committed EUR in 24 h, `run` and `status` say so. The owner may change it
65
+ # with CADDIS_SPEND_ADVISE_EUR (a finite number above 0; anything else means this default).
66
+ ADVISE_EUR_PER_24H = 300.0
67
+ ADVISE_VAR = "CADDIS_SPEND_ADVISE_EUR"
68
+
69
+
70
+ def advise_eur(env=None) -> float:
71
+ """The advisory level in EUR per 24 h: CADDIS_SPEND_ADVISE_EUR when it is a finite number above 0, else 300."""
72
+ env = os.environ if env is None else env
73
+ try:
74
+ value = float(str(env.get(ADVISE_VAR, "")).strip())
75
+ except ValueError:
76
+ return ADVISE_EUR_PER_24H
77
+ return value if math.isfinite(value) and value > 0 else ADVISE_EUR_PER_24H
78
+
79
+
80
+ def advisory_line(committed: float, level: float) -> str:
81
+ return (f"caddis_spend: ADVISORY: EUR {committed:.2f} committed in the last 24 h on this machine "
82
+ f"(advise level EUR {level:g}). No cap applies. Tell the owner.")
78
83
 
79
84
 
80
85
  # Recursion guard on headless starts (robustness #19). Every launcher of a headless caddis session passes
81
86
  # CADDIS_HEADLESS_DEPTH one higher than it got, and refuses to launch once the depth is at the limit, so a
82
87
  # headless session that starts a headless session that starts one... ends after MAX_HEADLESS_DEPTH levels.
83
88
  # The owner may change the limit with CADDIS_HEADLESS_MAX_DEPTH. This stops accidents and loops; a hostile
84
- # process can reset the variable, like the cap file (see the Limits above).
89
+ # process can reset the variable.
85
90
  HEADLESS_DEPTH_VAR = "CADDIS_HEADLESS_DEPTH"
86
91
  MAX_HEADLESS_DEPTH = 3
87
92
 
@@ -112,19 +117,8 @@ def bump_headless_depth(env) -> dict:
112
117
  return out
113
118
 
114
119
 
115
- class NotConfigured(Exception):
116
- """The cap file is missing, unreadable, or holds a value that is not a finite number above 0."""
117
-
118
-
119
- @dataclass
120
- class Cap:
121
- eur_per_24h: float
122
- reserve: float
123
- price_in: float
124
- price_out: float
125
-
126
-
127
- def _cap_path(home: Path) -> Path:
120
+ def _prices_path(home: Path) -> Path:
121
+ """The optional price file. Only its two token prices are read; any cap value in it is ignored."""
128
122
  return home / ".caddis" / "spend-cap.toml"
129
123
 
130
124
 
@@ -132,26 +126,24 @@ def _log_path(home: Path) -> Path:
132
126
  return home / ".caddis" / "spend" / "agy.jsonl"
133
127
 
134
128
 
135
- def _positive(value) -> float:
136
- """A finite float above 0, or ValueError (bool and NaN/inf rejected)."""
137
- if isinstance(value, bool):
138
- raise ValueError(f"not a number: {value!r}")
139
- number = float(value)
140
- if not math.isfinite(number) or number <= 0:
141
- raise ValueError(f"must be a finite number above 0: {value!r}")
142
- return number
143
-
144
-
145
- def load_cap(home: Path) -> Cap:
129
+ def load_prices(home: Path) -> tuple[float, float] | None:
130
+ """(EUR per million input tokens, EUR per million output tokens) from the `[agy]` table of the optional price
131
+ file, or None when the file is missing or unreadable, or a price is not a finite number above 0."""
146
132
  import tomllib
147
133
 
148
- path = _cap_path(home)
149
134
  try:
150
- data = tomllib.loads(path.read_text(encoding="utf-8")).get("agy", {})
151
- return Cap(_positive(data["eur_per_24h"]), _positive(data.get("reserve_eur_per_call", 10)),
152
- _positive(data["eur_per_million_input_tokens"]), _positive(data["eur_per_million_output_tokens"]))
153
- except (OSError, ValueError, KeyError, TypeError, AttributeError, tomllib.TOMLDecodeError) as exc:
154
- raise NotConfigured(f"{path}: {exc}") from exc
135
+ data = tomllib.loads(_prices_path(home).read_text(encoding="utf-8")).get("agy", {})
136
+ prices = (data["eur_per_million_input_tokens"], data["eur_per_million_output_tokens"])
137
+ except (OSError, ValueError, KeyError, TypeError, AttributeError, tomllib.TOMLDecodeError):
138
+ return None
139
+ numbers = []
140
+ for value in prices:
141
+ if isinstance(value, bool) or not isinstance(value, (int, float)):
142
+ return None
143
+ if not math.isfinite(value) or value <= 0:
144
+ return None
145
+ numbers.append(float(value))
146
+ return numbers[0], numbers[1]
155
147
 
156
148
 
157
149
  @contextmanager
@@ -251,10 +243,10 @@ def _amount(value) -> float | None:
251
243
 
252
244
  def committed_last_24h(home: Path, now: datetime) -> float:
253
245
  """Valid settled EUR, plus the reserve of every pending call with no valid settled line, newer than 24 h.
246
+ This is a report only; nothing refuses a launch on it.
254
247
 
255
- A settled line with a bad `eur` does not count as settled, so its pending reserve keeps counting.
256
- A pending line with a bad reserve (only a hand edit can write one; reserve() always writes a valid
257
- value) counts as 0."""
248
+ A settled line with a bad `eur` does not count as settled, so its pending reserve keeps counting (reserve()
249
+ now writes 0; older lines may hold a reserve). A pending line with a bad reserve (a hand edit) counts as 0."""
258
250
  since = now - timedelta(hours=24)
259
251
  records = _read(home)
260
252
  settled: dict[str, float] = {}
@@ -275,36 +267,33 @@ def committed_last_24h(home: Path, now: datetime) -> float:
275
267
  return total
276
268
 
277
269
 
278
- def reserve(home: Path, caller: str, now: datetime) -> str | None:
279
- """Book a pending call. None when it would go over the cap. Raises NotConfigured or TimeoutError."""
280
- cap = load_cap(home)
270
+ def reserve(home: Path, caller: str, now: datetime) -> str:
271
+ """Write a `pending` line for a call about to start and return its id. Never refuses for money.
272
+ Raises TimeoutError when the log cannot be locked, OSError when it cannot be written."""
281
273
  with _locked(home):
282
- if committed_last_24h(home, now) + cap.reserve > cap.eur_per_24h:
283
- return None
284
274
  rid = uuid.uuid4().hex
285
275
  _append(home, {"kind": "pending", "id": rid, "ts": now.isoformat(), "caller": caller,
286
- "pid": os.getpid(), "reserve_eur": cap.reserve})
276
+ "pid": os.getpid(), "reserve_eur": 0})
287
277
  return rid
288
278
 
289
279
 
290
280
  def settle(home: Path, rid: str, tokens: tuple[int, int] | None, now: datetime,
291
281
  duration_s: float | None = None) -> float:
292
- """Record the real cost of a reserved call; with no token counts, its reserve (estimated, with duration)."""
293
- try:
294
- cap = load_cap(home)
295
- except NotConfigured:
296
- cap = None
282
+ """Write the `settled` line of a call. With token counts and valid prices: the EUR from the counts. With counts
283
+ but no prices: the counts and EUR 0, estimated. With no counts: the pending line's reserve (0 for new lines),
284
+ estimated. The duration is recorded when given."""
285
+ prices = load_prices(home)
297
286
  record: dict = {"kind": "settled", "id": rid, "ts": now.isoformat()}
298
- if tokens is None or cap is None:
287
+ if tokens is None:
299
288
  pending = next((r for r in _read(home) if r.get("kind") == "pending" and r.get("id") == rid), {})
300
- eur = _amount(pending.get("reserve_eur"))
301
- if eur is None:
302
- eur = cap.reserve if cap else 0.0
289
+ eur = _amount(pending.get("reserve_eur")) or 0.0
303
290
  record.update({"tokens_in": 0, "tokens_out": 0, "eur": round(eur, 4), "estimated": True})
304
291
  else:
305
292
  t_in, t_out = tokens
306
- eur = t_in / 1e6 * cap.price_in + t_out / 1e6 * cap.price_out
307
- record.update({"tokens_in": t_in, "tokens_out": t_out, "eur": round(eur, 4), "estimated": False})
293
+ eur = 0.0 if prices is None else t_in / 1e6 * prices[0] + t_out / 1e6 * prices[1]
294
+ # Zero tokens cost exactly 0 (nothing ran); other counts with no prices are an estimate.
295
+ estimated = prices is None and (t_in, t_out) != (0, 0)
296
+ record.update({"tokens_in": t_in, "tokens_out": t_out, "eur": round(eur, 4), "estimated": estimated})
308
297
  if duration_s is not None:
309
298
  record["duration_s"] = round(duration_s, 1)
310
299
  with _locked(home):
@@ -344,7 +333,7 @@ def _count(value) -> int | None:
344
333
  def tokens_from_output(stdout: str) -> tuple[int, int] | None:
345
334
  """(usage.input_tokens, usage.output_tokens) from agy's JSON document; output_tokens includes thinking
346
335
  tokens (sample: 27249 in, 85 out of which 84 thinking, total 27334). None when not readable, or when a
347
- count is not a non-negative integer (then the call settles at its reserve)."""
336
+ count is not a non-negative integer (then the call settles as estimated)."""
348
337
  doc = _agy_document(stdout)
349
338
  usage = doc.get("usage") if doc else None
350
339
  if not isinstance(usage, dict):
@@ -426,35 +415,30 @@ def _run_child(argv: list[str], env: dict, timeout_s: float) -> tuple[int | None
426
415
  except BaseException:
427
416
  # Ctrl-C or any other error while waiting: the child (agy, spending) must not outlive us. It runs in its
428
417
  # own session/group, so it does not get our SIGINT. Kill the tree, then let the exception go on; run()
429
- # settles the reserve in its `finally`.
418
+ # settles the call in its `finally`.
430
419
  _kill_tree(proc)
431
420
  raise
432
421
 
433
422
 
434
423
  def run(argv: list[str], caller: str, home: Path, timeout_s: float | None = None) -> int:
435
- """Reserve, run agy, settle. Returns agy's exit code, or RUN_REFUSED (75) / RUN_NOT_CONFIGURED (78) /
436
- RUN_TIMEOUT (124: the child ran past `timeout_s`, default run_timeout_s(); its process tree was killed and the
437
- call is booked at its reserve)."""
424
+ """Log, run agy, settle. Returns agy's exit code, or RUN_REFUSED (75: headless depth at its limit, or the log
425
+ could not be locked or written) / RUN_TIMEOUT (124: the child ran past `timeout_s`, default run_timeout_s(); its
426
+ process tree was killed and the call is settled as estimated). Money never refuses a start."""
438
427
  now = lambda: datetime.now(timezone.utc) # noqa: E731
439
428
  try:
440
- env = bump_headless_depth(os.environ) # before the reserve: a refused start costs nothing
429
+ env = bump_headless_depth(os.environ) # before the pending line: a refused start writes nothing
441
430
  except HeadlessDepthExceeded as exc:
442
431
  print(str(exc), file=sys.stderr)
443
432
  return RUN_REFUSED
444
433
  try:
445
434
  rid = reserve(home, caller, now())
446
- except NotConfigured:
447
- print(NOT_CONFIGURED_MESSAGE, file=sys.stderr)
448
- return RUN_NOT_CONFIGURED
449
435
  except TimeoutError as exc:
450
436
  print(str(exc), file=sys.stderr)
451
437
  return RUN_REFUSED
452
- except Exception as exc: # an unreadable log or file error: refuse with the refusal code, never exit 1
453
- print(f"caddis_spend: could not check the spend cap: {exc!r}", file=sys.stderr)
454
- return RUN_REFUSED
455
- if rid is None:
456
- print(f"caddis_spend: over cap: agy refused ({status_line(home, now())})", file=sys.stderr)
438
+ except Exception as exc: # a file error on the log: refuse with the refusal code, never exit 1
439
+ print(f"caddis_spend: could not write the spend log: {exc!r}", file=sys.stderr)
457
440
  return RUN_REFUSED
441
+ advise(home, now()) # already at the level before the launch: say so, then start anyway
458
442
  out = ""
459
443
  counts: tuple[int, int] | None = None
460
444
  started = time.monotonic()
@@ -465,7 +449,7 @@ def run(argv: list[str], caller: str, home: Path, timeout_s: float | None = None
465
449
  sys.stdout.write(out)
466
450
  sys.stderr.write(err)
467
451
  print(f"caddis_spend: {argv[0]} timed out after {limit:g}s; its process tree was killed "
468
- f"(booked at the reserve). Set CADDIS_SPEND_RUN_TIMEOUT_S or --timeout-s to change the limit.",
452
+ f"(settled as estimated). Set CADDIS_SPEND_RUN_TIMEOUT_S or --timeout-s to change the limit.",
469
453
  file=sys.stderr)
470
454
  return RUN_TIMEOUT
471
455
  # Tokens only from JSON mode: in text mode the model's own lines could pose as a usage document.
@@ -481,29 +465,38 @@ def run(argv: list[str], caller: str, home: Path, timeout_s: float | None = None
481
465
  finally:
482
466
  try:
483
467
  settle(home, rid, counts, now(), duration_s=time.monotonic() - started)
484
- except Exception as exc: # the pending reserve keeps counting; never lose agy's own result
468
+ except Exception as exc: # the pending line stays unsettled; never lose agy's own result
485
469
  print(f"caddis_spend: could not settle {rid}: {exc}", file=sys.stderr)
470
+ advise(home, now())
486
471
 
487
472
 
488
- def status_line(home: Path, now: datetime) -> str:
473
+ def advise(home: Path, now: datetime) -> None:
474
+ """Print the ADVISORY line to stderr when the committed EUR of the last 24 h is at or above the advise level.
475
+ Advice only: it never changes an exit code, and a log it cannot read prints nothing."""
489
476
  try:
490
- cap = f"{load_cap(home).eur_per_24h:g}"
491
- except NotConfigured:
492
- cap = "NOT CONFIGURED"
493
- return f"agy: EUR {committed_last_24h(home, now):.2f} of {cap} in the last 24 h on this machine"
477
+ committed, level = committed_last_24h(home, now), advise_eur()
478
+ except Exception:
479
+ return
480
+ if committed >= level:
481
+ print(advisory_line(committed, level), file=sys.stderr)
482
+
483
+
484
+ def status_line(home: Path, now: datetime) -> str:
485
+ committed, level = committed_last_24h(home, now), advise_eur()
486
+ line = f"agy: EUR {committed:.2f} in the last 24 h on this machine (no cap)"
487
+ return line + (f" - ADVISORY (>= EUR {level:g})" if committed >= level else "")
494
488
 
495
489
 
496
490
  def spend_json(home: Path, now: datetime | None = None) -> dict:
497
- """The spend status as one JSON-ready dict. It holds no key, no prompt and no caller name."""
491
+ """The spend status as one JSON-ready dict. It holds no key, no prompt and no caller name.
492
+ There is no cap: `configured` is always False and `cap_eur` and `reserve_eur` are always None (the keys stay for
493
+ the hub schema, scripts/schemas/hub-spend.schema.json). `advise_eur` is the advise level and `advisory` is True at
494
+ or above it."""
498
495
  now = now or datetime.now(timezone.utc)
499
- try:
500
- cap = load_cap(home)
501
- cap_eur, reserve_eur = float(cap.eur_per_24h), float(cap.reserve)
502
- except NotConfigured:
503
- cap_eur = reserve_eur = None
504
- return {"schema": 1, "configured": cap_eur is not None, "cap_eur": cap_eur,
505
- "committed_eur": round(committed_last_24h(home, now), 6), "reserve_eur": reserve_eur,
506
- "window_h": 24}
496
+ committed, level = committed_last_24h(home, now), advise_eur()
497
+ return {"schema": 1, "configured": False, "cap_eur": None,
498
+ "committed_eur": round(committed, 6), "reserve_eur": None,
499
+ "window_h": 24, "advise_eur": level, "advisory": committed >= level}
507
500
 
508
501
 
509
502
  def main(argv: list[str] | None = None) -> int:
@@ -514,7 +507,7 @@ def main(argv: list[str] | None = None) -> int:
514
507
  if "--" in raw:
515
508
  i = raw.index("--")
516
509
  raw, tail = raw[:i], raw[i + 1:]
517
- parser = argparse.ArgumentParser(description="global agy spend cap (EUR per rolling 24 h, this machine)")
510
+ parser = argparse.ArgumentParser(description="agy usage log and run wrapper (EUR per rolling 24 h, this machine)")
518
511
  sub = parser.add_subparsers(dest="cmd", required=True)
519
512
  sub.add_parser("check")
520
513
  p_status = sub.add_parser("status")
@@ -532,23 +525,13 @@ def main(argv: list[str] | None = None) -> int:
532
525
  print(json.dumps(spend_json(home, now)) if args.json else status_line(home, now))
533
526
  except Exception as exc:
534
527
  print(f"caddis_spend: could not read the spend log: {exc!r}", file=sys.stderr)
535
- return EXIT_NOT_CONFIGURED
528
+ return EXIT_LOG_ERROR
536
529
  return EXIT_OK
537
- if args.cmd == "check":
538
- try:
539
- cap = load_cap(home)
540
- except NotConfigured:
541
- print(NOT_CONFIGURED_MESSAGE, file=sys.stderr)
542
- return EXIT_NOT_CONFIGURED
530
+ if args.cmd == "check": # there is no cap: always 0, so no caller is blocked by it
543
531
  try:
544
- committed = committed_last_24h(home, now)
532
+ print(f"ok: {status_line(home, now)}")
545
533
  except Exception as exc:
546
- print(f"caddis_spend: could not read the spend log: {exc!r}", file=sys.stderr)
547
- return EXIT_NOT_CONFIGURED
548
- if committed + cap.reserve > cap.eur_per_24h:
549
- print(f"over cap: {status_line(home, now)}")
550
- return EXIT_OVER_CAP
551
- print(f"ok: {status_line(home, now)}")
534
+ print(f"ok: caddis_spend: could not read the spend log: {exc!r}")
552
535
  return EXIT_OK
553
536
  if not tail:
554
537
  parser.error("run needs the agy command after --")
@@ -34,8 +34,9 @@ Exit codes (fail-closed):
34
34
  denylisted path / possible secret; see secret_filter.py), OR an explicit
35
35
  --range has no changes (a review of nothing is not CLEAN), OR every
36
36
  provider failed with a PROVIDER failure: HTTP 429, any 5xx, a timeout, a
37
- connection error, an empty reply, an agy error status, the agy spend
38
- cap refused, or a one-file prompt too long for agy with no other provider
37
+ connection error, an empty reply, an agy error status, caddis_spend
38
+ refused agy (headless depth or log lock), or a one-file prompt too
39
+ long for agy with no other provider
39
40
  — actionable message on stderr/stdout either way
40
41
  4 error — no diff verdict parsed, git failure, other endpoint/parse failure, or the diff
41
42
  exceeds REVIEW_MAX_DIFF_CHARS (see below — never silently downgraded to CLEAN)
@@ -52,7 +53,7 @@ A named --provider goes first, then the rest in policy order; a provider with no
52
53
  is skipped. With no provider named, the chain starts at the first provider that is available. A provider failure
53
54
  moves to the next provider and never splits the diff. On HTTP 429 a `Retry-After` is honoured ONCE per
54
55
  provider (capped at 60 s), then the next provider is tried. A provider that failed gets no more calls in
55
- the same run. agy runs through `caddis_spend.py run` (the EUR spend cap), in plan mode, with the diff in
56
+ the same run. agy runs through `caddis_spend.py run` (usage log, timeout, depth guard; no EUR cap), in plan mode, with the diff in
56
57
  the prompt (no tools needed). The secret filter runs once, before any provider, agy included. The
57
58
  provider that gave each verdict is printed.
58
59
 
@@ -141,7 +142,7 @@ AGY_PROVIDER = "agy-argon"
141
142
  DEFAULT_PROVIDER = AGY_PROVIDER
142
143
  REVIEW_ORDER: tuple[str, ...] = (AGY_PROVIDER, "deepseek", "glm")
143
144
 
144
- # agy runs headless through the spend cap: plan mode (it needs no tools, the diff is in the prompt).
145
+ # agy runs headless through caddis_spend.py run: plan mode (it needs no tools, the diff is in the prompt).
145
146
  AGY_MODEL = "gemini-4-argon-high"
146
147
  AGY_TIMEOUT_S = 15 * 60
147
148
  # The prompt is one command-line argument (`--print=<prompt>`). A Windows command line holds at most
@@ -152,8 +153,9 @@ AGY_TIMEOUT_S = 15 * 60
152
153
  # the longest command line: python, two script paths, the agy path and the fixed flags.
153
154
  WINDOWS_CMDLINE_MAX = 32_767
154
155
  AGY_MAX_PROMPT_CHARS = 28_000
155
- # `caddis_spend.py run` refusal codes: 75 over the cap or no lock, 78 cap not configured. Never agy's own.
156
- SPEND_REFUSED = (75, 78)
156
+ # `caddis_spend.py run` refusal code: 75 = headless depth at its limit, or the usage log could not be locked or
157
+ # written. Never agy's own. (78 "cap not configured" is gone with the cap, 1 Nov 2026.)
158
+ SPEND_REFUSED = (75,)
157
159
 
158
160
  # On HTTP 429, wait for `Retry-After` once per provider per run, at most this long.
159
161
  RETRY_AFTER_CAP_S = 60.0
@@ -213,7 +215,7 @@ class ProviderFailure(RuntimeError):
213
215
 
214
216
 
215
217
  class ProviderSkipped(Exception):
216
- """The provider is not available for this run (the spend cap refused agy, agy is missing, the prompt
218
+ """The provider is not available for this run (caddis_spend refused agy, agy is missing, the prompt
217
219
  is too long for the agy command line). The chain moves on; nothing was reviewed. `for_run=False`: skip only
218
220
  this prompt (it was too long), so a smaller batch may still use the provider."""
219
221
 
@@ -635,8 +637,8 @@ def _spend_script() -> Path | None:
635
637
 
636
638
 
637
639
  def agy_launcher() -> list[str] | None:
638
- """The command prefix that runs agy under the spend cap, or None when agy or caddis_spend is missing.
639
- Every agy call goes through `caddis_spend.py run` (owner policy: agy only through the spend cap)."""
640
+ """The command prefix that runs agy through `caddis_spend.py run`, or None when agy or caddis_spend is missing.
641
+ Every agy call goes through `caddis_spend.py run` (usage log, timeout and depth guard; there is no EUR cap)."""
640
642
  agy = shutil.which("agy")
641
643
  spend = _spend_script()
642
644
  if not agy or spend is None:
@@ -704,9 +706,9 @@ def agy_prompt_chars(prompt: str) -> int:
704
706
 
705
707
 
706
708
  def call_agy(launcher: list[str], prompt: str, timeout: float = AGY_TIMEOUT_S) -> str:
707
- """One review by agy Argon through the spend cap -> the reply text.
709
+ """One review by agy Argon through `caddis_spend.py run` -> the reply text.
708
710
 
709
- ProviderSkipped: the cap refused, agy is missing, or the prompt is too long for one argument.
711
+ ProviderSkipped: caddis_spend refused (exit 75), agy is missing, or the prompt is too long for one argument.
710
712
  ProviderFailure: a non-zero exit, a status other than SUCCESS (ERROR, RESOURCE_EXHAUSTED), no JSON
711
713
  document, or an empty reply."""
712
714
  cost = agy_prompt_chars(prompt)
@@ -717,7 +719,7 @@ def call_agy(launcher: list[str], prompt: str, timeout: float = AGY_TIMEOUT_S) -
717
719
  f"--print={prompt}"]
718
720
  code, stdout, stderr = _run_capped(argv, timeout)
719
721
  if code in SPEND_REFUSED:
720
- raise ProviderSkipped(f"the agy spend cap refused the call (caddis_spend exit {code}): "
722
+ raise ProviderSkipped(f"caddis_spend refused the agy call (exit {code}): "
721
723
  f"{stderr.strip()[-300:]}")
722
724
  if code == 127:
723
725
  raise ProviderSkipped(f"agy could not start: {stderr.strip()[-300:]}")
@@ -1003,7 +1005,7 @@ def main(argv: list[str] | None = None, env: dict[str, str] | None = None) -> in
1003
1005
  + "). Verdict is CLEAN only if every batch is clean."
1004
1006
  )
1005
1007
 
1006
- # Per run: a provider that failed (429, 5xx, timeout, empty reply, cap refusal) gets no more calls,
1008
+ # Per run: a provider that failed (429, 5xx, timeout, empty reply, caddis_spend refusal) gets no more calls,
1007
1009
  # and each provider waits for a 429 Retry-After at most once. Hammering a throttled provider with
1008
1010
  # more, smaller calls is the 18-19 Oct 2026 failure.
1009
1011
  down: set[str] = set()
@@ -9,7 +9,9 @@
9
9
  # 3. `caddis_roadmap.py recheck` cleared a blocker (exit 0); in a `merged:`, `freed:` or `rollup-ready:` tick
10
10
  # recheck is NOT run (the
11
11
  # merge is the change, and a cleared blocker would change the roadmap the restart checks against its hash);
12
- # 4. agy engine only (the recorded launch options): `caddis_spend.py check` exits 0.
12
+ # 4. agy engine only (the recorded launch options): `caddis_spend.py check` exits 0. There is no spend cap (1 Nov
13
+ # 2026), so check always exits 0 and prints the usage line (with ADVISORY at the advise level); a non-zero
14
+ # exit now means the script itself failed.
13
15
  # It restarts with the launch options the last run recorded (`--restart-args`: engine, model, caps), never the
14
16
  # defaults. A run that holds the lock records the last stop `running`, so a run killed without a stop (a crash, a
15
17
  # reboot) is never restarted here: it needs the owner.
@@ -72,7 +74,7 @@ $options = @(& $py $runnerPy --roadmap $Roadmap --repo $Repo --restart-args | Wh
72
74
  if ($LASTEXITCODE -ne 0) { Write-Output "roadmap-recheck: launch options not readable; runner not started"; exit 1 }
73
75
  if ($GhAccount -and $options -notcontains '-GhAccount') { $options += @('-GhAccount', $GhAccount) }
74
76
 
75
- # The global agy spend cap applies to the agy engine only (a claude run needs no spend-cap file).
77
+ # agy engine only: print the agy usage line (no cap; check exits 0 unless the script itself fails).
76
78
  $engineAt = [array]::IndexOf($options, '-Engine')
77
79
  $engine = if ($engineAt -ge 0 -and $engineAt + 1 -lt $options.Count) { $options[$engineAt + 1] } else { 'claude' }
78
80
  if ($engine -eq 'agy') {
@@ -674,6 +674,12 @@
674
674
  },
675
675
  "window_h": {
676
676
  "type": "integer"
677
+ },
678
+ "advise_eur": {
679
+ "type": "number"
680
+ },
681
+ "advisory": {
682
+ "type": "boolean"
677
683
  }
678
684
  }
679
685
  },
@@ -34,6 +34,12 @@
34
34
  },
35
35
  "window_h": {
36
36
  "type": "integer"
37
+ },
38
+ "advise_eur": {
39
+ "type": "number"
40
+ },
41
+ "advisory": {
42
+ "type": "boolean"
37
43
  }
38
44
  }
39
45
  }
@@ -101,7 +101,7 @@ and never report the result as a full CLEAN.
101
101
  then DeepSeek, then GLM** (`REVIEW_ORDER` in `oss_review.py`). A named `--provider` goes first; on a provider failure
102
102
  (HTTP 429, any 5xx, a timeout, a connection error, an empty reply) the tool moves to the next one in
103
103
  that order and prints which provider gave the verdict. A provider with no key is skipped. agy runs
104
- through `caddis_spend.py run` (the spend cap); if the cap refuses, agy is skipped. On a 429 the tool
104
+ through `caddis_spend.py run` (usage log, time limit, depth guard; no spend cap); if it refuses (exit 75), agy is skipped. On a 429 the tool
105
105
  waits for `Retry-After` once (at most 60 s); it never splits the diff because of a 429 or an empty
106
106
  reply. A custom endpoint (`--base-url`/`--model`) never falls back. Name a provider only when you have
107
107
  a reason.
@@ -182,7 +182,7 @@ of that role and write its Lane line as follows:
182
182
  - `agy`: agy — `python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_spend.py" run --caller lane-pN -- agy --mode accept-edits --dangerously-skip-permissions --add-dir . --print-timeout 20m --output-format json -p "HEADLESS RUN RULES. Read <plan path> and its Constraints. Implement Phase N only in the current checkout. Do not switch or create branches, commit, push, or edit files outside this phase. Run its exit gate and report the literal result."`
183
183
 
184
184
  Replace `<plan path>` and `N` (also in `lane-pN`) with this plan's path and phase number. The agy line
185
- always starts with `caddis_spend.py run`: it books the call against the global EUR spend cap, and
185
+ always starts with `caddis_spend.py run`: it logs the call's usage and sets its time limit (there is no spend cap), and
186
186
  `caddis_gate.py lane-check` refuses a bare `agy` Lane line. If the routing command fails
187
187
  or exits 3, use `claude — this session` and state the reason in that phase. When a phase has cards, a
188
188
  prompt for one card names it by reference ("then Phase N card B"). Never paste card text into a prompt.
@@ -122,8 +122,8 @@ not hold the child's work. So these rules keep briefs and replies small:
122
122
  7. **Merge:** one member at a time into the feature branch. Run the whole test folder after each merge, and
123
123
  the phase gates. A conflict stops that member only.
124
124
  8. **Cost:** wave cost is the sum of its members, each on the cheapest fitting model from the session table
125
- (`caddis_routing.py session`). Before the wave, `caddis_spend.py status` headroom must cover the members
126
- × the per-call reserve. Exit 75 means "not run", not "failed".
125
+ (`caddis_routing.py session`). There is no spend cap: `caddis_spend.py status` shows the agy spend; if it
126
+ ends with ` - ADVISORY`, tell the owner before the wave. Exit 75 means "not run", not "failed".
127
127
  9. **No plan-time marker.** Pick the wave from the CURRENT `Files:` lists: at most 3 phases, disjoint, one
128
128
  worktree each. Safety comes from this run-time check and the whole test folder after each merge, not
129
129
  from the plan: phases often touch files outside their `Files:`. A plan adds only an optional
@@ -307,10 +307,11 @@ row, visible to any later reader without anyone having to catch it live.
307
307
  Re-dispatch the same phase prompt to the printed lane with its direct launch command:
308
308
  `codex exec ...` or `python "${CLAUDE_PLUGIN_ROOT}/scripts/caddis_spend.py" run --caller lane-pN -- agy ... -p "..."`,
309
309
  using the same form that `/feature-plan` writes. Never start agy without the `caddis_spend.py run`
310
- prefix: it is the global spend cap. Its own refusals have their own exit codes, never agy's:
311
- **75** = over the cap or could not lock (treat like out of budget: switch lane, not an attempt);
312
- **78** = the cap is not configured (stop and tell the owner to write `~/.caddis/spend-cap.toml`).
313
- Each refusal also prints a `caddis_spend:` line on stderr. Any other exit code is agy's own.
310
+ prefix: it logs the usage, sets the time limit and guards the headless depth (there is no spend cap).
311
+ Its own exit codes are never agy's: **75** = headless depth at its limit or the usage log could not
312
+ be locked (treat like out of budget: switch lane, not an attempt); **124** = the call ran past its
313
+ time limit and was killed. Each refusal also prints a `caddis_spend:` line on stderr. A
314
+ `caddis_spend: ADVISORY:` line is advice only: the call ran; tell the owner. Any other exit code is agy's own.
314
315
  An out-of-budget switch is not an attempt (item 4). Record the fallback in the Tracker
315
316
  `Lane` column, for example `sonnet -> agy (claude out of budget)`.
316
317
  If `next-lane` exits 3, stop and report that no lane is left. As a last resort, the owner can
@@ -193,9 +193,9 @@ unattended; `-Plan <slug>` runs one plain plan instead (the two are exclusive).
193
193
  code `BLOCKED review not run` (neither restartable); the review cost counts against the USD caps.
194
194
 
195
195
  Stops (each one notifies and releases the lock): a STOP file (`~/.caddis/STOP` or `.local/STOP`), any cap (10 h,
196
- 12 sessions, 120 min and USD 25 per session, USD 150 total; per run, in memory; the global agy spend cap of
197
- `caddis_spend.py` still counts across runs), a lock or batch claim that cannot be written
198
- (`BLOCKED claim not written`, before any session), the agy spend cap refusing a reservation, three sessions
196
+ 12 sessions, 120 min and USD 25 per session, USD 150 total; per run, in memory; there is no agy EUR cap since
197
+ 1 Nov 2026, only the usage log of `caddis_spend.py` and its ADVISORY line), a lock or batch claim that cannot be written
198
+ (`BLOCKED claim not written`, before any session), an agy usage log that cannot be locked or written, three sessions
199
199
  with no newly merged phase, a roadmap write that fails, and the **snapshot guard**: one baseline for the whole run.
200
200
  The Milestones and Blockers tables (every cell of every row, rows added, removed or moved), the `Runner host` line
201
201
  and the `**Exit setup:**` line are frozen. Every origin read (each `next`, after the runner's own writes, after each session) is compared with the
@@ -250,8 +250,8 @@ the owner edits the roadmap during a merge wait, the restart stops `FAILED roadm
250
250
  recovery: `roadmap-run.ps1 -Roadmap <slug> -AcceptRoadmap` (owner only, refused headless) takes the runner lock (a live
251
251
  runner refuses it), prints the diff from the published baseline, asks you to type `accept` (or `--yes`), and accepts
252
252
  the origin roadmap as the new baseline of the wait; the next start goes on. With `-DryRun` it prints the diff only. `--last-stop` uses `--gh-account`, else the account the run recorded
253
- in its launch options. In all cases the lock must be absent or stale; for the agy engine `caddis_spend.py check` must exit 0 too (a
254
- claude-engine roadmap needs no spend-cap file). A restart after a merge writes `pending-rollup.json` in its runner
253
+ in its launch options. In all cases the lock must be absent or stale; for the agy engine `caddis_spend.py check` must exit 0 too (it
254
+ always does unless the script fails; there is no spend cap). A restart after a merge writes `pending-rollup.json` in its runner
255
255
  folder, runs the rollup first, then removes the claim and the branch, and only then the file. Every stop records
256
256
  itself: a failed rollup, a crash or a STOP file before that is not restartable (the owner decides), and the next start
257
257
  finds the file and does the rollup first. A merged
@@ -272,7 +272,7 @@ Sessions are cooperative (our own sessions): the runner guards against mistakes
272
272
  deliberately hostile session, which runs as the same OS user and could change anything the runner can. The state
273
273
  tripwire catches accidents in a runner's own state only. In particular, a session in another worktree of the repo can
274
274
  delete or rewrite ANOTHER runner's claim or lock under `<git common dir>/caddis-runner/`; that is not caught while it
275
- happens, and the victim runner fails closed only at its next restart (own claim missing or changed, orphaned claim). Caps are per run; the agy spend cap is the only limit across runs. Each roadmap has one
275
+ happens, and the victim runner fails closed only at its next restart (own claim missing or changed, orphaned claim). Caps are per run; nothing limits spend across runs (the agy usage log only advises). Each roadmap has one
276
276
  worktree, removed when the roadmap is finished and the worktree is clean.
277
277
 
278
278
  Owner-only rules are enforced by this tool; a direct PR that edits `roadmap.md` bypasses them; the runner stops
@@ -44,8 +44,8 @@ publish a branch that does). Commit the phase there, with its tracker row set to
44
44
  ## 4. Work
45
45
 
46
46
  - Do ONE batch with `/caddis:implement` discipline: tests first, the phase's exit gate, a commit per phase.
47
- - agy sessions only: run `python {{scripts}}/caddis_spend.py check` before each agy call. Stop at the cap (exit 1 over
48
- the cap, 3 not configured).
47
+ - agy sessions only: run `python {{scripts}}/caddis_spend.py check` before each agy call. There is no spend cap (it
48
+ always exits 0); if its line ends with ` - ADVISORY`, say so in the relay for the owner.
49
49
  - You may do everything except pass an owner gate. Never pass an owner gate. Never raise a cap. Never delete a STOP file.
50
50
  - The runner reviews `risk: high` phases. A phase marked `**Risk:** high`: do not halt for it and do not run the
51
51
  review yourself. When its exit gate is green, set its row `done` and end with `STATUS: CONTINUE`. The runner then
@@ -193,9 +193,9 @@ unattended; `-Plan <slug>` runs one plain plan instead (the two are exclusive).
193
193
  code `BLOCKED review not run` (neither restartable); the review cost counts against the USD caps.
194
194
 
195
195
  Stops (each one notifies and releases the lock): a STOP file (`~/.caddis/STOP` or `.local/STOP`), any cap (10 h,
196
- 12 sessions, 120 min and USD 25 per session, USD 150 total; per run, in memory; the global agy spend cap of
197
- `caddis_spend.py` still counts across runs), a lock or batch claim that cannot be written
198
- (`BLOCKED claim not written`, before any session), the agy spend cap refusing a reservation, three sessions
196
+ 12 sessions, 120 min and USD 25 per session, USD 150 total; per run, in memory; there is no agy EUR cap since
197
+ 1 Nov 2026, only the usage log of `caddis_spend.py` and its ADVISORY line), a lock or batch claim that cannot be written
198
+ (`BLOCKED claim not written`, before any session), an agy usage log that cannot be locked or written, three sessions
199
199
  with no newly merged phase, a roadmap write that fails, and the **snapshot guard**: one baseline for the whole run.
200
200
  The Milestones and Blockers tables (every cell of every row, rows added, removed or moved), the `Runner host` line
201
201
  and the `**Exit setup:**` line are frozen. Every origin read (each `next`, after the runner's own writes, after each session) is compared with the
@@ -250,8 +250,8 @@ the owner edits the roadmap during a merge wait, the restart stops `FAILED roadm
250
250
  recovery: `roadmap-run.ps1 -Roadmap <slug> -AcceptRoadmap` (owner only, refused headless) takes the runner lock (a live
251
251
  runner refuses it), prints the diff from the published baseline, asks you to type `accept` (or `--yes`), and accepts
252
252
  the origin roadmap as the new baseline of the wait; the next start goes on. With `-DryRun` it prints the diff only. `--last-stop` uses `--gh-account`, else the account the run recorded
253
- in its launch options. In all cases the lock must be absent or stale; for the agy engine `caddis_spend.py check` must exit 0 too (a
254
- claude-engine roadmap needs no spend-cap file). A restart after a merge writes `pending-rollup.json` in its runner
253
+ in its launch options. In all cases the lock must be absent or stale; for the agy engine `caddis_spend.py check` must exit 0 too (it
254
+ always does unless the script fails; there is no spend cap). A restart after a merge writes `pending-rollup.json` in its runner
255
255
  folder, runs the rollup first, then removes the claim and the branch, and only then the file. Every stop records
256
256
  itself: a failed rollup, a crash or a STOP file before that is not restartable (the owner decides), and the next start
257
257
  finds the file and does the rollup first. A merged
@@ -272,7 +272,7 @@ Sessions are cooperative (our own sessions): the runner guards against mistakes
272
272
  deliberately hostile session, which runs as the same OS user and could change anything the runner can. The state
273
273
  tripwire catches accidents in a runner's own state only. In particular, a session in another worktree of the repo can
274
274
  delete or rewrite ANOTHER runner's claim or lock under `<git common dir>/caddis-runner/`; that is not caught while it
275
- happens, and the victim runner fails closed only at its next restart (own claim missing or changed, orphaned claim). Caps are per run; the agy spend cap is the only limit across runs. Each roadmap has one
275
+ happens, and the victim runner fails closed only at its next restart (own claim missing or changed, orphaned claim). Caps are per run; nothing limits spend across runs (the agy usage log only advises). Each roadmap has one
276
276
  worktree, removed when the roadmap is finished and the worktree is clean.
277
277
 
278
278
  Owner-only rules are enforced by this tool; a direct PR that edits `roadmap.md` bypasses them; the runner stops
@@ -44,8 +44,8 @@ publish a branch that does). Commit the phase there, with its tracker row set to
44
44
  ## 4. Work
45
45
 
46
46
  - Do ONE batch with `/caddis:implement` discipline: tests first, the phase's exit gate, a commit per phase.
47
- - agy sessions only: run `python {{scripts}}/caddis_spend.py check` before each agy call. Stop at the cap (exit 1 over
48
- the cap, 3 not configured).
47
+ - agy sessions only: run `python {{scripts}}/caddis_spend.py check` before each agy call. There is no spend cap (it
48
+ always exits 0); if its line ends with ` - ADVISORY`, say so in the relay for the owner.
49
49
  - You may do everything except pass an owner gate. Never pass an owner gate. Never raise a cap. Never delete a STOP file.
50
50
  - The runner reviews `risk: high` phases. A phase marked `**Risk:** high`: do not halt for it and do not run the
51
51
  review yourself. When its exit gate is green, set its row `done` and end with `STATUS: CONTINUE`. The runner then
@@ -1,7 +1,7 @@
1
1
  {
2
- "poolVersion": "1.3.175",
2
+ "poolVersion": "1.3.176",
3
3
  "bundles": {
4
- "antigravity-plugin": "1.3.175",
4
+ "antigravity-plugin": "1.3.176",
5
5
  "antigravity-plugin-extras": "1.3.49",
6
6
  "codex": "unknown"
7
7
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@caddis/cli",
3
- "version": "0.4.91",
3
+ "version": "0.4.92",
4
4
  "description": "Install, update and diagnose the caddis dev harness across every coding agent you use (Claude Code, agy/Antigravity, and more).",
5
5
  "keywords": [
6
6
  "caddis",