coding-agent-toolchain 1.0.0__py3-none-any.whl

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.
@@ -0,0 +1,3050 @@
1
+ #!/usr/bin/env python3
2
+ """Validate and atomically stage versioned tool/binary Skill pairs."""
3
+
4
+ from __future__ import annotations
5
+
6
+ import argparse
7
+ import ast
8
+ import base64
9
+ from collections.abc import Sequence
10
+ from contextlib import contextmanager
11
+ import fcntl
12
+ import hashlib
13
+ import io
14
+ import json
15
+ import os
16
+ from pathlib import Path
17
+ import re
18
+ import shutil
19
+ import stat
20
+ import subprocess
21
+ import sys
22
+ import tarfile
23
+ import tempfile
24
+ import time
25
+ import tomllib
26
+ from typing import Any
27
+
28
+ VERSION = "1.0.0"
29
+ SCHEMA_VERSION = 1
30
+ TOOL_SKILL_MANIFEST_SCHEMA_VERSION = 2
31
+ SKILL_NAME = "git-change-delivery"
32
+ COMPATIBILITY_SKILL_NAME = "three-tool-git-workflow"
33
+ COMPATIBILITY_BUNDLE_PATH = (
34
+ Path("compatibility") / COMPATIBILITY_SKILL_NAME / "SKILL.md"
35
+ )
36
+ SKILL_PAYLOAD = (
37
+ "SKILL.md",
38
+ "quick_validate.py",
39
+ "unpublished_queue.py",
40
+ "references/context-loader.md",
41
+ "references/git-finalizer.md",
42
+ "references/snapshot-runner.md",
43
+ "references/unpublished-queue.md",
44
+ )
45
+ HEX_SHA256 = re.compile(r"[0-9a-f]{64}\Z")
46
+ FULL_GIT_OID = re.compile(r"[0-9a-f]{40,64}\Z")
47
+ SAFE_NAME = re.compile(r"[a-z0-9][a-z0-9._-]*\Z")
48
+ VERSION_LITERAL_RE = re.compile(r"[0-9]+\.[0-9]+\.[0-9]+\Z")
49
+ DEFAULT_LOCK_TIMEOUT = 10.0
50
+ # Payload-tree digests of previously released canonical Skill lines that may
51
+ # legally sit in production before an upgrade. Never add a digest produced by
52
+ # local hand-editing. Keep RELEASED_CANONICAL_SKILL_SHA256 strictly bound to
53
+ # digests published in tagged/integrated git history.
54
+ RELEASED_CANONICAL_SKILL_SHA256 = frozenset(
55
+ {
56
+ # Provider-neutral payload of the first shipped canonical line.
57
+ "ff6d5bea2807b2c884c2ec5bee441e5fe8060abd9d03c0520c57ce39fe37adb5",
58
+ # Canonical payload carried by the two tagged releases of that line.
59
+ "3c8679b6cfd6578da41007feeea43e7ff83e8152e3daea9ab9154055642a92e2",
60
+ # Canonical payload carried by the merged live-policy release.
61
+ "7b85ec9da739bd60f76736ae6352e642dbf880bbd089058cce4cf7a9c0b5c665",
62
+ # Canonical payload carried by the handoff-documentation release, which
63
+ # is also the installed production tree this batch upgrades from.
64
+ "9c05e5b279731a37b3ce15e2fbda7ae9962f81355cbafb86fa410f28ec19f527",
65
+ # Canonical payload carried by the integration-boundary release and by
66
+ # the first publicly released line after it; both tags shipped it
67
+ # unchanged, so a production tree holding it is released lineage.
68
+ "0c82bceb12edde749aa6deddab25acb4ec083aeea92a37970ec64179ef92726b",
69
+ # Payload independently attested by the next published tag.
70
+ "943ebf4e56ae344cf88ab3dc579d5e497663b052c8ccbade5c42f1f52b5efa93",
71
+ # Published canonical payload at commit 67e3e6c.
72
+ "288d3126d9459913714aa2e3934773111b2d4430fb73a8385fd33511807a823c",
73
+ # Published canonical payload at v1.9.9 (ceae77f).
74
+ "010cb09faf50921149b5d22b26093d9445d15461e8d3f10b7faff35259cd8e45",
75
+ # Published canonical payload at git-finalizer v2.0.0.
76
+ "d1525f9aeb9dcdda18fc9a5e8914ba3ba7c7ed26d9ec5463ca1359b428940bf1",
77
+ }
78
+ )
79
+
80
+
81
+ class SyncError(Exception):
82
+ """A validation or safe activation condition was not met."""
83
+
84
+
85
+ def canonical_json(value: Any) -> bytes:
86
+ return (
87
+ json.dumps(value, ensure_ascii=False, sort_keys=True, indent=2) + "\n"
88
+ ).encode()
89
+
90
+
91
+ def sha256_bytes(value: bytes) -> str:
92
+ return hashlib.sha256(value).hexdigest()
93
+
94
+
95
+ def sha256_file(path: Path) -> str:
96
+ digest = hashlib.sha256()
97
+ with path.open("rb") as stream:
98
+ for chunk in iter(lambda: stream.read(1024 * 1024), b""):
99
+ digest.update(chunk)
100
+ return digest.hexdigest()
101
+
102
+
103
+ def read_json(path: Path) -> dict[str, Any]:
104
+ try:
105
+ raw = path.read_bytes()
106
+ value = json.loads(raw.decode("utf-8"))
107
+ except (OSError, UnicodeError, json.JSONDecodeError) as exc:
108
+ raise SyncError(f"invalid JSON {path}: {exc}") from exc
109
+ if not isinstance(value, dict):
110
+ raise SyncError(f"JSON root must be an object: {path}")
111
+ if raw != canonical_json(value):
112
+ raise SyncError(f"JSON is not deterministically serialized: {path}")
113
+ return value
114
+
115
+
116
+ def write_json(path: Path, value: dict[str, Any], mode: int = 0o600) -> None:
117
+ path.write_bytes(canonical_json(value))
118
+ path.chmod(mode)
119
+
120
+
121
+ def require_regular(path: Path, label: str) -> None:
122
+ if path.is_symlink() or not path.is_file():
123
+ raise SyncError(f"{label} is not a regular file: {path}")
124
+
125
+
126
+ def require_owned_directory(path: Path, *, create: bool = False) -> None:
127
+ if create and not path.exists():
128
+ path.mkdir(mode=0o700, parents=True)
129
+ if path.is_symlink() or not path.is_dir():
130
+ raise SyncError(f"directory is missing or unsafe: {path}")
131
+ if path.stat().st_uid != os.getuid():
132
+ raise SyncError(f"directory is not owned by current user: {path}")
133
+
134
+
135
+ def _flock_exclusive_bounded(descriptor: int, *, timeout: float = DEFAULT_LOCK_TIMEOUT, label: str = "lock") -> None:
136
+ deadline = time.monotonic() + timeout
137
+ while True:
138
+ try:
139
+ fcntl.flock(descriptor, fcntl.LOCK_EX | fcntl.LOCK_NB)
140
+ return
141
+ except BlockingIOError as exc:
142
+ if time.monotonic() >= deadline:
143
+ raise SyncError(f"timed out waiting for {label}") from exc
144
+ time.sleep(0.05)
145
+
146
+
147
+ @contextmanager
148
+ def deployment_lock(*roots: Path, timeout: float = DEFAULT_LOCK_TIMEOUT):
149
+ """Serialize installers through the same persistent locks, including rollback."""
150
+ descriptors = []
151
+ try:
152
+ for root in sorted({path.absolute() for path in roots}):
153
+ require_owned_directory(root, create=True)
154
+ descriptor = os.open(
155
+ root / ".tool-skill-sync.lock",
156
+ os.O_CREAT | os.O_RDWR | os.O_NOFOLLOW | os.O_CLOEXEC,
157
+ 0o600,
158
+ )
159
+ descriptors.append(descriptor)
160
+ info = os.fstat(descriptor)
161
+ if not stat.S_ISREG(info.st_mode) or info.st_uid != os.getuid() or info.st_mode & 0o077:
162
+ raise SyncError("unsafe deployment lock")
163
+ _flock_exclusive_bounded(descriptor, timeout=timeout, label="deployment lock")
164
+ yield
165
+ finally:
166
+ for descriptor in reversed(descriptors):
167
+ os.close(descriptor)
168
+
169
+
170
+ def tree_sha256(root: Path, relative_paths: Sequence[str]) -> str:
171
+ lines: list[str] = []
172
+ for relative in relative_paths:
173
+ path = root / relative
174
+ require_regular(path, "Skill payload")
175
+ lines.append(f"{sha256_file(path)} {relative}\n")
176
+ return sha256_bytes("".join(lines).encode())
177
+
178
+
179
+ def aggregate_hash(values: dict[str, str]) -> str:
180
+ return sha256_bytes(canonical_json(values))
181
+
182
+
183
+ def run(
184
+ arguments: Sequence[str],
185
+ *,
186
+ cwd: Path | None = None,
187
+ env: dict[str, str] | None = None,
188
+ ) -> subprocess.CompletedProcess[str]:
189
+ return subprocess.run(
190
+ arguments,
191
+ cwd=cwd,
192
+ env=env,
193
+ check=False,
194
+ capture_output=True,
195
+ text=True,
196
+ timeout=30,
197
+ )
198
+
199
+
200
+ def git(repo: Path, *arguments: str) -> str:
201
+ result = run(("git", "-C", str(repo), *arguments))
202
+ if result.returncode != 0:
203
+ detail = result.stderr.strip() or result.stdout.strip() or "unknown git error"
204
+ raise SyncError(f"git {' '.join(arguments)} failed for {repo}: {detail}")
205
+ return result.stdout.strip()
206
+
207
+
208
+ def git_head(repo: Path) -> str:
209
+ head = git(repo, "rev-parse", "HEAD")
210
+ if not FULL_GIT_OID.fullmatch(head):
211
+ raise SyncError(f"repository HEAD is not a full object id: {repo}")
212
+ return head
213
+
214
+
215
+ def git_dirty(repo: Path) -> bool:
216
+ environment = os.environ.copy()
217
+ environment["GIT_OPTIONAL_LOCKS"] = "0"
218
+ result = run(
219
+ ("git", "-C", str(repo), "status", "--porcelain=v1", "--untracked-files=all"),
220
+ env=environment,
221
+ )
222
+ if result.returncode != 0:
223
+ detail = result.stderr.strip() or result.stdout.strip() or "unknown git error"
224
+ raise SyncError(f"git status failed for {repo}: {detail}")
225
+ return bool(result.stdout.strip())
226
+
227
+
228
+ def project_version(repo: Path, tool_name: str, *, kind: str | None = None) -> tuple[str, tuple[str, ...]]:
229
+ pyproject = repo / "pyproject.toml"
230
+ use_pyproject = kind == "python_console_scripts" or (
231
+ kind is None
232
+ and tool_name in {"agent-toolchain", "context-loader", "snapshot-runner", "git-finalizer"}
233
+ and pyproject.is_file()
234
+ )
235
+ if use_pyproject:
236
+ require_regular(pyproject, "project metadata")
237
+ with pyproject.open("rb") as stream:
238
+ data = tomllib.load(stream)
239
+ version = data.get("project", {}).get("version")
240
+ scripts = data.get("project", {}).get("scripts", {})
241
+ if not isinstance(version, str) or not isinstance(scripts, dict):
242
+ raise SyncError(f"invalid project version/scripts: {pyproject}")
243
+ return version, tuple(sorted(str(name) for name in scripts))
244
+
245
+ manifest_candidates = (
246
+ repo / "tool_skill_manifest.json",
247
+ repo / "manifests" / tool_name / "tool_skill_manifest.json",
248
+ )
249
+ manifest_path = next((p for p in manifest_candidates if p.exists()), manifest_candidates[0])
250
+ manifest = read_json(manifest_path)
251
+ entrypoints = validate_install_targets(manifest)
252
+ if manifest["executable"]["kind"] == "python_console_scripts":
253
+ return project_version(repo, tool_name, kind="python_console_scripts")
254
+ executable = repo / entrypoints[0]
255
+ require_regular(executable, "Git Finalizer executable")
256
+ match = re.search(
257
+ rb"(?m)^(?:readonly )?(?:VERSION|__version__)\s*=\s*['\"]([0-9]+\.[0-9]+\.[0-9]+)['\"]$",
258
+ executable.read_bytes(),
259
+ )
260
+ if match is None:
261
+ raise SyncError("cannot read source version")
262
+ return match.group(1).decode(), tuple(sorted(entrypoints))
263
+
264
+
265
+ class Sources:
266
+ def __init__(
267
+ self, source_root: Path, source_repos: dict[str, Path] | None = None,
268
+ source_refs: dict[str, str] | None = None,
269
+ ) -> None:
270
+ self.source_root = source_root.resolve()
271
+ self.source_refs = dict(source_refs or {})
272
+ self.source_repos = {
273
+ name: path.resolve() for name, path in (source_repos or {}).items()
274
+ }
275
+ self.owner_repo = self.source_repos.get(
276
+ "git-finalizer", self.source_root / "git-finalizer"
277
+ )
278
+ require_owned_directory(self.owner_repo)
279
+ self.compatibility_path = self.owner_repo / "toolchain_compatibility.json"
280
+ self.compatibility = read_json(self.compatibility_path)
281
+ if self.compatibility.get("schema_version") != SCHEMA_VERSION:
282
+ raise SyncError("unsupported toolchain compatibility schema_version")
283
+ workflow_skill = self.compatibility.get("workflow_skill")
284
+ if workflow_skill != {
285
+ "name": SKILL_NAME,
286
+ "contract_version": workflow_skill.get("contract_version")
287
+ if isinstance(workflow_skill, dict) else None,
288
+ "canonical_owner": "git-finalizer",
289
+ "compatibility_shims": [COMPATIBILITY_SKILL_NAME],
290
+ }:
291
+ raise SyncError("toolchain workflow Skill binding is unrecognized")
292
+ if workflow_skill["contract_version"] not in {1, 2}:
293
+ raise SyncError("unsupported workflow Skill contract version")
294
+ tools = self.compatibility.get("tools")
295
+ if not isinstance(tools, dict) or not tools:
296
+ raise SyncError("toolchain compatibility contract has no tools")
297
+ self.tool_config = tools
298
+ if (set(self.source_repos) | set(self.source_refs)) - set(tools):
299
+ raise SyncError("source-repo names an unknown tool")
300
+ self.skill_root = self.owner_repo / "skills" / SKILL_NAME
301
+ self.compatibility_skill_root = (
302
+ self.owner_repo / "skills" / COMPATIBILITY_SKILL_NAME
303
+ )
304
+
305
+ def head(self, tool: str) -> str:
306
+ return self.source_refs.get(tool) or git_head(self.repo(tool))
307
+
308
+ def dirty(self, tool: str) -> bool:
309
+ return False if tool in self.source_refs else git_dirty(self.repo(tool))
310
+
311
+ def source_bytes(self, tool: str, relative: str) -> bytes:
312
+ repo = self.repo(tool)
313
+ if tool not in self.source_refs:
314
+ return (repo / relative).read_bytes()
315
+ if relative not in {"pyproject.toml", "tool_cli_contract.json"}:
316
+ raise SyncError("pinned source reads are limited to package metadata and contract")
317
+ oid = self.source_refs[tool]
318
+ if not FULL_GIT_OID.fullmatch(oid):
319
+ raise SyncError("source-ref requires a full commit OID")
320
+ manifest = read_json(self.manifest_path(tool))
321
+ if manifest["executable"]["kind"] != "python_console_scripts":
322
+ raise SyncError("source-ref only supports released Python console-script metadata")
323
+ if git(repo, "rev-parse", f"{oid}^{{commit}}") != oid:
324
+ raise SyncError("source-ref must identify a commit, not a tag object")
325
+ result = subprocess.run(
326
+ ["git", "-C", str(repo), "show", f"{oid}:{relative}"],
327
+ capture_output=True, check=False, timeout=30,
328
+ )
329
+ if result.returncode:
330
+ raise SyncError(f"pinned source file is unavailable: {tool}/{relative}")
331
+ return result.stdout
332
+
333
+ def project_identity(self, tool: str, *, kind: str | None = None) -> tuple[str, tuple[str, ...]]:
334
+ if tool not in self.source_refs:
335
+ return project_version(self.repo(tool), tool, kind=kind)
336
+ data = tomllib.loads(self.source_bytes(tool, "pyproject.toml").decode())
337
+ return data["project"]["version"], tuple(sorted(data["project"]["scripts"]))
338
+
339
+ def names(self) -> tuple[str, ...]:
340
+ return tuple(sorted(self.tool_config))
341
+
342
+ def repo(self, tool: str) -> Path:
343
+ config = self.tool_config.get(tool)
344
+ if not isinstance(config, dict):
345
+ raise SyncError(f"unknown tool: {tool}")
346
+ if tool in self.source_repos:
347
+ repo = self.source_repos[tool]
348
+ require_owned_directory(repo)
349
+ return repo
350
+ source_directory = config.get("source_directory")
351
+ if not isinstance(source_directory, str) or not SAFE_NAME.fullmatch(
352
+ source_directory
353
+ ):
354
+ raise SyncError(f"unsafe source directory for {tool}")
355
+ repo = (self.source_root / source_directory).resolve()
356
+ if repo.parent != self.source_root:
357
+ raise SyncError(f"source directory escapes source root for {tool}")
358
+ require_owned_directory(repo)
359
+ return repo
360
+
361
+ def manifest_path(self, tool: str) -> Path:
362
+ config = self.tool_config.get(tool, {})
363
+ manifest_rel = config.get("skill_manifest")
364
+ if manifest_rel:
365
+ return (self.owner_repo / manifest_rel).resolve()
366
+ repo = self.repo(tool)
367
+ repo_manifest = repo / "tool_skill_manifest.json"
368
+ if repo_manifest.exists():
369
+ return repo_manifest
370
+ internal_manifest = (
371
+ self.owner_repo / "manifests" / tool / "tool_skill_manifest.json"
372
+ )
373
+ if internal_manifest.exists():
374
+ return internal_manifest
375
+ return repo_manifest
376
+
377
+
378
+ def validate_install_targets(
379
+ manifest: dict[str, Any], *, allow_legacy: bool = False
380
+ ) -> tuple[str, ...]:
381
+ executable = manifest.get("executable")
382
+ install_targets = manifest.get("install_targets")
383
+ if not isinstance(executable, dict) or not isinstance(install_targets, dict):
384
+ raise SyncError("manifest executable/install_targets must be objects")
385
+ kind = executable.get("kind")
386
+ if kind not in {"python_console_scripts", "source_files"}:
387
+ raise SyncError(f"unsupported executable kind: {kind}")
388
+ entrypoints = executable.get("entrypoints")
389
+ stable_entries = install_targets.get("stable_entries")
390
+ if (
391
+ not isinstance(entrypoints, list)
392
+ or not entrypoints
393
+ or not isinstance(stable_entries, list)
394
+ or tuple(entrypoints) != tuple(stable_entries)
395
+ ):
396
+ raise SyncError("manifest entrypoints and stable_entries must match")
397
+ if any(
398
+ not isinstance(name, str) or not SAFE_NAME.fullmatch(name)
399
+ for name in entrypoints
400
+ ):
401
+ raise SyncError("manifest contains unsafe entrypoint")
402
+ expected_skill = SKILL_NAME
403
+ if allow_legacy and manifest.get("schema_version") == 1:
404
+ expected_skill = COMPATIBILITY_SKILL_NAME
405
+ if install_targets.get("skill_directory") != expected_skill:
406
+ raise SyncError("manifest has unrecognized Skill install target")
407
+ if kind == "source_files":
408
+ paths = executable.get("paths")
409
+ if not isinstance(paths, list) or not paths:
410
+ raise SyncError("source_files executable requires paths")
411
+ if any(
412
+ not isinstance(path, str)
413
+ or Path(path).is_absolute()
414
+ or ".." in Path(path).parts
415
+ for path in paths
416
+ ):
417
+ raise SyncError("manifest contains unsafe executable source path")
418
+ production_targets = executable.get("production_targets")
419
+ if not isinstance(production_targets, dict) or set(production_targets) != set(
420
+ paths
421
+ ):
422
+ raise SyncError(
423
+ "source_files executable requires one production target per path"
424
+ )
425
+ for relative in production_targets.values():
426
+ if (
427
+ not isinstance(relative, str)
428
+ or Path(relative).is_absolute()
429
+ or ".." in Path(relative).parts
430
+ or not Path(relative).parts
431
+ or Path(relative).parts[0] not in {"bin", "hooks"}
432
+ ):
433
+ raise SyncError("manifest contains unsafe production target")
434
+ elif "production_targets" in executable:
435
+ raise SyncError("python_console_scripts must not declare production targets")
436
+ return tuple(str(name) for name in entrypoints)
437
+
438
+
439
+ def validate_contract_shape(contract: dict[str, Any]) -> None:
440
+ commands = contract.get("commands")
441
+ operation_classes = contract.get("operation_classes")
442
+ protected_operations = contract.get("protected_operations")
443
+ if not isinstance(commands, list) or not commands:
444
+ raise SyncError("public CLI contract must contain commands")
445
+ if not isinstance(operation_classes, list) or not operation_classes:
446
+ raise SyncError("public CLI contract must contain operation_classes")
447
+ if not isinstance(protected_operations, list):
448
+ raise SyncError("public CLI contract protected_operations must be a list")
449
+ allowed_classes = {"read_only", "local_mutation", "remote_mutation"}
450
+ if not set(operation_classes) <= allowed_classes:
451
+ raise SyncError("public CLI contract has an unknown operation_class")
452
+ names: set[str] = set()
453
+ for command in commands:
454
+ if not isinstance(command, dict):
455
+ raise SyncError("public CLI contract command must be an object")
456
+ name = command.get("name")
457
+ if not isinstance(name, str) or not SAFE_NAME.fullmatch(name) or name in names:
458
+ raise SyncError("public CLI contract command name is invalid or duplicated")
459
+ names.add(name)
460
+ if command.get("operation_class") not in operation_classes:
461
+ raise SyncError("command operation_class is not declared")
462
+ for key in ("flags", "preconditions", "result_statuses"):
463
+ if not isinstance(command.get(key), list):
464
+ raise SyncError(f"public CLI contract command {key} must be a list")
465
+
466
+
467
+ def validate_manifest_static_fields(
468
+ manifest: dict[str, Any], *, allow_legacy: bool = False
469
+ ) -> None:
470
+ required = {
471
+ "schema_version",
472
+ "tool_name",
473
+ "tool_version",
474
+ "tool_commit",
475
+ "skill_contract_version",
476
+ "public_cli_contract_sha256",
477
+ "canonical_skill_sha256",
478
+ "compatible_toolchain_contract_version",
479
+ "canonical_skill",
480
+ "executable",
481
+ "install_targets",
482
+ }
483
+ legacy = allow_legacy and manifest.get("schema_version") == 1
484
+ if not legacy:
485
+ required.add("compatibility_skill")
486
+ if set(manifest) != required:
487
+ raise SyncError("ToolSkillManifest fields do not match its schema")
488
+ for key in ("public_cli_contract_sha256", "canonical_skill_sha256"):
489
+ if not isinstance(manifest.get(key), str) or not HEX_SHA256.fullmatch(
490
+ manifest[key]
491
+ ):
492
+ raise SyncError(f"ToolSkillManifest {key} is not SHA-256")
493
+ expected_name = COMPATIBILITY_SKILL_NAME if legacy else SKILL_NAME
494
+ canonical_skill = manifest.get("canonical_skill")
495
+ if canonical_skill != {
496
+ "owner": "git-finalizer",
497
+ "path": f"skills/{expected_name}/SKILL.md",
498
+ }:
499
+ raise SyncError("ToolSkillManifest canonical Skill authority is unrecognized")
500
+ if legacy:
501
+ return
502
+ compatibility_skill = manifest.get("compatibility_skill")
503
+ if (
504
+ not isinstance(compatibility_skill, dict)
505
+ or set(compatibility_skill) != {"name", "path", "sha256"}
506
+ or compatibility_skill.get("name") != COMPATIBILITY_SKILL_NAME
507
+ or compatibility_skill.get("path")
508
+ != f"skills/{COMPATIBILITY_SKILL_NAME}/SKILL.md"
509
+ ):
510
+ raise SyncError("ToolSkillManifest compatibility Skill binding is invalid")
511
+ digest = compatibility_skill.get("sha256")
512
+ if not isinstance(digest, str) or not HEX_SHA256.fullmatch(digest):
513
+ raise SyncError("ToolSkillManifest compatibility Skill SHA is invalid")
514
+
515
+
516
+ def validate_controller_requirements(requirements: Any) -> None:
517
+ keys = {"cli_contract_versions", "storage_layout_versions", "capability_versions"}
518
+ if not isinstance(requirements, dict) or set(requirements) != keys:
519
+ raise SyncError("missing or malformed reviewed Controller runtime requirements")
520
+ for key in ("cli_contract_versions", "storage_layout_versions"):
521
+ values = requirements[key]
522
+ if (not isinstance(values, list) or not values
523
+ or any(type(value) is not int or value <= 0 for value in values)
524
+ or len(set(values)) != len(values)):
525
+ raise SyncError(f"invalid Controller {key}")
526
+ capabilities = requirements["capability_versions"]
527
+ if not isinstance(capabilities, dict) or "capabilities_version" not in capabilities:
528
+ raise SyncError("Controller capability_versions must bind capabilities_version")
529
+ for name, value in capabilities.items():
530
+ if (not isinstance(name, str) or not re.fullmatch(r"[a-z][a-z0-9_]*_version", name)
531
+ or type(value) is not int or value <= 0):
532
+ raise SyncError("invalid Controller capability version binding")
533
+
534
+
535
+ def check_tool(sources: Sources, tool: str) -> dict[str, Any]:
536
+ errors: list[str] = []
537
+ repo = sources.repo(tool)
538
+ manifest_path = sources.manifest_path(tool)
539
+ try:
540
+ manifest = read_json(manifest_path)
541
+ raw_contract = sources.source_bytes(tool, "tool_cli_contract.json")
542
+ contract = json.loads(raw_contract.decode("utf-8"))
543
+ if not isinstance(contract, dict) or canonical_json(contract) != raw_contract:
544
+ raise SyncError("source contract is not deterministically serialized")
545
+ if manifest.get("schema_version") != TOOL_SKILL_MANIFEST_SCHEMA_VERSION:
546
+ raise SyncError("unsupported ToolSkillManifest schema_version")
547
+ if contract.get("schema_version") != SCHEMA_VERSION:
548
+ raise SyncError("unsupported public CLI contract schema_version")
549
+ if manifest.get("tool_name") != tool or contract.get("tool_name") != tool:
550
+ raise SyncError("tool_name mismatch")
551
+ validate_manifest_static_fields(manifest)
552
+ validate_contract_shape(contract)
553
+ if manifest.get("tool_version") != contract.get("tool_version"):
554
+ raise SyncError("tool version mismatch between manifest and CLI contract")
555
+ source_version, source_entrypoints = sources.project_identity(
556
+ tool, kind=manifest.get("executable", {}).get("kind")
557
+ )
558
+ if source_version != manifest.get("tool_version"):
559
+ raise SyncError("source version does not match ToolSkillManifest")
560
+ entrypoints = validate_install_targets(manifest)
561
+ if tuple(sorted(entrypoints)) != source_entrypoints:
562
+ raise SyncError("source public entrypoints do not match ToolSkillManifest")
563
+ if manifest.get("tool_commit") != "@release":
564
+ raise SyncError("canonical source manifest tool_commit must be @release")
565
+ sources.head(tool)
566
+ contract_sha = sha256_bytes(raw_contract)
567
+ if manifest.get("public_cli_contract_sha256") != contract_sha:
568
+ raise SyncError("public CLI contract SHA mismatch")
569
+ skill_sha = tree_sha256(sources.skill_root, SKILL_PAYLOAD)
570
+ if manifest.get("canonical_skill_sha256") != skill_sha:
571
+ raise SyncError("canonical Skill payload SHA mismatch")
572
+ compatibility_sha = sha256_file(sources.compatibility_skill_root / "SKILL.md")
573
+ if manifest["compatibility_skill"]["sha256"] != compatibility_sha:
574
+ raise SyncError("compatibility Skill SHA mismatch")
575
+ compatibility_version = sources.compatibility.get("toolchain_contract_version")
576
+ if compatibility_version not in {1, 2, 3, 4, 5, 6}:
577
+ raise SyncError("unsupported toolchain compatibility contract version")
578
+ if compatibility_version == 6:
579
+ runtime_requirements = sources.compatibility.get("runtime_requirements")
580
+ if not isinstance(runtime_requirements, dict):
581
+ raise SyncError("v6 requires explicit runtime_requirements")
582
+ validate_controller_requirements(runtime_requirements.get("worktree-controller"))
583
+ if (
584
+ manifest.get("compatible_toolchain_contract_version")
585
+ != compatibility_version
586
+ ):
587
+ raise SyncError("toolchain compatibility version mismatch")
588
+ config = sources.tool_config[tool]
589
+ if contract.get("contract_version") != config.get(
590
+ "public_cli_contract_version"
591
+ ):
592
+ raise SyncError("public contract version is incompatible with workflow")
593
+ compatibility_key = tool.replace("-", "_") + "_contract_version"
594
+ if sources.compatibility.get(compatibility_key) != config.get(
595
+ "public_cli_contract_version"
596
+ ):
597
+ raise SyncError("top-level toolchain contract binding is inconsistent")
598
+ if manifest.get("skill_contract_version") != config.get(
599
+ "skill_contract_version"
600
+ ):
601
+ raise SyncError("Skill contract version is incompatible with workflow")
602
+ controller_adapter = sources.compatibility.get(
603
+ "worktree_controller_adapter_version"
604
+ )
605
+ controller_status = sources.compatibility.get("worktree_controller_status")
606
+ if compatibility_version == 1:
607
+ if (
608
+ controller_adapter is not None
609
+ or controller_status != "planned_unavailable"
610
+ ):
611
+ raise SyncError(
612
+ "v1 requires Worktree Controller contract to remain null/planned"
613
+ )
614
+ elif (
615
+ controller_adapter
616
+ != (3 if compatibility_version >= 5 else 2 if compatibility_version >= 4 else 1)
617
+ or controller_status != "available_external"
618
+ ):
619
+ raise SyncError(
620
+ "external Worktree Controller contract is incompatible with the toolchain"
621
+ )
622
+ except (OSError, UnicodeError, ValueError, KeyError, TypeError, SyncError) as exc:
623
+ errors.append(str(exc))
624
+ manifest = {}
625
+ contract_sha = None
626
+ skill_sha = None
627
+
628
+ return {
629
+ "tool": tool,
630
+ "status": "PASS" if not errors else "FAIL",
631
+ "canonical_commit": sources.head(tool),
632
+ "canonical_source_dirty": sources.dirty(tool),
633
+ "source_selection": "pinned_commit" if tool in sources.source_refs else "working_checkout",
634
+ "source_checkout_dirty": git_dirty(repo),
635
+ "canonical_tool_version": manifest.get("tool_version"),
636
+ "canonical_skill_sha256": skill_sha,
637
+ "public_cli_contract_sha256": contract_sha,
638
+ "errors": errors,
639
+ }
640
+
641
+
642
+ def extract_version(output: str) -> str | None:
643
+ matches = re.findall(r"(?<![0-9])([0-9]+\.[0-9]+\.[0-9]+)(?![0-9])", output)
644
+ return matches[-1] if matches else None
645
+
646
+
647
+ def bundled_sync_version(bundle: Path) -> str:
648
+ candidates = (
649
+ bundle / "executable" / "src" / "agent_toolchain" / "tool_skill_sync.py",
650
+ bundle / "executable" / "src" / "git_finalizer" / "toolchain" / "tool_skill_sync.py",
651
+ bundle / "executable" / "tooling" / "tool_skill_sync.py",
652
+ )
653
+ implementation = next((p for p in candidates if p.exists() or p.is_symlink()), candidates[0])
654
+ require_regular(implementation, "bundled tool-skill-sync implementation")
655
+ try:
656
+ tree = ast.parse(implementation.read_text(encoding="utf-8"), filename=str(implementation))
657
+ except (SyntaxError, UnicodeDecodeError) as exc:
658
+ raise SyncError(f"bundled tool-skill-sync implementation is unparseable: {exc}") from exc
659
+ versions: list[str] = []
660
+ for node in tree.body:
661
+ if isinstance(node, ast.Assign):
662
+ targets = [t.id for t in node.targets if isinstance(t, ast.Name)]
663
+ value = node.value
664
+ elif isinstance(node, ast.AnnAssign) and isinstance(node.target, ast.Name):
665
+ targets = [node.target.id]
666
+ value = node.value
667
+ else:
668
+ continue
669
+ if (
670
+ "VERSION" in targets
671
+ and isinstance(value, ast.Constant)
672
+ and isinstance(value.value, str)
673
+ and VERSION_LITERAL_RE.fullmatch(value.value)
674
+ ):
675
+ versions.append(value.value)
676
+ if len(versions) != 1:
677
+ raise SyncError("bundled tool-skill-sync VERSION constant is missing or ambiguous")
678
+ return versions[0]
679
+
680
+
681
+ def resolve_entry(name: str, bin_dir: Path | None) -> Path | None:
682
+ if bin_dir is not None:
683
+ candidate = bin_dir / name
684
+ return candidate.resolve() if candidate.exists() else None
685
+ resolved = shutil.which(name)
686
+ return Path(resolved).resolve() if resolved else None
687
+
688
+
689
+ def installed_binary_state(
690
+ entrypoints: Sequence[str], bin_dir: Path | None
691
+ ) -> dict[str, Any]:
692
+ entries: dict[str, dict[str, str | None]] = {}
693
+ hashes: dict[str, str] = {}
694
+ versions: set[str] = set()
695
+ complete = True
696
+ for entrypoint in entrypoints:
697
+ path = resolve_entry(entrypoint, bin_dir)
698
+ if path is None or path.is_symlink() or not path.is_file():
699
+ entries[entrypoint] = {
700
+ "path": str(path) if path else None,
701
+ "sha256": None,
702
+ "version": None,
703
+ }
704
+ complete = False
705
+ continue
706
+ digest = sha256_file(path)
707
+ environment = os.environ.copy()
708
+ environment["PYTHONDONTWRITEBYTECODE"] = "1"
709
+ environment["GIT_OPTIONAL_LOCKS"] = "0"
710
+ result = run((str(path), "--version"), env=environment)
711
+ version = (
712
+ extract_version(result.stdout + "\n" + result.stderr)
713
+ if result.returncode == 0
714
+ else None
715
+ )
716
+ if version is None:
717
+ complete = False
718
+ else:
719
+ versions.add(version)
720
+ hashes[entrypoint] = digest
721
+ entries[entrypoint] = {"path": str(path), "sha256": digest, "version": version}
722
+ installed_version = (
723
+ next(iter(versions)) if complete and len(versions) == 1 else None
724
+ )
725
+ return {
726
+ "version": installed_version,
727
+ "sha256": aggregate_hash(hashes) if complete else None,
728
+ "entries": entries,
729
+ }
730
+
731
+
732
+ def check_tool_deployment(
733
+ sources: Sources,
734
+ tool: str,
735
+ agents_root: Path,
736
+ bin_dir: Path | None,
737
+ hooks_dir: Path | None = None,
738
+ ) -> dict[str, Any]:
739
+ """Validate the source contract and the installed production state together.
740
+
741
+ ``source_contract_status`` keeps the original meaning: the canonical source repo is
742
+ internally consistent. ``installed_drift`` reports whether the executables actually on
743
+ PATH match the declared canonical release. ``status`` is PASS only when both hold, so
744
+ a stale or mismatched installation can no longer be reported as clean.
745
+ """
746
+ checked = check_tool(sources, tool)
747
+ source_status = str(checked["status"])
748
+ installed_skill_sha, installed_compatibility_sha = installed_skill_hashes(
749
+ agents_root
750
+ )
751
+ errors = list(checked["errors"])
752
+ binary: dict[str, Any] = {"version": None, "sha256": None, "entries": {}}
753
+ drift = "unknown"
754
+ verification: dict[str, Any] = {}
755
+ try:
756
+ manifest = read_json(sources.manifest_path(tool))
757
+ entrypoints = validate_install_targets(manifest)
758
+ binary = installed_binary_state(entrypoints, bin_dir)
759
+ drift = classify_drift(
760
+ manifest,
761
+ source_status=source_status,
762
+ binary_version=binary["version"],
763
+ installed_skill_sha=installed_skill_sha,
764
+ installed_compatibility_sha=installed_compatibility_sha,
765
+ )
766
+ if drift != "none":
767
+ errors.append(
768
+ f"installed production state drifts from the canonical release: {drift}"
769
+ )
770
+ verification = verify_installed_tool_bytes(
771
+ sources, tool, manifest, entrypoints, bin_dir,
772
+ hooks_dir or agents_root / "hooks",
773
+ )
774
+ if verification.get("binary_content_drift"):
775
+ raise SyncError("installed executable/sidecar bytes differ from source")
776
+ except (OSError, ValueError, KeyError, SyncError) as exc:
777
+ errors.append(str(exc))
778
+ if drift == "none":
779
+ drift = "binary_only"
780
+
781
+ result = dict(checked)
782
+ result["source_contract_status"] = source_status
783
+ result["installed_binary_version"] = binary["version"]
784
+ result["installed_binary_sha256"] = binary["sha256"]
785
+ result["installed_binaries"] = binary["entries"]
786
+ result["installed_skill_sha256"] = installed_skill_sha
787
+ result["installed_compatibility_skill_sha256"] = installed_compatibility_sha
788
+ result["installed_drift"] = drift
789
+ result.update(verification)
790
+ result["errors"] = errors
791
+ result["status"] = "PASS" if not errors and source_status == "PASS" and drift == "none" else "FAIL"
792
+ return result
793
+
794
+
795
+ def verify_installed_tool_bytes(
796
+ sources: Sources, tool: str, manifest: dict[str, Any],
797
+ entrypoints: Sequence[str], bin_dir: Path | None, hooks_dir: Path,
798
+ ) -> dict[str, Any]:
799
+ """One read-only artifact check shared by check and doctor."""
800
+ executable = manifest["executable"]
801
+ if executable["kind"] == "python_console_scripts":
802
+ installation = python_tool_installation(entrypoints, bin_dir)
803
+ return {"artifact_verification": verify_installed_record(Path(installation["root"]))}
804
+ first = resolve_entry(entrypoints[0], bin_dir)
805
+ if first is None:
806
+ raise SyncError(f"entrypoint is missing: {entrypoints[0]}")
807
+ live_bin = bin_dir or first.parent
808
+ drift = []
809
+ for relative, target in executable["production_targets"].items():
810
+ parts = Path(target).parts
811
+ if parts[0] not in {"bin", "hooks"}:
812
+ raise SyncError(f"unsupported production target: {target}")
813
+ root = live_bin if parts[0] == "bin" else hooks_dir
814
+ live = root.joinpath(*parts[1:])
815
+ if not live.is_file() or sha256_file(live) != sha256_bytes(sources.source_bytes(tool, relative)):
816
+ drift.append(str(live))
817
+ return {"binary_content_drift": drift}
818
+
819
+
820
+ UV_EXECUTABLE = "uv"
821
+
822
+
823
+ def read_uv_receipt(root: Path) -> dict[str, Any]:
824
+ receipt = root / "uv-receipt.toml"
825
+ require_regular(receipt, "uv tool receipt")
826
+ with receipt.open("rb") as stream:
827
+ return tomllib.load(stream)
828
+
829
+
830
+ def python_tool_installation(
831
+ entrypoints: Sequence[str], bin_dir: Path | None
832
+ ) -> dict[str, Any]:
833
+ """Describe the uv tool installation that backs one tool's console scripts."""
834
+ resolved = {name: resolve_entry(name, bin_dir) for name in entrypoints}
835
+ missing = sorted(name for name, path in resolved.items() if path is None)
836
+ if missing:
837
+ raise SyncError(f"installed entrypoints are missing: {', '.join(missing)}")
838
+ # Retained legacy launchers deliberately live outside the uv tool directory and shim
839
+ # into it, so the uv root is the one directory that actually carries a uv receipt.
840
+ roots = set()
841
+ for path in resolved.values():
842
+ if path is None:
843
+ continue
844
+ for candidate in list(path.parents)[:3]:
845
+ if (candidate / "uv-receipt.toml").is_file():
846
+ roots.add(candidate)
847
+ break
848
+ if not roots:
849
+ raise SyncError(
850
+ "installed entrypoints do not resolve into a uv tool installation"
851
+ )
852
+ if len(roots) != 1:
853
+ raise SyncError("installed entrypoints resolve to more than one uv tool root")
854
+ root = roots.pop()
855
+ require_owned_directory(root)
856
+ receipt = read_uv_receipt(root)
857
+ tool_section = receipt.get("tool", {})
858
+ options = tool_section.get("options", {})
859
+ install_paths = {
860
+ entry["name"]: Path(entry["install-path"])
861
+ for entry in tool_section.get("entrypoints", [])
862
+ if isinstance(entry, dict) and "name" in entry and "install-path" in entry
863
+ }
864
+ if not set(entrypoints) <= set(install_paths):
865
+ raise SyncError("uv receipt does not cover every declared entrypoint")
866
+ directories = {path.parent for path in install_paths.values()}
867
+ if len(directories) != 1:
868
+ raise SyncError("uv receipt entrypoints span more than one bin directory")
869
+ indexes = [
870
+ item["url"]
871
+ for item in options.get("index", [])
872
+ if isinstance(item, dict) and isinstance(item.get("url"), str)
873
+ ]
874
+ return {
875
+ "root": str(root),
876
+ "bin_dir": str(directories.pop()),
877
+ "indexes": indexes,
878
+ "no_build": bool(options.get("no-build", False)),
879
+ "entry_targets": {
880
+ name: str(path) for name, path in sorted(install_paths.items())
881
+ },
882
+ "resolved": {
883
+ name: str(path)
884
+ for name, path in sorted(resolved.items())
885
+ if path is not None
886
+ },
887
+ }
888
+
889
+
890
+ def verify_installed_record(root: Path) -> dict[str, Any]:
891
+ """Verify installed runtime files against the published wheel RECORD."""
892
+ candidates = sorted(root.glob("lib/python*/site-packages"))
893
+ if len(candidates) != 1:
894
+ raise SyncError("uv tool installation has no single site-packages directory")
895
+ site_packages = candidates[0]
896
+ dist_infos = sorted(site_packages.glob("*.dist-info"))
897
+ if not dist_infos:
898
+ raise SyncError("uv tool installation has no dist-info directory")
899
+ verified = 0
900
+ for dist_info in dist_infos:
901
+ record = dist_info / "RECORD"
902
+ require_regular(record, "installed RECORD")
903
+ distribution_verified = 0
904
+ for line in record.read_text(encoding="utf-8").splitlines():
905
+ if not line:
906
+ continue
907
+ name, _, remainder = line.partition(",")
908
+ digest, _, _size = remainder.partition(",")
909
+ # Console scripts live outside site-packages and RECORD lists itself without a hash.
910
+ if not digest.startswith("sha256=") or name.startswith("../"):
911
+ continue
912
+ target = site_packages / name
913
+ if not target.is_file():
914
+ raise SyncError(f"installed file is missing: {name}")
915
+ expected = digest.split("=", 1)[1]
916
+ actual = (
917
+ base64.urlsafe_b64encode(hashlib.sha256(target.read_bytes()).digest())
918
+ .rstrip(b"=")
919
+ .decode()
920
+ )
921
+ if actual != expected:
922
+ raise SyncError(
923
+ f"installed file does not match the published artifact: {name}"
924
+ )
925
+ distribution_verified += 1
926
+ if not distribution_verified:
927
+ raise SyncError(f"installed RECORD verified no files: {dist_info.name}")
928
+ verified += distribution_verified
929
+ if len(dist_infos) == 1:
930
+ return {"dist_info": dist_infos[0].name, "verified_files": verified}
931
+ return {"dist_infos": [path.name for path in dist_infos], "verified_files": verified}
932
+
933
+
934
+ def install_python_tool(
935
+ tool: str,
936
+ version: str,
937
+ *,
938
+ bin_dir: str,
939
+ indexes: Sequence[str],
940
+ no_build: bool,
941
+ ) -> None:
942
+ """Install one pinned uv tool release, preserving the recorded installation shape.
943
+
944
+ ``--force`` is required: ``--reinstall`` removes the existing installation before it
945
+ validates entrypoint conflicts, which can leave production with no working CLI.
946
+ """
947
+ argv = [UV_EXECUTABLE, "tool", "install", "--force"]
948
+ if no_build:
949
+ argv.append("--no-build")
950
+ for index in indexes:
951
+ argv.extend(("--index", index))
952
+ argv.append(f"{tool}=={version}")
953
+ environment = dict(os.environ, UV_TOOL_BIN_DIR=bin_dir)
954
+ result = subprocess.run(
955
+ argv, capture_output=True, text=True, check=False, env=environment
956
+ )
957
+ if result.returncode:
958
+ raise SyncError(
959
+ f"uv tool install failed for {tool}=={version} "
960
+ f"(exit {result.returncode}): {result.stderr.strip()[:200]}"
961
+ )
962
+
963
+
964
+ def install_local_python_tool(
965
+ tool: str,
966
+ source_path: Path,
967
+ *,
968
+ bin_dir: str,
969
+ no_build: bool,
970
+ ) -> None:
971
+ """Install one tool offline from a verified local checkout or exported commit tree."""
972
+ argv = [UV_EXECUTABLE, "tool", "install", "--force", "--offline"]
973
+ if no_build:
974
+ argv.append("--no-build")
975
+ argv.append(os.fspath(source_path))
976
+ environment = dict(os.environ, UV_TOOL_BIN_DIR=bin_dir)
977
+ result = subprocess.run(
978
+ argv, capture_output=True, text=True, check=False, env=environment
979
+ )
980
+ if result.returncode:
981
+ raise SyncError(
982
+ f"uv tool offline install failed for {tool} "
983
+ f"(exit {result.returncode}): {result.stderr.strip()[:200]}"
984
+ )
985
+
986
+
987
+ def _resolves_into_python_venv(entry: Path) -> bool:
988
+ resolved = entry.resolve(strict=False)
989
+ return any((parent / "pyvenv.cfg").is_file() for parent in list(resolved.parents)[:3])
990
+
991
+
992
+ def _legacy_source_files_installation(
993
+ entrypoints: Sequence[str], bin_dir: Path | None
994
+ ) -> dict[str, Any] | None:
995
+ """Describe a legacy `source_files` install so 1.x -> 2.x wheel upgrade works cleanly."""
996
+ targets: dict[str, Path] = {}
997
+ dirs: set[Path] = set()
998
+ for name in entrypoints:
999
+ if bin_dir is not None:
1000
+ candidate = bin_dir / name
1001
+ else:
1002
+ found = shutil.which(name)
1003
+ if not found:
1004
+ return None
1005
+ candidate = Path(found)
1006
+ if not candidate.exists() or _resolves_into_python_venv(candidate):
1007
+ return None
1008
+ targets[name] = candidate
1009
+ dirs.add(candidate.parent.resolve())
1010
+ if len(dirs) != 1:
1011
+ return None
1012
+ target_bin = dirs.pop()
1013
+ return {
1014
+ "root": None,
1015
+ "bin_dir": str(target_bin),
1016
+ "indexes": [],
1017
+ "no_build": False,
1018
+ "entry_targets": {},
1019
+ "resolved": {},
1020
+ "legacy_targets": {name: str(path) for name, path in sorted(targets.items())},
1021
+ "legacy_source_files": True,
1022
+ }
1023
+
1024
+
1025
+ def _backup_legacy_entries(entry_map: dict[str, str]) -> dict[Path, dict[str, Any]]:
1026
+ snapshot: dict[Path, dict[str, Any]] = {}
1027
+ for raw_path in entry_map.values():
1028
+ path = Path(raw_path)
1029
+ if path.is_symlink():
1030
+ snapshot[path] = {"symlink": os.readlink(path)}
1031
+ elif path.is_file():
1032
+ snapshot[path] = {
1033
+ "bytes": path.read_bytes(),
1034
+ "mode": stat.S_IMODE(path.stat().st_mode),
1035
+ }
1036
+ return snapshot
1037
+
1038
+
1039
+ def _restore_legacy_entries(snapshot: dict[Path, dict[str, Any]]) -> None:
1040
+ for path, info in snapshot.items():
1041
+ if "symlink" in info:
1042
+ atomic_symlink(path.parent, path.name, Path(info["symlink"]))
1043
+ continue
1044
+ fd, tmp_name = tempfile.mkstemp(dir=path.parent, prefix=f".{path.name}.restore-")
1045
+ os.close(fd)
1046
+ tmp = Path(tmp_name)
1047
+ try:
1048
+ tmp.write_bytes(info["bytes"])
1049
+ tmp.chmod(info["mode"])
1050
+ os.replace(tmp, path)
1051
+ fsync_directory(path.parent)
1052
+ finally:
1053
+ if tmp.exists():
1054
+ tmp.unlink()
1055
+
1056
+
1057
+ @contextmanager
1058
+ def _local_install_source(sources: Sources, tool: str):
1059
+ repo = sources.repo(tool)
1060
+ if tool not in sources.source_refs:
1061
+ yield repo
1062
+ return
1063
+ oid = sources.source_refs[tool]
1064
+ if not FULL_GIT_OID.fullmatch(oid):
1065
+ raise SyncError("source-ref requires a full commit OID")
1066
+ with tempfile.TemporaryDirectory(prefix=f".{tool}-src-") as staging:
1067
+ archive = subprocess.run(
1068
+ ["git", "-C", str(repo), "archive", "--format=tar", oid],
1069
+ capture_output=True,
1070
+ check=False,
1071
+ timeout=30,
1072
+ )
1073
+ if archive.returncode:
1074
+ raise SyncError(f"git archive failed for pinned {tool}@{oid}")
1075
+ target_dir = Path(staging) / tool
1076
+ target_dir.mkdir(mode=0o700)
1077
+ with tarfile.open(fileobj=io.BytesIO(archive.stdout), mode="r:*") as tf:
1078
+ tf.extractall(target_dir, filter="data")
1079
+ yield target_dir
1080
+
1081
+
1082
+ def canonical_install_policy(
1083
+ sources: Sources, tool: str, observed: dict[str, Any]
1084
+ ) -> tuple[dict[str, Any], bool]:
1085
+ """Return the intended uv install shape and whether the observed receipt drifted.
1086
+
1087
+ ``uv_install_policy`` in the toolchain compatibility contract is authoritative when
1088
+ present, so a receipt that drifted away from the declared bin directory, package index
1089
+ or no-build policy is normalized instead of being preserved. Without a declared policy
1090
+ the observed receipt is kept, which is the previous behavior.
1091
+ """
1092
+ policy = sources.tool_config.get(tool, {}).get("uv_install_policy")
1093
+ if policy is None:
1094
+ return dict(observed), False
1095
+ if not isinstance(policy, dict):
1096
+ raise SyncError(f"{tool} uv_install_policy must be an object")
1097
+ bin_dir = policy.get("bin_dir")
1098
+ if not isinstance(bin_dir, str) or not bin_dir:
1099
+ raise SyncError(f"{tool} uv_install_policy bin_dir is invalid")
1100
+ resolved = Path(bin_dir).expanduser()
1101
+ if not resolved.is_absolute():
1102
+ raise SyncError(
1103
+ f"{tool} uv_install_policy bin_dir must resolve to an absolute path"
1104
+ )
1105
+ indexes = policy.get("index", [])
1106
+ if not isinstance(indexes, list) or not all(
1107
+ isinstance(item, str) and item for item in indexes
1108
+ ):
1109
+ raise SyncError(f"{tool} uv_install_policy index must be a list of URLs")
1110
+ intended = dict(observed)
1111
+ intended["bin_dir"] = os.fspath(resolved)
1112
+ intended["indexes"] = list(indexes)
1113
+ intended["no_build"] = bool(policy.get("no_build", False))
1114
+ drifted = (
1115
+ observed["bin_dir"] != intended["bin_dir"]
1116
+ or observed["no_build"] != intended["no_build"]
1117
+ or not set(intended["indexes"]) <= set(observed["indexes"])
1118
+ )
1119
+ return intended, drifted
1120
+
1121
+
1122
+ def verify_python_tool(
1123
+ tool: str,
1124
+ version: str,
1125
+ entrypoints: Sequence[str],
1126
+ bin_dir: Path | None,
1127
+ expected: dict[str, Any],
1128
+ *,
1129
+ expect_stable_paths: bool = True,
1130
+ ) -> dict[str, Any]:
1131
+ """Fail closed unless every entrypoint, hash and receipt field matches the release."""
1132
+ binary = installed_binary_state(entrypoints, bin_dir)
1133
+ if binary["version"] != version:
1134
+ raise SyncError(
1135
+ f"installed {tool} reports {binary['version']}, expected {version}"
1136
+ )
1137
+ installation = python_tool_installation(entrypoints, bin_dir)
1138
+ if installation["bin_dir"] != expected["bin_dir"]:
1139
+ raise SyncError("upgrade changed the entrypoint bin directory")
1140
+ if installation["no_build"] != expected["no_build"]:
1141
+ raise SyncError("upgrade changed the receipt no-build setting")
1142
+ if not set(expected["indexes"]) <= set(installation["indexes"]):
1143
+ raise SyncError("upgrade dropped a recorded package index")
1144
+ # A release may intentionally remove console scripts, so compare only the entrypoints
1145
+ # the target release declares. Retained entrypoints must keep their exact install path
1146
+ # and resolved target; entrypoints the new release drops are reported as retired.
1147
+ for name in entrypoints if expect_stable_paths else ():
1148
+ previous_target = expected["entry_targets"].get(name)
1149
+ if (
1150
+ previous_target is not None
1151
+ and installation["entry_targets"][name] != previous_target
1152
+ ):
1153
+ raise SyncError(f"upgrade changed the install path of {name}")
1154
+ previous_resolved = expected["resolved"].get(name)
1155
+ if (
1156
+ previous_resolved is not None
1157
+ and installation["resolved"][name] != previous_resolved
1158
+ ):
1159
+ raise SyncError(f"upgrade changed the resolved target of {name}")
1160
+ retired = sorted(set(expected["entry_targets"]) - set(entrypoints))
1161
+ for name in retired:
1162
+ path = Path(expected["entry_targets"][name])
1163
+ if path.exists() or path.is_symlink():
1164
+ raise SyncError(f"upgrade left a retired entrypoint installed: {name}")
1165
+ record = verify_installed_record(Path(installation["root"]))
1166
+ return {
1167
+ "version": binary["version"],
1168
+ "binary_sha256": binary["sha256"],
1169
+ "entries": binary["entries"],
1170
+ "installation": installation,
1171
+ "retired_entrypoints": retired,
1172
+ "record": record,
1173
+ }
1174
+
1175
+
1176
+ def upgrade(
1177
+ sources: Sources,
1178
+ tool: str,
1179
+ *,
1180
+ bin_dir: Path | None,
1181
+ dry_run: bool = False,
1182
+ previous_bundle: Path | None = None,
1183
+ ) -> dict[str, Any]:
1184
+ """Upgrade one console-script tool to its canonical release, or restore the old one."""
1185
+ checked = check_tool(sources, tool)
1186
+ if checked["status"] != "PASS":
1187
+ raise SyncError("canonical check failed: " + "; ".join(checked["errors"]))
1188
+ manifest = read_json(sources.manifest_path(tool))
1189
+ entrypoints = validate_install_targets(manifest)
1190
+ if manifest["executable"]["kind"] != "python_console_scripts":
1191
+ raise SyncError(f"{tool} is not installed as Python console scripts")
1192
+ target_version = str(manifest["tool_version"])
1193
+ previous_entries = entrypoints
1194
+ previous_manifest = None
1195
+ if previous_bundle is not None:
1196
+ verify_bundle(previous_bundle, tool)
1197
+ previous_manifest = read_json(previous_bundle / "tool_skill_manifest.json")
1198
+ if previous_manifest["executable"]["kind"] not in {"python_console_scripts", "source_files"}:
1199
+ raise SyncError("previous bundle is not a supported executable kind")
1200
+ previous_entries = validate_install_targets(previous_manifest, allow_legacy=True)
1201
+ if previous_manifest is not None and previous_manifest["executable"]["kind"] == "source_files":
1202
+ before = _legacy_source_files_installation(previous_entries, bin_dir)
1203
+ if before is None:
1204
+ raise SyncError("legacy source_files installation is incomplete or unavailable")
1205
+ else:
1206
+ try:
1207
+ before = python_tool_installation(previous_entries, bin_dir)
1208
+ except SyncError:
1209
+ legacy = (
1210
+ _legacy_source_files_installation(previous_entries, bin_dir)
1211
+ if previous_manifest is None
1212
+ else None
1213
+ )
1214
+ if legacy is None:
1215
+ raise
1216
+ before = legacy
1217
+ intended, drifted = canonical_install_policy(sources, tool, before)
1218
+ legacy_upgrade = bool(before.get("legacy_source_files"))
1219
+ previous_version = installed_binary_state(previous_entries, bin_dir)["version"]
1220
+ if previous_manifest is not None:
1221
+ if previous_version != previous_manifest["tool_version"]:
1222
+ raise SyncError("installed release does not match the explicit previous bundle")
1223
+ if not legacy_upgrade:
1224
+ verify_python_tool(tool, previous_version, previous_entries, bin_dir, before)
1225
+ stable_paths = intended["bin_dir"] == before["bin_dir"] and not legacy_upgrade
1226
+ plan = {
1227
+ "schema_version": SCHEMA_VERSION,
1228
+ "operation": "upgrade",
1229
+ "tool": tool,
1230
+ "previous_version": previous_version,
1231
+ "target_version": target_version,
1232
+ "bin_dir": intended["bin_dir"],
1233
+ "indexes": intended["indexes"],
1234
+ "no_build": intended["no_build"],
1235
+ "receipt_drifted": drifted,
1236
+ "observed_bin_dir": before["bin_dir"],
1237
+ "observed_no_build": before["no_build"],
1238
+ }
1239
+ if (
1240
+ not legacy_upgrade
1241
+ and previous_version == target_version
1242
+ and not drifted
1243
+ and previous_entries == entrypoints
1244
+ ):
1245
+ plan["status"] = "UNCHANGED"
1246
+ plan["verification"] = verify_python_tool(
1247
+ tool, target_version, entrypoints, bin_dir, intended
1248
+ )
1249
+ return plan
1250
+ if dry_run:
1251
+ plan["status"] = "DRY_RUN_NORMALIZE" if drifted else "DRY_RUN"
1252
+ return plan
1253
+ legacy_backup = (
1254
+ _backup_legacy_entries(before.get("legacy_targets", {})) if legacy_upgrade else None
1255
+ )
1256
+ try:
1257
+ if intended["indexes"]:
1258
+ install_python_tool(
1259
+ tool,
1260
+ target_version,
1261
+ bin_dir=intended["bin_dir"],
1262
+ indexes=intended["indexes"],
1263
+ no_build=intended["no_build"],
1264
+ )
1265
+ else:
1266
+ with _local_install_source(sources, tool) as local_source:
1267
+ install_local_python_tool(
1268
+ tool,
1269
+ local_source,
1270
+ bin_dir=intended["bin_dir"],
1271
+ no_build=intended["no_build"],
1272
+ )
1273
+ plan["verification"] = verify_python_tool(
1274
+ tool,
1275
+ target_version,
1276
+ entrypoints,
1277
+ bin_dir,
1278
+ intended,
1279
+ expect_stable_paths=stable_paths,
1280
+ )
1281
+ except (SyncError, OSError, subprocess.SubprocessError, KeyboardInterrupt) as exc:
1282
+ plan["status"] = "RESTORED"
1283
+ plan["error"] = str(exc)
1284
+ if legacy_backup is not None:
1285
+ try:
1286
+ _restore_legacy_entries(legacy_backup)
1287
+ plan["restored_shape"] = "legacy_source_files"
1288
+ except (SyncError, OSError, subprocess.SubprocessError) as restore_error:
1289
+ plan["status"] = "FAILED"
1290
+ raise SyncError(
1291
+ f"{exc}; restoring legacy {previous_version} also failed: {restore_error}"
1292
+ ) from None
1293
+ if isinstance(exc, KeyboardInterrupt):
1294
+ raise
1295
+ raise SyncError(
1296
+ f"upgrade failed and legacy {previous_version} was restored: {exc}"
1297
+ ) from None
1298
+ if previous_version is None:
1299
+ plan["status"] = "FAILED"
1300
+ raise SyncError(f"{exc}; no previous version recorded to restore") from None
1301
+ try:
1302
+ install_python_tool(
1303
+ tool,
1304
+ previous_version,
1305
+ bin_dir=before["bin_dir"],
1306
+ indexes=before["indexes"],
1307
+ no_build=before["no_build"],
1308
+ )
1309
+ plan["restored_verification"] = verify_python_tool(
1310
+ tool, previous_version, previous_entries, bin_dir, before
1311
+ )
1312
+ for name in set(entrypoints) - set(previous_entries):
1313
+ path = Path(intended["bin_dir"]) / name
1314
+ if path.exists() or path.is_symlink():
1315
+ raise SyncError(f"restoration left a new entrypoint installed: {name}")
1316
+ plan["restored_shape"] = "observed"
1317
+ except (SyncError, OSError, subprocess.SubprocessError) as restore_error:
1318
+ plan["status"] = "FAILED"
1319
+ raise SyncError(
1320
+ f"{exc}; restoring {previous_version} also failed: {restore_error}"
1321
+ ) from None
1322
+ if isinstance(exc, KeyboardInterrupt):
1323
+ raise
1324
+ raise SyncError(
1325
+ f"upgrade failed and {previous_version} was restored: {exc}"
1326
+ ) from None
1327
+ plan["status"] = (
1328
+ "NORMALIZED" if (not legacy_upgrade and previous_version == target_version) else "UPGRADED"
1329
+ )
1330
+ return plan
1331
+
1332
+
1333
+ def installed_skill_hashes(agents_root: Path) -> tuple[str | None, str | None]:
1334
+ """Return the installed canonical and compatibility Skill payload hashes."""
1335
+ try:
1336
+ skill_sha = tree_sha256(agents_root / "skills" / SKILL_NAME, SKILL_PAYLOAD)
1337
+ except SyncError:
1338
+ skill_sha = None
1339
+ compatibility = agents_root / "skills" / COMPATIBILITY_SKILL_NAME / "SKILL.md"
1340
+ try:
1341
+ require_regular(compatibility, "installed compatibility Skill")
1342
+ compatibility_sha = sha256_file(compatibility)
1343
+ except SyncError:
1344
+ compatibility_sha = None
1345
+ return skill_sha, compatibility_sha
1346
+
1347
+
1348
+ def classify_drift(
1349
+ manifest: dict[str, Any],
1350
+ *,
1351
+ source_status: str,
1352
+ binary_version: str | None,
1353
+ installed_skill_sha: str | None,
1354
+ installed_compatibility_sha: str | None,
1355
+ ) -> str:
1356
+ """Classify installed production state against the declared canonical release."""
1357
+ binary_matches = binary_version == manifest.get("tool_version")
1358
+ skill_matches = installed_skill_sha == manifest.get(
1359
+ "canonical_skill_sha256"
1360
+ ) and installed_compatibility_sha == manifest.get("compatibility_skill", {}).get(
1361
+ "sha256"
1362
+ )
1363
+ if source_status != "PASS" or (not binary_matches and not skill_matches):
1364
+ return "incompatible"
1365
+ if binary_matches and skill_matches:
1366
+ return "none"
1367
+ if binary_matches:
1368
+ return "skill_only"
1369
+ return "binary_only"
1370
+
1371
+
1372
+ def status(sources: Sources, agents_root: Path, bin_dir: Path | None) -> dict[str, Any]:
1373
+ result: dict[str, Any] = {
1374
+ "schema_version": SCHEMA_VERSION,
1375
+ "operation": "status",
1376
+ "tools": [],
1377
+ }
1378
+ installed_skill_sha, installed_compatibility_sha = installed_skill_hashes(
1379
+ agents_root
1380
+ )
1381
+
1382
+ for tool in sources.names():
1383
+ checked = check_tool(sources, tool)
1384
+ try:
1385
+ manifest = read_json(sources.manifest_path(tool))
1386
+ entrypoints = validate_install_targets(manifest)
1387
+ except SyncError:
1388
+ result["tools"].append(
1389
+ {
1390
+ "tool_name": tool,
1391
+ "canonical_tool_version": checked["canonical_tool_version"],
1392
+ "canonical_commit": checked["canonical_commit"],
1393
+ "canonical_source_dirty": checked["canonical_source_dirty"],
1394
+ "canonical_skill_sha256": checked["canonical_skill_sha256"],
1395
+ "public_cli_contract_sha256": checked["public_cli_contract_sha256"],
1396
+ "installed_binary_version": None,
1397
+ "installed_binary_sha256": None,
1398
+ "installed_binaries": {},
1399
+ "installed_skill_sha256": installed_skill_sha,
1400
+ "installed_compatibility_skill_sha256": (
1401
+ installed_compatibility_sha
1402
+ ),
1403
+ "drift": "incompatible",
1404
+ }
1405
+ )
1406
+ continue
1407
+ binary = installed_binary_state(entrypoints, bin_dir)
1408
+ drift = classify_drift(
1409
+ manifest,
1410
+ source_status=str(checked["status"]),
1411
+ binary_version=binary["version"],
1412
+ installed_skill_sha=installed_skill_sha,
1413
+ installed_compatibility_sha=installed_compatibility_sha,
1414
+ )
1415
+ result["tools"].append(
1416
+ {
1417
+ "tool_name": tool,
1418
+ "canonical_tool_version": manifest.get("tool_version"),
1419
+ "canonical_commit": sources.head(tool),
1420
+ "canonical_source_dirty": sources.dirty(tool),
1421
+ "canonical_skill_sha256": manifest.get("canonical_skill_sha256"),
1422
+ "public_cli_contract_sha256": manifest.get(
1423
+ "public_cli_contract_sha256"
1424
+ ),
1425
+ "installed_binary_version": binary["version"],
1426
+ "installed_binary_sha256": binary["sha256"],
1427
+ "installed_binaries": binary["entries"],
1428
+ "installed_skill_sha256": installed_skill_sha,
1429
+ "installed_compatibility_skill_sha256": installed_compatibility_sha,
1430
+ "drift": drift,
1431
+ }
1432
+ )
1433
+ return result
1434
+
1435
+
1436
+ def copy_skill_payload(source: Path, target: Path) -> None:
1437
+ for relative in SKILL_PAYLOAD:
1438
+ source_path = source / relative
1439
+ target_path = target / relative
1440
+ target_path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
1441
+ shutil.copyfile(source_path, target_path)
1442
+ target_path.chmod(0o600)
1443
+
1444
+
1445
+ def copy_compatibility_skill(source: Path, target: Path) -> None:
1446
+ source_path = source / "SKILL.md"
1447
+ require_regular(source_path, "compatibility Skill source")
1448
+ target_path = target / COMPATIBILITY_BUNDLE_PATH
1449
+ target_path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
1450
+ shutil.copyfile(source_path, target_path)
1451
+ target_path.chmod(0o600)
1452
+
1453
+
1454
+ def source_executable_payload(
1455
+ repo: Path,
1456
+ manifest: dict[str, Any],
1457
+ target: Path,
1458
+ tool_commit: str,
1459
+ ) -> tuple[str, dict[str, str]]:
1460
+ executable = manifest["executable"]
1461
+ kind = executable["kind"]
1462
+ if kind == "python_console_scripts":
1463
+ identity = {
1464
+ "schema_version": SCHEMA_VERSION,
1465
+ "kind": kind,
1466
+ "tool_name": manifest["tool_name"],
1467
+ "tool_version": manifest["tool_version"],
1468
+ "tool_commit": tool_commit,
1469
+ "entrypoints": executable["entrypoints"],
1470
+ }
1471
+ identity_path = target / "executable_identity.json"
1472
+ write_json(identity_path, identity)
1473
+ digest = sha256_file(identity_path)
1474
+ return digest, {"executable_identity.json": digest}
1475
+
1476
+ executable_root = target / "executable"
1477
+ executable_root.mkdir(mode=0o700)
1478
+ hashes: dict[str, str] = {}
1479
+ for relative in executable["paths"]:
1480
+ source_path = repo / relative
1481
+ require_regular(source_path, "executable source")
1482
+ target_path = executable_root / relative
1483
+ target_path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
1484
+ shutil.copyfile(source_path, target_path)
1485
+ target_path.chmod(stat.S_IMODE(source_path.stat().st_mode) & 0o755)
1486
+ hashes[f"executable/{relative}"] = sha256_file(target_path)
1487
+ return aggregate_hash(hashes), hashes
1488
+
1489
+
1490
+ def verify_bundle(bundle: Path, expected_tool: str | None = None) -> dict[str, Any]:
1491
+ require_owned_directory(bundle)
1492
+ release = read_json(bundle / "release_manifest.json")
1493
+ manifest = read_json(bundle / "tool_skill_manifest.json")
1494
+ contract = read_json(bundle / "tool_cli_contract.json")
1495
+ if release.get("schema_version") != SCHEMA_VERSION:
1496
+ raise SyncError("unsupported ToolReleaseBundle schema_version")
1497
+ if set(release) != {
1498
+ "schema_version",
1499
+ "tool_name",
1500
+ "tool_version",
1501
+ "tool_commit",
1502
+ "binary_or_entry_sha",
1503
+ "skill_sha",
1504
+ "cli_contract_sha",
1505
+ "manifest_sha",
1506
+ "source_state",
1507
+ }:
1508
+ raise SyncError(
1509
+ "ToolReleaseBundle release manifest fields do not match schema v1"
1510
+ )
1511
+ manifest_schema = manifest.get("schema_version")
1512
+ if manifest_schema not in {1, TOOL_SKILL_MANIFEST_SCHEMA_VERSION}:
1513
+ raise SyncError("unsupported bundled ToolSkillManifest schema_version")
1514
+ if contract.get("schema_version") != SCHEMA_VERSION:
1515
+ raise SyncError("unsupported bundled CLI contract schema_version")
1516
+ validate_manifest_static_fields(manifest, allow_legacy=True)
1517
+ validate_install_targets(manifest, allow_legacy=True)
1518
+ validate_contract_shape(contract)
1519
+ tool = release.get("tool_name")
1520
+ if expected_tool is not None and tool != expected_tool:
1521
+ raise SyncError("ToolReleaseBundle tool mismatch")
1522
+ if manifest.get("tool_name") != tool or contract.get("tool_name") != tool:
1523
+ raise SyncError("ToolReleaseBundle identity mismatch")
1524
+ if not (
1525
+ release.get("tool_version")
1526
+ == manifest.get("tool_version")
1527
+ == contract.get("tool_version")
1528
+ ):
1529
+ raise SyncError("ToolReleaseBundle version mismatch")
1530
+ if manifest.get("tool_commit") != release.get("tool_commit"):
1531
+ raise SyncError("ToolReleaseBundle commit mismatch")
1532
+ tool_commit = release.get("tool_commit")
1533
+ source_state = release.get("source_state")
1534
+ if source_state == "committed_release":
1535
+ if not isinstance(tool_commit, str) or not FULL_GIT_OID.fullmatch(tool_commit):
1536
+ raise SyncError("committed bundle does not bind a full Git OID")
1537
+ elif source_state == "dirty_test_only":
1538
+ if (
1539
+ not isinstance(tool_commit, str)
1540
+ or not tool_commit.startswith("worktree:")
1541
+ or not FULL_GIT_OID.fullmatch(tool_commit.removeprefix("worktree:"))
1542
+ ):
1543
+ raise SyncError("dirty test bundle has invalid worktree identity")
1544
+ else:
1545
+ raise SyncError("ToolReleaseBundle source_state is invalid")
1546
+ hashes = {
1547
+ "skill_sha": tree_sha256(bundle, SKILL_PAYLOAD),
1548
+ "cli_contract_sha": sha256_file(bundle / "tool_cli_contract.json"),
1549
+ "manifest_sha": sha256_file(bundle / "tool_skill_manifest.json"),
1550
+ }
1551
+ for key, value in hashes.items():
1552
+ if release.get(key) != value:
1553
+ raise SyncError(f"ToolReleaseBundle {key} mismatch")
1554
+ if manifest.get("canonical_skill_sha256") != hashes["skill_sha"]:
1555
+ raise SyncError("bundle Skill does not match ToolSkillManifest")
1556
+ if manifest_schema == TOOL_SKILL_MANIFEST_SCHEMA_VERSION:
1557
+ compatibility_path = bundle / COMPATIBILITY_BUNDLE_PATH
1558
+ require_regular(compatibility_path, "bundled compatibility Skill")
1559
+ if sha256_file(compatibility_path) != manifest["compatibility_skill"]["sha256"]:
1560
+ raise SyncError(
1561
+ "bundle compatibility Skill does not match ToolSkillManifest"
1562
+ )
1563
+ if manifest.get("public_cli_contract_sha256") != hashes["cli_contract_sha"]:
1564
+ raise SyncError("bundle CLI contract does not match ToolSkillManifest")
1565
+ executable = manifest.get("executable", {})
1566
+ if executable.get("kind") == "python_console_scripts":
1567
+ identity_path = bundle / "executable_identity.json"
1568
+ executable_hash = sha256_file(identity_path)
1569
+ elif executable.get("kind") == "source_files":
1570
+ file_hashes = {
1571
+ f"executable/{relative}": sha256_file(bundle / "executable" / relative)
1572
+ for relative in executable.get("paths", [])
1573
+ }
1574
+ executable_hash = aggregate_hash(file_hashes)
1575
+ else:
1576
+ raise SyncError("bundle executable kind is unsupported")
1577
+ if release.get("binary_or_entry_sha") != executable_hash:
1578
+ raise SyncError("ToolReleaseBundle executable identity mismatch")
1579
+ return release
1580
+
1581
+
1582
+ def smoke_bundle(bundle: Path) -> None:
1583
+ release = verify_bundle(bundle)
1584
+ manifest = read_json(bundle / "tool_skill_manifest.json")
1585
+ if manifest["executable"]["kind"] == "python_console_scripts":
1586
+ identity = read_json(bundle / "executable_identity.json")
1587
+ if identity.get("tool_version") != release.get("tool_version"):
1588
+ raise SyncError("entrypoint identity smoke failed")
1589
+ return
1590
+ entry = bundle / "executable" / manifest["executable"]["entrypoints"][0]
1591
+ result = run((str(entry), "--version"))
1592
+ if result.returncode != 0 or extract_version(
1593
+ result.stdout + result.stderr
1594
+ ) != release.get("tool_version"):
1595
+ raise SyncError("bundled executable --version smoke failed")
1596
+ sync_entry = bundle / "executable" / "tool-skill-sync"
1597
+ if sync_entry.exists():
1598
+ result = run((str(sync_entry), "--version"))
1599
+ if result.returncode != 0 or extract_version(
1600
+ result.stdout + result.stderr
1601
+ ) != bundled_sync_version(bundle):
1602
+ raise SyncError("bundled tool-skill-sync --version smoke failed")
1603
+
1604
+
1605
+ def atomic_symlink(directory: Path, name: str, target: Path) -> None:
1606
+ temporary = directory / f".{name}.{os.getpid()}"
1607
+ if temporary.exists() or temporary.is_symlink():
1608
+ temporary.unlink()
1609
+ relative = os.path.relpath(target, directory)
1610
+ os.symlink(relative, temporary)
1611
+ os.replace(temporary, directory / name)
1612
+ descriptor = os.open(directory, os.O_RDONLY)
1613
+ try:
1614
+ os.fsync(descriptor)
1615
+ finally:
1616
+ os.close(descriptor)
1617
+
1618
+
1619
+ def resolve_pointer(pointer: Path, bundles_root: Path) -> Path | None:
1620
+ if not pointer.exists() and not pointer.is_symlink():
1621
+ return None
1622
+ if not pointer.is_symlink():
1623
+ raise SyncError(f"bundle pointer is not a symlink: {pointer}")
1624
+ resolved = pointer.resolve(strict=True)
1625
+ try:
1626
+ resolved.relative_to(bundles_root.resolve())
1627
+ except ValueError as exc:
1628
+ raise SyncError(f"bundle pointer escapes managed root: {pointer}") from exc
1629
+ return resolved
1630
+
1631
+
1632
+ def fsync_directory(path: Path) -> None:
1633
+ descriptor = os.open(path, os.O_RDONLY)
1634
+ try:
1635
+ os.fsync(descriptor)
1636
+ finally:
1637
+ os.close(descriptor)
1638
+
1639
+
1640
+ def require_owned_regular(path: Path, label: str) -> None:
1641
+ require_regular(path, label)
1642
+ if path.stat().st_uid != os.getuid():
1643
+ raise SyncError(f"{label} is not owned by current user: {path}")
1644
+
1645
+
1646
+ def ensure_owned_subdirectory(root: Path, relative: Path) -> Path:
1647
+ require_owned_directory(root, create=True)
1648
+ current = root
1649
+ for part in relative.parts:
1650
+ if part in {"", ".", ".."}:
1651
+ raise SyncError(f"unsafe production directory component: {relative}")
1652
+ current /= part
1653
+ require_owned_directory(current, create=True)
1654
+ return current
1655
+
1656
+
1657
+ def production_target_sources(
1658
+ bundle: Path,
1659
+ *,
1660
+ agents_root: Path,
1661
+ bin_dir: Path | None,
1662
+ hooks_dir: Path,
1663
+ assert_installed_version: bool = True,
1664
+ ) -> tuple[dict[Path, Path], Path | None]:
1665
+ manifest = read_json(bundle / "tool_skill_manifest.json")
1666
+ entrypoints = validate_install_targets(manifest, allow_legacy=True)
1667
+ require_owned_directory(agents_root)
1668
+ skill_parent = ensure_owned_subdirectory(agents_root, Path("skills"))
1669
+ manifest_schema = manifest.get("schema_version")
1670
+ installed_skill_name = (
1671
+ COMPATIBILITY_SKILL_NAME if manifest_schema == 1 else SKILL_NAME
1672
+ )
1673
+ skill_root = ensure_owned_subdirectory(skill_parent, Path(installed_skill_name))
1674
+ targets: dict[Path, Path] = {}
1675
+ for skill_relative in SKILL_PAYLOAD:
1676
+ target = skill_root / skill_relative
1677
+ ensure_owned_subdirectory(skill_root, Path(skill_relative).parent)
1678
+ targets[target] = bundle / skill_relative
1679
+ if manifest_schema == TOOL_SKILL_MANIFEST_SCHEMA_VERSION:
1680
+ compatibility_root = ensure_owned_subdirectory(
1681
+ skill_parent, Path(COMPATIBILITY_SKILL_NAME)
1682
+ )
1683
+ compatibility_target = compatibility_root / "SKILL.md"
1684
+ targets[compatibility_target] = bundle / COMPATIBILITY_BUNDLE_PATH
1685
+
1686
+ executable = manifest["executable"]
1687
+ if executable["kind"] == "python_console_scripts":
1688
+ if assert_installed_version:
1689
+ binary = installed_binary_state(entrypoints, bin_dir)
1690
+ if binary["version"] != manifest["tool_version"]:
1691
+ raise SyncError(
1692
+ f"installed entrypoints do not match {manifest['tool_name']} "
1693
+ f"{manifest['tool_version']}"
1694
+ )
1695
+ return targets, bin_dir
1696
+
1697
+ if bin_dir is None:
1698
+ primary = resolve_entry(entrypoints[0], None)
1699
+ if primary is None:
1700
+ raise SyncError(f"stable entry is unavailable: {entrypoints[0]}")
1701
+ live_bin_dir = primary.parent
1702
+ else:
1703
+ live_bin_dir = bin_dir.resolve()
1704
+ require_owned_directory(live_bin_dir)
1705
+ roots = {"bin": live_bin_dir, "hooks": hooks_dir}
1706
+ for source_relative, target_relative in executable["production_targets"].items():
1707
+ target_path = Path(target_relative)
1708
+ root = roots[target_path.parts[0]]
1709
+ require_owned_directory(root)
1710
+ within_root = Path(*target_path.parts[1:])
1711
+ if not within_root.parts:
1712
+ raise SyncError("production target must name a file")
1713
+ ensure_owned_subdirectory(root, within_root.parent)
1714
+ target = root / within_root
1715
+ if target in targets:
1716
+ raise SyncError(f"duplicate production target: {target}")
1717
+ targets[target] = bundle / "executable" / source_relative
1718
+ return targets, live_bin_dir
1719
+
1720
+
1721
+ def verify_production_bundle(
1722
+ bundle: Path,
1723
+ *,
1724
+ agents_root: Path,
1725
+ bin_dir: Path | None,
1726
+ hooks_dir: Path,
1727
+ ) -> dict[str, Any]:
1728
+ release = verify_bundle(bundle)
1729
+ manifest = read_json(bundle / "tool_skill_manifest.json")
1730
+ targets, live_bin_dir = production_target_sources(
1731
+ bundle,
1732
+ agents_root=agents_root,
1733
+ bin_dir=bin_dir,
1734
+ hooks_dir=hooks_dir,
1735
+ )
1736
+ for target, source in targets.items():
1737
+ require_owned_regular(target, "active production target")
1738
+ if sha256_file(target) != sha256_file(source):
1739
+ raise SyncError(f"active production target SHA mismatch: {target}")
1740
+ manifest_schema = manifest.get("schema_version")
1741
+ installed_skill_name = (
1742
+ COMPATIBILITY_SKILL_NAME if manifest_schema == 1 else SKILL_NAME
1743
+ )
1744
+ if (
1745
+ tree_sha256(
1746
+ agents_root / "skills" / installed_skill_name,
1747
+ SKILL_PAYLOAD,
1748
+ )
1749
+ != release["skill_sha"]
1750
+ ):
1751
+ raise SyncError("active Skill SHA does not match ToolReleaseBundle")
1752
+ if manifest_schema == TOOL_SKILL_MANIFEST_SCHEMA_VERSION:
1753
+ compatibility_path = (
1754
+ agents_root / "skills" / COMPATIBILITY_SKILL_NAME / "SKILL.md"
1755
+ )
1756
+ require_owned_regular(compatibility_path, "active compatibility Skill")
1757
+ if sha256_file(compatibility_path) != manifest["compatibility_skill"]["sha256"]:
1758
+ raise SyncError("active compatibility Skill SHA does not match bundle")
1759
+
1760
+ entrypoints = validate_install_targets(manifest, allow_legacy=True)
1761
+ binary = installed_binary_state(entrypoints, live_bin_dir)
1762
+ if binary["version"] != release["tool_version"]:
1763
+ raise SyncError("active stable entry version does not match ToolReleaseBundle")
1764
+ if manifest["executable"]["kind"] == "source_files":
1765
+ sync_entry = next(
1766
+ (
1767
+ target
1768
+ for target, source in targets.items()
1769
+ if source.name == "tool-skill-sync"
1770
+ ),
1771
+ None,
1772
+ )
1773
+ if sync_entry is not None:
1774
+ result = run((str(sync_entry), "--version"))
1775
+ if result.returncode != 0 or extract_version(
1776
+ result.stdout + result.stderr
1777
+ ) != bundled_sync_version(bundle):
1778
+ raise SyncError("active tool-skill-sync smoke failed")
1779
+ return {
1780
+ "binary_version": binary["version"],
1781
+ "binary_sha256": binary["sha256"],
1782
+ "skill_sha256": release["skill_sha"],
1783
+ "cli_contract_sha256": release["cli_contract_sha"],
1784
+ "target_sha256": {
1785
+ str(target): sha256_file(target) for target in sorted(targets)
1786
+ },
1787
+ }
1788
+
1789
+
1790
+ def production_pair_matches(
1791
+ bundle: Path,
1792
+ *,
1793
+ agents_root: Path,
1794
+ bin_dir: Path | None,
1795
+ hooks_dir: Path,
1796
+ ) -> bool:
1797
+ targets, _ = production_target_sources(
1798
+ bundle,
1799
+ agents_root=agents_root,
1800
+ bin_dir=bin_dir,
1801
+ hooks_dir=hooks_dir,
1802
+ )
1803
+ for target, source in targets.items():
1804
+ if not target.exists() and not target.is_symlink():
1805
+ return False
1806
+ require_owned_regular(target, "active production target")
1807
+ if sha256_file(target) != sha256_file(source):
1808
+ return False
1809
+ verify_production_bundle(
1810
+ bundle,
1811
+ agents_root=agents_root,
1812
+ bin_dir=bin_dir,
1813
+ hooks_dir=hooks_dir,
1814
+ )
1815
+ return True
1816
+
1817
+
1818
+ def verify_production_backup(backup: Path) -> dict[str, Any]:
1819
+ require_owned_directory(backup)
1820
+ receipt = read_json(backup / "receipt.json")
1821
+ if set(receipt) != {"schema_version", "operation", "tool", "entries"} or (
1822
+ receipt.get("schema_version") != SCHEMA_VERSION
1823
+ or receipt.get("operation") != "production_pair_backup"
1824
+ or not isinstance(receipt.get("tool"), str)
1825
+ or not isinstance(receipt.get("entries"), list)
1826
+ ):
1827
+ raise SyncError("production backup receipt is invalid")
1828
+ seen: set[str] = set()
1829
+ for entry in receipt["entries"]:
1830
+ if not isinstance(entry, dict) or set(entry) != {
1831
+ "target",
1832
+ "backup_file",
1833
+ "sha256",
1834
+ "mode",
1835
+ }:
1836
+ raise SyncError("production backup entry is invalid")
1837
+ target = entry["target"]
1838
+ if (
1839
+ not isinstance(target, str)
1840
+ or not Path(target).is_absolute()
1841
+ or target in seen
1842
+ ):
1843
+ raise SyncError("production backup target is invalid or duplicated")
1844
+ seen.add(target)
1845
+ backup_file = entry["backup_file"]
1846
+ digest = entry["sha256"]
1847
+ mode = entry["mode"]
1848
+ if backup_file is None:
1849
+ if digest is not None or mode is not None:
1850
+ raise SyncError("absent production backup entry has file metadata")
1851
+ continue
1852
+ if (
1853
+ not isinstance(backup_file, str)
1854
+ or Path(backup_file).is_absolute()
1855
+ or ".." in Path(backup_file).parts
1856
+ or not isinstance(digest, str)
1857
+ or not HEX_SHA256.fullmatch(digest)
1858
+ or not isinstance(mode, int)
1859
+ ):
1860
+ raise SyncError("production backup file metadata is invalid")
1861
+ stored = backup / backup_file
1862
+ require_owned_regular(stored, "production backup file")
1863
+ if sha256_file(stored) != digest:
1864
+ raise SyncError("production backup file SHA mismatch")
1865
+ return receipt
1866
+
1867
+
1868
+ def capture_production_pair(
1869
+ tool: str,
1870
+ targets: Sequence[Path],
1871
+ production_root: Path,
1872
+ ) -> Path:
1873
+ backups_root = ensure_owned_subdirectory(production_root, Path("backups"))
1874
+ staging = Path(tempfile.mkdtemp(prefix=".staging-", dir=backups_root))
1875
+ staging.chmod(0o700)
1876
+ try:
1877
+ entries: list[dict[str, Any]] = []
1878
+ files_root = staging / "files"
1879
+ files_root.mkdir(mode=0o700)
1880
+ for index, target in enumerate(sorted(targets)):
1881
+ if not target.exists() and not target.is_symlink():
1882
+ entries.append(
1883
+ {
1884
+ "target": str(target),
1885
+ "backup_file": None,
1886
+ "sha256": None,
1887
+ "mode": None,
1888
+ }
1889
+ )
1890
+ continue
1891
+ require_owned_regular(target, "active production target")
1892
+ relative = f"files/{index:03d}"
1893
+ stored = staging / relative
1894
+ shutil.copyfile(target, stored)
1895
+ mode = stat.S_IMODE(target.stat().st_mode)
1896
+ stored.chmod(mode)
1897
+ entries.append(
1898
+ {
1899
+ "target": str(target),
1900
+ "backup_file": relative,
1901
+ "sha256": sha256_file(stored),
1902
+ "mode": mode,
1903
+ }
1904
+ )
1905
+ receipt = {
1906
+ "schema_version": SCHEMA_VERSION,
1907
+ "operation": "production_pair_backup",
1908
+ "tool": tool,
1909
+ "entries": entries,
1910
+ }
1911
+ write_json(staging / "receipt.json", receipt)
1912
+ identity = sha256_file(staging / "receipt.json")
1913
+ destination = backups_root / identity
1914
+ if destination.exists():
1915
+ verify_production_backup(destination)
1916
+ shutil.rmtree(staging)
1917
+ return destination
1918
+ os.replace(staging, destination)
1919
+ fsync_directory(backups_root)
1920
+ verify_production_backup(destination)
1921
+ return destination
1922
+ except BaseException:
1923
+ if staging.exists():
1924
+ shutil.rmtree(staging)
1925
+ raise
1926
+
1927
+
1928
+ def restore_production_pair(
1929
+ backup: Path, expected_targets: Sequence[Path], *, execution_locked: bool = False,
1930
+ ) -> None:
1931
+ if not execution_locked:
1932
+ with finalizer_execution_lock(expected_targets):
1933
+ return restore_production_pair(backup, expected_targets, execution_locked=True)
1934
+ receipt = verify_production_backup(backup)
1935
+ entries = {Path(entry["target"]): entry for entry in receipt["entries"]}
1936
+ if set(entries) != set(expected_targets):
1937
+ raise SyncError("production backup target set does not match active pair")
1938
+ staged: dict[Path, Path] = {}
1939
+ try:
1940
+ for target, entry in entries.items():
1941
+ if entry["backup_file"] is None:
1942
+ continue
1943
+ ensure_owned_subdirectory(target.parent, Path("."))
1944
+ descriptor, temporary_name = tempfile.mkstemp(
1945
+ dir=target.parent, prefix=f".{target.name}.restore-"
1946
+ )
1947
+ os.close(descriptor)
1948
+ temporary = Path(temporary_name)
1949
+ shutil.copyfile(backup / entry["backup_file"], temporary)
1950
+ temporary.chmod(entry["mode"])
1951
+ staged[target] = temporary
1952
+ for target, entry in entries.items():
1953
+ if entry["backup_file"] is None:
1954
+ if target.exists() or target.is_symlink():
1955
+ require_owned_regular(target, "active production target")
1956
+ target.unlink()
1957
+ fsync_directory(target.parent)
1958
+ continue
1959
+ os.replace(staged.pop(target), target)
1960
+ fsync_directory(target.parent)
1961
+ finally:
1962
+ for temporary in staged.values():
1963
+ if temporary.exists():
1964
+ temporary.unlink()
1965
+
1966
+
1967
+ def installed_skill_tree(agents_root: Path, bundle: Path) -> str | None:
1968
+ manifest = read_json(bundle / "tool_skill_manifest.json")
1969
+ installed_skill_name = (
1970
+ COMPATIBILITY_SKILL_NAME
1971
+ if manifest.get("schema_version") == 1
1972
+ else SKILL_NAME
1973
+ )
1974
+ skill_root = agents_root / "skills" / installed_skill_name
1975
+ present = [
1976
+ skill_root / relative
1977
+ for relative in SKILL_PAYLOAD
1978
+ if (skill_root / relative).exists() or (skill_root / relative).is_symlink()
1979
+ ]
1980
+ if not present:
1981
+ return None
1982
+ if len(present) != len(SKILL_PAYLOAD):
1983
+ missing = ", ".join(
1984
+ relative
1985
+ for relative in SKILL_PAYLOAD
1986
+ if not (skill_root / relative).exists()
1987
+ and not (skill_root / relative).is_symlink()
1988
+ )
1989
+ raise SyncError(
1990
+ "installed production Skill is incomplete; preserve and classify the "
1991
+ f"missing payload files before activation: {missing}"
1992
+ )
1993
+ return tree_sha256(skill_root, SKILL_PAYLOAD)
1994
+
1995
+
1996
+ def validate_production_skill_trusted(
1997
+ bundle: Path,
1998
+ agents_root: Path,
1999
+ *,
2000
+ previous_bundle: Path | None,
2001
+ ) -> None:
2002
+ live_tree = installed_skill_tree(agents_root, bundle)
2003
+ if live_tree is None:
2004
+ return
2005
+ bundle_tree = verify_bundle(bundle)["skill_sha"]
2006
+ if live_tree == bundle_tree:
2007
+ return
2008
+ if live_tree in RELEASED_CANONICAL_SKILL_SHA256:
2009
+ return
2010
+ if previous_bundle is not None and verify_bundle(previous_bundle)["skill_sha"] == live_tree:
2011
+ return
2012
+ manifest = read_json(bundle / "tool_skill_manifest.json")
2013
+ installed_skill_name = (
2014
+ COMPATIBILITY_SKILL_NAME
2015
+ if manifest.get("schema_version") == 1
2016
+ else SKILL_NAME
2017
+ )
2018
+ skill_root = agents_root / "skills" / installed_skill_name
2019
+ drifted = ", ".join(
2020
+ f"{relative} live={sha256_file(skill_root / relative)}"
2021
+ for relative in SKILL_PAYLOAD
2022
+ if sha256_file(skill_root / relative) != sha256_file(bundle / relative)
2023
+ )
2024
+ raise SyncError(
2025
+ f"unknown content drift in installed production Skill (live_tree={live_tree} "
2026
+ f"bundle_tree={bundle_tree} accepted_released_trees="
2027
+ f"{', '.join(sorted(RELEASED_CANONICAL_SKILL_SHA256))}); preserve and "
2028
+ "classify these files first, activation refuses to overwrite them: "
2029
+ + drifted
2030
+ )
2031
+
2032
+
2033
+ def replace_production_pair(targets: dict[Path, Path]) -> None:
2034
+ staged: dict[Path, Path] = {}
2035
+ try:
2036
+ for target, source in targets.items():
2037
+ require_owned_regular(source, "bundled production source")
2038
+ descriptor, temporary_name = tempfile.mkstemp(
2039
+ dir=target.parent, prefix=f".{target.name}.install-"
2040
+ )
2041
+ os.close(descriptor)
2042
+ temporary = Path(temporary_name)
2043
+ shutil.copyfile(source, temporary)
2044
+ temporary.chmod(stat.S_IMODE(source.stat().st_mode))
2045
+ staged[target] = temporary
2046
+ for target in sorted(staged):
2047
+ if target.exists() or target.is_symlink():
2048
+ require_owned_regular(target, "active production target")
2049
+ os.replace(staged.pop(target), target)
2050
+ fsync_directory(target.parent)
2051
+ finally:
2052
+ for temporary in staged.values():
2053
+ if temporary.exists():
2054
+ temporary.unlink()
2055
+
2056
+
2057
+ @contextmanager
2058
+ def finalizer_execution_lock(targets: Sequence[Path], *, timeout: float = DEFAULT_LOCK_TIMEOUT):
2059
+ """Keep active CLI readers out of a production activation or rollback."""
2060
+ entries = [target for target in targets if target.name == "git-finalize"]
2061
+ if not entries:
2062
+ yield
2063
+ return
2064
+ if len(entries) != 1:
2065
+ raise SyncError("ambiguous Finalizer execution lock target")
2066
+ lock_path = entries[0].with_name(".git-finalizer-execution.lock")
2067
+ require_owned_directory(lock_path.parent)
2068
+ descriptor = os.open(lock_path, os.O_CREAT | os.O_RDWR | os.O_NOFOLLOW | os.O_CLOEXEC, 0o600)
2069
+ try:
2070
+ info = os.fstat(descriptor)
2071
+ if not stat.S_ISREG(info.st_mode) or info.st_uid != os.getuid() or info.st_mode & 0o077:
2072
+ raise SyncError("unsafe Finalizer execution lock")
2073
+ _flock_exclusive_bounded(descriptor, timeout=timeout, label="Finalizer execution lock")
2074
+ yield
2075
+ finally:
2076
+ os.close(descriptor)
2077
+
2078
+
2079
+ def activate_production_bundle(
2080
+ bundle: Path,
2081
+ tool: str,
2082
+ production_root: Path,
2083
+ *,
2084
+ agents_root: Path,
2085
+ bin_dir: Path | None,
2086
+ hooks_dir: Path,
2087
+ previous_bundle: Path | None = None,
2088
+ ) -> tuple[Path | None, dict[str, Any]]:
2089
+ targets, live_bin_dir = production_target_sources(
2090
+ bundle,
2091
+ agents_root=agents_root,
2092
+ bin_dir=bin_dir,
2093
+ hooks_dir=hooks_dir,
2094
+ )
2095
+ validate_production_skill_trusted(
2096
+ bundle,
2097
+ agents_root,
2098
+ previous_bundle=previous_bundle,
2099
+ )
2100
+ previous_targets = {}
2101
+ if previous_bundle is not None:
2102
+ # Transition bookkeeping only: the retired target set is a static
2103
+ # property of the previous manifest. Installed-version consistency is
2104
+ # asserted against the incoming bundle and by the post-activation
2105
+ # verification, never against the superseded release.
2106
+ prev_manifest = read_json(previous_bundle / "tool_skill_manifest.json")
2107
+ cur_manifest = read_json(bundle / "tool_skill_manifest.json")
2108
+ prev_kind = prev_manifest["executable"]["kind"]
2109
+ cur_kind = cur_manifest["executable"]["kind"]
2110
+ prev_bin_dir = live_bin_dir
2111
+ new_entrypoints = validate_install_targets(cur_manifest, allow_legacy=True)
2112
+ if prev_bin_dir is None and prev_kind == "source_files":
2113
+ for name in new_entrypoints:
2114
+ found = shutil.which(name)
2115
+ if found:
2116
+ prev_bin_dir = Path(found).parent
2117
+ break
2118
+ previous_targets, resolved_prev_bin = production_target_sources(
2119
+ previous_bundle,
2120
+ agents_root=agents_root,
2121
+ bin_dir=prev_bin_dir,
2122
+ hooks_dir=hooks_dir,
2123
+ assert_installed_version=False,
2124
+ )
2125
+ if prev_kind == "source_files" and cur_kind == "python_console_scripts":
2126
+ # Keep active console scripts managed by uv tool install; only retire
2127
+ # genuinely obsolete source_files sidecars and helpers.
2128
+ new_entry_set = set(new_entrypoints)
2129
+ active_console_paths: set[Path] = set()
2130
+ for dir_cand in (resolved_prev_bin, bin_dir.resolve() if bin_dir else None):
2131
+ if dir_cand is not None:
2132
+ for name in new_entry_set:
2133
+ active_console_paths.add(dir_cand / name)
2134
+ try:
2135
+ uv_info = python_tool_installation(new_entrypoints, bin_dir)
2136
+ active_console_paths.update(
2137
+ Path(entry_path) for entry_path in uv_info["entry_targets"].values()
2138
+ )
2139
+ except SyncError:
2140
+ pass
2141
+ previous_targets = {
2142
+ target: source
2143
+ for target, source in previous_targets.items()
2144
+ if target not in active_console_paths
2145
+ and not (target.name in new_entry_set and target.is_symlink())
2146
+ }
2147
+ retired = set(previous_targets) - set(targets)
2148
+ for target in retired:
2149
+ if not target.exists() and not target.is_symlink():
2150
+ continue
2151
+ require_owned_regular(target, "retiring production target")
2152
+ source = previous_targets[target]
2153
+ if (sha256_file(target) != sha256_file(source)
2154
+ or stat.S_IMODE(target.stat().st_mode) != stat.S_IMODE(source.stat().st_mode)):
2155
+ raise SyncError(f"retiring production target drifted: {target}")
2156
+ all_targets = tuple(set(targets) | set(previous_targets))
2157
+ if not retired and production_pair_matches(
2158
+ bundle,
2159
+ agents_root=agents_root,
2160
+ bin_dir=live_bin_dir,
2161
+ hooks_dir=hooks_dir,
2162
+ ):
2163
+ return None, verify_production_bundle(
2164
+ bundle,
2165
+ agents_root=agents_root,
2166
+ bin_dir=live_bin_dir,
2167
+ hooks_dir=hooks_dir,
2168
+ )
2169
+ with finalizer_execution_lock(all_targets):
2170
+ backup = capture_production_pair(tool, all_targets, production_root)
2171
+ try:
2172
+ replace_production_pair(targets)
2173
+ verified = verify_production_bundle(
2174
+ bundle,
2175
+ agents_root=agents_root,
2176
+ bin_dir=live_bin_dir,
2177
+ hooks_dir=hooks_dir,
2178
+ )
2179
+ for target in retired:
2180
+ if target.exists():
2181
+ target.unlink()
2182
+ fsync_directory(target.parent)
2183
+ verified["retired_targets"] = sorted(map(str, retired))
2184
+ except BaseException:
2185
+ restore_production_pair(backup, all_targets, execution_locked=True)
2186
+ raise
2187
+ return backup, verified
2188
+
2189
+
2190
+ def resolve_production_backup(pointer: Path, backups_root: Path) -> Path | None:
2191
+ return resolve_pointer(pointer, backups_root)
2192
+
2193
+
2194
+ def restore_pointer(directory: Path, name: str, target: Path | None) -> None:
2195
+ pointer = directory / name
2196
+ if target is None:
2197
+ if pointer.exists() or pointer.is_symlink():
2198
+ if not pointer.is_symlink():
2199
+ raise SyncError(f"managed pointer is not a symlink: {pointer}")
2200
+ pointer.unlink()
2201
+ fsync_directory(directory)
2202
+ return
2203
+ atomic_symlink(directory, name, target)
2204
+
2205
+
2206
+ def build_bundle(
2207
+ sources: Sources,
2208
+ tool: str,
2209
+ bundles_root: Path,
2210
+ *,
2211
+ allow_dirty_source: bool,
2212
+ ) -> Path:
2213
+ checked = check_tool(sources, tool)
2214
+ if checked["status"] != "PASS":
2215
+ raise SyncError("canonical check failed: " + "; ".join(checked["errors"]))
2216
+ repo = sources.repo(tool)
2217
+ head = sources.head(tool)
2218
+ dirty = sources.dirty(tool) or git_dirty(sources.owner_repo)
2219
+ if dirty and not allow_dirty_source:
2220
+ raise SyncError(
2221
+ "source repositories are dirty; release bundle requires committed sources"
2222
+ )
2223
+ tool_commit = f"worktree:{head}" if dirty else head
2224
+ manifest = read_json(sources.manifest_path(tool))
2225
+ manifest["tool_commit"] = tool_commit
2226
+ tool_root = bundles_root / tool
2227
+ require_owned_directory(tool_root, create=True)
2228
+ staging = Path(tempfile.mkdtemp(prefix=".staging-", dir=tool_root))
2229
+ staging.chmod(0o700)
2230
+ try:
2231
+ copy_skill_payload(sources.skill_root, staging)
2232
+ copy_compatibility_skill(sources.compatibility_skill_root, staging)
2233
+ (staging / "tool_cli_contract.json").write_bytes(
2234
+ sources.source_bytes(tool, "tool_cli_contract.json")
2235
+ )
2236
+ (staging / "tool_cli_contract.json").chmod(0o600)
2237
+ write_json(staging / "tool_skill_manifest.json", manifest)
2238
+ executable_sha, _ = source_executable_payload(
2239
+ repo, manifest, staging, tool_commit
2240
+ )
2241
+ release = {
2242
+ "schema_version": SCHEMA_VERSION,
2243
+ "tool_name": tool,
2244
+ "tool_version": manifest["tool_version"],
2245
+ "tool_commit": tool_commit,
2246
+ "binary_or_entry_sha": executable_sha,
2247
+ "skill_sha": tree_sha256(staging, SKILL_PAYLOAD),
2248
+ "cli_contract_sha": sha256_file(staging / "tool_cli_contract.json"),
2249
+ "manifest_sha": sha256_file(staging / "tool_skill_manifest.json"),
2250
+ "source_state": "dirty_test_only" if dirty else "committed_release",
2251
+ }
2252
+ write_json(staging / "release_manifest.json", release)
2253
+ verify_bundle(staging, tool)
2254
+ smoke_bundle(staging)
2255
+ release_sha = sha256_file(staging / "release_manifest.json")
2256
+ safe_commit = tool_commit.replace(":", "-")[:21]
2257
+ bundle_name = f"{manifest['tool_version']}-{safe_commit}-{release_sha[:12]}"
2258
+ destination = tool_root / bundle_name
2259
+ if destination.exists():
2260
+ verify_bundle(destination, tool)
2261
+ shutil.rmtree(staging)
2262
+ return destination
2263
+ os.replace(staging, destination)
2264
+ return destination
2265
+ except BaseException:
2266
+ if staging.exists():
2267
+ shutil.rmtree(staging)
2268
+ raise
2269
+
2270
+
2271
+ def install(
2272
+ sources: Sources,
2273
+ tool: str,
2274
+ install_root: Path,
2275
+ *,
2276
+ allow_dirty_source: bool,
2277
+ activate_production: bool = False,
2278
+ agents_root: Path | None = None,
2279
+ bin_dir: Path | None = None,
2280
+ hooks_dir: Path | None = None,
2281
+ ) -> dict[str, Any]:
2282
+ roots = [install_root]
2283
+ if activate_production and agents_root is not None:
2284
+ roots.append(agents_root / "skills")
2285
+ with deployment_lock(*roots):
2286
+ return _install_unlocked(
2287
+ sources, tool, install_root, allow_dirty_source=allow_dirty_source,
2288
+ activate_production=activate_production, agents_root=agents_root,
2289
+ bin_dir=bin_dir, hooks_dir=hooks_dir,
2290
+ )
2291
+
2292
+
2293
+ def _install_unlocked(
2294
+ sources: Sources, tool: str, install_root: Path, *, allow_dirty_source: bool,
2295
+ activate_production: bool = False, agents_root: Path | None = None,
2296
+ bin_dir: Path | None = None, hooks_dir: Path | None = None,
2297
+ ) -> dict[str, Any]:
2298
+ require_owned_directory(install_root, create=True)
2299
+ bundles_root = install_root / "bundles"
2300
+ state_root = install_root / "tools" / tool
2301
+ require_owned_directory(bundles_root, create=True)
2302
+ require_owned_directory(state_root, create=True)
2303
+ bundle = build_bundle(
2304
+ sources,
2305
+ tool,
2306
+ bundles_root,
2307
+ allow_dirty_source=allow_dirty_source,
2308
+ )
2309
+ current = resolve_pointer(state_root / "CURRENT", bundles_root)
2310
+ if current == bundle and not activate_production:
2311
+ return {"status": "UNCHANGED", "tool": tool, "current_bundle": bundle.name}
2312
+ previous_before = resolve_pointer(state_root / "PREVIOUS", bundles_root)
2313
+ if current is not None:
2314
+ verify_bundle(current, tool)
2315
+ smoke_bundle(current)
2316
+
2317
+ production_root: Path | None = None
2318
+ production_previous: Path | None = None
2319
+ production_backup: Path | None = None
2320
+ production_verified: dict[str, Any] | None = None
2321
+ if activate_production:
2322
+ if agents_root is None or hooks_dir is None:
2323
+ raise SyncError("production activation requires agents_root and hooks_dir")
2324
+ production_root = state_root / "production"
2325
+ require_owned_directory(production_root, create=True)
2326
+ backups_root = ensure_owned_subdirectory(production_root, Path("backups"))
2327
+ production_previous = resolve_production_backup(
2328
+ production_root / "PREVIOUS", backups_root
2329
+ )
2330
+ production_backup, production_verified = activate_production_bundle(
2331
+ bundle,
2332
+ tool,
2333
+ production_root,
2334
+ agents_root=agents_root,
2335
+ bin_dir=bin_dir,
2336
+ hooks_dir=hooks_dir,
2337
+ previous_bundle=current,
2338
+ )
2339
+
2340
+ try:
2341
+ if current != bundle:
2342
+ if current is not None:
2343
+ atomic_symlink(state_root, "PREVIOUS", current)
2344
+ atomic_symlink(state_root, "CURRENT", bundle)
2345
+ active = resolve_pointer(state_root / "CURRENT", bundles_root)
2346
+ verify_bundle(active or bundle, tool)
2347
+ if production_backup is not None and production_root is not None:
2348
+ atomic_symlink(production_root, "PREVIOUS", production_backup)
2349
+ if activate_production:
2350
+ assert agents_root is not None
2351
+ assert hooks_dir is not None
2352
+ production_verified = verify_production_bundle(
2353
+ bundle,
2354
+ agents_root=agents_root,
2355
+ bin_dir=bin_dir,
2356
+ hooks_dir=hooks_dir,
2357
+ )
2358
+ except BaseException:
2359
+ if production_backup is not None:
2360
+ # Failure cleanup must never be blocked by pairing assertions;
2361
+ # these calls only rebuild the target set for byte-verified
2362
+ # restoration from the recorded backup.
2363
+ targets, _ = production_target_sources(
2364
+ bundle,
2365
+ agents_root=agents_root or Path(),
2366
+ bin_dir=bin_dir,
2367
+ hooks_dir=hooks_dir or Path(),
2368
+ assert_installed_version=False,
2369
+ )
2370
+ if current is not None:
2371
+ previous_targets, _ = production_target_sources(
2372
+ current, agents_root=agents_root or Path(), bin_dir=bin_dir,
2373
+ hooks_dir=hooks_dir or Path(),
2374
+ assert_installed_version=False,
2375
+ )
2376
+ targets.update(previous_targets)
2377
+ restore_production_pair(production_backup, tuple(targets))
2378
+ restore_pointer(state_root, "CURRENT", current)
2379
+ restore_pointer(state_root, "PREVIOUS", previous_before)
2380
+ if production_root is not None:
2381
+ restore_pointer(production_root, "PREVIOUS", production_previous)
2382
+ raise
2383
+ return {
2384
+ "status": "INSTALLED" if current != bundle else "ACTIVATED",
2385
+ "tool": tool,
2386
+ "current_bundle": bundle.name,
2387
+ "previous_bundle": current.name if current else None,
2388
+ "production_activation": activate_production,
2389
+ "production_verified": production_verified,
2390
+ }
2391
+
2392
+
2393
+ def rollback(
2394
+ tool: str,
2395
+ install_root: Path,
2396
+ *,
2397
+ activate_production: bool = False,
2398
+ agents_root: Path | None = None,
2399
+ bin_dir: Path | None = None,
2400
+ hooks_dir: Path | None = None,
2401
+ ) -> dict[str, Any]:
2402
+ roots = [install_root]
2403
+ if activate_production and agents_root is not None:
2404
+ roots.append(agents_root / "skills")
2405
+ with deployment_lock(*roots):
2406
+ return _rollback_unlocked(
2407
+ tool, install_root, activate_production=activate_production,
2408
+ agents_root=agents_root, bin_dir=bin_dir, hooks_dir=hooks_dir,
2409
+ )
2410
+
2411
+
2412
+ def _rollback_unlocked(
2413
+ tool: str, install_root: Path, *, activate_production: bool = False,
2414
+ agents_root: Path | None = None, bin_dir: Path | None = None,
2415
+ hooks_dir: Path | None = None,
2416
+ ) -> dict[str, Any]:
2417
+ bundles_root = install_root / "bundles"
2418
+ state_root = install_root / "tools" / tool
2419
+ require_owned_directory(bundles_root)
2420
+ require_owned_directory(state_root)
2421
+ current = resolve_pointer(state_root / "CURRENT", bundles_root)
2422
+ previous = resolve_pointer(state_root / "PREVIOUS", bundles_root)
2423
+ if current is None or previous is None:
2424
+ raise SyncError(f"rollback requires CURRENT and PREVIOUS for {tool}")
2425
+ verify_bundle(current, tool)
2426
+ verify_bundle(previous, tool)
2427
+ smoke_bundle(previous)
2428
+ production_root: Path | None = None
2429
+ production_previous: Path | None = None
2430
+ current_production_backup: Path | None = None
2431
+ production_verified: dict[str, Any] | None = None
2432
+ current_targets: dict[Path, Path] = {}
2433
+ if activate_production:
2434
+ if agents_root is None or hooks_dir is None:
2435
+ raise SyncError("production rollback requires agents_root and hooks_dir")
2436
+ production_root = state_root / "production"
2437
+ require_owned_directory(production_root)
2438
+ backups_root = ensure_owned_subdirectory(production_root, Path("backups"))
2439
+ production_previous = resolve_production_backup(
2440
+ production_root / "PREVIOUS", backups_root
2441
+ )
2442
+ current_targets, _ = production_target_sources(
2443
+ current,
2444
+ agents_root=agents_root,
2445
+ bin_dir=bin_dir,
2446
+ hooks_dir=hooks_dir,
2447
+ assert_installed_version=False,
2448
+ )
2449
+ previous_targets, _ = production_target_sources(
2450
+ previous,
2451
+ agents_root=agents_root,
2452
+ bin_dir=bin_dir,
2453
+ hooks_dir=hooks_dir,
2454
+ assert_installed_version=False,
2455
+ )
2456
+ retired = set(current_targets) - set(previous_targets)
2457
+ all_targets = tuple(set(current_targets) | set(previous_targets))
2458
+ if not any(p.exists() or p.is_symlink() for p in retired) and production_pair_matches(
2459
+ previous,
2460
+ agents_root=agents_root,
2461
+ bin_dir=bin_dir,
2462
+ hooks_dir=hooks_dir,
2463
+ ):
2464
+ production_verified = verify_production_bundle(
2465
+ previous,
2466
+ agents_root=agents_root,
2467
+ bin_dir=bin_dir,
2468
+ hooks_dir=hooks_dir,
2469
+ )
2470
+ else:
2471
+ if production_previous is None:
2472
+ raise SyncError(f"production rollback has no previous pair for {tool}")
2473
+ verify_production_bundle(
2474
+ current, agents_root=agents_root, bin_dir=bin_dir, hooks_dir=hooks_dir
2475
+ )
2476
+ receipt = verify_production_backup(production_previous)
2477
+ if {Path(entry["target"]) for entry in receipt["entries"]} != set(all_targets):
2478
+ raise SyncError("production rollback backup does not cover both target sets")
2479
+ current_production_backup = capture_production_pair(
2480
+ tool, all_targets, production_root
2481
+ )
2482
+ try:
2483
+ restore_production_pair(production_previous, all_targets)
2484
+ production_verified = verify_production_bundle(
2485
+ previous,
2486
+ agents_root=agents_root,
2487
+ bin_dir=bin_dir,
2488
+ hooks_dir=hooks_dir,
2489
+ )
2490
+ except BaseException:
2491
+ restore_production_pair(
2492
+ current_production_backup, all_targets
2493
+ )
2494
+ raise
2495
+ try:
2496
+ atomic_symlink(state_root, "PREVIOUS", current)
2497
+ atomic_symlink(state_root, "CURRENT", previous)
2498
+ active = resolve_pointer(state_root / "CURRENT", bundles_root)
2499
+ verify_bundle(active or previous, tool)
2500
+ if production_root is not None and current_production_backup is not None:
2501
+ atomic_symlink(production_root, "PREVIOUS", current_production_backup)
2502
+ except BaseException:
2503
+ restore_pointer(state_root, "CURRENT", current)
2504
+ restore_pointer(state_root, "PREVIOUS", previous)
2505
+ if current_production_backup is not None:
2506
+ restore_production_pair(current_production_backup, all_targets)
2507
+ if production_root is not None:
2508
+ restore_pointer(production_root, "PREVIOUS", production_previous)
2509
+ raise
2510
+ return {
2511
+ "status": "ROLLED_BACK",
2512
+ "tool": tool,
2513
+ "current_bundle": previous.name,
2514
+ "previous_bundle": current.name,
2515
+ "production_activation": activate_production,
2516
+ "production_verified": production_verified,
2517
+ }
2518
+
2519
+
2520
+ SKILL_LINK_CLIENTS = ("claude", "cursor", "qoder", "qoder-cn")
2521
+ MANAGED_SKILL_NAMES = (SKILL_NAME, COMPATIBILITY_SKILL_NAME)
2522
+
2523
+
2524
+ def _validate_skill_frontmatter_and_refs(skill_root: Path) -> None:
2525
+ skill_md = skill_root / "SKILL.md"
2526
+ require_regular(skill_md, "canonical SKILL.md")
2527
+ content = skill_md.read_text(encoding="utf-8")
2528
+ frontmatter = re.match(r"\A---\n(.*?)\n---\n", content, re.DOTALL)
2529
+ if frontmatter is None:
2530
+ raise SyncError("invalid YAML frontmatter delimiters in SKILL.md")
2531
+ lines = [line for line in frontmatter.group(1).splitlines() if line.strip()]
2532
+ fields = [line.split(":", 1)[0].strip() for line in lines if ":" in line]
2533
+ if fields != ["name", "description"]:
2534
+ raise SyncError("SKILL.md frontmatter must contain only name and description")
2535
+ name = next((line.split(":", 1)[1].strip() for line in lines if line.startswith("name:")), "")
2536
+ description = next((line.split(":", 1)[1].strip() for line in lines if line.startswith("description:")), "")
2537
+ if name != SKILL_NAME or not description or len(description) > 1024 or "<" in description or ">" in description:
2538
+ raise SyncError("SKILL.md frontmatter name or description is invalid")
2539
+ if len(content.splitlines()) >= 500 or any(line.endswith((" ", "\t")) for line in content.splitlines()):
2540
+ raise SyncError("SKILL.md exceeds line limit or contains trailing whitespace")
2541
+ for rel in SKILL_PAYLOAD:
2542
+ if rel.startswith("references/") and f"]({rel})" not in content:
2543
+ raise SyncError(f"SKILL.md does not link required reference: {rel}")
2544
+
2545
+
2546
+ def _validate_skill_source(sources: Sources) -> tuple[str, str]:
2547
+ require_owned_directory(sources.skill_root)
2548
+ for rel in SKILL_PAYLOAD:
2549
+ p = sources.skill_root / rel
2550
+ require_owned_regular(p, "canonical Skill payload")
2551
+ mode = stat.S_IMODE(p.stat().st_mode)
2552
+ if mode & 0o111 or mode & 0o002:
2553
+ raise SyncError(f"unsafe canonical Skill file permissions: {p} ({mode:#05o})")
2554
+ _validate_skill_frontmatter_and_refs(sources.skill_root)
2555
+ require_owned_directory(sources.compatibility_skill_root)
2556
+ compat_md = sources.compatibility_skill_root / "SKILL.md"
2557
+ require_owned_regular(compat_md, "compatibility Skill")
2558
+ compat_text = compat_md.read_text(encoding="utf-8")
2559
+ for marker in ("name: three-tool-git-workflow", "Deprecated compatibility entry", f"${SKILL_NAME}"):
2560
+ if marker not in compat_text:
2561
+ raise SyncError("compatibility Skill does not point to canonical Skill")
2562
+ return tree_sha256(sources.skill_root, SKILL_PAYLOAD), sha256_file(compat_md)
2563
+
2564
+
2565
+ def _default_client_homes(home_dir: Path | None = None) -> dict[str, Path]:
2566
+ base = home_dir or Path.home()
2567
+ return {
2568
+ "codex": Path(os.environ.get("CODEX_HOME", base / ".codex")),
2569
+ "claude": Path(os.environ.get("CLAUDE_CONFIG_DIR", base / ".claude")),
2570
+ "gemini": Path(os.environ.get("GEMINI_HOME", base / ".gemini")),
2571
+ "cursor": Path(os.environ.get("CURSOR_HOME", base / ".cursor")),
2572
+ "qoder": Path(os.environ.get("QODER_HOME", base / ".qoder")),
2573
+ "qoder-cn": Path(os.environ.get("QODER_CN_HOME", base / ".qoder-cn")),
2574
+ }
2575
+
2576
+
2577
+ def _check_multi_client_skills(
2578
+ agents_root: Path,
2579
+ client_homes: dict[str, Path],
2580
+ ) -> dict[str, Any]:
2581
+ shared_skills = agents_root / "skills"
2582
+ clients: dict[str, Any] = {}
2583
+ if (shared_skills / "synced").exists():
2584
+ raise SyncError("personal skill root contains disallowed account-synced directory: skills/synced")
2585
+
2586
+ # Codex reads ~/.agents/skills directly and adds no duplicate symlinks under ~/.codex/skills.
2587
+ codex_dir = client_homes["codex"]
2588
+ codex_dup = [
2589
+ name for name in MANAGED_SKILL_NAMES
2590
+ if (codex_dir / "skills" / name).exists() or (codex_dir / "skills" / name).is_symlink()
2591
+ ]
2592
+ clients["codex"] = {
2593
+ "present": codex_dir.is_dir(),
2594
+ "uses_shared_root": True,
2595
+ "duplicate_links": codex_dup,
2596
+ "status": "FAIL" if codex_dup else "PASS",
2597
+ }
2598
+
2599
+ for cname in SKILL_LINK_CLIENTS:
2600
+ cdir = client_homes[cname]
2601
+ if not cdir.is_dir():
2602
+ clients[cname] = {"present": False, "status": "SKIP"}
2603
+ continue
2604
+ cskills = cdir / "skills"
2605
+ if cskills.is_symlink() and cskills.resolve(strict=False) == shared_skills.resolve(strict=False):
2606
+ clients[cname] = {
2607
+ "present": True,
2608
+ "status": "FAIL",
2609
+ "error": f"{cname} uses a whole-root symlink to ~/.agents/skills instead of per-Skill links",
2610
+ }
2611
+ continue
2612
+ exposed: dict[str, bool] = {}
2613
+ for sname in MANAGED_SKILL_NAMES:
2614
+ link = cskills / sname
2615
+ target = shared_skills / sname
2616
+ exposed[sname] = link.exists() and link.resolve(strict=False) == target.resolve(strict=False)
2617
+ clients[cname] = {
2618
+ "present": True,
2619
+ "per_skill_links": exposed,
2620
+ "status": "PASS" if all(exposed.values()) else "DRIFT",
2621
+ }
2622
+
2623
+ gemini_dir = client_homes["gemini"]
2624
+ if not gemini_dir.is_dir():
2625
+ clients["gemini"] = {"present": False, "status": "SKIP"}
2626
+ else:
2627
+ cfg_path = gemini_dir / "config" / "skills.json"
2628
+ if not cfg_path.is_file():
2629
+ clients["gemini"] = {"present": True, "config": str(cfg_path), "status": "DRIFT"}
2630
+ else:
2631
+ try:
2632
+ cfg_data = json.loads(cfg_path.read_text(encoding="utf-8"))
2633
+ except (OSError, ValueError):
2634
+ clients["gemini"] = {"present": True, "config": str(cfg_path), "status": "FAIL"}
2635
+ else:
2636
+ expected_roots = {str(shared_skills), str(shared_skills / SKILL_NAME)}
2637
+ recorded: set[str] = set()
2638
+ if isinstance(cfg_data, dict):
2639
+ for key in ("paths", "skillPaths", "skills"):
2640
+ val = cfg_data.get(key)
2641
+ if isinstance(val, list):
2642
+ recorded.update(str(v) for v in val if isinstance(v, str))
2643
+ clients["gemini"] = {
2644
+ "present": True,
2645
+ "config": str(cfg_path),
2646
+ "registered_paths": sorted(recorded & expected_roots),
2647
+ "status": "PASS" if (recorded & expected_roots) else "DRIFT",
2648
+ }
2649
+ return clients
2650
+
2651
+
2652
+ def skill_check(
2653
+ sources: Sources,
2654
+ *,
2655
+ agents_root: Path,
2656
+ client_homes: dict[str, Path] | None = None,
2657
+ ) -> dict[str, Any]:
2658
+ canonical_sha, compat_sha = _validate_skill_source(sources)
2659
+ installed_sha, installed_compat_sha = installed_skill_hashes(agents_root)
2660
+ homes = _default_client_homes() if client_homes is None else client_homes
2661
+ clients = _check_multi_client_skills(agents_root, homes)
2662
+ trusted = (
2663
+ installed_sha in (None, canonical_sha)
2664
+ or installed_sha in RELEASED_CANONICAL_SKILL_SHA256
2665
+ )
2666
+ payload_match = installed_sha == canonical_sha and installed_compat_sha == compat_sha
2667
+ return {
2668
+ "schema_version": SCHEMA_VERSION,
2669
+ "operation": "skill-check",
2670
+ "status": "PASS" if (payload_match and trusted) else ("DRIFT" if trusted else "FAIL"),
2671
+ "source_skill_sha256": canonical_sha,
2672
+ "source_compatibility_sha256": compat_sha,
2673
+ "installed_skill_sha256": installed_sha,
2674
+ "installed_compatibility_sha256": installed_compat_sha,
2675
+ "trusted_lineage": trusted,
2676
+ "clients": clients,
2677
+ }
2678
+
2679
+
2680
+ def _sync_multi_client_skills(
2681
+ agents_root: Path,
2682
+ client_homes: dict[str, Path],
2683
+ ) -> dict[str, Any]:
2684
+ shared_skills = agents_root / "skills"
2685
+ require_owned_directory(shared_skills)
2686
+ if (shared_skills / "synced").exists():
2687
+ raise SyncError("refusing to sync while skills/synced exists inside shared personal root")
2688
+ results: dict[str, Any] = {}
2689
+
2690
+ for cname in SKILL_LINK_CLIENTS:
2691
+ cdir = client_homes[cname]
2692
+ if not cdir.is_dir():
2693
+ results[cname] = {"status": "SKIP"}
2694
+ continue
2695
+ cskills = cdir / "skills"
2696
+ if cskills.is_symlink():
2697
+ if cskills.resolve(strict=False) == shared_skills.resolve(strict=False):
2698
+ raise SyncError(f"{cname} skills directory must not symlink whole shared root")
2699
+ raise SyncError(f"{cname} skills directory is an unsafe symlink: {cskills}")
2700
+ require_owned_directory(cskills, create=True)
2701
+ linked: list[str] = []
2702
+ for sname in MANAGED_SKILL_NAMES:
2703
+ link_path = cskills / sname
2704
+ target = shared_skills / sname
2705
+ if link_path.is_symlink():
2706
+ if link_path.resolve(strict=False) == target.resolve(strict=False):
2707
+ linked.append(sname)
2708
+ continue
2709
+ link_path.unlink()
2710
+ elif link_path.exists():
2711
+ raise SyncError(f"{cname} already has non-symlink skill at {link_path}; preserve manually")
2712
+ os.symlink(str(target), link_path)
2713
+ linked.append(sname)
2714
+ results[cname] = {"status": "SYNCED", "linked": linked}
2715
+
2716
+ gemini_dir = client_homes["gemini"]
2717
+ if not gemini_dir.is_dir():
2718
+ results["gemini"] = {"status": "SKIP"}
2719
+ else:
2720
+ cfg_dir = ensure_owned_subdirectory(gemini_dir, Path("config"))
2721
+ cfg_path = cfg_dir / "skills.json"
2722
+ if cfg_path.is_symlink():
2723
+ raise SyncError(f"unsafe Gemini config symlink: {cfg_path}")
2724
+ if cfg_path.exists():
2725
+ try:
2726
+ cfg = json.loads(cfg_path.read_text(encoding="utf-8"))
2727
+ except (OSError, ValueError) as exc:
2728
+ raise SyncError(f"invalid existing Gemini skills.json: {exc}") from exc
2729
+ if not isinstance(cfg, dict):
2730
+ raise SyncError("Gemini skills.json root must be an object")
2731
+ else:
2732
+ cfg = {}
2733
+ key = "paths" if "paths" in cfg or "skillPaths" not in cfg else "skillPaths"
2734
+ existing = cfg.get(key)
2735
+ if existing is None:
2736
+ entries: list[str] = []
2737
+ elif isinstance(existing, list) and all(isinstance(x, str) for x in existing):
2738
+ entries = list(existing)
2739
+ else:
2740
+ raise SyncError(f"Gemini skills.json field {key} must be a list of strings")
2741
+ shared_str = str(shared_skills)
2742
+ if shared_str not in entries:
2743
+ entries.append(shared_str)
2744
+ cfg[key] = entries
2745
+ write_json(cfg_path, cfg, mode=0o600)
2746
+ results["gemini"] = {"status": "SYNCED", "config": str(cfg_path), "registered": shared_str}
2747
+
2748
+ codex_dir = client_homes["codex"]
2749
+ results["codex"] = {"status": "NATIVE", "shared_root": str(shared_skills), "present": codex_dir.is_dir()}
2750
+ return results
2751
+
2752
+
2753
+ def skill_install(
2754
+ sources: Sources,
2755
+ *,
2756
+ agents_root: Path,
2757
+ client_homes: dict[str, Path] | None = None,
2758
+ sync_clients: bool = True,
2759
+ ) -> dict[str, Any]:
2760
+ canonical_sha, compat_sha = _validate_skill_source(sources)
2761
+ require_owned_directory(agents_root, create=True)
2762
+ skills_root = ensure_owned_subdirectory(agents_root, Path("skills"))
2763
+ if (skills_root / "synced").exists():
2764
+ raise SyncError("refusing installation while skills/synced exists inside shared root")
2765
+ with deployment_lock(skills_root):
2766
+ live_canonical = skills_root / SKILL_NAME
2767
+ if live_canonical.exists():
2768
+ if live_canonical.is_symlink():
2769
+ raise SyncError(f"live Skill target is a symlink: {live_canonical}")
2770
+ installed_sha, _ = installed_skill_hashes(agents_root)
2771
+ if installed_sha not in (canonical_sha, None) and installed_sha not in RELEASED_CANONICAL_SKILL_SHA256:
2772
+ raise SyncError("unknown content drift in live Skill; preserve before installing")
2773
+
2774
+ stage_root = Path(tempfile.mkdtemp(prefix=".skill-stage-", dir=skills_root))
2775
+ try:
2776
+ copy_skill_payload(sources.skill_root, stage_root / SKILL_NAME)
2777
+ copy_compatibility_skill(sources.compatibility_skill_root, stage_root)
2778
+ canon_target = ensure_owned_subdirectory(skills_root, Path(SKILL_NAME))
2779
+ for rel in SKILL_PAYLOAD:
2780
+ dest = canon_target / rel
2781
+ ensure_owned_subdirectory(canon_target, Path(rel).parent)
2782
+ if dest.is_symlink():
2783
+ raise SyncError(f"live target file is a symlink: {dest}")
2784
+ shutil.copyfile(sources.skill_root / rel, dest)
2785
+ dest.chmod(0o600)
2786
+ compat_dir = ensure_owned_subdirectory(skills_root, Path(COMPATIBILITY_SKILL_NAME))
2787
+ compat_dest = compat_dir / "SKILL.md"
2788
+ if compat_dest.is_symlink():
2789
+ raise SyncError(f"live compatibility target is a symlink: {compat_dest}")
2790
+ shutil.copyfile(sources.compatibility_skill_root / "SKILL.md", compat_dest)
2791
+ compat_dest.chmod(0o600)
2792
+ finally:
2793
+ if stage_root.exists():
2794
+ shutil.rmtree(stage_root)
2795
+
2796
+ homes = _default_client_homes() if client_homes is None else client_homes
2797
+ clients = _sync_multi_client_skills(agents_root, homes) if sync_clients else {}
2798
+
2799
+ installed_sha, installed_compat_sha = installed_skill_hashes(agents_root)
2800
+ if installed_sha != canonical_sha or installed_compat_sha != compat_sha:
2801
+ raise SyncError("post-install Skill payload hash verification failed")
2802
+ return {
2803
+ "schema_version": SCHEMA_VERSION,
2804
+ "operation": "skill-install",
2805
+ "status": "INSTALLED",
2806
+ "skill_sha256": installed_sha,
2807
+ "compatibility_skill_sha256": installed_compat_sha,
2808
+ "clients": clients,
2809
+ }
2810
+
2811
+
2812
+ def _default_source_root(repo: Path | None = None) -> Path:
2813
+ env_root = os.environ.get("TOOL_SKILL_SYNC_SOURCE_ROOT", "").strip()
2814
+ if env_root:
2815
+ return Path(env_root).expanduser()
2816
+ resolved_file = Path(__file__).resolve()
2817
+ for depth in (2, 3):
2818
+ if len(resolved_file.parents) > depth:
2819
+ checkout_root = resolved_file.parents[depth]
2820
+ if (checkout_root / "toolchain_compatibility.json").is_file():
2821
+ return checkout_root.parent
2822
+ if repo is not None:
2823
+ candidate = repo.resolve(strict=False)
2824
+ for parent in (candidate, *candidate.parents):
2825
+ if (parent / "toolchain_compatibility.json").is_file():
2826
+ return parent.parent
2827
+ projects_root = Path.home() / "projects"
2828
+ if (projects_root / "git-finalizer" / "toolchain_compatibility.json").is_file():
2829
+ return projects_root
2830
+ cwd = Path.cwd().resolve(strict=False)
2831
+ for parent in (cwd, *cwd.parents):
2832
+ if (parent / "toolchain_compatibility.json").is_file():
2833
+ return parent.parent
2834
+ return projects_root
2835
+
2836
+
2837
+ def parser() -> argparse.ArgumentParser:
2838
+ result = argparse.ArgumentParser(prog="tool-skill-sync")
2839
+ result.add_argument("--version", action="version", version=f"%(prog)s {VERSION}")
2840
+ result.add_argument("--source-root", type=Path, default=_default_source_root())
2841
+ result.add_argument(
2842
+ "--source-repo", action="append", default=[], metavar="TOOL=PATH",
2843
+ help="explicit source checkout; repeat for independently allocated worktrees",
2844
+ )
2845
+ result.add_argument(
2846
+ "--install-root",
2847
+ type=Path,
2848
+ default=Path.home() / ".local" / "state" / "tool-skill-sync",
2849
+ )
2850
+ result.add_argument(
2851
+ "--source-ref", action="append", default=[], metavar="TOOL=FULL_COMMIT_OID",
2852
+ help="read released Python package metadata from an exact commit without touching its checkout",
2853
+ )
2854
+ result.add_argument("--agents-root", type=Path, default=Path.home() / ".agents")
2855
+ result.add_argument("--bin-dir", type=Path)
2856
+ result.add_argument(
2857
+ "--hooks-dir", type=Path, default=Path.home() / ".agents" / "hooks"
2858
+ )
2859
+ subcommands = result.add_subparsers(dest="command", required=True)
2860
+ subcommands.add_parser("status")
2861
+ for sname in ("skill-check", "skill-install"):
2862
+ sp = subcommands.add_parser(sname)
2863
+ sp.add_argument("--codex-home", type=Path)
2864
+ sp.add_argument("--claude-home", type=Path)
2865
+ sp.add_argument("--gemini-home", type=Path)
2866
+ sp.add_argument("--cursor-home", type=Path)
2867
+ sp.add_argument("--qoder-home", type=Path)
2868
+ if sname == "skill-install":
2869
+ sp.add_argument("--no-sync-clients", action="store_true")
2870
+ doctor_parser = subcommands.add_parser(
2871
+ "doctor", help="read-only toolchain deployment and instruction freshness check"
2872
+ )
2873
+ doctor_parser.add_argument("--repo", type=Path)
2874
+ doctor_parser.add_argument("--summary", action="store_true")
2875
+ doctor_parser.add_argument("--previous-fingerprint")
2876
+ doctor_parser.add_argument(
2877
+ "--codex-home",
2878
+ type=Path,
2879
+ default=Path(os.environ.get("CODEX_HOME", Path.home() / ".codex")),
2880
+ )
2881
+ doctor_parser.add_argument(
2882
+ "--claude-home",
2883
+ type=Path,
2884
+ default=Path(os.environ.get("CLAUDE_CONFIG_DIR", Path.home() / ".claude")),
2885
+ )
2886
+ doctor_parser.add_argument("--controller", type=Path)
2887
+ doctor_parser.add_argument("--controller-source", type=Path)
2888
+ doctor_parser.add_argument(
2889
+ "--controller-runtime-root",
2890
+ type=Path,
2891
+ default=Path.home() / ".local/share/worktree-controller",
2892
+ )
2893
+ check_parser = subcommands.add_parser("check")
2894
+ check_parser.add_argument("tool")
2895
+ check_parser.add_argument(
2896
+ "--source-only",
2897
+ action="store_true",
2898
+ help=(
2899
+ "validate only the canonical source contract and skip installed-production "
2900
+ "drift detection (for build environments with no installation)"
2901
+ ),
2902
+ )
2903
+ install_parser = subcommands.add_parser("install")
2904
+ install_parser.add_argument("tool")
2905
+ install_parser.add_argument("--allow-dirty-source", action="store_true")
2906
+ install_parser.add_argument("--activate-production", action="store_true")
2907
+ upgrade_parser = subcommands.add_parser("upgrade")
2908
+ upgrade_parser.add_argument("tool")
2909
+ upgrade_parser.add_argument("--dry-run", action="store_true")
2910
+ upgrade_parser.add_argument(
2911
+ "--previous-bundle",
2912
+ type=Path,
2913
+ help="verified prior release identity when all console-script names changed",
2914
+ )
2915
+ rollback_parser = subcommands.add_parser("rollback")
2916
+ rollback_parser.add_argument("tool")
2917
+ rollback_parser.add_argument("--activate-production", action="store_true")
2918
+ return result
2919
+
2920
+
2921
+ def main(arguments: Sequence[str] | None = None) -> int:
2922
+ raw_argv = list(sys.argv[1:] if arguments is None else arguments)
2923
+ args = parser().parse_args(raw_argv)
2924
+ explicit_source_root = any(
2925
+ tok == "--source-root" or tok.startswith("--source-root=") for tok in raw_argv
2926
+ )
2927
+ source_root = args.source_root
2928
+ if (
2929
+ not explicit_source_root
2930
+ and getattr(args, "repo", None) is not None
2931
+ and not (source_root / "git-finalizer" / "toolchain_compatibility.json").is_file()
2932
+ ):
2933
+ source_root = _default_source_root(repo=args.repo)
2934
+ try:
2935
+ source_repos = {}
2936
+ for value in args.source_repo:
2937
+ name, separator, path = value.partition("=")
2938
+ if not separator or not SAFE_NAME.fullmatch(name) or not Path(path).is_absolute():
2939
+ raise SyncError("source-repo requires TOOL=/absolute/path")
2940
+ if name in source_repos:
2941
+ raise SyncError("source-repo contains a duplicate tool")
2942
+ source_repos[name] = Path(path)
2943
+ source_refs = {}
2944
+ for value in args.source_ref:
2945
+ name, separator, oid = value.partition("=")
2946
+ if not separator or not SAFE_NAME.fullmatch(name) or not FULL_GIT_OID.fullmatch(oid):
2947
+ raise SyncError("source-ref requires TOOL=FULL_COMMIT_OID")
2948
+ if name in source_refs:
2949
+ raise SyncError("source-ref contains a duplicate tool")
2950
+ source_refs[name] = oid
2951
+ sources = Sources(source_root, source_repos, source_refs)
2952
+ if args.command in {"skill-check", "skill-install"}:
2953
+ homes = _default_client_homes()
2954
+ for key, attr in (
2955
+ ("codex", "codex_home"),
2956
+ ("claude", "claude_home"),
2957
+ ("gemini", "gemini_home"),
2958
+ ("cursor", "cursor_home"),
2959
+ ("qoder", "qoder_home"),
2960
+ ):
2961
+ val = getattr(args, attr, None)
2962
+ if val is not None:
2963
+ homes[key] = val.resolve()
2964
+ if args.command == "skill-check":
2965
+ output = skill_check(sources, agents_root=args.agents_root.resolve(), client_homes=homes)
2966
+ print(canonical_json(output).decode(), end="")
2967
+ return 0 if output["status"] == "PASS" else 1
2968
+ output = skill_install(
2969
+ sources,
2970
+ agents_root=args.agents_root.resolve(),
2971
+ client_homes=homes,
2972
+ sync_clients=not args.no_sync_clients,
2973
+ )
2974
+ print(canonical_json(output).decode(), end="")
2975
+ return 0
2976
+ if args.command == "doctor":
2977
+ from . import workflow_health
2978
+ output = workflow_health.doctor(
2979
+ sources,
2980
+ agents_root=args.agents_root.resolve(),
2981
+ bin_dir=args.bin_dir,
2982
+ hooks_dir=args.hooks_dir.resolve(),
2983
+ repo=args.repo,
2984
+ codex_home=args.codex_home.resolve(),
2985
+ controller=args.controller,
2986
+ claude_home=args.claude_home.resolve(),
2987
+ controller_runtime_root=args.controller_runtime_root,
2988
+ controller_source=args.controller_source or source_root / "worktree-controller",
2989
+ previous_fingerprint=args.previous_fingerprint,
2990
+ )
2991
+ print(canonical_json(workflow_health.summary(output) if args.summary else output).decode(), end="")
2992
+ return 0 if output["status"] == "PASS" else 1
2993
+ if args.command == "status":
2994
+ output = status(sources, args.agents_root.resolve(), args.bin_dir)
2995
+ else:
2996
+ if args.tool not in sources.names():
2997
+ raise SyncError(f"unknown tool: {args.tool}")
2998
+ if args.command == "check":
2999
+ output = (
3000
+ check_tool(sources, args.tool)
3001
+ if args.source_only
3002
+ else check_tool_deployment(
3003
+ sources,
3004
+ args.tool,
3005
+ args.agents_root.resolve(),
3006
+ args.bin_dir,
3007
+ args.hooks_dir.resolve(),
3008
+ )
3009
+ )
3010
+ print(canonical_json(output).decode(), end="")
3011
+ return 0 if output["status"] == "PASS" else 1
3012
+ if args.command == "upgrade":
3013
+ output = upgrade(
3014
+ sources,
3015
+ args.tool,
3016
+ bin_dir=args.bin_dir,
3017
+ dry_run=args.dry_run,
3018
+ previous_bundle=args.previous_bundle,
3019
+ )
3020
+ print(canonical_json(output).decode(), end="")
3021
+ return 0
3022
+ if args.command == "install":
3023
+ output = install(
3024
+ sources,
3025
+ args.tool,
3026
+ args.install_root.resolve(),
3027
+ allow_dirty_source=args.allow_dirty_source,
3028
+ activate_production=args.activate_production,
3029
+ agents_root=args.agents_root.resolve(),
3030
+ bin_dir=args.bin_dir.resolve() if args.bin_dir else None,
3031
+ hooks_dir=args.hooks_dir.resolve(),
3032
+ )
3033
+ else:
3034
+ output = rollback(
3035
+ args.tool,
3036
+ args.install_root.resolve(),
3037
+ activate_production=args.activate_production,
3038
+ agents_root=args.agents_root.resolve(),
3039
+ bin_dir=args.bin_dir.resolve() if args.bin_dir else None,
3040
+ hooks_dir=args.hooks_dir.resolve(),
3041
+ )
3042
+ print(canonical_json(output).decode(), end="")
3043
+ return 0
3044
+ except (OSError, SyncError, subprocess.SubprocessError) as exc:
3045
+ print(f"tool-skill-sync: {exc}", file=sys.stderr)
3046
+ return 2
3047
+
3048
+
3049
+ if __name__ == "__main__":
3050
+ raise SystemExit(main())