@caddis/cli 0.4.91 → 0.4.93

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 (74) hide show
  1. package/README.md +4 -0
  2. package/bundles/antigravity-plugin/agents/debug.md +2 -0
  3. package/bundles/antigravity-plugin/plugin.json +1 -1
  4. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_exit.cpython-311.pyc +0 -0
  5. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_file_lock.cpython-311.pyc +0 -0
  6. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_frontmatter.cpython-311.pyc +0 -0
  7. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_redact.cpython-311.pyc +0 -0
  8. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_roadmap.cpython-311.pyc +0 -0
  9. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_rows.cpython-311.pyc +0 -0
  10. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_status.cpython-311.pyc +0 -0
  11. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_tidy.cpython-311.pyc +0 -0
  12. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_todo.cpython-311.pyc +0 -0
  13. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_workstreams.cpython-311.pyc +0 -0
  14. package/bundles/antigravity-plugin/scripts/__pycache__/caddis_worktree_safety.cpython-311.pyc +0 -0
  15. package/bundles/antigravity-plugin/scripts/caddis_checkout_guard.py +1 -1
  16. package/bundles/antigravity-plugin/scripts/caddis_fleet.py +26 -9
  17. package/bundles/antigravity-plugin/scripts/caddis_gate.py +8 -8
  18. package/bundles/antigravity-plugin/scripts/caddis_guide.json +58 -6
  19. package/bundles/antigravity-plugin/scripts/caddis_lanes.py +17 -17
  20. package/bundles/antigravity-plugin/scripts/caddis_preload_review.py +554 -0
  21. package/bundles/antigravity-plugin/scripts/caddis_review.py +1 -1
  22. package/bundles/antigravity-plugin/scripts/caddis_roadmap_run.py +25 -39
  23. package/bundles/antigravity-plugin/scripts/caddis_routing.py +1 -1
  24. package/bundles/antigravity-plugin/scripts/caddis_run.py +160 -0
  25. package/bundles/antigravity-plugin/scripts/caddis_spawn.py +17 -1
  26. package/bundles/antigravity-plugin/scripts/caddis_spend.py +121 -138
  27. package/bundles/antigravity-plugin/scripts/caddis_upstream_check.py +108 -10
  28. package/bundles/antigravity-plugin/scripts/oss_review.py +15 -13
  29. package/bundles/antigravity-plugin/scripts/roadmap-recheck.ps1 +4 -2
  30. package/bundles/antigravity-plugin/scripts/schemas/hub-collect.schema.json +6 -0
  31. package/bundles/antigravity-plugin/scripts/schemas/hub-spend.schema.json +6 -0
  32. package/bundles/antigravity-plugin/scripts/setup_project_ai.py +65 -1
  33. package/bundles/antigravity-plugin/skills/_registry.md +3 -1
  34. package/bundles/antigravity-plugin/skills/brainstorming/SKILL.md +232 -40
  35. package/bundles/antigravity-plugin/skills/brainstorming/builder-check-prompt.md +25 -0
  36. package/bundles/antigravity-plugin/skills/cross-review/SKILL.md +1 -1
  37. package/bundles/antigravity-plugin/skills/feature-plan/SKILL.md +8 -2
  38. package/bundles/antigravity-plugin/skills/fleet-close/SKILL.md +4 -1
  39. package/bundles/antigravity-plugin/skills/graph-email/SKILL.md +15 -0
  40. package/bundles/antigravity-plugin/skills/handoff/SKILL.md +9 -2
  41. package/bundles/antigravity-plugin/skills/implement/SKILL.md +10 -6
  42. package/bundles/antigravity-plugin/skills/particle-art/SKILL.md +1 -3
  43. package/bundles/antigravity-plugin/skills/preload-review/SKILL.md +69 -0
  44. package/bundles/antigravity-plugin/skills/roadmap/SKILL.md +10 -6
  45. package/bundles/antigravity-plugin/skills/roadmap/assets/plan-resume-prompt.md +7 -6
  46. package/bundles/antigravity-plugin/skills/spawn-session/SKILL.md +5 -0
  47. package/bundles/antigravity-plugin/skills/tdd/SKILL.md +2 -1
  48. package/bundles/antigravity-plugin/skills/usage-review/SKILL.md +2 -0
  49. package/bundles/antigravity-plugin-extras/plugin.json +1 -1
  50. package/bundles/antigravity-plugin-extras/skills/_registry.md +1 -0
  51. package/bundles/antigravity-plugin-extras/skills/graph-email/SKILL.md +53 -0
  52. package/bundles/antigravity-plugin-extras/skills/graph-email/email.toml.example +44 -0
  53. package/bundles/antigravity-plugin-extras/skills/graph-email/scripts/send_email.py +432 -0
  54. package/bundles/codex/.codex/skills/media/particle-art/SKILL.md +1 -3
  55. package/bundles/codex/.codex/skills/workflow/brainstorming/SKILL.md +232 -40
  56. package/bundles/codex/.codex/skills/workflow/brainstorming/builder-check-prompt.md +25 -0
  57. package/bundles/codex/.codex/skills/workflow/roadmap/SKILL.md +10 -6
  58. package/bundles/codex/.codex/skills/workflow/roadmap/assets/plan-resume-prompt.md +7 -6
  59. package/bundles/manifest.json +3 -3
  60. package/dist/export/assets/export-CMtV-slT.css +1 -0
  61. package/dist/export/index.html +2 -2
  62. package/dist/ui/assets/{Activity-DZKPMOeV.js → Activity-BDjet2xd.js} +1 -1
  63. package/dist/ui/assets/Guide-Czn5sK0f.js +9 -0
  64. package/dist/ui/assets/Guide-D-Zy4cUT.css +1 -0
  65. package/dist/ui/assets/{RoadmapTab-DPsiSmIF.js → RoadmapTab-Bd8geyQx.js} +1 -1
  66. package/dist/ui/assets/index-Bd0Z4jR8.css +1 -0
  67. package/dist/ui/assets/{index-xl156OCN.js → index-CmngQ8Mk.js} +12 -12
  68. package/dist/ui/index.html +2 -2
  69. package/package.json +1 -1
  70. package/dist/export/assets/export-HxTgj3z2.css +0 -1
  71. package/dist/ui/assets/Guide-5ZFfL6sl.js +0 -9
  72. package/dist/ui/assets/Guide-Dnsb-TRd.css +0 -1
  73. package/dist/ui/assets/index-DGlNAmeA.css +0 -1
  74. /package/dist/export/assets/{export-B7BBDg5I.js → export-DtlDFN4L.js} +0 -0
@@ -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
@@ -145,6 +145,7 @@ import caddis_created # noqa: E402
145
145
  import caddis_notify # noqa: E402
146
146
  import caddis_redact # noqa: E402
147
147
  import caddis_review # noqa: E402
148
+ import caddis_run # noqa: E402
148
149
  import caddis_roadmap # noqa: E402
149
150
  import caddis_spend # noqa: E402
150
151
  import caddis_worktree_root # noqa: E402
@@ -339,12 +340,13 @@ def resolve_target(repo: Path, plan: str | None) -> Target:
339
340
 
340
341
 
341
342
  def render_prompt(template: Path, slug: str, phase: int | None = None) -> str:
342
- """The template body with `{{slug}}`, `{{phase}}` (empty when None) and `{{scripts}}` (this scripts folder: an
343
- app repo has no caddis `scripts/`) filled in."""
343
+ """The template body with `{{slug}}`, `{{phase}}` (empty when None) and `{{run}}` (`python "<home>/.caddis/bin/
344
+ caddis_run.py"`, the stable launcher: an app repo has no caddis `scripts/`, and a versioned plugin path is gone
345
+ after the next update, while a runner session can outlive it) filled in."""
344
346
  text = template.read_text(encoding="utf-8")
345
347
  _meta, body = caddis_workstreams.split_document(text)
346
348
  for key, value in (("{{slug}}", slug), ("{{phase}}", "" if phase is None else str(phase)),
347
- ("{{scripts}}", _HERE.as_posix())):
349
+ ("{{run}}", caddis_run.stable_prefix())):
348
350
  body = body.replace(key, value)
349
351
  return body.strip() + "\n"
350
352
 
@@ -912,7 +914,7 @@ def _one_session(ctx: _Ctx, prompt: str, relay_slug: str, n: int, spent: float,
912
914
  usd = min(caps.max_usd_per_session, caps.max_usd_total - spent)
913
915
  cmd = build_command(ctx.engine, ctx.model, prompt, usd=usd, timeout_min=remaining_s / 60, governor=ctx.governor,
914
916
  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
917
+ rid = _spend_reserve(ctx.home, spend_slug, ctx.now()) if ctx.engine == "agy" else None
916
918
  if ctx.engine == "agy": # agy's tool consoles open on a hidden desktop, not on the owner's screen
917
919
  g = len(ctx.governor)
918
920
  cmd = [*cmd[:g], *caddis_spend.hidden_argv(cmd[g:], session_env())]
@@ -1245,6 +1247,10 @@ def run(*, repo: Path, plan: str | None = None, roadmap: str | None = None, caps
1245
1247
  print(f"caddis_roadmap_run: resume prompt template {target.prompt_name} not found", file=sys.stderr)
1246
1248
  return caddis_exit.ERROR
1247
1249
  template = Path(template)
1250
+ try: # the prompt names ~/.caddis/bin/caddis_run.py; the SessionStart hook keeps it there, this covers a first run
1251
+ caddis_run.install_launcher(_HERE / "caddis_run.py")
1252
+ except OSError as exc:
1253
+ print(f"caddis_roadmap_run: cannot install the caddis_run.py launcher: {exc}", file=sys.stderr)
1248
1254
  if governor is None:
1249
1255
  governor = default_governor()
1250
1256
  if governor is None:
@@ -1318,8 +1324,6 @@ def _run_plan(ctx: _Ctx, template: Path, dry_run: bool, after_session: Callable[
1318
1324
  raise held
1319
1325
  _dry_lock_check(lock.path)
1320
1326
  ctx.checks(0, 0.0, 0.0)
1321
- if ctx.engine == "agy":
1322
- _spend_preview(ctx.home, ctx.now())
1323
1327
  except _Stop as stop:
1324
1328
  print(f"would stop: {caddis_redact.redact(stop.reason, masks)}")
1325
1329
  return caddis_exit.NOT_RUN
@@ -1855,8 +1859,6 @@ def _run_roadmap(ctx: _Ctx, template: Path, dry_run: bool, after_session: Callab
1855
1859
  try:
1856
1860
  _dry_lock_check(lock.path)
1857
1861
  ctx.checks(0, 0.0, 0.0)
1858
- if ctx.engine == "agy":
1859
- _spend_preview(ctx.home, ctx.now())
1860
1862
  try:
1861
1863
  batch, snap = caddis_roadmap.next_with_snapshot(repo, slug)
1862
1864
  except caddis_roadmap.RoadmapError as exc:
@@ -2332,28 +2334,25 @@ def _publish_and_wait(ctx: _Ctx, repo: Path, slug: str, mid: str, plan: str, pha
2332
2334
  raise _Stop(f"{WAITING_PREFIX} {ref} {url}", caddis_exit.BLOCKED)
2333
2335
 
2334
2336
 
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>`."""
2337
+ def _spend_reserve(home: Path, slug: str, moment: datetime) -> str:
2338
+ """Write the pending line of one agy session to the usage log (caddis_spend.py; there is no cap). _Stop only when
2339
+ the log cannot be locked or written (a file error never crashes the runner: the stop is logged and notified,
2340
+ redacted, like any other). The caller name in the spend log is `runner-<slug>`. At or above the advise level it
2341
+ prints the ADVISORY line and goes on."""
2339
2342
  try:
2340
2343
  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
2344
  except TimeoutError:
2345
- raise _Stop("BLOCKED spend cap lock busy", caddis_exit.BLOCKED) from None
2345
+ raise _Stop("BLOCKED spend log lock busy", caddis_exit.BLOCKED) from None
2346
2346
  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)
2347
+ raise _Stop(f"FAILED spend log error: {exc!r}", caddis_exit.BLOCKED) from None
2348
+ caddis_spend.advise(home, moment)
2350
2349
  return rid
2351
2350
 
2352
2351
 
2353
2352
  def _spend_settle(home: Path, rid: str, cmd: Sequence[str], outcome: "_Outcome | None", moment: datetime,
2354
2353
  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."""
2354
+ """Record the session's real cost: (0, 0) when it never started, estimated when there is no outcome (an
2355
+ exception) or no readable token counts."""
2357
2356
  try:
2358
2357
  if outcome is None:
2359
2358
  usage_counts = None
@@ -2364,23 +2363,10 @@ def _spend_settle(home: Path, rid: str, cmd: Sequence[str], outcome: "_Outcome |
2364
2363
  else:
2365
2364
  usage_counts = None
2366
2365
  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
2366
+ except Exception as exc: # the pending line stays unsettled; never lose the session's result
2368
2367
  print(f"caddis_roadmap_run: could not settle spend {rid}: {exc}", file=sys.stderr)
2369
2368
 
2370
2369
 
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
2370
  @dataclass
2385
2371
  class _Outcome:
2386
2372
  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"],
@@ -0,0 +1,160 @@
1
+ #!/usr/bin/env python3
2
+ """caddis_run.py: run a caddis script by its bare name, from the plugin that is installed NOW.
3
+
4
+ Usage: python "<home>/.caddis/bin/caddis_run.py" <script.py> [args...]
5
+
6
+ Why it exists: Claude Code expands `${CLAUDE_PLUGIN_ROOT}` to a folder with the plugin version in its name
7
+ (`~/.claude/plugins/cache/caddis/caddis/1.3.165/`). A restart prompt, relay or restart sheet that copies that
8
+ expanded path fails after the next update, because the old version folder is gone. Text that a LATER session reads
9
+ names this launcher instead. The SessionStart hook keeps the copy in `~/.caddis/bin/` fresh (`install_launcher`).
10
+
11
+ The launcher finds the install in `~/.claude/plugins/installed_plugins.json` (key `caddis@caddis`), else the highest
12
+ version folder under `~/.claude/plugins/cache/caddis/caddis/`. It runs `<install>/scripts/<script.py>` with the
13
+ same Python, and passes stdout, stderr and the exit code through.
14
+
15
+ Exit codes: the script's own; 2 = bad usage or a script name that is not a bare `.py` file name; 3 = no caddis
16
+ install found, or the script is not in it.
17
+
18
+ Standard library only. This file is copied alone to `~/.caddis/bin/`: it imports no sibling script.
19
+ """
20
+ from __future__ import annotations
21
+
22
+ import json
23
+ import os
24
+ import re
25
+ import subprocess
26
+ import sys
27
+ import tempfile
28
+ from pathlib import Path
29
+
30
+ EXIT_USAGE, EXIT_NOT_FOUND = 2, 3
31
+ PLUGIN_KEY = "caddis@caddis"
32
+ LAUNCHER_NAME = "caddis_run.py"
33
+
34
+ # A path into the versioned plugin cache: `.../plugins/cache/caddis/caddis/1.3.165/...`. Gone after the next update.
35
+ VERSIONED_PATH = re.compile(r"[/\\]caddis[/\\]caddis[/\\]\d")
36
+ VERSIONED_PATH_HELP = ("it names a versioned plugin path (.../caddis/caddis/<version>/...), which breaks at the next "
37
+ f'update: write python "<home>/.caddis/bin/{LAUNCHER_NAME}" <script> ... instead')
38
+
39
+ _BARE_PY = re.compile(r"[A-Za-z0-9_][A-Za-z0-9_.-]*\.py")
40
+ _VERSION = re.compile(r"\d+(\.\d+)*")
41
+
42
+
43
+ def valid_script_name(name: str) -> bool:
44
+ """A bare file name ending `.py`: no folder part, no `..`, no drive, no space."""
45
+ return bool(_BARE_PY.fullmatch(name)) and ".." not in name
46
+
47
+
48
+ def _install_paths(home: Path) -> list[Path]:
49
+ """The `installPath` values of `caddis@caddis` in installed_plugins.json: a list of entries or one object."""
50
+ try:
51
+ data = json.loads((home / ".claude" / "plugins" / "installed_plugins.json").read_text(encoding="utf-8"))
52
+ except (OSError, ValueError):
53
+ return []
54
+ if not isinstance(data, dict):
55
+ return []
56
+ plugins = data.get("plugins", data)
57
+ entry = plugins.get(PLUGIN_KEY) if isinstance(plugins, dict) else None
58
+ entries = entry if isinstance(entry, list) else [entry]
59
+ return [Path(e["installPath"]) for e in entries if isinstance(e, dict) and isinstance(e.get("installPath"), str)]
60
+
61
+
62
+ def _cache_dir(home: Path) -> Path:
63
+ return home / ".claude" / "plugins" / "cache" / "caddis" / "caddis"
64
+
65
+
66
+ def _newest_cached(home: Path) -> Path | None:
67
+ """The version folder with the highest version, compared as tuples of ints (1.3.99 < 1.3.172)."""
68
+ try:
69
+ found = [(tuple(int(p) for p in d.name.split(".")), d) for d in _cache_dir(home).iterdir()
70
+ if d.is_dir() and _VERSION.fullmatch(d.name) and (d / "scripts").is_dir()]
71
+ except OSError:
72
+ return None
73
+ return max(found, key=lambda pair: pair[0])[1] if found else None
74
+
75
+
76
+ def find_install(home: Path) -> Path | None:
77
+ """The installed caddis plugin folder, or None."""
78
+ for path in _install_paths(home):
79
+ if (path / "scripts").is_dir():
80
+ return path
81
+ return _newest_cached(home)
82
+
83
+
84
+ def main(argv: list[str], home: Path | None = None) -> int:
85
+ home = home or Path.home()
86
+ if not argv:
87
+ sys.stderr.write(f'usage: python "<home>/.caddis/bin/{LAUNCHER_NAME}" <script.py> [args...]\n')
88
+ return EXIT_USAGE
89
+ name, rest = argv[0], argv[1:]
90
+ if not valid_script_name(name):
91
+ sys.stderr.write(f"{LAUNCHER_NAME}: the script must be a bare file name that ends .py (no folder, no ..): {name!r}\n")
92
+ return EXIT_USAGE
93
+ install = find_install(home)
94
+ if install is None:
95
+ sys.stderr.write(f"{LAUNCHER_NAME}: no caddis plugin found: looked for key {PLUGIN_KEY} in "
96
+ f"{home / '.claude' / 'plugins' / 'installed_plugins.json'} and for a version folder in "
97
+ f"{_cache_dir(home)}\n")
98
+ return EXIT_NOT_FOUND
99
+ script = install / "scripts" / name
100
+ if not script.is_file():
101
+ sys.stderr.write(f"{LAUNCHER_NAME}: {name} is not in {install / 'scripts'}\n")
102
+ return EXIT_NOT_FOUND
103
+ return subprocess.call([sys.executable, str(script), *rest])
104
+
105
+
106
+ # -- the stable text, and the copy that keeps the launcher fresh -------------------------------------------------------
107
+
108
+
109
+ def _base(home: Path | None) -> Path:
110
+ """`~` for the launcher copy: the `home` argument beats CADDIS_HOME, which beats the user's home folder
111
+ (the rule of caddis_created.py and setup_project_ai.py: a test or sandbox points CADDIS_HOME at a temp folder)."""
112
+ return Path(home) if home else Path(os.environ.get("CADDIS_HOME") or Path.home())
113
+
114
+
115
+ def launcher_path(home: Path | None = None) -> Path:
116
+ return _base(home) / ".caddis" / "bin" / LAUNCHER_NAME
117
+
118
+
119
+ def stable_prefix(home: Path | None = None) -> str:
120
+ """`python "<home>/.caddis/bin/caddis_run.py"`: put a bare script name and its arguments after it."""
121
+ return f'python "{launcher_path(home).as_posix()}"'
122
+
123
+
124
+ def stable_command(script: str, home: Path | None = None) -> str:
125
+ """`python "<home>/.caddis/bin/caddis_run.py" <script>`: the form for TEXT THAT A LATER SESSION READS.
126
+ Forward slashes, so the same text works in bash and PowerShell. Machine-local on purpose."""
127
+ if not valid_script_name(script):
128
+ raise ValueError(f"not a bare .py file name: {script!r}")
129
+ return f"{stable_prefix(home)} {script}"
130
+
131
+
132
+ def install_launcher(src: str | os.PathLike, home: Path | None = None) -> bool:
133
+ """Copy `src` to `~/.caddis/bin/caddis_run.py` when the content differs. True when it wrote.
134
+
135
+ A temp file in the same folder, then os.replace: a reader never sees a half-written launcher. Raises on error;
136
+ the SessionStart hook catches it, because a launcher that cannot be refreshed must never stop a session."""
137
+ data = Path(src).read_bytes()
138
+ dest = launcher_path(home)
139
+ try:
140
+ if dest.read_bytes() == data:
141
+ return False
142
+ except OSError:
143
+ pass
144
+ dest.parent.mkdir(parents=True, exist_ok=True)
145
+ fd, tmp = tempfile.mkstemp(dir=dest.parent, prefix=".caddis_run-", suffix=".tmp")
146
+ try:
147
+ with os.fdopen(fd, "wb") as fh:
148
+ fh.write(data)
149
+ os.replace(tmp, dest)
150
+ except BaseException:
151
+ try:
152
+ os.unlink(tmp)
153
+ except OSError:
154
+ pass
155
+ raise
156
+ return True
157
+
158
+
159
+ if __name__ == "__main__":
160
+ sys.exit(main(sys.argv[1:]))
@@ -39,6 +39,14 @@ import time
39
39
  from dataclasses import dataclass, field
40
40
  from pathlib import Path
41
41
 
42
+ try:
43
+ import caddis_run # VERSIONED_PATH: a handover never names a versioned plugin path
44
+ except ModuleNotFoundError as _exc:
45
+ if _exc.name != "caddis_run":
46
+ raise
47
+ sys.path.insert(0, str(Path(__file__).resolve().parent))
48
+ import caddis_run
49
+
42
50
  if hasattr(sys.stdout, "reconfigure"):
43
51
  sys.stdout.reconfigure(encoding="utf-8", errors="replace")
44
52
 
@@ -110,9 +118,13 @@ class DocFindings:
110
118
  # different. A stale hash is an accident the successor will notice; a stored answer key
111
119
  # defeats the exercise SILENTLY — it certifies a reader who understood nothing.
112
120
  answer_key: list[tuple[int, str]] = field(default_factory=list)
121
+ # A path into the versioned plugin cache. The successor reads the handover after an update, when that
122
+ # folder is gone: the command fails with "can't open file". Refusing, so the author fixes it now.
123
+ versioned_paths: list[tuple[int, str]] = field(default_factory=list)
113
124
 
114
125
  def ok(self) -> bool:
115
- return not self.stale_prone and not self.missing_paths and not self.answer_key
126
+ return (not self.stale_prone and not self.missing_paths and not self.answer_key
127
+ and not self.versioned_paths)
116
128
 
117
129
 
118
130
  # ── answer-key detection ────────────────────────────────────────────────────────────────────
@@ -184,6 +196,8 @@ def check_document(text: str, repo_root: Path | None = None) -> DocFindings:
184
196
  if _INLINE_ANSWER.search(line):
185
197
  out.answer_key.append((n, "a question and its answer on one line. The questions may "
186
198
  "ship; the answers may not"))
199
+ if caddis_run.VERSIONED_PATH.search(line): # a fence does not exempt it: a command in a fence is the case
200
+ out.versioned_paths.append((n, caddis_run.VERSIONED_PATH_HELP))
187
201
  if _is_exempt(line, in_fence):
188
202
  continue
189
203
  for m in _HASH.finditer(line):
@@ -915,6 +929,8 @@ def main(argv: list[str] | None = None) -> int:
915
929
  sys.stderr.write(f"[spawn] {doc.name} FAILS round 0:\n")
916
930
  for n, msg in f.answer_key:
917
931
  sys.stderr.write(f" line {n}: ANSWER KEY — {msg}" + chr(10))
932
+ for n, msg in f.versioned_paths:
933
+ sys.stderr.write(f" line {n}: {msg}\n")
918
934
  for n, msg in f.stale_prone:
919
935
  sys.stderr.write(f" line {n}: {msg}\n")
920
936
  for p_ in f.missing_paths: