runsentry 0.1.0a1__tar.gz

runsentry-0.1.0a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RunSentry contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

runsentry-0.1.0a1/PKG-INFO

@@ -0,0 +1,227 @@
+Metadata-Version: 2.4
+Name: runsentry
+Version: 0.1.0a1
+Summary: A lightweight local health observer for long-running commands and Python jobs.
+Author: RunSentry contributors
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Monitoring
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: psutil>=5.9
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Dynamic: license-file
+
+# RunSentry
+
+A lightweight local observer for long-running commands.
+
+Wrap any command without modifying it:
+
+```bash
+runsentry run --name training -- python train.py
+```
+
+RunSentry records:
+
+- process/resource activity;
+- stdout/stderr activity;
+- watched file/directory changes;
+- conservative health state;
+- local JSONL telemetry;
+- final `summary.json`.
+
+No daemon.
+No cloud.
+No automatic killing.
+
+It is for developers, researchers, and local AI/agent users who want factual evidence
+about commands that may stay active for minutes or hours.
+
+```bash
+runsentry run \
+  --name demo \
+  --watch /tmp/runsentry-demo-output.txt \
+  -- python examples/demo_long_job.py
+```
+
+## Public alpha status
+
+RunSentry is in conservative public alpha. The P0 scope is useful for local observation
+and debugging, but it is not a production supervisor or a guaranteed stuck-process
+detector.
+
+## Current P0 capabilities
+
+RunSentry P0 can:
+
+- launch a command directly with `shell=False`;
+- preserve the child command argv after an explicit `--` boundary;
+- tee child stdout and stderr back to the terminal as byte streams;
+- count stdout/stderr bytes and chunks without storing output content;
+- observe process/resource facts with `psutil`;
+- observe watched file/directory size, mtime, file count, and disk usage facts;
+- write local `.runsentry/runs/<run_id>/telemetry.jsonl`;
+- write local `.runsentry/runs/<run_id>/summary.json`;
+- emit conservative health states:
+  - `STARTING`
+  - `HEALTHY`
+  - `QUIET`
+  - `SUSPECTED_STALL`
+  - `FAILED`
+  - `COMPLETE`
+
+`SUSPECTED_STALL` is a conservative suspicion, not proof. Silence alone is not a stall.
+No watch path is not stall evidence. Unavailable metrics reduce confidence.
+
+## Install from source
+
+RunSentry currently targets Python 3.10+ on macOS and Linux.
+
+Current source installation:
+
+```bash
+python -m pip install -e .
+```
+
+For development tests:
+
+```bash
+python -m pip install -e ".[test]"
+python -m pytest -q
+```
+
+Future PyPI installation is planned, but the package has not been published to PyPI yet.
+Until that happens, source installation is required.
+
+## Basic usage
+
+Always put the command to run after the explicit `--` boundary:
+
+```bash
+runsentry run --name demo -- python3 -c "import time; time.sleep(2)"
+```
+
+Watch an output file or directory:
+
+```bash
+runsentry run --name io-demo --watch out.log -- python3 job.py
+```
+
+Use more than one watch path:
+
+```bash
+runsentry run --watch out.log --watch output_dir -- python3 job.py
+```
+
+Everything after `--` belongs to the child command unchanged:
+
+```bash
+runsentry run --name outer -- python3 job.py --watch child-value
+```
+
+RunSentry does not invoke a shell. If you need shell syntax, launch the shell explicitly:
+
+```bash
+runsentry run --name shell-demo -- bash -lc 'python3 job.py | tee output.log'
+```
+
+In that case, the shell is the observed root process and shell quoting rules are your
+responsibility.
+
+## Output artifacts
+
+By default, each run writes:
+
+```text
+.runsentry/
+  runs/
+    <run_id>/
+      telemetry.jsonl
+      summary.json
+```
+
+Use `--output-dir` to place artifacts elsewhere:
+
+```bash
+runsentry run --output-dir /tmp/runsentry-demo -- python3 job.py
+```
+
+Telemetry is local. RunSentry does not upload data or contact a service.
+
+RunSentry stores stdout/stderr activity counters, not stdout/stderr content. Command argv
+is stored because it is part of the factual launch record, so avoid putting secrets in
+command arguments.
+
+Generated `.runsentry/` artifacts are ignored by this repository and should normally
+stay out of commits.
+
+## Health states
+
+- `STARTING`: the run is inside the initial observation window.
+- `HEALTHY`: recent positive activity was observed.
+- `QUIET`: little activity is visible, but evidence is insufficient to suspect a stall.
+- `SUSPECTED_STALL`: multiple independent available signals show sustained inactivity.
+- `FAILED`: the wrapped root command failed to launch or exited nonzero.
+- `COMPLETE`: the wrapped root command completed successfully under current P0 semantics.
+
+Only `FAILED` and `COMPLETE` are ordinary terminal success/failure states. `SUSPECTED_STALL`
+can recover if activity resumes.
+
+## P0 limitations
+
+RunSentry P0 is intentionally small:
+
+- local machine only;
+- macOS and Linux target;
+- no Windows compatibility promise yet;
+- no web dashboard;
+- no SaaS or remote monitoring;
+- no notifications;
+- no database;
+- no workflow orchestration;
+- no AI/LLM health judgment;
+- no automatic kill or recovery;
+- no OOM prediction;
+- no disk exhaustion prediction;
+- no generic job-completion ETA.
+
+Process/resource visibility may be partial due to OS permissions. The health logic is
+conservative and may miss real stalls rather than creating aggressive false positives.
+
+## More detail
+
+See [docs/public-alpha.md](docs/public-alpha.md) for the public-alpha readiness notes.
+
+Historical design and implementation records live in `docs/RS-P0-*.md`.
+
+## Reporting bugs
+
+Use the GitHub issue templates. For behavior bugs, include:
+
+- OS and Python version;
+- the `runsentry run ...` command, with secrets removed;
+- expected versus actual behavior;
+- a sanitized `summary.json` excerpt if useful.
+
+Do not share command arguments or paths that contain secrets.
+
+## Feedback wanted
+
+If you try RunSentry on a real local command, feedback on install friction, health-state
+accuracy, `summary.json` usefulness, and missing P0 facts is especially useful.
+
+## License
+
+MIT.

runsentry-0.1.0a1/README.md

@@ -0,0 +1,202 @@
+# RunSentry
+
+A lightweight local observer for long-running commands.
+
+Wrap any command without modifying it:
+
+```bash
+runsentry run --name training -- python train.py
+```
+
+RunSentry records:
+
+- process/resource activity;
+- stdout/stderr activity;
+- watched file/directory changes;
+- conservative health state;
+- local JSONL telemetry;
+- final `summary.json`.
+
+No daemon.
+No cloud.
+No automatic killing.
+
+It is for developers, researchers, and local AI/agent users who want factual evidence
+about commands that may stay active for minutes or hours.
+
+```bash
+runsentry run \
+  --name demo \
+  --watch /tmp/runsentry-demo-output.txt \
+  -- python examples/demo_long_job.py
+```
+
+## Public alpha status
+
+RunSentry is in conservative public alpha. The P0 scope is useful for local observation
+and debugging, but it is not a production supervisor or a guaranteed stuck-process
+detector.
+
+## Current P0 capabilities
+
+RunSentry P0 can:
+
+- launch a command directly with `shell=False`;
+- preserve the child command argv after an explicit `--` boundary;
+- tee child stdout and stderr back to the terminal as byte streams;
+- count stdout/stderr bytes and chunks without storing output content;
+- observe process/resource facts with `psutil`;
+- observe watched file/directory size, mtime, file count, and disk usage facts;
+- write local `.runsentry/runs/<run_id>/telemetry.jsonl`;
+- write local `.runsentry/runs/<run_id>/summary.json`;
+- emit conservative health states:
+  - `STARTING`
+  - `HEALTHY`
+  - `QUIET`
+  - `SUSPECTED_STALL`
+  - `FAILED`
+  - `COMPLETE`
+
+`SUSPECTED_STALL` is a conservative suspicion, not proof. Silence alone is not a stall.
+No watch path is not stall evidence. Unavailable metrics reduce confidence.
+
+## Install from source
+
+RunSentry currently targets Python 3.10+ on macOS and Linux.
+
+Current source installation:
+
+```bash
+python -m pip install -e .
+```
+
+For development tests:
+
+```bash
+python -m pip install -e ".[test]"
+python -m pytest -q
+```
+
+Future PyPI installation is planned, but the package has not been published to PyPI yet.
+Until that happens, source installation is required.
+
+## Basic usage
+
+Always put the command to run after the explicit `--` boundary:
+
+```bash
+runsentry run --name demo -- python3 -c "import time; time.sleep(2)"
+```
+
+Watch an output file or directory:
+
+```bash
+runsentry run --name io-demo --watch out.log -- python3 job.py
+```
+
+Use more than one watch path:
+
+```bash
+runsentry run --watch out.log --watch output_dir -- python3 job.py
+```
+
+Everything after `--` belongs to the child command unchanged:
+
+```bash
+runsentry run --name outer -- python3 job.py --watch child-value
+```
+
+RunSentry does not invoke a shell. If you need shell syntax, launch the shell explicitly:
+
+```bash
+runsentry run --name shell-demo -- bash -lc 'python3 job.py | tee output.log'
+```
+
+In that case, the shell is the observed root process and shell quoting rules are your
+responsibility.
+
+## Output artifacts
+
+By default, each run writes:
+
+```text
+.runsentry/
+  runs/
+    <run_id>/
+      telemetry.jsonl
+      summary.json
+```
+
+Use `--output-dir` to place artifacts elsewhere:
+
+```bash
+runsentry run --output-dir /tmp/runsentry-demo -- python3 job.py
+```
+
+Telemetry is local. RunSentry does not upload data or contact a service.
+
+RunSentry stores stdout/stderr activity counters, not stdout/stderr content. Command argv
+is stored because it is part of the factual launch record, so avoid putting secrets in
+command arguments.
+
+Generated `.runsentry/` artifacts are ignored by this repository and should normally
+stay out of commits.
+
+## Health states
+
+- `STARTING`: the run is inside the initial observation window.
+- `HEALTHY`: recent positive activity was observed.
+- `QUIET`: little activity is visible, but evidence is insufficient to suspect a stall.
+- `SUSPECTED_STALL`: multiple independent available signals show sustained inactivity.
+- `FAILED`: the wrapped root command failed to launch or exited nonzero.
+- `COMPLETE`: the wrapped root command completed successfully under current P0 semantics.
+
+Only `FAILED` and `COMPLETE` are ordinary terminal success/failure states. `SUSPECTED_STALL`
+can recover if activity resumes.
+
+## P0 limitations
+
+RunSentry P0 is intentionally small:
+
+- local machine only;
+- macOS and Linux target;
+- no Windows compatibility promise yet;
+- no web dashboard;
+- no SaaS or remote monitoring;
+- no notifications;
+- no database;
+- no workflow orchestration;
+- no AI/LLM health judgment;
+- no automatic kill or recovery;
+- no OOM prediction;
+- no disk exhaustion prediction;
+- no generic job-completion ETA.
+
+Process/resource visibility may be partial due to OS permissions. The health logic is
+conservative and may miss real stalls rather than creating aggressive false positives.
+
+## More detail
+
+See [docs/public-alpha.md](docs/public-alpha.md) for the public-alpha readiness notes.
+
+Historical design and implementation records live in `docs/RS-P0-*.md`.
+
+## Reporting bugs
+
+Use the GitHub issue templates. For behavior bugs, include:
+
+- OS and Python version;
+- the `runsentry run ...` command, with secrets removed;
+- expected versus actual behavior;
+- a sanitized `summary.json` excerpt if useful.
+
+Do not share command arguments or paths that contain secrets.
+
+## Feedback wanted
+
+If you try RunSentry on a real local command, feedback on install friction, health-state
+accuracy, `summary.json` usefulness, and missing P0 facts is especially useful.
+
+## License
+
+MIT.

runsentry-0.1.0a1/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "runsentry"
+version = "0.1.0a1"
+description = "A lightweight local health observer for long-running commands and Python jobs."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [
+  {name = "RunSentry contributors"}
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Operating System :: MacOS",
+  "Operating System :: POSIX :: Linux",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: System :: Monitoring",
+  "Topic :: Utilities"
+]
+dependencies = [
+  "psutil>=5.9"
+]
+
+[project.optional-dependencies]
+test = [
+  "pytest>=7"
+]
+
+[project.scripts]
+runsentry = "runsentry.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

runsentry-0.1.0a1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

runsentry-0.1.0a1/src/runsentry/__init__.py

@@ -0,0 +1,3 @@
+from .version import __version__
+
+__all__ = ["__version__"]

runsentry-0.1.0a1/src/runsentry/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

runsentry-0.1.0a1/src/runsentry/cli.py

@@ -0,0 +1,128 @@
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Sequence
+
+from .execution import EXIT_USAGE, LaunchError, RunSpec, run_command
+from .observation import DEFAULT_RESOURCE_SAMPLE_INTERVAL_S
+from .version import __version__
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="runsentry",
+        description="Local conservative health observer for one long-running command.",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {__version__}",
+    )
+
+    subparsers = parser.add_subparsers(dest="command_name")
+    run_parser = subparsers.add_parser(
+        "run",
+        help="observe a command after an explicit -- boundary",
+        description=(
+            "Launch COMMAND directly with shell=False, tee stdout/stderr, "
+            "observe local facts, and write .runsentry telemetry."
+        ),
+    )
+    run_parser.add_argument("--name", default=None, help="optional human-readable run name")
+    run_parser.add_argument(
+        "--interval",
+        type=float,
+        default=DEFAULT_RESOURCE_SAMPLE_INTERVAL_S,
+        help="resource/watch/telemetry sampling interval in seconds",
+    )
+    run_parser.add_argument(
+        "--watch",
+        action="append",
+        default=[],
+        help="path to observe for factual size/mtime/disk data",
+    )
+    run_parser.add_argument(
+        "--output-dir",
+        default=None,
+        help="directory for RunSentry telemetry artifacts",
+    )
+    run_parser.add_argument(
+        "run_args",
+        nargs=argparse.REMAINDER,
+        help="must contain -- followed by COMMAND [ARG ...]; all arguments after -- belong to the child",
+    )
+    run_parser.set_defaults(func=_run)
+    return parser
+
+
+def _parse_run_args(
+    name: str | None,
+    interval: float,
+    watches: Sequence[str],
+    output_dir: str | None,
+    run_args: Sequence[str],
+) -> RunSpec:
+    if interval < 1.0 or interval > 60.0:
+        raise LaunchError("runsentry run --interval must be between 1.0 and 60.0.", EXIT_USAGE)
+
+    if "--" not in run_args:
+        raise LaunchError(
+            "runsentry run requires an explicit -- before the command.",
+            EXIT_USAGE,
+        )
+
+    boundary_index = list(run_args).index("--")
+    option_args = list(run_args[:boundary_index])
+    command_argv = list(run_args[boundary_index + 1 :])
+    if not command_argv:
+        raise LaunchError("runsentry run requires a command after --.", EXIT_USAGE)
+
+    watch_paths = list(watches) + _parse_watch_options(option_args)
+
+    return RunSpec(
+        name=name,
+        argv=command_argv,
+        sample_interval_s=interval,
+        watch_paths=watch_paths,
+        output_dir=output_dir,
+    )
+
+
+def _parse_watch_options(option_args: list[str]) -> list[str]:
+    watch_paths: list[str] = []
+    index = 0
+    while index < len(option_args):
+        arg = option_args[index]
+        if arg != "--watch":
+            raise LaunchError(f"unexpected argument before --: {arg}", EXIT_USAGE)
+        index += 1
+        if index >= len(option_args):
+            raise LaunchError("runsentry run --watch requires a path.", EXIT_USAGE)
+        watch_paths.append(option_args[index])
+        index += 1
+    return watch_paths
+
+
+def _run(args: argparse.Namespace) -> int:
+    try:
+        run_spec = _parse_run_args(
+            args.name,
+            args.interval,
+            args.watch,
+            args.output_dir,
+            args.run_args,
+        )
+        return run_command(run_spec)
+    except LaunchError as exc:
+        print(f"runsentry: {exc}", file=sys.stderr)
+        return exc.exit_code
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if not hasattr(args, "func"):
+        parser.print_help()
+        return 0
+    return int(args.func(args))