ci-fleet 0.1.0__py3-none-any.whl

ci_fleet/__init__.py

@@ -0,0 +1,12 @@
+"""ci_fleet — self-hosted GitHub Actions runner fleet management.
+
+Extracted from ``charlie_work`` so runner development and orchestrator
+development stop colliding. Import concrete modules directly; this package
+intentionally exposes no barrel re-exports.
+
+The one exception is :mod:`ci_fleet.charlie_work_adapter`, which exists solely
+to hold the legacy import surface stable during the migration. Nothing inside
+this package may import from it.
+"""
+
+__version__ = "0.1.0"

ci_fleet/_vendor/__init__.py

@@ -0,0 +1,16 @@
+"""Vendored support code copied from ``charlie_work``.
+
+Every module here carries a provenance header naming the source module and the
+date it was copied. These are *copies of specific named functions and classes*,
+not whole-file mirrors: only the surface the fleet code actually calls comes
+across.
+
+Hard rule for this package: **nothing under ``ci_fleet`` may import
+``charlie_work``.** Vendoring exists precisely so the dependency arrow points
+one way. A ``charlie_work`` import here would create the cycle the extraction
+was meant to break.
+
+Two readings of "vendor" were considered and rejected in the plan:
+  - having ``ci_fleet`` depend on ``charlie_work`` (creates the cycle), and
+  - extracting a third shared package (out of scope for this migration).
+"""

ci_fleet/_vendor/fleet_paths.py

@@ -0,0 +1,119 @@
+# vendored from charlie_work.fleet_paths on 2026-07-30;
+# do not import charlie_work from this package.
+from __future__ import annotations
+
+import logging
+import os
+import sys
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+def _paths_equal(a: Path, b: Path) -> bool:
+    """Compare two paths for equality using the OS's own normalization.
+
+    ``PurePath.__eq__`` is case-sensitive even on Windows, so ``C:\\Foo`` and
+    ``c:\\foo`` (the same file) would falsely report virtualization. The probe
+    keys on a real divergence between literal and resolved paths, not on a
+    case-only spelling difference, so normalize before comparing.
+    """
+    return os.path.normcase(os.fspath(a)) == os.path.normcase(os.fspath(b))
+
+
+def detect_path_virtualization(literal: Path) -> tuple[Path, Path] | None:
+    """Detect per-process virtualization of a path (issue #624).
+
+    MSIX/container copy-on-write redirection sits *below* the environment
+    variable: the literal path string is identical in both the container and
+    the host, but ``Path.resolve()`` follows the reparse point to the
+    redirected location. Reads pass through to the real file; the first write
+    forks a private copy that daemons reading the same path string never see.
+
+    The load-bearing signal is that the literal path and its resolved form
+    disagree — never a hardcoded package moniker (which would rot on the next
+    app update and only cover one container). Returns ``(literal, resolved)``
+    when they diverge, else ``None``.
+
+    Resolution errors are treated as "not virtualized" rather than raising: a
+    probe that crashes the caller is worse than one that stays silent on an
+    unreadable path. ``Path.resolve(strict=False)`` (the default) does not
+    require the path to exist, so an absent fleet dir still resolves cleanly
+    and only a real reparse-point divergence fires.
+    """
+    try:
+        resolved = literal.resolve()
+    except OSError:
+        return None
+    if not _paths_equal(resolved, literal):
+        return (literal, resolved)
+    return None
+
+
+def fleet_dir_virtualization(*, override: str | None = None) -> tuple[Path, Path] | None:
+    """Detect per-process virtualization of the fleet directory (issue #624).
+
+    Thin wrapper over :func:`detect_path_virtualization` keyed on the fleet
+    dir. Repo-agnostic by construction: the fleet dir is a host-wide
+    per-process property, not a project layout, so the same probe fires for
+    every registered repo on this host.
+    """
+    return detect_path_virtualization(fleet_dir(override=override))
+
+
+def warn_fleet_dir_virtualization_on_write(literal: Path, *, context: str) -> None:
+    """Log a warning when a host-wide write lands in a virtualized copy.
+
+    Called from fleet-dir state writers so "I deployed it" cannot be reported
+    when the write forked a private copy that daemons reading the same path
+    string will never see (issue #624; this is the exact shape of the #590
+    failure). Never raises and never blocks the write — the operator already
+    asked for it; this only names where it actually landed.
+    """
+    diverged = detect_path_virtualization(literal)
+    if diverged is None:
+        return
+    _literal, resolved = diverged
+    logger.warning(
+        "Fleet dir virtualization detected while %s: %s resolves to %s — "
+        "this write lands in a private copy invisible to scheduled tasks and "
+        "daemons reading the same path string (issue #624; see also #590). "
+        "Daemon-visible state must be written via a non-redirected route "
+        "(e.g. a UNC path).",
+        context,
+        literal,
+        resolved,
+    )
+
+
+def fleet_dir(*, override: str | None = None) -> Path:
+    """Return the user-level fleet directory for charlie-work.
+
+    Platform-specific defaults:
+    - Windows (win32): %LOCALAPPDATA%\\charlie-work\\
+    - POSIX: ${XDG_STATE_HOME:-~/.local/state}/charlie-work/
+
+    The override parameter (or CHARLIE_WORK_FLEET_DIR env var) allows
+    test isolation without hardcoding platform-specific paths in fixtures.
+
+    Args:
+        override: Optional path string to use instead of the platform default.
+                  If None, checks CHARLIE_WORK_FLEET_DIR env var, then uses
+                  the platform default.
+
+    Returns:
+        Path to the fleet directory.
+    """
+    if override is not None:
+        return Path(override)
+
+    env_override = os.environ.get("CHARLIE_WORK_FLEET_DIR")
+    if env_override:
+        return Path(env_override)
+
+    if sys.platform == "win32":
+        base = Path(os.environ.get("LOCALAPPDATA", Path.home() / "AppData" / "Local"))
+    else:
+        base = Path(os.environ.get("XDG_STATE_HOME", Path.home() / ".local" / "state"))
+
+    return base / "charlie-work"

ci_fleet/_vendor/safe_path.py

@@ -0,0 +1,73 @@
+# vendored from charlie_work.safe_path on 2026-07-30; do not import charlie_work from this package.
+"""Single point of enforcement for path-containment checks.
+
+Consolidates the ad hoc ``.resolve()`` + ``is_relative_to()`` pairs previously
+duplicated across five independent call sites (``runner_slots.py``,
+``worktree.py`` x3, ``supervise.py``) with no single source of truth for what
+"safely contained" means. None of them resolved symlinks/junctions
+defensively on *both* sides before comparing, and one (``worktree.py``'s
+``_materialize_directory``) compared unresolved paths, which does not detect
+a `..` segment escaping the base directory (``Path.is_relative_to`` is a
+purely lexical part-prefix check; it does not collapse ``..``).
+
+The two-function shape (a predicate plus a raising variant) is ported from a
+prior Node implementation -- the design, not the code, since ``fs.realpathSync``
+and ``pathlib`` differ in exactly the nonexistent-path handling that matters
+here.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def _resolve_defensive(path: Path) -> Path:
+    """Resolve ``path``, collapsing symlinks/junctions on every existing segment.
+
+    ``Path.resolve()`` does not require ``path`` to exist: it resolves every
+    existing leading segment (following symlinks/junctions along the way) and
+    leaves only trailing nonexistent components as literal names. That already
+    matches the ``realpathSync``-with-existing-parent-fallback design, so a
+    candidate path that hasn't been created yet can still be checked for
+    containment before it's materialized.
+    """
+    return path.resolve()
+
+
+def contains(base: Path, candidate: Path) -> bool:
+    """Return ``True`` when ``candidate`` resolves to a path inside ``base``.
+
+    Both sides are resolved before comparing, so this catches a reparse point
+    or symlink that makes ``candidate`` *look* contained lexically but
+    actually escapes ``base`` on disk (the CLAUDE.md-declared ``managed_root``
+    invariant this guards). Use at any site that can simply skip a
+    non-contained entry (e.g. a discovery loop); use ``require_contained``
+    where skipping isn't an option.
+    """
+    resolved_base = _resolve_defensive(base)
+    resolved_candidate = _resolve_defensive(candidate)
+    return resolved_candidate == resolved_base or resolved_candidate.is_relative_to(resolved_base)
+
+
+def require_contained(base: Path, candidate: Path, *, context: str) -> Path:
+    """Return the resolved ``candidate``, raising ``ValueError`` if it escapes ``base``.
+
+    For boundaries where an externally-influenced path (config, JSON state, a
+    subprocess's stdout) is about to be read from or written to, and silently
+    skipping would hide the problem rather than surface it. ``context`` is
+    included in the error message to identify the call site without needing a
+    traceback.
+    """
+    resolved_base = _resolve_defensive(base)
+    resolved_candidate = _resolve_defensive(candidate)
+    if resolved_candidate != resolved_base and not resolved_candidate.is_relative_to(
+        resolved_base
+    ):
+        raise ValueError(
+            f"{context}: {candidate} resolves to {resolved_candidate}, which "
+            f"escapes {base} (resolves to {resolved_base})"
+        )
+    return resolved_candidate
+
+
+__all__ = ["contains", "require_contained"]

ci_fleet/_vendor/subprocess_runner.py

@@ -0,0 +1,227 @@
+# vendored from charlie_work.subprocess_runner on 2026-07-30;
+# do not import charlie_work from this package.
+"""One subprocess runner for every adapter and cross-family invocation.
+
+Centralizes the Windows-safe capture contract: text mode with explicit UTF-8
+decoding and ``errors="replace"`` (never the cp1252 default), and bytes-safe
+handling of ``TimeoutExpired`` partial output. Callers get a plain result and
+never an encoding crash.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import shutil
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, TypedDict
+
+_CREATE_NO_WINDOW = getattr(subprocess, "CREATE_NO_WINDOW", 0)
+_DETACHED_PROCESS = getattr(subprocess, "DETACHED_PROCESS", 0)
+_CREATE_NEW_CONSOLE = getattr(subprocess, "CREATE_NEW_CONSOLE", 0)
+_STARTF_USESHOWWINDOW = getattr(subprocess, "STARTF_USESHOWWINDOW", 0)
+_SW_HIDE = getattr(subprocess, "SW_HIDE", 0)
+
+
+class _SpawnKwargs(TypedDict, total=False):
+    creationflags: int
+    startupinfo: Any
+
+
+def no_console_window_kwargs(extra_creationflags: int = 0) -> _SpawnKwargs:
+    """Return the ``creationflags`` kwargs that suppress the transient console
+    window Windows allocates for a spawned child when the parent has no
+    console/window of its own (e.g. an orchestrator running headless or from
+    a service). This is the single point of enforcement for
+    ``CREATE_NO_WINDOW`` — every ``subprocess.run``/``Popen`` call site in
+    this codebase should route its creationflags through this helper rather
+    than hard-coding the flag itself.
+
+    ``extra_creationflags`` composes in whatever flags the call site already
+    needs (e.g. ``CREATE_NEW_PROCESS_GROUP`` so a launched worker can still be
+    killed by process group). ``CREATE_NO_WINDOW`` is never combined with
+    ``DETACHED_PROCESS`` — that combination is invalid/contradictory on
+    Windows, since ``DETACHED_PROCESS`` already fully detaches the child from
+    any console. Callers passing ``DETACHED_PROCESS`` get their flags back
+    unchanged.
+
+    On POSIX platforms (no ``creationflags`` concept), returns an empty dict
+    so callers can unconditionally do
+    ``subprocess.Popen(..., **no_console_window_kwargs(...))`` cross-platform.
+    """
+    if sys.platform != "win32" or not _CREATE_NO_WINDOW:
+        return {}
+    if extra_creationflags & _DETACHED_PROCESS:
+        return {"creationflags": extra_creationflags}
+    return {"creationflags": extra_creationflags | _CREATE_NO_WINDOW}
+
+
+def hidden_console_kwargs(extra_creationflags: int = 0) -> _SpawnKwargs:
+    """Return the ``creationflags`` and ``startupinfo`` kwargs that allocate a
+    hidden console for a long-lived worker spawn (e.g. ``devin`` or ``claude``).
+
+    A ``CREATE_NEW_CONSOLE`` process is created with ``STARTF_USESHOWWINDOW`` and
+    ``wShowWindow=SW_HIDE``. The worker and all of its console-subsystem
+    descendants (pytest, git, gh, bash) inherit that hidden console, so they
+    do not each allocate their own visible console window. This is the worker-
+    spawn boundary; short-lived leaf spawns continue to use
+    ``no_console_window_kwargs()``.
+
+    ``extra_creationflags`` composes in whatever flags the call site already
+    needs (e.g. ``CREATE_NEW_PROCESS_GROUP`` so a launched worker can still be
+    killed by process group). ``CREATE_NEW_CONSOLE`` is never combined with
+    ``CREATE_NO_WINDOW`` or ``DETACHED_PROCESS`` — those console modes are
+    mutually exclusive on Windows. A ``ValueError`` is raised if the caller
+    tries to combine them.
+
+    On POSIX platforms (no ``creationflags`` concept), returns an empty dict so
+    callers can unconditionally do
+    ``subprocess.Popen(..., **hidden_console_kwargs(...))`` cross-platform.
+    """
+    if sys.platform != "win32" or not _CREATE_NEW_CONSOLE:
+        return {}
+    forbidden = extra_creationflags & (_CREATE_NO_WINDOW | _DETACHED_PROCESS)
+    if forbidden:
+        raise ValueError(
+            f"CREATE_NEW_CONSOLE cannot be combined with mutually-exclusive "
+            f"console modes (CREATE_NO_WINDOW, DETACHED_PROCESS); got {forbidden:#x}"
+        )
+    startupinfo = subprocess.STARTUPINFO()
+    startupinfo.dwFlags |= _STARTF_USESHOWWINDOW
+    startupinfo.wShowWindow = _SW_HIDE
+    return {
+        "creationflags": extra_creationflags | _CREATE_NEW_CONSOLE,
+        "startupinfo": startupinfo,
+    }
+
+
+_NPM_SHIM_EXE_PATTERN = re.compile(r'"%dp0%\\([^"]+\.exe)"', re.IGNORECASE)
+
+
+def resolve_cli_binary(name: str) -> str:
+    """Resolve an npm-installed CLI tool name to its underlying ``.exe`` on Windows.
+
+    npm-published shims (``claude.CMD``, ``gemini.CMD``, ...) are batch-file
+    wrappers around the real ``.exe``. Two distinct problems follow from that,
+    and this is the single point of enforcement that fixes both:
+
+    1. ``subprocess.Popen``/``subprocess.run`` with ``shell=False`` and a bare
+       name (e.g. ``"claude"``) goes straight to Windows' ``CreateProcessW``,
+       which does **not** perform the ``PATHEXT``-based extension search that
+       ``cmd.exe`` does — so it cannot find ``claude.CMD`` at all and fails
+       with ``OSError: [WinError 2] The system cannot find the file
+       specified``, even though ``claude`` is on ``PATH`` and works fine when
+       typed at a shell prompt (see charlie-work issue #487).
+    2. Pre-resolving via ``shutil.which()`` alone (which *does* honor
+       ``PATHEXT`` and returns the full ``.CMD`` path) fixes (1) but trades it
+       for a subtler bug: ``CreateProcessW`` on a ``.CMD`` file implicitly
+       routes the child through ``cmd.exe``, whose argv parser uses
+       caret-escaping rather than the C-runtime backslash-escaping that
+       Python's ``subprocess.list2cmdline`` emits. A literal ``|`` in an
+       argument value (e.g. a prompt containing ``"small|mid|large"``) is
+       then interpreted as a ``cmd.exe`` pipeline separator, breaking the
+       invocation.
+
+    The real fix is to skip ``cmd.exe`` entirely: parse the ``.CMD`` shim to
+    find the underlying ``.exe`` it wraps (the npm shim pattern is stable —
+    ``"%dp0%\\node_modules\\<pkg>\\bin\\<name>.exe" %*``) and use that ``.exe``
+    path directly as ``argv[0]``. ``CreateProcessW`` then invokes it without
+    any shell interposed. Ported from a sibling repo's
+    ``claude_client._resolve_cli_binary`` (commit fe0cdde7), which fixed the
+    identical class of bug for the same npm-installed CLI shims.
+
+    On POSIX, or when ``shutil.which`` resolves to something other than a
+    ``.cmd``/``.bat`` file, the resolved path is returned unchanged (already
+    directly executable). If the binary cannot be found on ``PATH`` at all,
+    or the shim cannot be parsed/its target ``.exe`` does not exist, the
+    original (or ``shutil.which``-resolved) value is returned unchanged — a
+    deliberately conservative fallback that preserves the caller's existing
+    "binary not found" error handling rather than masking a missing install.
+
+    Args:
+        name: CLI tool name or path, e.g. ``"claude"``.
+
+    Returns:
+        A path safe to pass as ``argv[0]`` to ``subprocess.Popen``/``.run``
+        with ``shell=False``.
+    """
+    path = shutil.which(name)
+    if path is None:
+        return name
+    if os.name != "nt" or not path.lower().endswith((".cmd", ".bat")):
+        return path
+    try:
+        shim_text = Path(path).read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return path
+    match = _NPM_SHIM_EXE_PATTERN.search(shim_text)
+    if match is None:
+        return path
+    exe_path = Path(os.path.normpath(Path(path).parent / match.group(1)))
+    return str(exe_path) if exe_path.exists() else path
+
+
+@dataclass(frozen=True)
+class RunResult:
+    returncode: int | None
+    stdout: str
+    stderr: str
+    timed_out: bool = False
+    error: str | None = None
+
+    @property
+    def ok(self) -> bool:
+        return self.returncode == 0 and self.error is None
+
+
+def _as_text(value: object) -> str:
+    if isinstance(value, bytes):
+        return value.decode("utf-8", "replace")
+    return str(value) if value else ""
+
+
+def run_captured(
+    command: list[str] | str,
+    *,
+    cwd: Path | str,
+    timeout_seconds: int,
+    shell: bool = False,
+    stdin: str | None = None,
+) -> RunResult:
+    """Run ``command`` and capture output. Never raises for runtime failures —
+    timeouts, missing binaries, and non-zero exits all come back as a result."""
+    try:
+        completed = subprocess.run(
+            command,
+            cwd=str(cwd),
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            capture_output=True,
+            timeout=timeout_seconds,
+            shell=shell,
+            check=False,
+            input=stdin,
+            **hidden_console_kwargs(),
+        )
+    except subprocess.TimeoutExpired as exc:
+        return RunResult(
+            returncode=None,
+            stdout=_as_text(exc.stdout),
+            stderr=_as_text(exc.stderr),
+            timed_out=True,
+            error=f"command timed out after {timeout_seconds}s",
+        )
+    except OSError as exc:
+        return RunResult(returncode=None, stdout="", stderr="", error=str(exc))
+    except subprocess.SubprocessError as exc:
+        return RunResult(returncode=None, stdout="", stderr="", error=str(exc))
+    return RunResult(
+        returncode=completed.returncode,
+        stdout=completed.stdout or "",
+        stderr=completed.stderr or "",
+        error=None if completed.returncode == 0 else f"command exited {completed.returncode}",
+    )