getcodexy 1.13.0__tar.gz → 1.13.2__tar.gz

{getcodexy-1.13.0 → getcodexy-1.13.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: getcodexy
-Version: 1.13.0
+Version: 1.13.2
 Summary: A Codex harness for coordinating agents through planning, implementation, verification, and review.
 Author: Eunsoo Lee
 License-Expression: MIT

{getcodexy-1.13.0 → getcodexy-1.13.2}/build_backend.py

@@ -14,6 +14,7 @@ _PACKAGED_LOCK = _ROOT / "src/codexy_runtime_tools/_version_data/uv.lock"
 
 
 def _materialize_version_lock() -> None:
+    """Copy the canonical project lock into the package payload before builds."""
     contents = _CANONICAL_LOCK.read_bytes()
     if not contents:
         raise ValueError("packages/getcodexy/uv.lock must not be empty")

{getcodexy-1.13.0 → getcodexy-1.13.2}/pyproject.toml

@@ -5,7 +5,7 @@ backend-path = ["."]
 
 [project]
 name = "getcodexy"
-version = "1.13.0"
+version = "1.13.2"
 description = "A Codex harness for coordinating agents through planning, implementation, verification, and review."
 readme = { file = "README.md", content-type = "text/markdown" }
 requires-python = ">=3.10"

{getcodexy-1.13.0 → getcodexy-1.13.2}/src/codexy_runtime_tools/_version_data/uv.lock

@@ -4,5 +4,5 @@ requires-python = ">=3.10"
 
 [[package]]
 name = "getcodexy"
-version = "1.13.0"
+version = "1.13.2"
 source = { editable = "." }

{getcodexy-1.13.0 → getcodexy-1.13.2}/src/codexy_runtime_tools/activation_transaction.py

@@ -22,6 +22,7 @@ class ActivationSnapshot:
 
     @classmethod
     def capture(cls, home: Path) -> "ActivationSnapshot":
+        """Capture only Codexy activation paths and named config backups."""
         if not home.exists():
             return cls(home, ())
         files: list[Entry] = []
@@ -36,6 +37,7 @@ class ActivationSnapshot:
         return cls(home, tuple(files))
 
     def restore(self) -> None:
+        """Rebuild the captured paths without following links or overwriting files."""
         for root in (
             Path("agents/codexy-github"),
             Path("agents/codexy"),
@@ -47,6 +49,7 @@ class ActivationSnapshot:
                 _remove_tree(backup)
         if self.entries:
             self.home.mkdir(parents=True, exist_ok=True)
+        # Recreate parents before children; O_EXCL rejects unexpected replacements.
         for entry in sorted(self.entries, key=lambda item: len(item.relative.parts)):
             path = self.home / entry.relative
             if entry.data is None:
@@ -84,6 +87,7 @@ def _capture_directory(relative: Path, descriptor: int) -> list[Entry]:
     _require_safe(metadata, relative)
     entries = [Entry(relative, None, stat.S_IMODE(metadata.st_mode))]
     for name in sorted(os.listdir(descriptor)):
+        # Inspect children without following links, then confirm each opened inode.
         child = os.stat(name, dir_fd=descriptor, follow_symlinks=False)
         child_relative = relative / name
         _require_safe(child, child_relative)
@@ -174,6 +178,7 @@ def _open_directory(path: Path, expected: os.stat_result) -> int:
 
 
 def _require_safe(metadata: os.stat_result, path: Path) -> None:
+    """Reject links, multiply-linked files, and special files in activation state."""
     reparse = getattr(stat, "FILE_ATTRIBUTE_REPARSE_POINT", 0x400)
     if (
         stat.S_ISLNK(metadata.st_mode)

{getcodexy-1.13.0 → getcodexy-1.13.2}/src/codexy_runtime_tools/cache.py

@@ -1,3 +1,5 @@
+"""Validate plugin release identities and derive runtime cache keys."""
+
 from __future__ import annotations
 
 import hashlib
@@ -15,6 +17,7 @@ SEMVER = re.compile(
 
 
 def plugin_release(manifest_path: Path, package_override: bool = False) -> str:
+    """Return a valid manifest version or the explicit package-override identity."""
     if not manifest_path.is_file():
         if package_override:
             return "package-override"
@@ -29,6 +32,7 @@ def plugin_release(manifest_path: Path, package_override: bool = False) -> str:
 def releases_match(
     expected_manifest: Path, observed_manifest: Path
 ) -> tuple[bool, str]:
+    """Compare release versions while retaining safe mismatch text."""
     try:
         expected = plugin_release(expected_manifest)
     except (OSError, ValueError, json.JSONDecodeError):
@@ -54,7 +58,9 @@ def releases_match(
 def runtime_cache_key(
     *, manifest: Path, package_override: bool, identity: list[str]
 ) -> str:
+    """Bind cache identity to package release so an upgrade cannot reuse old state."""
     release = plugin_release(manifest, package_override)
+    # NUL delimiters prevent adjacent identity components from becoming ambiguous.
     digest_input = "\0".join(
         ("codexy.runtime-cache/v2", *identity[:-1], release, identity[-1])
     )

{getcodexy-1.13.0 → getcodexy-1.13.2}/src/codexy_runtime_tools/component-manifest.json

@@ -29,7 +29,7 @@
     {
       "id": "core",
       "plugin": "codexy",
-      "version": "1.13.0",
+      "version": "1.13.2",
       "dependencies": [],
       "asset": {
         "pluginId": "codexy@codexy",
@@ -63,7 +63,7 @@
     {
       "id": "github",
       "plugin": "codexy-github",
-      "version": "1.13.0",
+      "version": "1.13.2",
       "dependencies": [
         "core"
       ],
@@ -79,7 +79,7 @@
     {
       "id": "devtools",
       "plugin": "codexy-devtools",
-      "version": "1.13.0",
+      "version": "1.13.2",
       "dependencies": [
         "core"
       ],
@@ -97,27 +97,27 @@
   "compatibleCombinations": [
     {
       "components": [],
-      "version": "1.13.0"
+      "version": "1.13.2"
     },
     {
       "components": [
         "core"
       ],
-      "version": "1.13.0"
+      "version": "1.13.2"
     },
     {
       "components": [
         "core",
         "github"
       ],
-      "version": "1.13.0"
+      "version": "1.13.2"
     },
     {
       "components": [
         "core",
         "devtools"
       ],
-      "version": "1.13.0"
+      "version": "1.13.2"
     },
     {
       "components": [
@@ -125,7 +125,7 @@
         "github",
         "devtools"
       ],
-      "version": "1.13.0"
+      "version": "1.13.2"
     }
   ]
 }

{getcodexy-1.13.0 → getcodexy-1.13.2}/src/codexy_runtime_tools/component_capability_observation.py

@@ -39,6 +39,7 @@ def component_observations(
         name: _entry(configured, source=_REGISTRATION_SOURCE, scope=_REGISTRATION_SCOPE)
         for name in CAPABILITIES.get(component, ())
     }
+    # Registration establishes configuration only; absent direct probes stay unknown.
     if not probe:
         return observations
     direct = probe.get("_capability_probes")
@@ -94,6 +95,7 @@ def _entry(
     source: str,
     scope: str,
 ) -> dict[str, object]:
+    """Keep unobserved capability states unknown and never infer verification."""
     return {
         "states": {
             "configured": "configured" if configured else UNKNOWN,

{getcodexy-1.13.0 → getcodexy-1.13.2}/src/codexy_runtime_tools/component_capability_probe.py

@@ -57,6 +57,7 @@ def _request(method, identifier=None, params=None):
 
 
 def probe_component(component, plugin, record):
+    """Probe one installed component, keeping core hook and watcher checks linked."""
     base = _base(record)
     if plugin is None:
         return base
@@ -67,6 +68,7 @@ def probe_component(component, plugin, record):
 
 
 def _probe_core(plugin, base):
+    # The watcher probe depends on a callable core hook; merge only observed results.
     hook = _probe_hook("core", plugin, base)
     if not hook.get("started") or not hook.get("callable"):
         return hook
@@ -80,6 +82,7 @@ def _probe_core(plugin, base):
 
 
 def _probe_hook(component, plugin, base):
+    """Execute a registered hook and validate its event-specific response."""
     event, marker = HOOK_SPECS[component]
     capability = f"hook:{marker}"
     payload = {"prompt": "review GitHub issue 723"}
@@ -121,6 +124,7 @@ def _probe_hook(component, plugin, base):
 
 
 def _registered_hook(plugin, event, marker):
+    """Return the platform-specific command for the registered marker, if any."""
     try:
         hooks = json.loads((plugin / "hooks/hooks.json").read_text(encoding="utf-8"))
     except (OSError, ValueError, json.JSONDecodeError):
@@ -163,6 +167,7 @@ def _argv(command, plugin, args=()):
         and values[0].lower().endswith((".bat", ".cmd"))
         and os.path.isfile(values[0])
     ):
+        # Batch files need cmd.exe quoting; other launchers remain an argv sequence.
         shell = os.environ.get("COMSPEC", "cmd.exe")
         command = f'"{values[0]}" {subprocess.list2cmdline(values[1:])}'.rstrip()
         return f'{subprocess.list2cmdline([shell])} /d /s /c "{command}"'
@@ -178,6 +183,7 @@ def probe_reason(probe, default):
 
 
 def identity_matches(manifest, component, record, probe):
+    """Require the registered release to match each probed runtime."""
     names = probe.get("runtime_names")
     versions = probe.get("runtime_versions")
     return (

{getcodexy-1.13.0 → getcodexy-1.13.2}/src/codexy_runtime_tools/component_cli.py

@@ -20,6 +20,7 @@ from .version_lock import default_package_version
 
 
 def main(argv: list[str] | None = None) -> int:
+    """Dispatch lifecycle and inspection commands to their stable receipt forms."""
     parser = argparse.ArgumentParser(prog="getcodexy", allow_abbrev=False)
     parser.add_argument(
         "--codex",
@@ -68,6 +69,7 @@ def main(argv: list[str] | None = None) -> int:
                 arguments.codex,
             )
     except PreAdmissionError as error:
+        # Host admission failures use machine receipts only where JSON was requested.
         if arguments.command == "bootstrap" and arguments.json_output:
             print(json.dumps(_bootstrap_host_failure(), sort_keys=True))
             return 2
@@ -92,6 +94,7 @@ def main(argv: list[str] | None = None) -> int:
 
 
 def _record_capability_failures(receipt: dict[str, object]) -> None:
+    """Add each known live capability failure once to doctor/status errors."""
     errors = receipt.get("errors")
     health = receipt.get("component_health")
     if not isinstance(errors, list) or not isinstance(health, list):
@@ -140,6 +143,7 @@ def _human(command: str, receipt: dict[str, object]) -> str:
     if command in {"install", "update", "remove", "bootstrap"} and receipt.get(
         "outcome"
     ) in {"completed", "pending-action"}:
+        # A new Codex task is needed because the host loads installed tools at startup.
         return (
             f"getcodexy {command}: {receipt['outcome']}; "
             "start a fresh Codex task to refresh installed plugins and MCP tools"
@@ -165,6 +169,7 @@ def _human(command: str, receipt: dict[str, object]) -> str:
 
 
 def _bootstrap_host_failure() -> dict[str, object]:
+    """Encode trusted-host admission rejection using the bootstrap receipt schema."""
     rejection = Rejection.from_failure(
         RejectionStage.HOST, StateFailure.INCONSISTENT_INSTALLED_STATE
     )
@@ -174,6 +179,7 @@ def _bootstrap_host_failure() -> dict[str, object]:
 
 
 def _migration_host_failure() -> dict[str, object]:
+    """Return the equivalent machine-readable migration rejection without running it."""
     return {
         "schema": "getcodexy.monolith-migration-receipt.v1",
         "command": "migrate",

{getcodexy-1.13.0 → getcodexy-1.13.2}/src/codexy_runtime_tools/component_core_hooks.py

@@ -14,6 +14,8 @@ LAUNCHERS = tuple(
     for _, stem in (*COMMAND_HOOKS, *LIFECYCLE_HOOKS)
     for extension in ("sh", "cmd")
 )
+# Windows invokes the event script with `py.exe -3 -I -B`, bypassing the POSIX
+# resolver; keep the entrypoint and sibling event helper in this required set.
 DEPENDENCIES = (
     "hooks/codexy-hook-runtime.sh",
     "hooks/codexy-thread-delivery.py",
@@ -30,4 +32,5 @@ DEPENDENCIES = (
     "hooks/codexy-watcher-interrupt.sh",
     "hooks/codexy-watcher-interrupt.cmd",
     "hooks/codexy_watcher_interrupt.py",
+    "hooks/codexy_watcher_interrupt_events.py",
 )

{getcodexy-1.13.0 → getcodexy-1.13.2}/src/codexy_runtime_tools/component_health.py

@@ -41,7 +41,7 @@ def health(
     activation: dict[str, str] | None = None,
     codex_home=None,
 ) -> list[dict[str, object]]:
-    expected = set(recorded or ()) | set(actual)
+    expected = set(recorded or ()) | set(actual)  # Include known and live components.
     context = (
         manifest,
         actual,
@@ -118,7 +118,7 @@ def _component_health(context, component):
         (not installed, "installed", "component-not-installed"),
         (not configured, "configured", "component-not-configured"),
     )
-    for failed, stage, reason in checks:
+    for failed, stage, reason in checks:  # Report the earliest failure.
         if failed:
             return _mark(result, stage, reason)
     if activation is not None and component in activation:
@@ -155,7 +155,7 @@ def _component_health(context, component):
 
 
 def _mark(result: dict[str, object], stage: str, reason: str) -> dict[str, object]:
-    fallback, restart = FAILURES[reason]
+    fallback, restart = FAILURES[reason]  # Map the reason to recovery guidance.
     result.update(
         first_failure_stage=stage,
         reason_code=reason,
@@ -173,7 +173,7 @@ def _mark(result: dict[str, object], stage: str, reason: str) -> dict[str, objec
 
 
 def _registration_roles(home, root, marker, expected, read_regular, max_bytes):
-    roles, managed, unmanaged = [], [], []
+    roles, managed, unmanaged = [], [], []  # Track expected and marker-owned roles.
     for name, value in expected.items():
         roles.append(
             _registered_role(home, root, name, value, marker, read_regular, max_bytes)
@@ -219,7 +219,7 @@ def _registered_role(
     read_regular,
     max_bytes: int,
 ) -> dict[str, object]:
-    try:
+    try:  # Inspect the marker-owned role file as a bounded regular input.
         current = (
             read_regular(home, root.relative_to(home) / name, max_bytes)
             .decode()

{getcodexy-1.13.0 → getcodexy-1.13.2}/src/codexy_runtime_tools/component_health_support.py

@@ -36,6 +36,7 @@ def _legacy_state(
     host_error,
     codex_home=None,
 ):
+    """Preserve the coarse state contract while checking installed package integrity."""
     record = records.get(component)
     if admission_error or host_error:
         return "incompatible"
@@ -94,6 +95,7 @@ def _observed(record):
 
 
 def _authority_valid(record):
+    """Accept explicit attestation or recognized local marketplace forms."""
     if not record:
         return False
     key = next((key for key in AUTHORITY_KEYS if key in record), None)
@@ -128,6 +130,7 @@ def _authority_valid(record):
 
 
 def version_relation(manifest, record):
+    """Treat unparseable installed versions as incompatible, never as a match."""
     try:
         return compare_versions(record_version(record), manifest.version)
     except ComponentResolutionError:

{getcodexy-1.13.0 → getcodexy-1.13.2}/src/codexy_runtime_tools/component_hook_activation_expected.py

@@ -32,6 +32,8 @@ _EVENT_KEYS = {
 
 @dataclass(frozen=True)
 class ExpectedHook:
+    """Installed hook identity and settings used to verify the host's active row."""
+
     component: str
     plugin_id: str
     version: str
@@ -48,6 +50,7 @@ class ExpectedHook:
 
     @property
     def key(self) -> str:
+        """Keep duplicate registrations distinct by their declared array positions."""
         return (
             f"{self.plugin_id}:hooks/hooks.json:{self.event_key}:"
             f"{self.group_index}:{self.hook_index}"
@@ -59,6 +62,7 @@ def expected_hooks(
     components: tuple[str, ...],
     records: dict[str, dict[str, object]],
 ) -> dict[str, tuple[ExpectedHook, ...]]:
+    """Parse installed manifests into exact, platform-specific hook expectations."""
     expected: dict[str, tuple[ExpectedHook, ...]] = {}
     for component in components:
         record = records.get(component)
@@ -81,6 +85,7 @@ def expected_hooks(
             raise HookStateError("installed hook registration has an invalid shape")
         hooks_map = cast(dict[str, object], hooks)
         entries: list[ExpectedHook] = []
+        # Event, positions, and command variant bind each host row to its source.
         for event, groups_value in hooks_map.items():
             if event not in _EVENT_LABELS or event not in _EVENT_KEYS:
                 raise HookStateError("installed hook registration has an unknown event")

{getcodexy-1.13.0 → getcodexy-1.13.2}/src/codexy_runtime_tools/component_hook_activation_host.py

@@ -43,6 +43,7 @@ def list_hooks(executable: Path, codex_home: Path) -> tuple[dict[str, object], .
             "unable to determine the inspected working directory"
         ) from error
     environment = os.environ.copy()
+    # Drop inherited variables that can redirect Git or Python during host startup.
     for name in _ENVIRONMENT_UNSAFE:
         _ = environment.pop(name, None)
     environment.update(
@@ -132,6 +133,7 @@ def list_hooks(executable: Path, codex_home: Path) -> tuple[dict[str, object], .
             pass
         cleanup_failed = False
         if process.poll() is None:
+            # Stop the Windows process tree; POSIX cleans up the direct child.
             if os.name == "nt":
                 try:
                     _ = process.wait(timeout=1)
@@ -194,6 +196,7 @@ def normalize_hook_rows(value: object) -> tuple[dict[str, object], ...]:
         if isinstance(hooks, list):
             value = cast(list[object], hooks)
         elif isinstance(data, list):
+            # Host versions may group hooks by CWD; reject any group carrying warnings.
             flattened: list[dict[str, object]] = []
             for item_value in cast(list[object], data):
                 if not isinstance(item_value, dict):
@@ -223,6 +226,7 @@ def normalize_hook_rows(value: object) -> tuple[dict[str, object], ...]:
 
 
 def _response(values: queue.Queue[object], identifier: int) -> dict[str, object]:
+    """Wait for the requested JSON-RPC id within this call's timeout window."""
     deadline = time.monotonic() + HOOK_LIST_TIMEOUT_SECONDS
     while True:
         remaining = deadline - time.monotonic()

{getcodexy-1.13.0 → getcodexy-1.13.2}/src/codexy_runtime_tools/component_hook_activation_validation.py

@@ -16,6 +16,7 @@ def classify_activation(
     *,
     codex_home: Path | None = None,
 ) -> dict[str, str]:
+    """Require one enabled, trusted host row matching each installed hook exactly."""
     observed = normalize_hook_rows(rows)
     by_key: dict[str, list[dict[str, object]]] = {}
     for row in observed:
@@ -38,6 +39,7 @@ def classify_activation(
         component_keys = {
             row.get("key") for row in component_rows if isinstance(row.get("key"), str)
         }
+        # Extra rows indicate stale host state, even when required rows match.
         if component_keys - required_keys:
             failures[component] = "required-hook-trust-stale"
             continue

getcodexy-1.13.2/src/codexy_runtime_tools/component_hook_registration.py

@@ -0,0 +1,120 @@
+"""Canonical hook manifests for installed Codexy components."""
+
+from .component_core_hooks import (
+    COMMAND_HOOKS as _CORE_COMMAND_HOOKS,
+    LIFECYCLE_HOOKS as _CORE_LIFECYCLE_HOOKS,
+    LAUNCHERS as CORE_HOOK_LAUNCHERS,
+)
+
+
+def _hook(command: str, windows: str, timeout: int) -> dict[str, object]:
+    return {
+        "type": "command",
+        "command": command,
+        "commandWindows": windows,
+        "timeout": timeout,
+    }
+
+
+def _command_hook(matcher: str, launcher_stem: str, event: str) -> dict[str, object]:
+    command = f'"${{PLUGIN_ROOT}}/hooks/{launcher_stem}'
+    return {
+        "matcher": matcher,
+        "hooks": [_hook(f'{command}.sh" {event}', f'{command}.cmd" {event}', 5)],
+    }
+
+
+def _lifecycle_hook(launcher_stem: str, event: str) -> dict[str, object]:
+    command = f'"${{PLUGIN_ROOT}}/hooks/{launcher_stem}'
+    return {"hooks": [_hook(f'{command}.sh" {event}', f'{command}.cmd" {event}', 3)]}
+
+
+def _bash_hooks(event: str) -> list[dict[str, object]]:
+    return [_command_hook("^Bash$", "codexy-destructive-command", event)]
+
+
+def _title_hooks(event: str) -> list[dict[str, object]]:
+    return [_title_hook(matcher, kind, event) for matcher, kind in _TITLE_MATCHERS]
+
+
+def _title_hook(matcher: str, kind: str, event: str) -> dict[str, object]:
+    return {
+        "matcher": matcher,
+        "hooks": [
+            _hook(
+                f'"${{PLUGIN_ROOT}}/hooks/codexy-title-check.sh" {event} {kind}',
+                f'"${{PLUGIN_ROOT}}/hooks/codexy-title-check.cmd" {event} {kind}',
+                5,
+            )
+        ],
+    }
+
+
+_TITLE_MATCHERS = (
+    (
+        "^(?:mcp__codex_apps__github_(?:create|update)_issue|github\\.(?:create|update)_issue)$",
+        "issue",
+    ),
+    (
+        "^(?:mcp__codex_apps__github_(?:create|update)_pull_request|github\\.(?:create|update)_pull_request)$",
+        "pr",
+    ),
+    (
+        "^(?:mcp__codex_apps__github_(?:merge_pull_request|enable_auto_merge)|github\\.(?:merge_pull_request|enable_auto_merge))$",
+        "merge",
+    ),
+    ("^functions\\.exec$", "nested"),
+    ("^Bash$", "shell"),
+)
+
+
+def _core_hooks() -> dict[str, object]:
+    """Build core event groups, keeping interrupt and prompt callbacks matcher-free."""
+    command = lambda event: [
+        _command_hook(matcher, stem, event) for matcher, stem in _CORE_COMMAND_HOOKS
+    ]
+    lifecycle = lambda event: [
+        _command_hook(matcher, stem, event) for matcher, stem in _CORE_LIFECYCLE_HOOKS
+    ]
+    return {
+        "hooks": {
+            "PermissionRequest": command("PermissionRequest"),
+            "PreToolUse": command("PreToolUse") + lifecycle("PreToolUse"),
+            "Interrupt": [
+                _lifecycle_hook(stem, "Interrupt") for _, stem in _CORE_LIFECYCLE_HOOKS
+            ],
+            "UserPromptSubmit": [
+                _lifecycle_hook(stem, "UserPromptSubmit")
+                for _, stem in _CORE_LIFECYCLE_HOOKS
+            ],
+        }
+    }
+
+
+def _github_hooks() -> dict[str, object]:
+    context = '"${PLUGIN_ROOT}/hooks/codexy-github-workflow-context'
+    return {
+        "hooks": {
+            "UserPromptSubmit": [
+                {"hooks": [_hook(f'{context}.sh"', f'{context}.cmd"', 5)]}
+            ],
+            "PermissionRequest": _title_hooks("PermissionRequest")
+            + _bash_hooks("PermissionRequest"),
+            "PreToolUse": _title_hooks("PreToolUse") + _bash_hooks("PreToolUse"),
+        }
+    }
+
+
+HOOKS = {"core": _core_hooks(), "github": _github_hooks()}
+LAUNCHERS = {
+    "core": CORE_HOOK_LAUNCHERS,
+    "github": (
+        "hooks/codexy-github-workflow-context.sh",
+        "hooks/codexy-github-workflow-context.cmd",
+        "hooks/codexy-title-check.sh",
+        "hooks/codexy-title-check.cmd",
+        "hooks/codexy-destructive-command.sh",
+        "hooks/codexy-destructive-command.cmd",
+    ),
+    "devtools": ("mcp/codexy-mcp-devtools",),
+}

{getcodexy-1.13.0 → getcodexy-1.13.2}/src/codexy_runtime_tools/component_inspection.py

@@ -104,6 +104,7 @@ def _inspect(
     runner: Runner | None,
     hook_lister: HookLister | None = None,
 ) -> InspectionReport:
+    """Compare live host and hook state with recorded package data."""
     home, manifest = _absolute(codex_home), load_component_manifest()
     _validate_real_path(home, require_exists=False)
     recorded, inventory, inventory_error = _recorded(home)
@@ -115,6 +116,7 @@ def _inspect(
     host_error = probe.value if probe else None
     if probe is None:
         assert executable is not None and invoke is not None
+        # Installed-plugin and marketplace reads supply live authority for the report.
         try:
             installed = _json(
                 invoke([str(executable), "plugin", "list", "--json"]), "plugin list"
@@ -210,6 +212,7 @@ def _actual(
     installed: object,
     root: MarketplaceBinding | None,
 ) -> tuple[tuple[str, ...], dict[str, dict[str, object]], str | None]:
+    """Reconcile parsed installed records with host-admitted canonical components."""
     actual: tuple[str, ...] = ()
     records: dict[str, dict[str, object]] = {}
     try:

{getcodexy-1.13.0 → getcodexy-1.13.2}/src/codexy_runtime_tools/component_inspection_host.py

@@ -23,6 +23,7 @@ class ProbeStage(str, Enum):
 def host(
     home: Path, codex: Path | None, runner: Runner | None
 ) -> tuple[Path, Runner, None] | tuple[None, None, ProbeStage]:
+    """Resolve Codex and return a stage-specific setup failure."""
     try:
         return (
             trusted_codex(codex or _find_codex()),

{getcodexy-1.13.0 → getcodexy-1.13.2}/src/codexy_runtime_tools/component_inspection_types.py

@@ -6,6 +6,8 @@ from .component_manifest import ComponentManifest
 
 
 class InspectionReport(TypedDict):
+    """Internal read-only snapshot shared by status and doctor projections."""
+
     manifest: ComponentManifest
     actual: tuple[str, ...]
     recorded: tuple[str, ...] | None

{getcodexy-1.13.0 → getcodexy-1.13.2}/src/codexy_runtime_tools/component_integrity.py

@@ -41,8 +41,8 @@ def _verify_component(
 def _read_component(
     root: Path, verified: dict[Path, bytes], modes: dict[Path, int]
 ) -> None:
-    size = sum(map(len, verified.values()))
-    pending = [Path()]
+    size = sum(map(len, verified.values()))  # The manifest shares the same cap.
+    pending = [Path()]  # Traverse from the component root.
     while pending:
         relative_directory = pending.pop()
         directory = root / relative_directory
@@ -94,7 +94,7 @@ def frozen_component(
             )
             with os.fdopen(descriptor, "wb") as output:
                 output.write(data)
-            os.chmod(destination, 0o600 | (modes.get(relative, 0) & 0o111))
+            os.chmod(destination, 0o600 | (modes.get(relative, 0) & 0o111))  # keep exec
         yield target
 
 
@@ -177,7 +177,7 @@ def _read_regular_windows(
         opened = os.fstat(descriptor)
         if not stat.S_ISREG(opened.st_mode):
             raise ValueError(f"component integrity requires regular files: {target}")
-        _, final = _windows_safe_path(root, relative)
+        _, final = _windows_safe_path(root, relative)  # Recheck path after opening it.
         if (opened.st_dev, opened.st_ino) != (final.st_dev, final.st_ino):
             raise ValueError(
                 f"component integrity path changed while reading: {target}"
@@ -231,7 +231,7 @@ def _has_windows_reparse_point(metadata: os.stat_result) -> bool:
 def valid_agent_toml(text: str, path: Path) -> bool:
     try:
         import tomllib
-    except ModuleNotFoundError:
+    except ModuleNotFoundError:  # Keep validation dependency-free on older runtimes.
         import ast
 
         tree = ast.parse(text, filename=str(path))