lemming-cli 0.1.0__tar.gz → 0.1.1__tar.gz

{lemming_cli-0.1.0 → lemming_cli-0.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lemming-cli
-Version: 0.1.0
+Version: 0.1.1
 Summary: An autonomous, iterative task runner for AI coding agents.
 Project-URL: Homepage, https://github.com/owahltinez/lemming
 Project-URL: Repository, https://github.com/owahltinez/lemming
@@ -54,7 +54,7 @@ human-readable `tasks.yml` file.
 Install globally using `uv`:
 
 ```bash
-uv tool install git+https://github.com/owahltinez/lemming.git
+uv tool install lemming-cli
 ```
 
 ## Quick Start in 3 Steps
@@ -303,6 +303,22 @@ prompt text and skips all default flag injection.
 
 ---
 
+## Releasing
+
+Releases are published to PyPI as
+[`lemming-cli`](https://pypi.org/project/lemming-cli/) via trusted publishing:
+pushing a `v*` tag triggers the `publish.yml` GitHub Actions workflow, which
+builds the package with `uv build` and uploads it.
+
+```bash
+# 1. Bump the version in pyproject.toml, commit, and push
+# 2. Tag the release and push the tag
+git tag v0.1.1
+git push origin v0.1.1
+```
+
+---
+
 ## Screenshots
 
 ### Dashboard

{lemming_cli-0.1.0 → lemming_cli-0.1.1}/README.md

@@ -32,7 +32,7 @@ human-readable `tasks.yml` file.
 Install globally using `uv`:
 
 ```bash
-uv tool install git+https://github.com/owahltinez/lemming.git
+uv tool install lemming-cli
 ```
 
 ## Quick Start in 3 Steps
@@ -281,6 +281,22 @@ prompt text and skips all default flag injection.
 
 ---
 
+## Releasing
+
+Releases are published to PyPI as
+[`lemming-cli`](https://pypi.org/project/lemming-cli/) via trusted publishing:
+pushing a `v*` tag triggers the `publish.yml` GitHub Actions workflow, which
+builds the package with `uv build` and uploads it.
+
+```bash
+# 1. Bump the version in pyproject.toml, commit, and push
+# 2. Tag the release and push the tag
+git tag v0.1.1
+git push origin v0.1.1
+```
+
+---
+
 ## Screenshots
 
 ### Dashboard

{lemming_cli-0.1.0 → lemming_cli-0.1.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "lemming-cli"
-version = "0.1.0"
+version = "0.1.1"
 description = "An autonomous, iterative task runner for AI coding agents."
 readme = "README.md"
 authors = [

{lemming_cli-0.1.0 → lemming_cli-0.1.1}/src/lemming/runner.py

@@ -17,6 +17,14 @@ logger = logging.getLogger(__name__)
 # Sentinel return codes for non-standard process termination.
 RETURNCODE_TIMEOUT = -14
 
+# Grace period after SIGTERM before escalating to SIGKILL.
+KILL_GRACE_SECONDS = 5
+
+# How long to wait for EOF on the runner's stdout after it exits. A process
+# that escaped the process group (e.g. by starting its own session) can
+# inherit the pipe and hold it open indefinitely.
+OUTPUT_DRAIN_SECONDS = 5
+
 
 def _pretty_quote(s: str) -> str:
     """Quotes a string for shell execution, preferring readable quoting.
@@ -177,19 +185,38 @@ def build_runner_command(
 def _kill_process_tree(process: subprocess.Popen) -> None:
     """Kills a process and its entire process group.
 
-    Tries SIGTERM on the process group first, falls back to killing the
-    process directly if the group signal fails.
+    Sends SIGTERM to the process group first so the runner can clean up,
+    then escalates to SIGKILL if the process is still alive after a grace
+    period. Falls back to killing the process directly if the group signal
+    fails.
 
     Args:
         process: The subprocess to kill.
     """
+    # Ask the whole group to terminate gracefully.
     try:
-        os.killpg(os.getpgid(process.pid), signal.SIGTERM)
+        pgid = os.getpgid(process.pid)
+        os.killpg(pgid, signal.SIGTERM)
     except OSError:
         try:
             process.kill()
         except OSError:
             pass
+        return
+
+    # Escalate to SIGKILL if the process ignored SIGTERM.
+    try:
+        process.wait(timeout=KILL_GRACE_SECONDS)
+    except subprocess.TimeoutExpired:
+        logger.warning(
+            "Process %d survived SIGTERM for %ss; sending SIGKILL.",
+            process.pid,
+            KILL_GRACE_SECONDS,
+        )
+        try:
+            os.killpg(pgid, signal.SIGKILL)
+        except OSError:
+            pass
 
 
 def run_with_heartbeat(
@@ -264,6 +291,23 @@ def run_with_heartbeat(
 
     timed_out = False
 
+    def stream_output():
+        """Streams runner output to the log file and optionally the console."""
+        if not process.stdout:
+            return
+        with open(log_file, "a", encoding="utf-8") as f:
+            for line in process.stdout:
+                full_log.append(line)
+                f.write(line)
+                f.flush()
+                if verbose:
+                    echo_fn(line)
+
+    # Read stdout on a separate thread so the main thread can wait on the
+    # process itself: reading until EOF can block long after the runner
+    # exits if an escaped child still holds the pipe open.
+    reader_thread = threading.Thread(target=stream_output, daemon=True)
+
     try:
         # Heartbeat and cancellation management
         is_claimed = tasks.update_heartbeat(
@@ -302,26 +346,35 @@ def run_with_heartbeat(
             )
             heartbeat_thread.start()
 
-        # Stream output to log file and optionally to console
-        try:
-            if process.stdout:
-                with open(log_file, "a", encoding="utf-8") as f:
-                    for line in process.stdout:
-                        full_log.append(line)
-                        f.write(line)
-                        f.flush()
-                        if verbose:
-                            echo_fn(line)
+        reader_thread.start()
 
+        try:
             process.wait()
         except BaseException:
             _kill_process_tree(process)
             raise
 
+        # Drain remaining output, but don't wait forever: an escaped child
+        # holding the pipe open must not wedge the attempt.
+        reader_thread.join(timeout=OUTPUT_DRAIN_SECONDS)
+        if reader_thread.is_alive():
+            logger.warning(
+                "Runner stdout still open %ss after exit for task %s; "
+                "abandoning output reader.",
+                OUTPUT_DRAIN_SECONDS,
+                task_id,
+            )
+
         returncode = process.returncode
         if timed_out:
             returncode = RETURNCODE_TIMEOUT
         return returncode, "".join(full_log), ""
     finally:
-        if process.stdout and hasattr(process.stdout, "close"):
+        # Closing the stream while the reader is blocked on it can deadlock
+        # on the stream's internal lock, so only close it after EOF.
+        if (
+            process.stdout
+            and not reader_thread.is_alive()
+            and hasattr(process.stdout, "close")
+        ):
             process.stdout.close()

{lemming_cli-0.1.0 → lemming_cli-0.1.1}/src/lemming/runner_test.py

@@ -1,5 +1,6 @@
 import signal
 import subprocess
+import sys
 import time
 import unittest.mock
 
@@ -376,3 +377,105 @@ def test_run_with_heartbeat_no_timeout(tmp_path):
     )
 
     assert returncode == 0
+
+
+def test_kill_process_tree_escalates_to_sigkill():
+    """Verifies SIGKILL escalation when SIGTERM does not stop the process."""
+    process = unittest.mock.MagicMock(spec=subprocess.Popen)
+    process.pid = 12345
+    process.wait.side_effect = subprocess.TimeoutExpired(cmd="x", timeout=1)
+
+    with (
+        unittest.mock.patch("os.killpg") as mock_killpg,
+        unittest.mock.patch("os.getpgid", return_value=54321),
+    ):
+        runner._kill_process_tree(process)
+
+    assert mock_killpg.call_args_list == [
+        unittest.mock.call(54321, signal.SIGTERM),
+        unittest.mock.call(54321, signal.SIGKILL),
+    ]
+
+
+def test_run_with_heartbeat_timeout_kills_sigterm_immune_runner(tmp_path):
+    """Verifies a runner that ignores SIGTERM is still killed on timeout."""
+    tasks_file = tmp_path / "tasks.yml"
+    task_id = "sigterm_immune"
+
+    roadmap = tasks.Roadmap(
+        tasks=[tasks.Task(id=task_id, description="test escalation")]
+    )
+    tasks.save_tasks(tasks_file, roadmap)
+    tasks.mark_task_in_progress(tasks_file, task_id)
+
+    # The runner ignores SIGTERM and signals readiness via a sentinel file.
+    sentinel = tmp_path / "ready"
+    child_code = (
+        "import pathlib, signal, time\n"
+        "signal.signal(signal.SIGTERM, signal.SIG_IGN)\n"
+        f"pathlib.Path({str(sentinel)!r}).touch()\n"
+        "time.sleep(300)\n"
+    )
+
+    # Jump the clock past the limit only once the child has installed its
+    # SIGTERM handler, so the kill cannot land before setup completes.
+    real_monotonic = time.monotonic
+
+    def fast_monotonic():
+        return real_monotonic() + (120 if sentinel.exists() else 0)
+
+    start = real_monotonic()
+    with (
+        unittest.mock.patch("time.monotonic", side_effect=fast_monotonic),
+        unittest.mock.patch.object(tasks, "STALE_THRESHOLD", 2),
+        unittest.mock.patch.object(runner, "KILL_GRACE_SECONDS", 1),
+    ):
+        returncode, _, _ = runner.run_with_heartbeat(
+            [sys.executable, "-c", child_code],
+            tasks_file,
+            task_id,
+            verbose=False,
+            time_limit=1,
+        )
+
+    assert returncode == runner.RETURNCODE_TIMEOUT
+    assert real_monotonic() - start < 30
+
+
+def test_run_with_heartbeat_returns_when_grandchild_holds_stdout(tmp_path):
+    """Verifies return when a detached grandchild keeps the pipe open.
+
+    A process that starts its own session escapes the group kill and
+    inherits the stdout pipe; reading until EOF would block until it
+    exits, long after the runner itself is gone.
+    """
+    tasks_file = tmp_path / "tasks.yml"
+    task_id = "detached_grandchild"
+
+    roadmap = tasks.Roadmap(
+        tasks=[tasks.Task(id=task_id, description="test pipe hold")]
+    )
+    tasks.save_tasks(tasks_file, roadmap)
+
+    child_code = (
+        "import subprocess, sys\n"
+        "subprocess.Popen(\n"
+        "    [sys.executable, '-c', 'import time; time.sleep(30)'],\n"
+        "    start_new_session=True,\n"
+        ")\n"
+        "print('runner done', flush=True)\n"
+    )
+
+    start = time.monotonic()
+    with unittest.mock.patch.object(runner, "OUTPUT_DRAIN_SECONDS", 1):
+        returncode, stdout, _ = runner.run_with_heartbeat(
+            [sys.executable, "-c", child_code],
+            tasks_file,
+            task_id,
+            verbose=False,
+            time_limit=0,
+        )
+
+    assert returncode == 0
+    assert "runner done" in stdout
+    assert time.monotonic() - start < 10

{lemming_cli-0.1.0 → lemming_cli-0.1.1}/src/lemming/tasks/lifecycle.py

@@ -1,5 +1,6 @@
 """Task lifecycle management: claiming, heartbeats, cancellation, resets."""
 
+import logging
 import os
 import pathlib
 import secrets
@@ -8,9 +9,14 @@ import time
 
 from .. import models, paths, persistence
 
+logger = logging.getLogger(__name__)
+
 # Re-export constants for internal/external use
 STALE_THRESHOLD = persistence.STALE_THRESHOLD
 
+# Grace period after SIGTERM before escalating to SIGKILL.
+KILL_GRACE_SECONDS = 5
+
 
 def generate_task_id() -> str:
     """Generates a random short hex string for a unique task ID.
@@ -252,6 +258,49 @@ def reset_task_logs(tasks_file: pathlib.Path, task_id: str) -> None:
         log_file.unlink()
 
 
+def _kill_pid_tree(pid: int) -> None:
+    """Kills a process and its entire process group by PID.
+
+    Sends SIGTERM to the process group first so it can clean up, then
+    escalates to SIGKILL if the process is still alive after a grace
+    period. Unlike runner._kill_process_tree, this works from a bare PID
+    (no subprocess handle), so exit is detected by polling.
+
+    Args:
+        pid: The process ID to kill.
+    """
+    # Ask the whole group to terminate gracefully.
+    pgid = None
+    try:
+        pgid = os.getpgid(pid)
+        os.killpg(pgid, signal.SIGTERM)
+    except OSError:
+        try:
+            os.kill(pid, signal.SIGTERM)
+        except OSError:
+            return
+
+    # Poll for exit, then escalate to SIGKILL if SIGTERM was ignored.
+    deadline = time.monotonic() + KILL_GRACE_SECONDS
+    while time.monotonic() < deadline:
+        if not is_pid_alive(pid):
+            return
+        time.sleep(0.1)
+
+    logger.warning(
+        "Process %d survived SIGTERM for %ss; sending SIGKILL.",
+        pid,
+        KILL_GRACE_SECONDS,
+    )
+    try:
+        if pgid is not None:
+            os.killpg(pgid, signal.SIGKILL)
+        else:
+            os.kill(pid, signal.SIGKILL)
+    except OSError:
+        pass
+
+
 def cancel_task(tasks_file: pathlib.Path, task_id: str) -> bool:
     """Kill the task process AND the orchestrator loop, then mark cancelled.
 
@@ -263,39 +312,39 @@ def cancel_task(tasks_file: pathlib.Path, task_id: str) -> bool:
         True if the task was found and cancellation was attempted, False
         otherwise.
     """
+    # Update the task state first and release the lock: the kill below can
+    # wait out a grace period and must not stall heartbeats or readers.
+    task_pid = None
+    loop_pid = None
     with persistence.lock_tasks(tasks_file):
         data = persistence.load_tasks(tasks_file)
+        task = next((t for t in data.tasks if t.id == task_id), None)
+        if not task:
+            return False
 
-        for task in data.tasks:
-            if task.id == task_id:
-                # First kill the task itself
-                if task.pid:
-                    try:
-                        # Try to kill the whole process group if possible
-                        os.killpg(os.getpgid(task.pid), signal.SIGTERM)
-                    except OSError:
-                        try:
-                            os.kill(task.pid, signal.SIGTERM)
-                        except OSError:
-                            pass
-
-                # Also kill the orchestrator loop if it's running
-                loop_pid = persistence.get_loop_pid(tasks_file)
-                if loop_pid:
-                    try:
-                        os.kill(loop_pid, signal.SIGTERM)
-                    except OSError:
-                        pass
+        task_pid = task.pid
+        loop_pid = persistence.get_loop_pid(tasks_file)
 
-                update_run_time(task)
-                task.status = models.TaskStatus.CANCELLED
-                task.pid = None
-                task.last_heartbeat = None
-                task.requested_status = None
+        update_run_time(task)
+        task.status = models.TaskStatus.CANCELLED
+        task.pid = None
+        task.last_heartbeat = None
+        task.requested_status = None
 
-                persistence.save_tasks(tasks_file, data)
-                return True
-    return False
+        persistence.save_tasks(tasks_file, data)
+
+    # Kill the orchestrator loop first so it cannot pick up the next task
+    # while we wait for the task process tree to die.
+    if loop_pid:
+        try:
+            os.kill(loop_pid, signal.SIGTERM)
+        except OSError:
+            pass
+
+    if task_pid:
+        _kill_pid_tree(task_pid)
+
+    return True
 
 
 def reset_task(tasks_file: pathlib.Path, task_id: str) -> models.Task:

{lemming_cli-0.1.0 → lemming_cli-0.1.1}/src/lemming/tasks/lifecycle_test.py

@@ -168,7 +168,10 @@ def test_cancel_task(tmp_path):
     )
     persistence.save_tasks(tasks_file, data)
 
-    with patch("lemming.tasks.lifecycle.os.killpg"):
+    with (
+        patch("lemming.tasks.lifecycle.os.killpg"),
+        patch("lemming.tasks.lifecycle.is_pid_alive", return_value=False),
+    ):
         success = lifecycle.cancel_task(tasks_file, "1")
         assert success is True
 
@@ -197,6 +200,7 @@ def test_cancel_task_kills_loop_pid(tmp_path):
         patch("lemming.tasks.lifecycle.os.getpgid", return_value=123),
         patch("lemming.tasks.lifecycle.os.kill") as mock_kill,
         patch("lemming.tasks.lifecycle.os.killpg") as mock_killpg,
+        patch("lemming.tasks.lifecycle.is_pid_alive", return_value=False),
     ):
         success = lifecycle.cancel_task(tasks_file, "1")
         assert success is True
@@ -211,6 +215,78 @@ def test_cancel_task_kills_loop_pid(tmp_path):
         assert updated_data.tasks[0].status == models.TaskStatus.CANCELLED
 
 
+def test_kill_pid_tree_escalates_to_sigkill():
+    """Verifies SIGKILL escalation when SIGTERM does not stop the process."""
+    with (
+        patch("lemming.tasks.lifecycle.os.getpgid", return_value=54321),
+        patch("lemming.tasks.lifecycle.os.killpg") as mock_killpg,
+        patch("lemming.tasks.lifecycle.is_pid_alive", return_value=True),
+        patch.object(lifecycle, "KILL_GRACE_SECONDS", 0),
+    ):
+        lifecycle._kill_pid_tree(12345)
+
+    assert mock_killpg.call_args_list == [
+        ((54321, signal.SIGTERM),),
+        ((54321, signal.SIGKILL),),
+    ]
+
+
+def test_kill_pid_tree_no_escalation_when_process_exits():
+    """Verifies no SIGKILL is sent when the process exits on SIGTERM."""
+    with (
+        patch("lemming.tasks.lifecycle.os.getpgid", return_value=54321),
+        patch("lemming.tasks.lifecycle.os.killpg") as mock_killpg,
+        patch("lemming.tasks.lifecycle.is_pid_alive", return_value=False),
+    ):
+        lifecycle._kill_pid_tree(12345)
+
+    mock_killpg.assert_called_once_with(54321, signal.SIGTERM)
+
+
+def test_cancel_task_escalates_sigterm_immune_process(tmp_path):
+    """Verifies cancellation kills a process that ignores SIGTERM.
+
+    Also verifies the task state is saved as CANCELLED before any signal
+    is sent, since the kill (which can wait out a grace period) must
+    happen outside the tasks-file lock.
+    """
+    tasks_file = tmp_path / "tasks.yml"
+    data = models.Roadmap(
+        tasks=[
+            models.Task(
+                id="1",
+                description="Task 1",
+                status=models.TaskStatus.IN_PROGRESS,
+                pid=12345,
+            )
+        ],
+    )
+    persistence.save_tasks(tasks_file, data)
+
+    status_at_first_signal = []
+
+    def record_status(*args):
+        saved = persistence.load_tasks(tasks_file)
+        status_at_first_signal.append(saved.tasks[0].status)
+
+    with (
+        patch("lemming.tasks.lifecycle.os.getpgid", return_value=54321),
+        patch(
+            "lemming.tasks.lifecycle.os.killpg", side_effect=record_status
+        ) as mock_killpg,
+        patch("lemming.tasks.lifecycle.is_pid_alive", return_value=True),
+        patch.object(lifecycle, "KILL_GRACE_SECONDS", 0),
+    ):
+        success = lifecycle.cancel_task(tasks_file, "1")
+
+    assert success is True
+    assert mock_killpg.call_args_list == [
+        ((54321, signal.SIGTERM),),
+        ((54321, signal.SIGKILL),),
+    ]
+    assert status_at_first_signal[0] == models.TaskStatus.CANCELLED
+
+
 def test_reset_task(tmp_path):
     tasks_file = tmp_path / "tasks.yml"
     task_id = "12345678"

{lemming_cli-0.1.0 → lemming_cli-0.1.1}/uv.lock

@@ -222,7 +222,7 @@ wheels = [
 
 [[package]]
 name = "lemming-cli"
-version = "0.1.0"
+version = "0.1.1"
 source = { editable = "." }
 dependencies = [
     { name = "beautifulsoup4" },