keepwatch 0.1.1__tar.gz

keepwatch-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nightshift 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.

keepwatch-0.1.1/PKG-INFO

@@ -0,0 +1,192 @@
+Metadata-Version: 2.4
+Name: keepwatch
+Version: 0.1.1
+Summary: Reliability layer for unattended agent mailboxes: leases, heartbeats, and silent-failure detection.
+License: MIT
+Project-URL: Documentation, https://github.com/OWNER/keepwatch#readme
+Project-URL: Issues, https://github.com/OWNER/keepwatch/issues
+Keywords: agents,multi-agent,reliability,mailbox,unattended
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Distributed Computing
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Dynamic: license-file
+
+# keepwatch
+
+> **Keep work alive when the process that started it is not.**
+> A 300-line, zero-dependency ledger for agents that run unattended.
+
+[![ci](https://github.com/ReZeroStarting/keepwatch/actions/workflows/ci.yml/badge.svg)](https://github.com/ReZeroStarting/keepwatch/actions/workflows/ci.yml)
+
+---
+
+## The problem
+
+An unattended pipeline does not fail loudly. It goes quiet:
+
+- a task sits in `pending/` and nobody claims it
+- a worker dies mid-task and the task is stuck in `processing/` forever
+- a worker finishes but never marks it done, so the next round re-dispatches it
+- the agent says "all tests pass" and you have nothing to check that against
+
+All four look identical from the outside: **nothing happened, and the logs are clean.**
+
+## What it does
+
+Three folders, one ledger, four verbs.
+
+```
+<root>/agents/<agent>/pending/      tasks a worker can pick up
+<root>/agents/<agent>/processing/   tasks someone is holding (with a lease)
+<root>/agents/<agent>/done/         closed tasks, never deleted
+<root>/audit/YYYY-MM.jsonl          append-only record of everything
+```
+
+| Verb | Meaning |
+|---|---|
+| `check` | what can I pick up |
+| `claim` | take one, and hold a lease on it |
+| `done` | close it — **only if a passing `verify` record exists** |
+| `verify` | record a check result (`--rc 0`) against a task |
+| **`run`** | **claim → run a command → record its exit code → close or release** |
+
+Plus `send`, `renew`, `release`, `reap`, `status`.
+
+## The one command you actually need
+
+```bash
+keepwatch run --who builder -- python -m pytest
+```
+
+That does the whole loop in one go:
+
+1. claims the oldest pending task (or `--id <id>`)
+2. runs the command with inherited stdio, so you still see the output
+3. writes `verify ... --rc <real exit code>` into the ledger
+4. `rc=0` → `done`; `rc!=0` → back to `pending` for another try
+5. after `--max-tries` (default 3) failures → left in `processing` with a `suspect` record
+
+If the process is killed mid-command, nothing is lost: the lease expires and `reap` puts the
+task back. **You do not have to remember to write the ledger — the wrapper does it.**
+
+## Why it matters
+
+`claim` starts a lease. If the worker dies, the lease expires and `reap` puts the task
+back with a trail (`tries`, `prev_owners`). No task is ever stranded, and no task is
+silently done twice.
+
+`done` refuses to close a task unless the ledger holds a `verify ... rc=0` for it.
+That is the whole point: **the model can say "it passed"; the ledger is what proves it.**
+
+```console
+$ keepwatch done --who builder --id 20261023T083729-8c4fae
+keepwatch: refusing to close 20261023T083729-8c4fae: no verify record with rc=0.
+Run `verify --id ... --name <check> --rc 0` first, or pass --force.
+$ echo $?
+13
+```
+
+## Install
+
+Python 3.9+, no dependencies.
+
+```bash
+pip install -e .
+# or just run it from a checkout:
+PYTHONPATH=src python -m keepwatch.cli --help
+```
+
+## 60-second demo
+
+```bash
+keepwatch --root /tmp/ns init builder reviewer
+
+keepwatch --root /tmp/ns send \
+  --from reviewer --to builder --subject "batch 3: add login page"
+
+keepwatch --root /tmp/ns check --who builder
+keepwatch --root /tmp/ns claim --who builder --id <id> --ttl 60
+```
+
+Now pretend the worker dies. Wait for the lease, then:
+
+```console
+$ keepwatch --root /tmp/ns status
+root: /tmp/ns
+  builder        pending 0  processing 1  done 0  hb 61s (alive)
+  reviewer       pending 0  processing 0  done 0  never seen (unknown)
+next:
+  - builder: 20261023T083750-ef2c5d held by builder, 1s past its lease - run `reap`
+
+$ keepwatch --root /tmp/ns reap
+reaped 1 task(s)
+  20261023T083750-ef2c5d  back to pending (tries=1)
+
+$ keepwatch --root /tmp/ns claim --who builder --id 20261023T083750-ef2c5d
+claimed 20261023T083750-ef2c5d (try 2) lease until 2026-10-23T08:42:31Z
+```
+
+The task came back with `tries=1` and the previous owner recorded. Close it, but only
+after proof:
+
+```bash
+keepwatch --root /tmp/ns verify --id <id> --name pytest --rc 0
+keepwatch --root /tmp/ns done   --who builder --id <id> --note "e2e green"
+```
+
+## Exit codes
+
+Exit codes are the interface; agents read them instead of parsing prose.
+
+| Code | Meaning |
+|---|---|
+| 0 | ok |
+| 1 | bad arguments, IO error |
+| 2 | task not found / already taken |
+| 3 | task held by another worker (or busy) |
+| 13 | blocked: no passing verify, or `status` found something that needs attention |
+
+## Design notes
+
+**Files are the source of truth.** No database, no daemon, no network. `ls` and `cat`
+are the debugging tools.
+
+**Exclusive create is the mutex, not rename.** On at least one Windows filesystem two
+concurrent `os.replace()` calls on the same source *both report success*. Claiming is
+therefore guarded by `O_CREAT|O_EXCL` on a short-lived token file. This is documented in
+[`docs/PROTOCOL.md`](docs/PROTOCOL.md) because it cost a real bug to find.
+
+**One worker per agent box.** Leases are per agent directory, so `builder` running two
+processes is a configuration error, not a supported mode.
+
+**`status` exits 13 when something needs attention** — so `keepwatch status || alert`
+works in cron.
+
+## What it is not
+
+- not a mailbox (see [docs/COMPETITION.md](docs/COMPETITION.md) for what exists)
+- not an orchestrator: it never decides *what* to do next
+- not an agent: it makes no model calls
+- not durable execution: it will not replay your side effects
+
+## Docs
+
+| File | Contents |
+|---|---|
+| [docs/PROTOCOL.md](docs/PROTOCOL.md) | layout, task format, lease rules, exit codes |
+| [docs/COMPETITION.md](docs/COMPETITION.md) | why this exists next to agent-mailbox / A2A / Temporal |
+| [docs/ROADMAP.md](docs/ROADMAP.md) | v0.1 → v1.0 and the release checklist |
+| [docs/zh/](docs/zh/) | 中文原文 (Chinese originals) |
+
+Tests: `PYTHONPATH=src python -m unittest discover -s tests -v`
+
+## License
+
+MIT. See [LICENSE](LICENSE).

keepwatch-0.1.1/README.md

@@ -0,0 +1,172 @@
+# keepwatch
+
+> **Keep work alive when the process that started it is not.**
+> A 300-line, zero-dependency ledger for agents that run unattended.
+
+[![ci](https://github.com/ReZeroStarting/keepwatch/actions/workflows/ci.yml/badge.svg)](https://github.com/ReZeroStarting/keepwatch/actions/workflows/ci.yml)
+
+---
+
+## The problem
+
+An unattended pipeline does not fail loudly. It goes quiet:
+
+- a task sits in `pending/` and nobody claims it
+- a worker dies mid-task and the task is stuck in `processing/` forever
+- a worker finishes but never marks it done, so the next round re-dispatches it
+- the agent says "all tests pass" and you have nothing to check that against
+
+All four look identical from the outside: **nothing happened, and the logs are clean.**
+
+## What it does
+
+Three folders, one ledger, four verbs.
+
+```
+<root>/agents/<agent>/pending/      tasks a worker can pick up
+<root>/agents/<agent>/processing/   tasks someone is holding (with a lease)
+<root>/agents/<agent>/done/         closed tasks, never deleted
+<root>/audit/YYYY-MM.jsonl          append-only record of everything
+```
+
+| Verb | Meaning |
+|---|---|
+| `check` | what can I pick up |
+| `claim` | take one, and hold a lease on it |
+| `done` | close it — **only if a passing `verify` record exists** |
+| `verify` | record a check result (`--rc 0`) against a task |
+| **`run`** | **claim → run a command → record its exit code → close or release** |
+
+Plus `send`, `renew`, `release`, `reap`, `status`.
+
+## The one command you actually need
+
+```bash
+keepwatch run --who builder -- python -m pytest
+```
+
+That does the whole loop in one go:
+
+1. claims the oldest pending task (or `--id <id>`)
+2. runs the command with inherited stdio, so you still see the output
+3. writes `verify ... --rc <real exit code>` into the ledger
+4. `rc=0` → `done`; `rc!=0` → back to `pending` for another try
+5. after `--max-tries` (default 3) failures → left in `processing` with a `suspect` record
+
+If the process is killed mid-command, nothing is lost: the lease expires and `reap` puts the
+task back. **You do not have to remember to write the ledger — the wrapper does it.**
+
+## Why it matters
+
+`claim` starts a lease. If the worker dies, the lease expires and `reap` puts the task
+back with a trail (`tries`, `prev_owners`). No task is ever stranded, and no task is
+silently done twice.
+
+`done` refuses to close a task unless the ledger holds a `verify ... rc=0` for it.
+That is the whole point: **the model can say "it passed"; the ledger is what proves it.**
+
+```console
+$ keepwatch done --who builder --id 20261023T083729-8c4fae
+keepwatch: refusing to close 20261023T083729-8c4fae: no verify record with rc=0.
+Run `verify --id ... --name <check> --rc 0` first, or pass --force.
+$ echo $?
+13
+```
+
+## Install
+
+Python 3.9+, no dependencies.
+
+```bash
+pip install -e .
+# or just run it from a checkout:
+PYTHONPATH=src python -m keepwatch.cli --help
+```
+
+## 60-second demo
+
+```bash
+keepwatch --root /tmp/ns init builder reviewer
+
+keepwatch --root /tmp/ns send \
+  --from reviewer --to builder --subject "batch 3: add login page"
+
+keepwatch --root /tmp/ns check --who builder
+keepwatch --root /tmp/ns claim --who builder --id <id> --ttl 60
+```
+
+Now pretend the worker dies. Wait for the lease, then:
+
+```console
+$ keepwatch --root /tmp/ns status
+root: /tmp/ns
+  builder        pending 0  processing 1  done 0  hb 61s (alive)
+  reviewer       pending 0  processing 0  done 0  never seen (unknown)
+next:
+  - builder: 20261023T083750-ef2c5d held by builder, 1s past its lease - run `reap`
+
+$ keepwatch --root /tmp/ns reap
+reaped 1 task(s)
+  20261023T083750-ef2c5d  back to pending (tries=1)
+
+$ keepwatch --root /tmp/ns claim --who builder --id 20261023T083750-ef2c5d
+claimed 20261023T083750-ef2c5d (try 2) lease until 2026-10-23T08:42:31Z
+```
+
+The task came back with `tries=1` and the previous owner recorded. Close it, but only
+after proof:
+
+```bash
+keepwatch --root /tmp/ns verify --id <id> --name pytest --rc 0
+keepwatch --root /tmp/ns done   --who builder --id <id> --note "e2e green"
+```
+
+## Exit codes
+
+Exit codes are the interface; agents read them instead of parsing prose.
+
+| Code | Meaning |
+|---|---|
+| 0 | ok |
+| 1 | bad arguments, IO error |
+| 2 | task not found / already taken |
+| 3 | task held by another worker (or busy) |
+| 13 | blocked: no passing verify, or `status` found something that needs attention |
+
+## Design notes
+
+**Files are the source of truth.** No database, no daemon, no network. `ls` and `cat`
+are the debugging tools.
+
+**Exclusive create is the mutex, not rename.** On at least one Windows filesystem two
+concurrent `os.replace()` calls on the same source *both report success*. Claiming is
+therefore guarded by `O_CREAT|O_EXCL` on a short-lived token file. This is documented in
+[`docs/PROTOCOL.md`](docs/PROTOCOL.md) because it cost a real bug to find.
+
+**One worker per agent box.** Leases are per agent directory, so `builder` running two
+processes is a configuration error, not a supported mode.
+
+**`status` exits 13 when something needs attention** — so `keepwatch status || alert`
+works in cron.
+
+## What it is not
+
+- not a mailbox (see [docs/COMPETITION.md](docs/COMPETITION.md) for what exists)
+- not an orchestrator: it never decides *what* to do next
+- not an agent: it makes no model calls
+- not durable execution: it will not replay your side effects
+
+## Docs
+
+| File | Contents |
+|---|---|
+| [docs/PROTOCOL.md](docs/PROTOCOL.md) | layout, task format, lease rules, exit codes |
+| [docs/COMPETITION.md](docs/COMPETITION.md) | why this exists next to agent-mailbox / A2A / Temporal |
+| [docs/ROADMAP.md](docs/ROADMAP.md) | v0.1 → v1.0 and the release checklist |
+| [docs/zh/](docs/zh/) | 中文原文 (Chinese originals) |
+
+Tests: `PYTHONPATH=src python -m unittest discover -s tests -v`
+
+## License
+
+MIT. See [LICENSE](LICENSE).

keepwatch-0.1.1/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+# Name checked on PyPI 2026-10-23. "nightshift", "agentbus", "agent-mailbox",
+# "agent-watchdog", "deadman", "backstop", "watchpost", "handover" are all taken.
+# See docs/COMPETITION.md.
+name = "keepwatch"
+version = "0.1.1"
+description = "Reliability layer for unattended agent mailboxes: leases, heartbeats, and silent-failure detection."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+keywords = ["agents", "multi-agent", "reliability", "mailbox", "unattended"]
+classifiers = [
+  "Development Status :: 2 - Pre-Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Topic :: System :: Distributed Computing",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=8"]
+
+[project.scripts]
+keepwatch = "keepwatch.cli:main"
+
+[project.urls]
+Documentation = "https://github.com/OWNER/keepwatch#readme"
+Issues = "https://github.com/OWNER/keepwatch/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

keepwatch-0.1.1/setup.cfg

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

keepwatch-0.1.1/src/keepwatch/__init__.py

@@ -0,0 +1,11 @@
+"""keepwatch — keep work alive when the process that started it is not.
+
+A task is a JSON file that moves between three folders. Whoever holds it holds a
+lease; a dead holder's lease expires and the task comes back with a trail. A task
+is only ``done`` when the ledger holds a ``verify`` record with ``rc == 0``.
+
+Protocol: docs/PROTOCOL.md. Story: examples/two_workers.py.
+"""
+
+__version__ = "0.1.1"
+__all__ = ["__version__"]

keepwatch-0.1.1/src/keepwatch/cli.py

@@ -0,0 +1,242 @@
+"""Command line interface. Every command maps to one function in ``core``."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any
+
+from . import __version__, core
+
+
+def _default_root() -> str:
+    return os.environ.get("KEEPWATCH_ROOT", ".")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="keepwatch",
+        description="Keep agent work alive when the process that started it is not.",
+    )
+    parser.add_argument("--root", default=_default_root(), help="work root (default: $KEEPWATCH_ROOT or .)")
+    parser.add_argument("--json", action="store_true", help="machine readable output")
+    parser.add_argument("--version", action="version", version=f"keepwatch {__version__}")
+
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_init = sub.add_parser("init", help="create the layout for some agents")
+    p_init.add_argument("agents", nargs="+", metavar="AGENT")
+
+    p_send = sub.add_parser("send", help="hand a task to an agent")
+    p_send.add_argument("--from", dest="sender", required=True)
+    p_send.add_argument("--to", required=True)
+    p_send.add_argument("--subject", required=True)
+    p_send.add_argument("--body", default="")
+    p_send.add_argument("--body-file")
+
+    p_check = sub.add_parser("check", help="list tasks you can pick up")
+    p_check.add_argument("--who", required=True)
+
+    p_claim = sub.add_parser("claim", help="take a task (and hold a lease on it)")
+    p_claim.add_argument("--who", required=True)
+    p_claim.add_argument("--id", required=True)
+    p_claim.add_argument("--ttl", type=int, default=core.DEFAULT_TTL_SECONDS)
+
+    p_renew = sub.add_parser("renew", help="extend your own lease on a task")
+    p_renew.add_argument("--who", required=True)
+    p_renew.add_argument("--id", required=True)
+    p_renew.add_argument("--ttl", type=int, default=core.DEFAULT_TTL_SECONDS)
+
+    p_done = sub.add_parser("done", help="close a task (requires a passing verify)")
+    p_done.add_argument("--who", required=True)
+    p_done.add_argument("--id", required=True)
+    p_done.add_argument("--note", default="")
+    p_done.add_argument("--force", action="store_true", help="close without a verify record")
+
+    p_verify = sub.add_parser("verify", help="record a check result against a task")
+    p_verify.add_argument("--id", required=True)
+    p_verify.add_argument("--name", required=True)
+    p_verify.add_argument("--rc", type=int, required=True)
+
+    p_run = sub.add_parser(
+        "run",
+        help="claim a task, run a command, record the exit code and close or release it",
+        usage="keepwatch run --who AGENT [--id ID] [--ttl SECONDS] [--max-tries N] -- COMMAND ...",
+    )
+    p_run.add_argument("--who", required=True)
+    p_run.add_argument("--id", help="task id (default: the oldest pending task)")
+    p_run.add_argument("--ttl", type=int, default=core.DEFAULT_TTL_SECONDS)
+    p_run.add_argument("--max-tries", type=int, default=3)
+    p_run.add_argument("cmd", nargs=argparse.REMAINDER)
+
+    sub.add_parser("reap", help="return expired leases to pending")
+
+    p_status = sub.add_parser("status", help="what is stuck, who is dead, what is next")
+    p_status.add_argument("--stale", type=int, default=core.DEFAULT_STALE_SECONDS)
+
+    return parser
+
+
+def _emit(args: argparse.Namespace, payload: Any, human: list[str]) -> None:
+    if args.json:
+        print(json.dumps(payload, ensure_ascii=False, indent=2))
+    else:
+        for line in human:
+            print(line)
+
+
+def _short(text: str, width: int = 40) -> str:
+    text = (text or "").replace("\n", " ")
+    return text if len(text) <= width else text[: width - 1] + "…"
+
+
+def run(args: argparse.Namespace) -> int:
+    store = core.Store(args.root)
+
+    if args.command == "init":
+        store.init(args.agents)
+        _emit(args, {"root": str(store.root), "agents": args.agents},
+              [f"initialised {store.root}", "agents: " + ", ".join(args.agents)])
+        return core.EXIT_OK
+
+    if args.command == "send":
+        body = args.body
+        if args.body_file:
+            body = Path(args.body_file).read_text(encoding="utf-8")
+        task = core.send(store, args.sender, args.to, args.subject, body)
+        _emit(args, task, [f"sent {task['id']} -> {args.to}: {args.subject}"])
+        return core.EXIT_OK
+
+    if args.command == "check":
+        core.heartbeat(store, args.who)
+        tasks = core.check(store, args.who)
+        human = [f"{len(tasks)} task(s) for {args.who}"]
+        for t in tasks:
+            age = int(core.age_seconds(t["created_at"]))
+            human.append(f"  {t['id']}  {age:>6}s  from {t['from']:<12} {_short(t['subject'])}")
+        _emit(args, {"who": args.who, "tasks": tasks}, human)
+        return core.EXIT_OK
+
+    if args.command == "claim":
+        core.heartbeat(store, args.who)
+        task = core.claim(store, args.who, args.id, args.ttl)
+        lease = task["_lease"]
+        _emit(args, task, [
+            f"claimed {task['id']} (try {task['tries']}) lease until {lease['expires_at']}",
+        ])
+        return core.EXIT_OK
+
+    if args.command == "renew":
+        core.heartbeat(store, args.who)
+        task = core.renew(store, args.who, args.id, args.ttl)
+        _emit(args, task, [f"renewed {task['id']} until {task['_lease']['expires_at']}"])
+        return core.EXIT_OK
+
+    if args.command == "done":
+        core.heartbeat(store, args.who)
+        task = core.done(store, args.who, args.id, args.note, args.force)
+        _emit(args, task, [f"closed {task['id']}"])
+        return core.EXIT_OK
+
+    if args.command == "verify":
+        record = core.verify(store, args.id, args.name, args.rc)
+        _emit(args, record, [f"recorded {args.name} rc={args.rc} for {args.id}"])
+        return core.EXIT_OK
+
+    if args.command == "run":
+        return run_task(store, args)
+
+    if args.command == "reap":
+        tasks = core.reap(store)
+        human = [f"reaped {len(tasks)} task(s)"]
+        for t in tasks:
+            human.append(f"  {t['id']}  back to pending (tries={t['tries']})")
+        _emit(args, {"reaped": tasks}, human)
+        return core.EXIT_OK
+
+    if args.command == "status":
+        state = core.status(store, args.stale)
+        human = [f"root: {state['root']}"]
+        for name, row in state["agents"].items():
+            if row["heartbeat_age_s"] is None:
+                hb, flag = "never seen", "unknown"
+            elif row["alive"]:
+                hb, flag = f"hb {row['heartbeat_age_s']}s", "alive"
+            else:
+                hb, flag = f"hb {row['heartbeat_age_s']}s", "STALE"
+            human.append(
+                f"  {name:<14} pending {row['pending']}  processing {row['processing']}"
+                f"  done {row['done']}  {hb} ({flag})"
+            )
+        if state["next_steps"]:
+            human.append("next:")
+            human.extend(f"  - {line}" for line in state["next_steps"])
+        else:
+            human.append("next: nothing to do")
+        _emit(args, state, human)
+        return core.EXIT_OK if state["ok"] else core.EXIT_BLOCKED
+
+    raise core.keepwatchError(f"unknown command: {args.command}")
+
+
+def run_task(store: core.Store, args: argparse.Namespace) -> int:
+    """Claim -> run -> verify -> close or release. The one command an agent needs."""
+    cmd = list(args.cmd)
+    if cmd and cmd[0] == "--":
+        cmd = cmd[1:]
+    if not cmd:
+        raise core.keepwatchError(
+            "no command given; use: keepwatch run --who AGENT -- COMMAND ..."
+        )
+
+    core.heartbeat(store, args.who)
+    task_id = args.id
+    if not task_id:
+        task = core.oldest_pending(store, args.who)
+        if task is None:
+            raise core.NotFound(f"no pending task for {args.who}")
+        task_id = task["id"]
+
+    claimed = core.claim(store, args.who, task_id, args.ttl)
+    label = " ".join(cmd)
+    print(f"running {task_id} (try {claimed['tries']}): {label}", flush=True)
+
+    # stdio is inherited on purpose: the agent's output must reach the human.
+    rc = subprocess.run(cmd, check=False).returncode
+    core.verify(store, task_id, label, rc)
+
+    if rc == 0:
+        core.done(store, args.who, task_id, note=label)
+        print(f"closed {task_id} (rc=0)", flush=True)
+        return core.EXIT_OK
+
+    if claimed["tries"] >= args.max_tries:
+        core.ledger_append(store, "suspect", id=task_id, tries=claimed["tries"], rc=rc)
+        print(
+            f"left {task_id} in processing: rc={rc}, tries={claimed['tries']} >= {args.max_tries}. "
+            f"Check `status`, then `reap` if it should be retried anyway.",
+            flush=True,
+        )
+        return rc if 0 < rc < 256 else core.EXIT_ERROR
+
+    core.release(store, args.who, task_id, reason=f"rc={rc}")
+    print(f"released {task_id} back to pending (rc={rc})", flush=True)
+    return rc if 0 < rc < 256 else core.EXIT_ERROR
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        return run(args)
+    except core.keepwatchError as exc:
+        print(f"keepwatch: {exc}", file=sys.stderr)
+        return exc.code
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())