ai-push-hooks 0.3.3 → 0.3.4

package/CHANGELOG.md

@@ -4,6 +4,36 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
+## [0.3.4] - 2026-09-14
+
+This is the first stable release. Python and npm both use `0.3.4`, the canonical
+Git tag is `v0.3.4`, npm uses the `latest` dist-tag, and GitHub publishes a
+standard release.
+
+### Fixed
+
+- Failed the clean-worktree gate when Git cannot verify checkout status.
+- Rejected apply destinations inside configured Git hooks directories before
+  propagating any changes to the checkout.
+- Isolated npm's Python startup from consuming-repository modules, inherited
+  `PYTHONPATH`, and user-site imports so they cannot replace the installed hook.
+- Excluded Git-ignored local documentation from default model context collection.
+- Required explicit boolean Beads verdicts before commands, report changes, or
+  quality-gate decisions.
+- Kept failed command output in private artifacts rather than terminal errors.
+- Redacted known sensitive values across diagnostic truncation and partial-output
+  boundaries, including timeout errors.
+- Collected review diffs independently of external diff drivers, text conversion,
+  and color settings.
+- Made private runtime directory creation tolerate concurrent OpenCode stages
+  while retaining directory and symlink checks.
+- Included regular-file, symlink, and other Git type changes in pushed-file
+  facts exposed to workflows and Python callbacks.
+- Preserved each Python callback source's annotation semantics and registered
+  callback modules for dataclasses and runtime type-hint introspection.
+- Validated recovered Actions artifacts against their associated push run,
+  release workflow, repository, tag, and commit before downloading archives.
+
 ## [0.3.3] - 2026-09-14
 
 This is a beta patch release. Python and npm both use `0.3.3`, the canonical
@@ -215,7 +245,8 @@ the exact `0.2.0` version rather than a PyPI beta channel.
 - Preserved Git porcelain paths and protected pre-existing dirty allowlisted files during apply steps.
 - Clarified module-local artifact references and standardized the repository hook integration.
 
-[Unreleased]: https://github.com/shanebishop1/ai-push-hooks/compare/v0.3.3...HEAD
+[Unreleased]: https://github.com/shanebishop1/ai-push-hooks/compare/v0.3.4...HEAD
+[0.3.4]: https://github.com/shanebishop1/ai-push-hooks/compare/v0.3.3...v0.3.4
 [0.3.3]: https://github.com/shanebishop1/ai-push-hooks/compare/v0.3.2...v0.3.3
 [0.3.2]: https://github.com/shanebishop1/ai-push-hooks/compare/v0.3.1...v0.3.2
 [0.3.1]: https://github.com/shanebishop1/ai-push-hooks/compare/v0.3.0...v0.3.1

package/README.md

@@ -1,6 +1,6 @@
 # ai-push-hooks
 
-[![CI](https://github.com/shanebishop1/ai-push-hooks/actions/workflows/ci.yml/badge.svg)](https://github.com/shanebishop1/ai-push-hooks/actions/workflows/ci.yml) [![npm beta](https://img.shields.io/npm/v/ai-push-hooks/beta?label=npm%20beta)](https://www.npmjs.com/package/ai-push-hooks/v/beta)
+[![CI](https://github.com/shanebishop1/ai-push-hooks/actions/workflows/ci.yml/badge.svg)](https://github.com/shanebishop1/ai-push-hooks/actions/workflows/ci.yml) [![npm](https://img.shields.io/npm/v/ai-push-hooks)](https://www.npmjs.com/package/ai-push-hooks)
 
 **Agentic linting for the rules your coding agent forgot.**
 
@@ -30,7 +30,7 @@ Use it alongside [Lefthook](https://github.com/evilmartians/lefthook) for hook m
 Install the [ai-push-hooks skill](https://github.com/shanebishop1/ai-push-hooks/blob/main/skills/ai-push-hooks/SKILL.md), tell your agent what intelligent checks you want before pushes, and let it set up the modules for you.
 
 ```bash
-npm install --save-dev ai-push-hooks@beta
+npm install --save-dev ai-push-hooks
 npx --no-install ai-push-hooks init
 npx --no-install ai-push-hooks install
 ```

package/SECURITY.md

@@ -40,6 +40,14 @@ transcript files as proof that provider-side data was deleted.
 
 ## Repository callbacks and commands
 
+The npm launcher uses Python isolated mode to prevent the consuming checkout,
+inherited `PYTHONPATH`, and the user site directory from shadowing the shipped
+launcher or standard-library modules. It retains the selected interpreter's
+normal system/virtual-environment site-packages for callback dependencies; use
+that environment rather than `--user` installs or `PYTHONPATH`. This is launch
+path isolation, not an operating-system sandbox, and trusted interpreter
+startup customization or callback code is not made safe by it.
+
 The published `0.3.0` beta includes the `ask` spelling, repository Python
 callbacks, and direct `exec`/`assert` commands. The previous `0.2.1` beta used
 `llm` for model-backed workflow steps; there is no compatibility alias, so
@@ -70,9 +78,11 @@ default command timeout is 60 seconds. stdout/stderr are private, unredacted
 is capped at 16 MiB; invalid UTF-8, timeout, signal, missing executable, or
 truncation fails closed. A command may explicitly invoke `bash -c`, and
 `exec`/`assert` commands may modify the real checkout, so these are user-policy
-choices rather than host isolation guarantees. `assert` saves its report before
-blocking on a false/nonzero result. Only the workflow-level fail-open setting
-overrides that block; there is no per-command override.
+choices rather than host isolation guarantees. Failed command diagnostics name
+the step, status/error class, and private artifact namespace only; they never
+include captured stream text. `assert` saves its report before blocking on a
+false/nonzero result. Only the workflow-level fail-open setting overrides that
+block; there is no per-command override.
 
 Read-only `collect` callback work may overlap up to `max_parallel`; trusted
 callback/command authors must provide their own concurrency safety. `exec` and

package/bin/ai-push-hooks.js

@@ -5,17 +5,22 @@ const fs = require('node:fs');
 const path = require('node:path');
 
 const packageRoot = path.resolve(__dirname, '..');
-const srcDir = path.join(packageRoot, 'src');
-const tomliWheel = path.join(packageRoot, 'vendor', 'tomli-2.4.0-py3-none-any.whl');
-const args = ['-m', 'ai_push_hooks', ...process.argv.slice(2)];
+const bootstrap = path.join(packageRoot, 'bin', 'bootstrap.py');
+const capabilityEnvironment = 'AI_PUSH_HOOKS_INTERNAL_CAPABILITY';
+const args = ['-I', bootstrap, ...process.argv.slice(2)];
 const pythonCommands = ['python3.14', 'python3.13', 'python3.12', 'python3.11', 'python3.10', 'python3', 'python'];
 
-function buildEnv() {
+function buildEnv(capability = false) {
   const env = { ...process.env };
   env.AI_PUSH_HOOKS_NODE_EXECUTABLE = process.execPath;
   env.AI_PUSH_HOOKS_NODE_SCRIPT = fs.realpathSync(__filename);
-  // Pure-Python wheels are importable archives; no pip or install scripts needed.
-  env.PYTHONPATH = [srcDir, tomliWheel, env.PYTHONPATH].filter(Boolean).join(path.delimiter);
+  // -I intentionally ignores PYTHONPATH.  The bootstrap adds only shipped paths.
+  delete env.PYTHONPATH;
+  if (capability) {
+    env[capabilityEnvironment] = '1';
+  } else {
+    delete env[capabilityEnvironment];
+  }
   return env;
 }
 
@@ -29,11 +34,8 @@ function run(command) {
 function canRunPackage(command) {
   const check = spawnSync(
     command,
-    [
-      '-c',
-      'import sys; assert sys.version_info >= (3, 10); __import__("tomllib" if sys.version_info >= (3, 11) else "tomli")',
-    ],
-    { stdio: 'ignore', env: buildEnv() },
+    ['-I', bootstrap],
+    { stdio: 'ignore', env: buildEnv(true) },
   );
   return check.status === 0;
 }

package/bin/bootstrap.py

@@ -0,0 +1,69 @@
+"""Isolated entry point for the npm launcher.
+
+The npm package is not a Python installation.  This file adds only the Python
+sources and the vendored Python 3.10 TOML dependency shipped beside it, while
+leaving the selected interpreter's regular site-packages available for user
+callbacks.
+"""
+
+from __future__ import annotations
+
+import os
+import pathlib
+import runpy
+import sys
+
+
+_PACKAGE_ROOT = pathlib.Path(__file__).resolve().parent.parent
+_SHIPPED_SOURCE = _PACKAGE_ROOT / "src"
+_SHIPPED_TOMLI = _PACKAGE_ROOT / "vendor" / "tomli-2.4.0-py3-none-any.whl"
+_CAPABILITY_ENVIRONMENT = "AI_PUSH_HOOKS_INTERNAL_CAPABILITY"
+
+
+def _without_working_directory(entries: list[str]) -> list[str]:
+    working_directory = os.path.realpath(os.getcwd())
+    safe_entries: list[str] = []
+    for entry in entries:
+        if not entry or not os.path.isabs(entry):
+            continue
+        try:
+            if os.path.realpath(entry) == working_directory:
+                continue
+        except OSError:
+            continue
+        safe_entries.append(entry)
+    return safe_entries
+
+
+def _configure_imports() -> None:
+    """Retain interpreter site-packages and add only shipped import paths."""
+    sys.path[:] = _without_working_directory(sys.path)
+    sys.path.insert(0, str(_SHIPPED_TOMLI))
+    sys.path.insert(0, str(_SHIPPED_SOURCE))
+
+
+def _has_supported_toml() -> bool:
+    if sys.version_info < (3, 10):
+        return False
+    try:
+        if sys.version_info >= (3, 11):
+            import tomllib  # noqa: F401
+        else:
+            import tomli  # noqa: F401
+    except ImportError:
+        return False
+    return True
+
+
+def main() -> int:
+    _configure_imports()
+    if not _has_supported_toml():
+        return 1
+    if os.environ.get(_CAPABILITY_ENVIRONMENT) == "1":
+        return 0
+    runpy.run_module("ai_push_hooks", run_name="__main__")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/docs/configuration.md

@@ -4,12 +4,14 @@ Define workflows in `ai-push-hooks.toml` at the repository root. Start with the
 
 ## Installation
 
-The [npm quick start](../README.md#quick-start) installs a repository-local wrapper. It needs Node 18+ and Python 3.10-3.13 on the hook's `PATH`; the npm package does not bundle Python.
+The [npm quick start](../README.md#quick-start) installs a repository-local wrapper. Its tested/supported Python range is 3.10-3.13; the Python code requires 3.10+ and the launcher may probe newer interpreters, but newer versions are not part of that compatibility claim. The npm package does not bundle Python. The wrapper starts the selected interpreter in Python isolated mode: it ignores `PYTHONPATH` and the user site directory, then adds only the package's shipped `src` and vendored Tomli wheel. The interpreter's normal system or virtual-environment site-packages remain available.
+
+If a repository callback needs an external dependency, install it with the exact Python executable the wrapper will select (for example, `/path/to/python -m pip install <dependency>`), into that interpreter's normal system or virtual-environment site-packages. The wrapper tests candidates in its ordered list (`python3.14`, `python3.13`, `python3.12`, `python3.11`, `python3.10`, `python3`, then `python`), so activating a virtual environment alone does not guarantee that it wins over a higher-priority executable elsewhere on `PATH`; make the intended candidate discoverable first. Do not rely on `pip install --user` or `PYTHONPATH`; they are intentionally not part of the npm launch path.
 
 For pnpm:
 
 ```bash
-pnpm add -D ai-push-hooks@beta
+pnpm add -D ai-push-hooks
 pnpm exec ai-push-hooks init --template minimal-docs
 pnpm exec ai-push-hooks install
 ```
@@ -22,7 +24,7 @@ ai-push-hooks init --template minimal-docs
 ai-push-hooks install
 ```
 
-`uv tool install ai-push-hooks` or `pipx install ai-push-hooks` can replace the pip command. npm uses the `beta` tag while the package is in beta.
+`uv tool install ai-push-hooks` or `pipx install ai-push-hooks` can replace the pip command.
 
 AI steps need the selected CLI installed and authenticated with an available model. Deterministic-only workflows do not need one. `init` and `install` refuse to overwrite existing files; `--force` explicitly replaces them.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-push-hooks",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "description": "Run structured AI-assisted checks and allowlisted maintenance before git push",
   "license": "MIT",
   "author": {

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ai-push-hooks"
-version = "0.3.3"
+version = "0.3.4"
 description = "Run structured AI-assisted checks and allowlisted maintenance before git push"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -12,7 +12,7 @@ license = "MIT"
 authors = [{ name = "Shane Bishop" }]
 keywords = ["git", "lefthook", "docs", "ai", "pre-push"]
 classifiers = [
-  "Development Status :: 4 - Beta",
+  "Development Status :: 5 - Production/Stable",
   "Intended Audience :: Developers",
   "Programming Language :: Python :: 3",
   "Programming Language :: Python :: 3 :: Only",

package/src/ai_push_hooks/cli.py

@@ -10,6 +10,7 @@ from .hook import run_hook
 from .install import install_hook
 from .paths import path_is_link_or_reparse, write_text_no_follow
 from .prompts_builtin import MINIMAL_DOCS_TEMPLATE
+from .executors.runners import RunnerError
 from .types import HookError
 
 
@@ -117,6 +118,6 @@ def main(argv: list[str] | None = None) -> int:
         if args.command == "install":
             return install_hook(args.force)
         raise HookError(f"Unknown command: {args.command}")
-    except HookError as exc:
+    except (HookError, RunnerError) as exc:
         sys.stderr.write(f"[ai-push-hooks] {exc}\n")
         return 1

package/src/ai_push_hooks/executors/apply.py

@@ -213,6 +213,20 @@ def _runtime_metadata_namespaces(context: RuntimeContext) -> tuple[pathlib.Path,
     return namespaces
 
 
+def _resolve_effective_hooks_path(context: RuntimeContext) -> pathlib.Path:
+    raw_hooks_path = run_command(
+        ["git", "rev-parse", "--git-path", "hooks"],
+        cwd=context.repo_root,
+        check=True,
+    ).stdout.strip()
+    if not raw_hooks_path:
+        raise HookError("Git did not return an effective hooks path")
+    hooks_path = pathlib.Path(raw_hooks_path)
+    if not hooks_path.is_absolute():
+        hooks_path = context.repo_root / hooks_path
+    return pathlib.Path(os.path.abspath(hooks_path))
+
+
 def _snapshot_git_control_metadata(context: RuntimeContext) -> MetadataSnapshot:
     git_dir = context.git_dir.resolve(strict=True)
     common_dir = resolve_git_common_dir(context.repo_root).resolve(strict=True)
@@ -323,15 +337,7 @@ def _snapshot_git_control_metadata(context: RuntimeContext) -> MetadataSnapshot:
     for name in ("HEAD", "config", "config.worktree", "packed-refs"):
         record(f"shared:{name}", common_dir / name)
     scan_tree("shared:refs", common_dir / "refs")
-    raw_hooks_path = run_command(
-        ["git", "rev-parse", "--git-path", "hooks"],
-        cwd=context.repo_root,
-        check=True,
-    ).stdout.strip()
-    hooks_path = pathlib.Path(raw_hooks_path)
-    if not hooks_path.is_absolute():
-        hooks_path = context.repo_root / hooks_path
-    hooks_path = pathlib.Path(os.path.abspath(hooks_path))
+    hooks_path = _resolve_effective_hooks_path(context)
     if any(is_path_within(hooks_path, namespace) for namespace in excluded_namespaces):
         raise HookError(
             "Configured core.hooksPath must not overlap ai-push-hooks runtime metadata: "
@@ -582,6 +588,12 @@ def _safe_destination(context: RuntimeContext, relative_path: str) -> pathlib.Pa
         raise HookError(
             f"Apply destination resolves inside Git metadata: {relative_path}"
         )
+    hooks_path = _resolve_effective_hooks_path(context).resolve(strict=False)
+    if is_path_within(resolved_destination, hooks_path):
+        raise HookError(
+            f"Apply destination resolves inside configured Git hooks path: "
+            f"{relative_path}"
+        )
     return destination
 
 
@@ -602,6 +614,12 @@ def _preflight_apply_operations(
     context: RuntimeContext,
     operations: list[ApplyOperation],
 ) -> None:
+    # Validate every destination before the propagation loop can create a
+    # parent directory or write even the first operation.  In particular, a
+    # configured core.hooksPath may not exist yet, so this guard cannot depend
+    # on the hooks tree being present in the checkout.
+    for operation in operations:
+        _safe_destination(context, operation.relative_path)
     conflicts = [
         operation.relative_path
         for operation in operations
@@ -647,7 +665,6 @@ def _propagate_staging_changes(
     operations: list[ApplyOperation] = []
     expected: dict[str, StagedFile | None] = {}
     for relative_path in sorted(changed_paths):
-        _safe_destination(context, relative_path)
         baseline = baselines.get(relative_path, DestinationState("missing"))
         staged = after.get(relative_path)
         if staged is None:

package/src/ai_push_hooks/executors/ask.py

@@ -63,14 +63,20 @@ def validate_schema(schema: str | None, payload: Any) -> Any:
     if schema == "beads_alignment_result":
         if not isinstance(payload, dict):
             raise HookError("Expected schema beads_alignment_result")
-        commands = payload.get("commands", [])
-        if commands is not None and (
-            not isinstance(commands, list)
-            or not all(isinstance(item, str) for item in commands)
+        unresolved = payload.get("unresolved")
+        if type(unresolved) is not bool:
+            raise HookError("beads_alignment_result.unresolved must be a boolean")
+        if "commands" in payload and (
+            not isinstance(payload["commands"], list)
+            or not all(isinstance(item, str) for item in payload["commands"])
         ):
             raise HookError(
                 "beads_alignment_result.commands must be an array of strings"
             )
+        if "report_markdown" in payload and not isinstance(
+            payload["report_markdown"], str
+        ):
+            raise HookError("beads_alignment_result.report_markdown must be a string")
         return payload
     if schema == "pr_create_payload":
         if not isinstance(payload, dict):

package/src/ai_push_hooks/executors/assertions.py

@@ -5,6 +5,7 @@ import pathlib
 from typing import Any
 
 from ..types import RuntimeContext, StepConfig
+from .ask import validate_schema
 
 
 def docs_apply_requires_manual_commit(
@@ -28,8 +29,10 @@ def beads_alignment_clean(
     _step: StepConfig,
     inputs: list[pathlib.Path],
 ) -> dict[str, Any]:
-    payload = json.loads(inputs[0].read_text(encoding="utf-8"))
-    unresolved = bool(payload.get("unresolved", False))
+    payload = validate_schema(
+        "beads_alignment_result", json.loads(inputs[0].read_text(encoding="utf-8"))
+    )
+    unresolved = payload["unresolved"]
     if unresolved:
         return {
             "ok": False,

package/src/ai_push_hooks/executors/exec.py

@@ -209,12 +209,10 @@ def beads_alignment_executor(
             "report_written": False,
             "unresolved": False,
         }
-    payload = json.loads(inputs[0].read_text(encoding="utf-8"))
-    if not isinstance(payload, dict):
-        raise HookError("beads_alignment payload must be an object")
+    payload = validate_schema(
+        "beads_alignment_result", json.loads(inputs[0].read_text(encoding="utf-8"))
+    )
     commands = payload.get("commands", [])
-    if not isinstance(commands, list):
-        raise HookError("beads_alignment commands must be an array")
     if len(commands) > BEADS_ALIGNMENT_MAX_COMMANDS:
         raise HookError(
             f"beads_alignment accepts at most {BEADS_ALIGNMENT_MAX_COMMANDS} commands"
@@ -245,8 +243,8 @@ def beads_alignment_executor(
         )
         commands_run.append(command)
 
-    report_markdown = str(payload.get("report_markdown", "")).strip()
-    unresolved = bool(payload.get("unresolved", False))
+    report_markdown = payload.get("report_markdown", "").strip()
+    unresolved = payload["unresolved"]
     report_written = False
     if report_markdown:
         if not report_markdown.endswith("\n"):

package/src/ai_push_hooks/executors/runners/contracts.py

@@ -403,25 +403,15 @@ def strip_terminal_controls(value: str) -> str:
     return _UNSAFE_TERMINAL_CONTROL_PATTERN.sub("", without_ansi)
 
 
-def redact_diagnostic(value: str, *, secrets: Sequence[str] = ()) -> str:
-    """Redact supplied secrets and common credential-shaped values."""
-
-    redacted = strip_terminal_controls(value)
-    for pattern in _SECRET_PATTERNS:
-        redacted = pattern.sub(
-            lambda match: (
-                f"{match.group(1)}[REDACTED]" if match.lastindex else "[REDACTED]"
-            ),
-            redacted,
-        )
-    redaction_values: list[str] = []
+def _diagnostic_redaction_values(secrets: Sequence[str]) -> tuple[str, ...]:
+    values: list[str] = []
     seen: set[str] = set()
     fragment_count = 0
     for secret in secrets:
         if not isinstance(secret, str) or not secret or secret in seen:
             continue
         seen.add(secret)
-        redaction_values.append(secret)
+        values.append(secret)
         # A bounded fragment set catches a child echoing one prompt token,
         # while skipping a whole large diff avoids the old O(words * stream)
         # behavior.  The request-sensitive helper additionally suppresses
@@ -430,12 +420,72 @@ def redact_diagnostic(value: str, *, secrets: Sequence[str] = ()) -> str:
             for fragment in _DIAGNOSTIC_FRAGMENT_PATTERN.findall(secret):
                 if fragment not in seen:
                     seen.add(fragment)
-                    redaction_values.append(fragment)
+                    values.append(fragment)
                     fragment_count += 1
                     if fragment_count >= 512:
                         break
             if fragment_count >= 512:
                 continue
+    return tuple(values)
+
+
+def _longest_prefix_suffix(value: str, prefix: str) -> int:
+    """Return the longest suffix of ``value`` that is a prefix of ``prefix``."""
+
+    limit = min(len(value), len(prefix))
+    if limit == 0:
+        return 0
+    pattern = prefix[:limit]
+    failure = [0] * limit
+    matched = 0
+    for index in range(1, limit):
+        while matched and pattern[matched] != pattern[index]:
+            matched = failure[matched - 1]
+        if pattern[matched] == pattern[index]:
+            matched += 1
+        failure[index] = matched
+
+    matched = 0
+    for character in value[-limit:]:
+        while matched and (matched == limit or pattern[matched] != character):
+            matched = failure[matched - 1]
+        if pattern[matched] == character:
+            matched += 1
+    return matched
+
+
+def _boundary_redaction_start(value: str, secrets: Sequence[str]) -> int | None:
+    """Find the earliest visible prefix of a known value at a cutoff."""
+
+    earliest: int | None = None
+    for secret in secrets:
+        if len(secret) <= 1:
+            continue
+        # The captured child stream may itself end while a known value is
+        # being emitted, so do not require the value's unseen suffix to exist
+        # in ``value``.  This comparison is bounded by the preview and secret
+        # prefix, rather than scanning an unbounded stream tail.
+        prefix = secret[: min(len(value), len(secret) - 1)]
+        overlap = _longest_prefix_suffix(value, prefix)
+        if overlap:
+            start = len(value) - overlap
+            if earliest is None or start < earliest:
+                earliest = start
+    return earliest
+
+
+def redact_diagnostic(value: str, *, secrets: Sequence[str] = ()) -> str:
+    """Redact supplied secrets and common credential-shaped values."""
+
+    redacted = strip_terminal_controls(value)
+    for pattern in _SECRET_PATTERNS:
+        redacted = pattern.sub(
+            lambda match: (
+                f"{match.group(1)}[REDACTED]" if match.lastindex else "[REDACTED]"
+            ),
+            redacted,
+        )
+    redaction_values = _diagnostic_redaction_values(secrets)
     for secret in sorted(redaction_values, key=len, reverse=True):
         redacted = redacted.replace(secret, "[REDACTED]")
     return redacted
@@ -454,10 +504,18 @@ def bounded_diagnostic(
     raw = str(value)
     # Redact only the bounded preview.  Anything after this point cannot be
     # present in the returned diagnostic, and therefore does not need a scan.
-    # Credential-shaped values which reach the preview boundary are still
-    # handled by the regex redactor before the preview is returned.
-    preview = raw[:max_chars]
+    # A known value can start in the preview and finish after it, though; mask
+    # that visible prefix after ordinary redaction so a complete match cannot
+    # be destroyed first.  Boundary matching is bounded even for large
+    # streams/secrets.
+    preview = strip_terminal_controls(raw[:max_chars])
+    redaction_values = _diagnostic_redaction_values(secrets)
     safe = redact_diagnostic(preview, secrets=secrets)
+    boundary_start = _boundary_redaction_start(safe, redaction_values)
+    if boundary_start is not None:
+        # Several known values can overlap at the cutoff.  Replace their
+        # union once so insertion cannot invalidate another span's index.
+        safe = safe[:boundary_start] + "[REDACTED]"
     if len(raw) <= max_chars and len(safe) <= max_chars:
         return safe
     if max_chars <= len(DIAGNOSTIC_TRUNCATION_MARKER):

package/src/ai_push_hooks/executors/step_commands.py

@@ -9,7 +9,6 @@ engine integration lane.
 from __future__ import annotations
 
 import math
-import os
 import pathlib
 import re
 import sys
@@ -26,7 +25,12 @@ from ..types import (
     RuntimeContext,
     StepConfig,
 )
-from .runners.contracts import bounded_diagnostic, redact_diagnostic
+from .runners.contracts import (
+    RunnerError,
+    RunnerExecutableNotFoundError,
+    RunnerSignalError,
+    RunnerTimeoutError,
+)
 from .runners.process import (
     DEFAULT_MAX_OUTPUT_BYTES,
     ProcessResult,
@@ -297,14 +301,26 @@ def run_step_command(
         inputs=input_paths,
         python_executable=python_executable or sys.executable,
     )
-    process_result = run_process(
-        argv,
-        cwd=pathlib.Path(repo_root).resolve(strict=True),
-        input_path=input_path,
-        timeout_seconds=timeout_seconds,
-        env=None,
-        max_output_bytes=max_output_bytes,
-    )
+    try:
+        process_result = run_process(
+            argv,
+            cwd=pathlib.Path(repo_root).resolve(strict=True),
+            input_path=input_path,
+            timeout_seconds=timeout_seconds,
+            env=None,
+            max_output_bytes=max_output_bytes,
+        )
+    except RunnerError as error:
+        # Do not retain process causes: they can contain rendered argv or
+        # captured stream bytes when displayed as an exception chain.
+        error.__cause__ = None
+        error.__suppress_context__ = True
+        if isinstance(error, RunnerExecutableNotFoundError):
+            # The command vector is configuration-controlled and may contain
+            # credentials.  Do not let the process layer's executable detail
+            # cross the step-command boundary.
+            error.args = ("step command executable was not found",)
+        raise
     result = _from_process_result(process_result)
     if result.stdout_truncated or result.stderr_truncated:
         streams = " and ".join(
@@ -320,31 +336,31 @@ def run_step_command(
         )
         error._step_command_result = result
         raise error
-    _validate_utf8(result)
+    try:
+        _validate_utf8(result)
+    except StepCommandEncodingError as error:
+        error.__cause__ = None
+        error.__suppress_context__ = True
+        raise
     return result
 
 
-def _environment_secrets() -> tuple[str, ...]:
-    markers = ("API_KEY", "TOKEN", "SECRET", "PASSWORD", "AUTH", "CREDENTIAL")
-    return tuple(
-        value
-        for name, value in os.environ.items()
-        if any(marker in name.upper() for marker in markers) and value
-    )
-
-
-def _assert_message(result: StepCommandResult) -> str:
-    # A process error can occur before the normal strict UTF-8 validation pass.
-    # Surrogateescape keeps that diagnostic bounded and non-throwing; the
-    # private stream artifacts still retain the exact original bytes.
-    stdout = result.stdout.decode("utf-8", errors="surrogateescape")
-    stderr = result.stderr.decode("utf-8", errors="surrogateescape")
-    combined = "\n".join(part for part in (stderr.strip(), stdout.strip()) if part)
-    safe = redact_diagnostic(combined, secrets=_environment_secrets())
-    return (
-        bounded_diagnostic(safe, max_chars=1_200)
-        or f"command exited with status {result.returncode}"
-    )
+def _command_failure_status(
+    error: BaseException, result: StepCommandResult | None
+) -> str:
+    if isinstance(error, RunnerTimeoutError):
+        return "timeout"
+    if isinstance(error, RunnerSignalError):
+        return "signal"
+    if isinstance(error, StepCommandEncodingError):
+        return "invalid_utf8"
+    if isinstance(error, StepCommandTruncatedError):
+        return "capture_limit"
+    if isinstance(error, RunnerExecutableNotFoundError):
+        return "not_started"
+    if result is not None:
+        return str(result.returncode)
+    return "error"
 
 
 def step_command_result_payload(
@@ -368,7 +384,7 @@ def step_command_result_payload(
     if step_type == "assert":
         payload["ok"] = result.returncode == 0
         if result.returncode != 0:
-            payload["message"] = _assert_message(result)
+            payload["message"] = f"command exited with status {result.returncode}"
     return payload
 
 
@@ -447,6 +463,7 @@ def execute_step_command(
         input_map = dict(zip(step.inputs, inputs))
     store = artifacts or ArtifactStore(context.run_dir)
     store.prepare()
+    persisted: PersistedStepCommandResult | None = None
     try:
         process_result = run_step_command(
             step.command,
@@ -459,42 +476,63 @@ def execute_step_command(
                 else DEFAULT_STEP_COMMAND_TIMEOUT_SECONDS
             ),
         )
+        payload = step_command_result_payload(process_result, step_type=step.type)
+        persisted = _persist_process_result(
+            store, state, step, process_result, payload=payload
+        )
+        if step.type == "exec" and process_result.returncode != 0:
+            error = StepCommandExecutionError(
+                "step exec command returned a non-zero status"
+            )
+            error._step_command_result = process_result
+            error._step_command_persisted = persisted
+            raise error
+        if step.type == "assert" and process_result.returncode != 0:
+            error = StepCommandAssertionError(str(payload["message"]))
+            error._step_command_result = process_result
+            error._step_command_persisted = persisted
+            raise error
     except BaseException as error:
         captured = _result_from_error(error)
         if captured is None:
             captured = getattr(error, "_step_command_result", None)
-        if isinstance(captured, StepCommandResult):
-            report = None
-            if isinstance(error, StepCommandEncodingError):
-                report = step_command_result_payload(captured, step_type=step.type)
-                report["malformed"] = True
-                report["message"] = "command output was not valid UTF-8"
-            persisted = _persist_process_result(
-                store,
-                state,
-                step,
-                captured,
-                payload=report,
-            )
+        captured_result = captured if isinstance(captured, StepCommandResult) else None
+        if captured_result is not None:
+            if persisted is None:
+                report = None
+                if isinstance(error, StepCommandEncodingError):
+                    report = step_command_result_payload(
+                        captured_result, step_type=step.type
+                    )
+                    report["malformed"] = True
+                    report["message"] = "command output was not valid UTF-8"
+                persisted = _persist_process_result(
+                    store,
+                    state,
+                    step,
+                    captured_result,
+                    payload=report,
+                )
             error._step_command_persisted = persisted
+        if isinstance(error, (RunnerError, StepCommandError)):
+            namespace = f"{state.module.id}/{state.step_index:02d}-{step.id}"
+            run_id = getattr(context, "run_id", store.run_dir.name)
+            location_suffix = "" if persisted is not None else " (not created)"
+            returncode = (
+                f"; returncode={captured_result.returncode}"
+                if captured_result is not None
+                else ""
+            )
+            error.args = (
+                f"command step={state.module.id}.{step.id} failed; "
+                f"status={_command_failure_status(error, captured_result)}; "
+                f"error_class={error.__class__.__name__}; "
+                f"artifact_location={run_id}/{namespace}{location_suffix}"
+                f"{returncode}",
+            )
         raise
-
-    payload = step_command_result_payload(process_result, step_type=step.type)
-    persisted = _persist_process_result(
-        store, state, step, process_result, payload=payload
-    )
-    if step.type == "exec" and process_result.returncode != 0:
-        error = StepCommandExecutionError(
-            "step exec command returned a non-zero status"
-        )
-        error._step_command_result = process_result
-        error._step_command_persisted = persisted
-        raise error
-    if step.type == "assert" and process_result.returncode != 0:
-        error = StepCommandAssertionError(str(payload["message"]))
-        error._step_command_result = process_result
-        error._step_command_persisted = persisted
-        raise error
+    if persisted is None:  # pragma: no cover - successful persistence is required above
+        raise StepCommandError("step command result was not persisted")
     return persisted
 
 

package/src/ai_push_hooks/git_utils.py

@@ -543,8 +543,11 @@ def collect_changed_files(repo_root: pathlib.Path, ranges: list[str]) -> list[st
             [
                 "git",
                 "diff",
+                "--no-ext-diff",
+                "--no-textconv",
+                "--no-color",
                 "--name-only",
-                "--diff-filter=ACMRD",
+                "--diff-filter=ACMRDT",
                 "-z",
                 range_expr,
             ],
@@ -639,7 +642,15 @@ def collect_diff(repo_root: pathlib.Path, ranges: list[str], max_bytes: int) ->
 
         body, body_truncated = _collect_bounded_git_diff(
             repo_root,
-            ["git", "diff", "--unified=3", range_expr],
+            [
+                "git",
+                "diff",
+                "--no-ext-diff",
+                "--no-textconv",
+                "--no-color",
+                "--unified=3",
+                range_expr,
+            ],
             limit - len(output),
         )
         if not body_truncated:

package/src/ai_push_hooks/hook.py

@@ -21,11 +21,11 @@ from .git_utils import (
     current_branch,
     ensure_dir,
     env_bool,
-    git,
     parse_push_updates,
     resolve_git_dir,
     resolve_repo_root,
     resolve_storage_path,
+    run_command,
     should_skip_for_sync_branch,
     unique_range_expressions,
 )
@@ -65,7 +65,10 @@ def _write_summary(context: RuntimeContext, result: dict[str, object]) -> None:
 
 
 def _assert_clean_worktree(repo_root: pathlib.Path) -> None:
-    status = git(repo_root, ["status", "--short"], check=False).strip()
+    completed = run_command(["git", "status", "--short"], cwd=repo_root, check=False)
+    if completed.returncode != 0:
+        raise HookError("Hook requires a clean worktree but Git status failed")
+    status = (completed.stdout or "").strip()
     if status:
         raise HookError("Hook requires a clean worktree but local changes are present")
 

package/src/ai_push_hooks/modules/docs.py

@@ -9,7 +9,13 @@ from pathlib import PurePosixPath
 from typing import Any
 
 from ..types import CollectorResult, RuntimeContext
-from ..git_utils import collect_commit_messages_for_ranges, git, path_matches
+from ..git_utils import (
+    collect_commit_messages_for_ranges,
+    git,
+    path_matches,
+    run_command,
+)
+from ..paths import path_is_link_or_reparse
 
 DOC_INCLUDE_PATTERNS = ("README.md", "docs/**/*.md")
 DOC_IGNORE_PATTERNS = ("docs/archive/**",)
@@ -34,7 +40,7 @@ def _is_safe_doc_file(repo_root: pathlib.Path, candidate: pathlib.Path) -> bool:
         current = repo_root
         for part in relative.parts:
             current /= part
-            if stat.S_ISLNK(current.lstat().st_mode):
+            if path_is_link_or_reparse(current):
                 return False
         candidate_stat = candidate.lstat()
         if not stat.S_ISREG(candidate_stat.st_mode):
@@ -47,18 +53,40 @@ def _is_safe_doc_file(repo_root: pathlib.Path, candidate: pathlib.Path) -> bool:
 
 
 def _expand_doc_files(repo_root: pathlib.Path) -> list[pathlib.Path]:
+    """List safe, relevant docs from Git's tracked/unignored file inventory.
+
+    ``--cached`` retains tracked files even when an ignore rule matches them;
+    ``--others --exclude-standard`` adds only untracked files that Git would
+    consider visible.  Enumerating this way avoids walking ignored directories
+    before any document content is opened.
+    """
     repo_root = repo_root.resolve(strict=True)
+    listed = run_command(
+        ["git", "ls-files", "--cached", "--others", "--exclude-standard", "-z"],
+        cwd=repo_root,
+        check=True,
+    )
+
     files: list[pathlib.Path] = []
-    for candidate in repo_root.rglob("*.md"):
-        relative = candidate.relative_to(repo_root).as_posix()
+    seen: set[str] = set()
+    for relative in listed.stdout.split("\x00"):
+        if not relative or relative in seen:
+            continue
+        seen.add(relative)
         if not _path_matches(relative, DOC_INCLUDE_PATTERNS):
             continue
         if _path_matches(relative, DOC_IGNORE_PATTERNS):
             continue
+        # Git emits POSIX separators even on platforms where a backslash has
+        # path semantics.  Reject such ambiguous names there rather than
+        # allowing a listed filename to change the lexical containment check.
+        if os.name == "nt" and "\\" in relative:
+            continue
+        candidate = repo_root.joinpath(*relative.split("/"))
         if not _is_safe_doc_file(repo_root, candidate):
             continue
         files.append(candidate)
-    return sorted(files)
+    return sorted(files, key=lambda path: path.relative_to(repo_root).as_posix())
 
 
 def _deterministic_seed_queries(diff_text: str, changed_files: list[str]) -> list[str]:

package/src/ai_push_hooks/paths.py

@@ -104,6 +104,18 @@ def resolve_contained_path(base: pathlib.Path, raw: str, label: str) -> pathlib.
     return resolved_candidate
 
 
+def _ensure_private_directory_component(directory: pathlib.Path) -> None:
+    try:
+        directory.mkdir(mode=PRIVATE_DIRECTORY_MODE)
+    except FileExistsError:
+        # Tolerate a concurrent creator winning the mkdir race, then validate
+        # the result before changing its permissions.
+        pass
+    if path_is_link_or_reparse(directory) or not directory.is_dir():
+        raise HookError(f"Private runtime path is not a safe directory: {directory}")
+    os.chmod(directory, PRIVATE_DIRECTORY_MODE)
+
+
 def ensure_private_directory(
     path: pathlib.Path,
     *,
@@ -119,8 +131,7 @@ def ensure_private_directory(
         if path_is_link_or_reparse(current) or not current.is_dir():
             raise HookError(f"Private runtime directory has an unsafe parent: {path}")
         for directory in reversed(missing):
-            directory.mkdir(mode=PRIVATE_DIRECTORY_MODE)
-            os.chmod(directory, PRIVATE_DIRECTORY_MODE)
+            _ensure_private_directory_component(directory)
         if path_is_link_or_reparse(target) or not target.is_dir():
             raise HookError(f"Private runtime directory is unsafe: {path}")
         os.chmod(target, PRIVATE_DIRECTORY_MODE)
@@ -141,11 +152,12 @@ def ensure_private_directory(
             raise HookError(
                 f"Private runtime directory traverses a symlink or reparse point: {directory}"
             )
-        if not directory.exists():
-            directory.mkdir(mode=PRIVATE_DIRECTORY_MODE)
-        if not directory.is_dir():
-            raise HookError(f"Private runtime path is not a directory: {directory}")
-        os.chmod(directory, PRIVATE_DIRECTORY_MODE)
+        if directory.exists():
+            if not directory.is_dir():
+                raise HookError(f"Private runtime path is not a directory: {directory}")
+            os.chmod(directory, PRIVATE_DIRECTORY_MODE)
+        else:
+            _ensure_private_directory_component(directory)
     return target
 
 

package/src/ai_push_hooks/plugin_loader.py

@@ -13,10 +13,12 @@ from __future__ import annotations  # noqa: I001
 import errno
 import hashlib
 import inspect
+import itertools
 import os
 import pathlib
 import re
 import stat
+import sys
 import threading
 from collections.abc import Callable, Mapping, Sequence
 from types import ModuleType
@@ -35,6 +37,8 @@ _CALLABLE_PATTERN = re.compile(r"[A-Za-z_][A-Za-z0-9_]*\Z")
 _SOURCE_ENCODING = "utf-8"
 PLUGIN_SOURCE_MAX_BYTES = 1 * 1024 * 1024
 _SOURCE_READ_CHUNK_BYTES = 64 * 1024
+_MODULE_NUMBER = itertools.count(1)
+_MODULE_NUMBER_LOCK = threading.Lock()
 _OS_OPEN = os.open
 _DESCRIPTOR_RELATIVE_SUPPORTED = bool(
     getattr(os, "O_DIRECTORY", 0)
@@ -221,7 +225,6 @@ class PluginLoader:
         self._cache: dict[tuple[pathlib.Path, pathlib.Path], ModuleType] = {}
         self._lock = threading.RLock()
         self._source_locks: dict[tuple[pathlib.Path, pathlib.Path], threading.Lock] = {}
-        self._module_number = 0
 
     def _source_lock(self, key: tuple[pathlib.Path, pathlib.Path]) -> threading.Lock:
         with self._lock:
@@ -248,7 +251,12 @@ class PluginLoader:
         # to the lexical cache key for a safe repository file.
         try:
             source_text = source.decode(_SOURCE_ENCODING)
-            code = compile(source_text, str(callback_path), "exec")
+            code = compile(
+                source_text,
+                str(callback_path),
+                "exec",
+                dont_inherit=True,
+            )
         except UnicodeDecodeError:
             raise HookError(
                 f"Python plugin {relative_path}:{callable_name} source is not valid UTF-8"
@@ -258,16 +266,18 @@ class PluginLoader:
                 f"Python plugin {relative_path}:{callable_name} could not be compiled"
             ) from None
 
-        with self._lock:
-            self._module_number += 1
-            module_number = self._module_number
+        with _MODULE_NUMBER_LOCK:
+            module_number = next(_MODULE_NUMBER)
         digest = hashlib.sha256(f"{root}\0{callback_path}".encode()).hexdigest()[:16]
         module_name = f"ai_push_hooks_plugin_{digest}_{module_number}"
         module = ModuleType(module_name)
         module.__file__ = str(callback_path)
         module.__package__ = ""
+        imported = False
+        sys.modules[module_name] = module
         try:
             exec(code, module.__dict__)  # noqa: S102
+            imported = True
         except KeyboardInterrupt:
             raise
         except SystemExit:
@@ -290,6 +300,9 @@ class PluginLoader:
             raise HookError(
                 f"Python plugin {relative_path}:{callable_name} failed during import"
             ) from None
+        finally:
+            if not imported and sys.modules.get(module_name) is module:
+                del sys.modules[module_name]
         return module
 
     def load(self, repo_root: pathlib.Path, reference: str) -> Callable[..., Any]:

package/vendor/README.md

@@ -2,7 +2,7 @@
 
 The npm package includes the unmodified pure-Python wheel for [Tomli](https://pypi.org/project/tomli/2.4.0/). Python 3.10 uses it to parse TOML; Python 3.11+ uses the standard-library `tomllib` module.
 
-The wrapper adds the wheel to `PYTHONPATH`, so no pip install, install script, or runtime download is needed. The wheel includes Tomli's MIT license under `tomli-2.4.0.dist-info/licenses/LICENSE`.
+The npm bootstrap adds the wheel directly to Python's import path, so no pip install, install script, or runtime download is needed. It does not inherit `PYTHONPATH`. The wheel includes Tomli's MIT license under `tomli-2.4.0.dist-info/licenses/LICENSE`.
 
 To reproduce the bundled download from the repository root: