@caddis/cli 0.4.90 → 0.4.91

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 (34) 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_budget.py +26 -2
  14. package/bundles/antigravity-plugin/scripts/caddis_checkout_guard.py +31 -2
  15. package/bundles/antigravity-plugin/scripts/caddis_docs_pr.py +8 -0
  16. package/bundles/antigravity-plugin/scripts/caddis_guide.json +3 -3
  17. package/bundles/antigravity-plugin/scripts/caddis_handoff.py +73 -45
  18. package/bundles/antigravity-plugin/scripts/caddis_lanes.py +96 -14
  19. package/bundles/antigravity-plugin/scripts/caddis_roadmap_run.py +6 -4
  20. package/bundles/antigravity-plugin/scripts/caddis_workstreams.py +60 -17
  21. package/bundles/antigravity-plugin/scripts/check_doc_coverage.py +17 -0
  22. package/bundles/antigravity-plugin/scripts/oss_review.py +89 -24
  23. package/bundles/antigravity-plugin/scripts/templates/coordinator.md +1 -1
  24. package/bundles/antigravity-plugin/skills/coordinate/SKILL.md +17 -4
  25. package/bundles/antigravity-plugin/skills/cross-review/SKILL.md +17 -5
  26. package/bundles/antigravity-plugin/skills/feature-plan/SKILL.md +5 -0
  27. package/bundles/antigravity-plugin/skills/handoff/SKILL.md +12 -2
  28. package/bundles/antigravity-plugin/skills/implement/SKILL.md +4 -1
  29. package/bundles/antigravity-plugin/skills/roadmap/SKILL.md +2 -1
  30. package/bundles/antigravity-plugin-extras/plugin.json +1 -1
  31. package/bundles/antigravity-plugin-extras/skills/cross-review/SKILL.md +5 -5
  32. package/bundles/codex/.codex/skills/workflow/roadmap/SKILL.md +2 -1
  33. package/bundles/manifest.json +3 -3
  34. package/package.json +1 -1
@@ -1,5 +1,5 @@
1
1
  {
2
2
  "name": "caddis",
3
- "version": "1.3.174",
3
+ "version": "1.3.175",
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
  }
@@ -5,6 +5,7 @@ from __future__ import annotations
5
5
  import argparse
6
6
  from pathlib import Path
7
7
  import re
8
+ import subprocess
8
9
  import sys
9
10
  from typing import NamedTuple
10
11
 
@@ -38,7 +39,7 @@ BUDGETS: tuple[Budget, ...] = (
38
39
  ".caddis/relay/*.md",
39
40
  "chars",
40
41
  4000,
41
- "rewrite: current state only, git keeps history",
42
+ "rewrite: current state only",
42
43
  ),
43
44
  Budget(
44
45
  ".caddis/relay/*.tasks.md",
@@ -199,6 +200,29 @@ def check(root: Path) -> list[Over]:
199
200
  return overs
200
201
 
201
202
 
203
+ def _git_ignored(root: Path, rel: str) -> bool:
204
+ """True when git ignores ``rel``. Where git cannot say (no repo, no git), the relay folder counts as ignored:
205
+ every caddis scaffold ignores it."""
206
+ try:
207
+ proc = subprocess.run(["git", "-C", str(root), "check-ignore", "-q", "--", rel],
208
+ capture_output=True, stdin=subprocess.DEVNULL, timeout=10)
209
+ except (OSError, subprocess.SubprocessError):
210
+ return rel.startswith(".caddis/relay/")
211
+ if proc.returncode in (0, 1): # 0 ignored, 1 not ignored; anything else is "git cannot say"
212
+ return proc.returncode == 0
213
+ return rel.startswith(".caddis/relay/")
214
+
215
+
216
+ def fix_text(root: Path, over: Over) -> str:
217
+ """The fix line for ``over``. A rewrite of a git-ignored file loses the old text for good, so say back up first."""
218
+ if not over.rule.startswith("rewrite"):
219
+ return over.rule
220
+ if _git_ignored(root, over.path):
221
+ return (f"{over.rule}. Back up first: copy {over.path} to {over.path}.bak "
222
+ "(git-ignored, so git keeps no history)")
223
+ return f"{over.rule}; git keeps history"
224
+
225
+
202
226
  def main(argv: list[str] | None = None) -> int:
203
227
  if sys.stdout and hasattr(sys.stdout, "reconfigure"):
204
228
  try:
@@ -235,7 +259,7 @@ def main(argv: list[str] | None = None) -> int:
235
259
  return caddis_exit.CLEAN
236
260
 
237
261
  for over in overs:
238
- print(f"OVER {over.path}: {over.value} {over.unit} > {over.limit}; fix: {over.rule}")
262
+ print(f"OVER {over.path}: {over.value} {over.unit} > {over.limit}; fix: {fix_text(args.root, over)}")
239
263
  if args.report:
240
264
  return caddis_exit.CLEAN
241
265
  return caddis_exit.BLOCKED
@@ -13,6 +13,7 @@ tracked, so a worktree carries the line too, but the worktree is the safe place
13
13
  from __future__ import annotations
14
14
 
15
15
  import argparse
16
+ import fnmatch
16
17
  import json
17
18
  from pathlib import Path
18
19
  import re
@@ -21,12 +22,25 @@ import sys
21
22
 
22
23
  try:
23
24
  import caddis_exit
25
+ from claudster_config import ARTIFACT_DIRS
24
26
  except ModuleNotFoundError as exc:
25
- if exc.name != "caddis_exit":
27
+ if exc.name not in {"caddis_exit", "claudster_config"}:
26
28
  raise
27
29
  sys.path.insert(0, str(Path(__file__).resolve().parent))
28
30
  sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "claude-harness" / "scripts"))
29
31
  import caddis_exit
32
+ from claudster_config import ARTIFACT_DIRS
33
+
34
+ # What caddis writes into its artifact folder at run time: the generated index, logs, caches, locks and backups. It
35
+ # is the scaffold's `.caddis/.gitignore` (setup_project_ai.ARTIFACT_GITIGNORE; a test keeps the two in step), minus
36
+ # PROJECT-FACTS.md, which a person writes. In a repo scaffolded before an entry existed, git shows these as dirty,
37
+ # and they are not another session's edit. Patterns are fnmatch on the path inside the artifact folder; `*` crosses `/`.
38
+ GENERATED_DIRS = ("relay/", "session-state/", "context-window/", ".relay-injected/")
39
+ GENERATED_PATTERNS = (
40
+ "relay.md", "usage-log.jsonl*", "agent-log.jsonl*", ".last-usage-review", "session-state.md",
41
+ "context-window.json*", ".session-state-*.tmp", "hook-errors.jsonl", "memory.jsonl", "reviews/*.html",
42
+ "*.lock", "*.bak",
43
+ )
30
44
 
31
45
 
32
46
  def get_porcelain_lines(repo: Path) -> tuple[int, list[str]]:
@@ -84,6 +98,17 @@ def _norm(path: str) -> str:
84
98
  return path.strip().replace("\\", "/")
85
99
 
86
100
 
101
+ def is_generated_path(path: str) -> bool:
102
+ """True for a file caddis writes at run time inside its artifact folder (see GENERATED_PATTERNS)."""
103
+ norm = _norm(path)
104
+ for folder in ARTIFACT_DIRS:
105
+ prefix = folder + "/"
106
+ if norm.startswith(prefix):
107
+ inside = norm[len(prefix):]
108
+ return inside.startswith(GENERATED_DIRS) or any(fnmatch.fnmatchcase(inside, pat) for pat in GENERATED_PATTERNS)
109
+ return False
110
+
111
+
87
112
  class CheckoutStatusError(OSError):
88
113
  """`git status` could not run in the checkout, so foreign changes cannot be ruled out."""
89
114
 
@@ -125,6 +150,7 @@ def checkout_is_shared(root: Path) -> bool:
125
150
 
126
151
  def foreign_changes(root: Path, own_files: set[str] | None = None) -> list[str]:
127
152
  """The dirty paths in `root` that are not in `own_files`, in `git status` order. A rename counts both paths.
153
+ Files caddis writes itself (`is_generated_path`) never count.
128
154
 
129
155
  Without session tracking (`own_files` None or empty), every dirty path counts. Raises CheckoutStatusError
130
156
  when `git status` fails: the caller must then treat the checkout as unsafe."""
@@ -134,7 +160,10 @@ def foreign_changes(root: Path, own_files: set[str] | None = None) -> list[str]:
134
160
  own = {_norm(p) for p in (own_files or set())}
135
161
  foreign: list[str] = []
136
162
  for entry in lines:
137
- for path in entry_paths(entry):
163
+ paths = entry_paths(entry)
164
+ if all(is_generated_path(p) for p in paths):
165
+ continue # caddis's own index, log or lock: not another session's edit
166
+ for path in paths:
138
167
  if _norm(path) not in own and path not in foreign:
139
168
  foreign.append(path)
140
169
  return foreign
@@ -20,6 +20,9 @@ handoff must not commit there. Instead:
20
20
  not the main worktree, it is under the temp folder, and its branch is `docs/handoff-<utc>[-n]`. Anything else
21
21
  is refused (exit 4) and left as it is.
22
22
 
23
+ A repo with no `origin` remote cannot make a docs PR: `start` exits 3 with "no remote: commit explicit paths in
24
+ place (git add <named files>; git commit)". It commits nothing itself.
25
+
23
26
  Exit codes (caddis_exit): 0 clean (PR opened, or no change), 1 blocked (the PR could not be opened),
24
27
  3 could not run (git or the push failed, no GitHub origin), 4 error (bad usage, not a docs-PR worktree).
25
28
  """
@@ -74,8 +77,13 @@ def _utc() -> str:
74
77
  return datetime.datetime.now(datetime.timezone.utc).strftime("%Y%m%d%H%M%S")
75
78
 
76
79
 
80
+ NO_REMOTE = "no remote: commit explicit paths in place (git add <named files>; git commit)"
81
+
82
+
77
83
  def start(repo: Path, out=print) -> int:
78
84
  repo = Path(repo).resolve()
85
+ if not _git(repo, "remote", "get-url", "origin", check=False).stdout.strip():
86
+ raise DocsPrError(NO_REMOTE, caddis_exit.NOT_RUN) # a docs PR needs origin; say what to do instead
79
87
  base = roadmap.fetch(repo)
80
88
  stamp = _utc()
81
89
  tmp_root = Path(tempfile.gettempdir())
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "schema": 1,
3
- "version": "1.3.173",
4
- "generated": "2026-10-29 01:50 UTC",
3
+ "version": "1.3.174",
4
+ "generated": "2026-11-01 00:26 UTC",
5
5
  "commands": [
6
6
  {
7
7
  "name": "add-rules",
@@ -2358,7 +2358,7 @@
2358
2358
  },
2359
2359
  {
2360
2360
  "event": "PostToolUse",
2361
- "matcher": "Bash|PowerShell|Read|Grep|Agent|Task|WebFetch",
2361
+ "matcher": "Bash|PowerShell|Read|Grep|Glob|Edit|Write|MultiEdit|Agent|Task|WebFetch",
2362
2362
  "handler": "context_size.py"
2363
2363
  },
2364
2364
  {
@@ -5,10 +5,16 @@ BEFORE the model composes the new relay, and prints the exact FINISH command. FI
5
5
  writes the relay with `put --require-status --expected-hash`, so a peer's change made in between is never
6
6
  overwritten, runs the cheap checklist rows, and prints the resume block as its last output.
7
7
 
8
+ Every repo path (relay, session state, plan, sub-tool `--root`) is under the git top level of the cwd, resolved once
9
+ (`git rev-parse --show-toplevel`; outside a git repo, the cwd), so a checkpoint run from a subfolder writes the relay
10
+ where the next session's inject_relay hook reads it. Every sibling runs with that root as its cwd. A relative `--plan`
11
+ is relative to the root; a relative `--relay-file` is relative to the cwd.
12
+
8
13
  Refusals (exit 1): a headless session (`CADDIS_HEADLESS`), the coordinator's relay, a coordinator check that
9
14
  cannot run or cannot be read (the safe side is to refuse), FINISH without `--idle`, a failed relay write, and a
10
15
  relay over the 4,000-character budget. After the relay is written, a late error (no resume block, an exception)
11
- exits 1 with the last line `ERROR after relay write: ...`; FINISH still prints the resume block when it can. In a shared checkout the checkpoint changes
16
+ exits 1 with the last line `ERROR after relay write: ...`; FINISH still prints the resume block when it can. Any
17
+ other internal error exits 1 with `CHECKPOINT: internal error: ...` on stderr. In a shared checkout the checkpoint changes
12
18
  no tracked file (the Tracker row is skipped; card state goes in the local relay). Siblings run as subprocesses
13
19
  with `sys.executable`, found in this script's dir, then `<dir>/../claude-harness/scripts` (source tree).
14
20
  A missing sibling degrades open (`skipped: <script> not installed`), except the relay write, the coordinator
@@ -43,12 +49,12 @@ def _sibling(name: str) -> Path | None:
43
49
  return None
44
50
 
45
51
 
46
- def _run(script: str, *args: str) -> subprocess.CompletedProcess | None:
47
- """Run a sibling script; None when it is not installed. Never `python -I` (siblings import siblings)."""
52
+ def _run(root: Path, script: str, *args: str) -> subprocess.CompletedProcess | None:
53
+ """Run a sibling script in `root`; None when it is not installed. Never `python -I` (siblings import siblings)."""
48
54
  path = _sibling(script)
49
55
  if path is None:
50
56
  return None
51
- return subprocess.run([sys.executable, str(path), *args], capture_output=True, text=True,
57
+ return subprocess.run([sys.executable, str(path), *args], cwd=root, capture_output=True, text=True,
52
58
  encoding="utf-8", errors="replace")
53
59
 
54
60
 
@@ -60,24 +66,39 @@ def _headless() -> bool:
60
66
  return os.environ.get("CADDIS_HEADLESS", "").strip().lower() in HEADLESS_VALUES
61
67
 
62
68
 
63
- def _git(*args: str) -> str | None:
69
+ def _git(cwd: Path, *args: str) -> str | None:
64
70
  try:
65
- res = subprocess.run(["git", *args], capture_output=True, text=True, encoding="utf-8", errors="replace")
71
+ res = subprocess.run(["git", "-C", str(cwd), *args], capture_output=True, text=True, encoding="utf-8",
72
+ errors="replace")
66
73
  except OSError:
67
74
  return None
68
75
  return res.stdout.strip() if res.returncode == 0 else None
69
76
 
70
77
 
78
+ def _repo_root() -> Path:
79
+ """The git top level of the cwd (a worktree's own folder in a worktree), else the cwd. inject_relay.py reads the
80
+ relay at the same place, so a checkpoint from a subfolder lands where the next session looks."""
81
+ cwd = Path.cwd()
82
+ top = _git(cwd, "rev-parse", "--show-toplevel")
83
+ return Path(top) if top else cwd
84
+
85
+
86
+ def _plan_path(root: Path, plan: str) -> Path:
87
+ path = Path(plan)
88
+ return path if path.is_absolute() else root / path
89
+
90
+
71
91
  def _resolve_name(args: argparse.Namespace) -> str | None:
72
92
  if args.name:
73
93
  return args.name
94
+ root = args.root
74
95
  extra = ["--plan", Path(args.plan).stem] if args.plan else []
75
- branch = _git("rev-parse", "--abbrev-ref", "HEAD")
96
+ branch = _git(root, "rev-parse", "--abbrev-ref", "HEAD")
76
97
  if not extra and branch and branch != "HEAD":
77
98
  # On the default branch there is no workstream name: without --default-branch the resolver names it `branch.main`.
78
- head = _git("symbolic-ref", "--short", "refs/remotes/origin/HEAD") or ""
99
+ head = _git(root, "symbolic-ref", "--short", "refs/remotes/origin/HEAD") or ""
79
100
  extra = ["--branch", branch, "--default-branch", head.split("/", 1)[-1] if head else "main"]
80
- res = _run("caddis_workstreams.py", "resolve", *extra)
101
+ res = _run(root, "caddis_workstreams.py", "resolve", *extra)
81
102
  if res is None or res.returncode != 0:
82
103
  return None
83
104
  return res.stdout.strip() or None
@@ -86,9 +107,9 @@ def _resolve_name(args: argparse.Namespace) -> str | None:
86
107
  _NO_COORDINATOR = "no coordinator config"
87
108
 
88
109
 
89
- def _coordinator_relay() -> tuple[bool, str | None]:
110
+ def _coordinator_relay(root: Path) -> tuple[bool, str | None]:
90
111
  """(known, relay). known is False when the check cannot run or its answer cannot be read."""
91
- res = _run("caddis_coordinate.py", "config", "show", "--path", ".", "--json")
112
+ res = _run(root, "caddis_coordinate.py", "config", "show", "--path", str(root), "--json")
92
113
  if res is None:
93
114
  return False, "caddis_coordinate.py not installed"
94
115
  if res.returncode != 0:
@@ -106,9 +127,9 @@ def _coordinator_relay() -> tuple[bool, str | None]:
106
127
  return True, relay if isinstance(relay, str) else None
107
128
 
108
129
 
109
- def _own_files(session_id: str) -> list[str]:
130
+ def _own_files(root: Path, session_id: str) -> list[str]:
110
131
  """The `## Files changed this session` list of the session state file (handoff Step 0, point 1)."""
111
- path = Path(".caddis") / "session-state" / f"{session_id}.md"
132
+ path = root / ".caddis" / "session-state" / f"{session_id}.md"
112
133
  try:
113
134
  lines = path.read_text(encoding="utf-8").splitlines()
114
135
  except (OSError, ValueError):
@@ -122,13 +143,13 @@ def _own_files(session_id: str) -> list[str]:
122
143
  return out
123
144
 
124
145
 
125
- def _shared(session_id: str) -> str:
146
+ def _shared(root: Path, session_id: str) -> str:
126
147
  """`no`, `yes <reason>`, or `unknown (<why>)`. FINISH treats anything but `no` as shared."""
127
148
  fd, tmp = tempfile.mkstemp(prefix="caddis-own-files-", suffix=".txt")
128
149
  try:
129
150
  with os.fdopen(fd, "w", encoding="utf-8") as handle:
130
- handle.write("\n".join(_own_files(session_id)) + "\n")
131
- res = _run("caddis_checkout_guard.py", "shared", "--root", ".", "--own-files", tmp)
151
+ handle.write("\n".join(_own_files(root, session_id)) + "\n")
152
+ res = _run(root, "caddis_checkout_guard.py", "shared", "--root", str(root), "--own-files", tmp)
132
153
  finally:
133
154
  try:
134
155
  os.unlink(tmp)
@@ -142,26 +163,27 @@ def _shared(session_id: str) -> str:
142
163
  return "unknown (" + (_output(res)[:200] or "no answer") + ")"
143
164
 
144
165
 
145
- def _tasks_file(session_id: str, name: str) -> tuple[str, str]:
166
+ def _tasks_file(root: Path, session_id: str, name: str) -> tuple[str, str]:
146
167
  """Run `session_state.py tasks-file`; return (row status, tasks line text)."""
147
- res = _run("session_state.py", "tasks-file", "--session-id", session_id, "--relay", name)
168
+ res = _run(root, "session_state.py", "tasks-file", "--session-id", session_id, "--relay", name,
169
+ "--root", str(root))
148
170
  if res is None:
149
171
  status = "skipped: session_state.py not installed"
150
172
  elif res.returncode != 0:
151
173
  status = "failed: " + (_output(res)[:200] or f"exit {res.returncode}")
152
174
  else:
153
175
  status = "done"
154
- rel = f".caddis/relay/{name}.tasks.md"
155
- if Path(rel).is_file():
176
+ rel = f".caddis/relay/{name}.tasks.md" # printed repo-relative, checked under the root
177
+ if (root / rel).is_file():
156
178
  return status, f"{rel} (put this line in the resume prompt: Load every row of {rel} with TaskCreate.)"
157
179
  return status, "none"
158
180
 
159
181
 
160
- def _refusals(name: str) -> int | None:
182
+ def _refusals(root: Path, name: str) -> int | None:
161
183
  if _headless():
162
184
  print("CHECKPOINT: refused headless: return BLOCKED with your state")
163
185
  return 1
164
- known, relay = _coordinator_relay()
186
+ known, relay = _coordinator_relay(root)
165
187
  if not known:
166
188
  print(f"CHECKPOINT: cannot tell if {name} is the coordinator relay ({relay}): run /caddis:handoff")
167
189
  return 1
@@ -179,17 +201,18 @@ def prepare(args: argparse.Namespace) -> int:
179
201
  if not name:
180
202
  print("CHECKPOINT: no workstream name: pass --name <ws>")
181
203
  return 1
182
- refused = _refusals(name)
204
+ root = args.root
205
+ refused = _refusals(root, name)
183
206
  if refused is not None:
184
207
  return refused
185
- hashed = _run("caddis_workstreams.py", "hash", name, "--root", ".")
208
+ hashed = _run(root, "caddis_workstreams.py", "hash", name, "--root", str(root))
186
209
  if hashed is None or hashed.returncode != 0:
187
210
  why = "caddis_workstreams.py not installed" if hashed is None else _output(hashed)[:200]
188
211
  print(f"CHECKPOINT: cannot read the relay hash: {why}")
189
212
  return 1
190
213
  digest = hashed.stdout.strip() or "none"
191
- shared = _shared(args.session_id)
192
- _status, tasks = _tasks_file(args.session_id, name)
214
+ shared = _shared(root, args.session_id)
215
+ _status, tasks = _tasks_file(root, args.session_id, name)
193
216
  plan = f" --plan {args.plan} --phase {args.phase}" if args.plan and args.phase else ""
194
217
  print(f"workstream: {name}")
195
218
  print(f"relay: .caddis/relay/{name}.md")
@@ -203,13 +226,13 @@ def prepare(args: argparse.Namespace) -> int:
203
226
  return 0
204
227
 
205
228
 
206
- def _tracker_row(plan: str | None, phase: str | None, shared: str) -> str:
229
+ def _tracker_row(root: Path, plan: str | None, phase: str | None, shared: str) -> str:
207
230
  if shared != "no":
208
231
  return SHARED_SKIP
209
232
  if not plan or not phase:
210
233
  return "skipped: no --plan and --phase"
211
234
  try:
212
- lines = Path(plan).read_text(encoding="utf-8").splitlines()
235
+ lines = _plan_path(root, plan).read_text(encoding="utf-8").splitlines()
213
236
  except (OSError, ValueError) as exc:
214
237
  return f"failed: cannot read {plan}: {exc}"
215
238
  pattern = re.compile(rf"^(phase\s+)?{re.escape(phase)}(\s|$)", re.IGNORECASE)
@@ -250,18 +273,20 @@ def finish(args: argparse.Namespace) -> int:
250
273
  if not args.name or not args.expected_hash:
251
274
  print("CHECKPOINT: finish needs --name and --expected-hash (run prepare first)")
252
275
  return 1
253
- refused = _refusals(args.name)
276
+ root = args.root
277
+ refused = _refusals(root, args.name)
254
278
  if refused is not None:
255
279
  return refused
256
280
  name, rows = args.name, {}
257
281
  try:
258
282
  rows["knowledge-transfer"] = _kt_row(args.kt)
259
- rows["plan-tracker"] = _tracker_row(args.plan, args.phase, _shared(args.session_id))
283
+ rows["plan-tracker"] = _tracker_row(root, args.plan, args.phase, _shared(root, args.session_id))
260
284
 
261
285
  # `put` accepts `none` (lower case) or a lower-case SHA-256 hex digest.
262
286
  expected = args.expected_hash.strip().lower()
263
- put = _run("caddis_workstreams.py", "put", name, args.relay_file, "--require-status",
264
- "--expected-hash", expected, "--session-id", args.session_id, "--root", ".")
287
+ # The sibling runs in the root: a relative --relay-file is made absolute against the caller's cwd first.
288
+ put = _run(root, "caddis_workstreams.py", "put", name, os.path.abspath(args.relay_file), "--require-status",
289
+ "--expected-hash", expected, "--session-id", args.session_id, "--root", str(root))
265
290
  except Exception as exc: # no traceback: the next step must be a clear line, and nothing was written
266
291
  print(f"CHECKPOINT: error before the relay write: {type(exc).__name__}: {exc}; the relay was not written")
267
292
  return 1
@@ -276,7 +301,7 @@ def finish(args: argparse.Namespace) -> int:
276
301
  except Exception as exc: # the relay is written: never exit 0 without the resume text
277
302
  if not state["resume"]:
278
303
  try:
279
- _resume_block(name, args.session_id, state)
304
+ _resume_block(root, name, args.session_id, state)
280
305
  except Exception:
281
306
  pass
282
307
  _late_error(f"{type(exc).__name__}: {exc}")
@@ -287,9 +312,10 @@ def _late_error(reason: str) -> None:
287
312
  print(f"ERROR after relay write: {reason}; the relay IS written, resume with the printed relay path")
288
313
 
289
314
 
290
- def _resume_block(name: str, session_id: str, state: dict) -> str | None:
315
+ def _resume_block(root: Path, name: str, session_id: str, state: dict) -> str | None:
291
316
  """Print the resume block; return None when printed, else the reason it could not be built."""
292
- block = _run("caddis_fleet.py", "resume-block", "--name", name, "--session-id", session_id, "--root", ".")
317
+ block = _run(root, "caddis_fleet.py", "resume-block", "--name", name, "--session-id", session_id,
318
+ "--root", str(root))
293
319
  if block is None:
294
320
  return "caddis_fleet.py not installed, no resume block"
295
321
  sys.stdout.write(block.stdout)
@@ -301,15 +327,16 @@ def _resume_block(name: str, session_id: str, state: dict) -> str | None:
301
327
 
302
328
 
303
329
  def _after_put(args: argparse.Namespace, name: str, rows: dict[str, str], state: dict) -> int:
330
+ root = args.root
304
331
  rows["relay"] = "done"
305
- index = _run("caddis_workstreams.py", "render-index", "--session-id", args.session_id, "--root", ".")
332
+ index = _run(root, "caddis_workstreams.py", "render-index", "--session-id", args.session_id, "--root", str(root))
306
333
  if index is not None and index.returncode != 0:
307
334
  rows["relay"] = "done (render-index failed: " + _output(index)[:160] + ")"
308
335
 
309
- rows["tasks-file"], _tasks = _tasks_file(args.session_id, name)
336
+ rows["tasks-file"], _tasks = _tasks_file(root, args.session_id, name)
310
337
 
311
- gate = _run("caddis_gate.py", "handover-check", "--doc", f".caddis/relay/{name}.md", "--repo-root", ".",
312
- "--max-chars", str(BUDGET))
338
+ gate = _run(root, "caddis_gate.py", "handover-check", "--doc", str(root / ".caddis" / "relay" / f"{name}.md"),
339
+ "--repo-root", str(root), "--max-chars", str(BUDGET))
313
340
  if gate is None:
314
341
  rows["handover-check"] = "skipped: caddis_gate.py not installed"
315
342
  elif gate.returncode != 0:
@@ -322,7 +349,7 @@ def _after_put(args: argparse.Namespace, name: str, rows: dict[str, str], state:
322
349
  else:
323
350
  rows["handover-check"] = "done"
324
351
 
325
- usage = _run("session_state.py", "usage", "--session-id", args.session_id)
352
+ usage = _run(root, "session_state.py", "usage", "--session-id", args.session_id, "--root", str(root))
326
353
  if usage is None:
327
354
  rows["usage-record"] = "skipped: session_state.py not installed"
328
355
  elif usage.returncode != 0:
@@ -332,10 +359,10 @@ def _after_put(args: argparse.Namespace, name: str, rows: dict[str, str], state:
332
359
  for row in CHECKPOINT_TIER_ROWS:
333
360
  rows[row] = "skipped: checkpoint tier"
334
361
 
335
- if args.plan and _git("status", "--porcelain", "--", args.plan):
362
+ if args.plan and _git(root, "status", "--porcelain", "--", str(_plan_path(root, args.plan))):
336
363
  print("plan file modified, not committed")
337
364
  _checklist(rows)
338
- failed = _resume_block(name, args.session_id, state)
365
+ failed = _resume_block(root, name, args.session_id, state)
339
366
  if failed is not None:
340
367
  _late_error(failed)
341
368
  return 1
@@ -360,10 +387,11 @@ def main(argv: list[str] | None = None) -> int:
360
387
  p.add_argument("--idle", action="store_true", help="FINISH: no agent or background command runs")
361
388
  args = parser.parse_args(argv)
362
389
  try:
390
+ args.root = _repo_root() # once: every path and every sibling call uses it
363
391
  return finish(args) if args.relay_file else prepare(args)
364
- except Exception as exc: # documented: internal errors exit 0, with no RESUME block
365
- print(f"CHECKPOINT: internal error: {exc}")
366
- return 0
392
+ except Exception as exc: # documented: an internal error exits 1, with no RESUME block
393
+ print(f"CHECKPOINT: internal error: {type(exc).__name__}: {exc}", file=sys.stderr)
394
+ return 1
367
395
 
368
396
 
369
397
  if __name__ == "__main__":