agent-dispatch 0.12.1__tar.gz → 0.13.0__tar.gz

{agent_dispatch-0.12.1 → agent_dispatch-0.13.0}/.github/workflows/publish.yml

@@ -26,5 +26,12 @@ jobs:
           pip install build
           python -m build
 
+      # Keep this current with the build backend. The pinned action bundles its
+      # own twine, and twine rejects a Metadata-Version it does not know: the
+      # v0.13.0 publish failed because hatchling 1.32 emits `Metadata-Version:
+      # 2.5` while the previous pin (Feb 2026) shipped twine 6.1.0 / packaging
+      # 25.0. `python -m build` resolves the newest hatchling at build time, so
+      # this drifts on its own with no repo change — see the release checklist's
+      # `twine check` step, which catches it before a tag is cut.
       - name: Publish to PyPI
-        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # release/v1
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2

{agent_dispatch-0.12.1 → agent_dispatch-0.13.0}/AGENTS.md

@@ -52,16 +52,25 @@ Tests must **never** invoke the real `claude` CLI. Runner tests mock `shutil.whi
 - **Never `close()` a pipe another thread may still be reading.** `close()` waits on the reader's buffer lock with *no timeout*, so it would hang the dispatch forever — the bounded `join()` before it buys nothing. `dispatch_stream` skips the stderr close while the drain thread is alive and lets the daemon reader + Popen finalizer release the fd. This is not hypothetical: a stdio MCP server inherits the child's `stderr`, so the pipe often has no EOF even after `claude` exits cleanly.
 - **No `await` inside `config_lock()`.** `ProcessLock`'s in-process guard is a `threading.RLock` — re-entrant per *thread* — and every MCP tool coroutine runs on the one event-loop thread. Suspending in the critical section lets a second coroutine re-enter the "held" lock and interleave its own load/mutate/save. Collect warnings as data, emit them after the `with` block (`test_no_await_inside_the_config_lock` enforces this by AST).
 - Cross-process locks are acquired with a **bounded** wait, never a blocking `flock`: the server takes them on its event-loop thread, so a wedged holder would freeze every tool. After the deadline it proceeds unlocked and logs — a possible lost update beats a permanent freeze.
-- `recover_stale` sweeps `pending` on a **much longer** threshold than `running`: the jobs directory is shared by every `agent-dispatch serve`, so an hours-old pending job may still be queued behind another live server's semaphore.
+- `recover_stale` sweeps `pending` on a **much longer** threshold than `running`: the jobs directory is shared by every `agent-dispatch serve`, so an hours-old pending job may still be queued behind another live server's semaphore. For a *running* job, `started_at` alone does **not** prove abandonment — a dispatch may legitimately run to the 7200s timeout ceiling, so the file's own mtime is checked too (a live worker rewrites it on every progress flush). That check can only ever *skip* a recovery, never add one.
+- Deleting job records is **opt-in** (`settings.job_retention_days`, default `0` = off) and only ever happens at server start, never inside a tool. They are the user's dispatch history and the deletion is irreversible, so an unreadable config is treated as "do nothing" rather than falling back to a default retention.
+- `max_concurrency` must bound *subprocesses*, not coroutines. Cancelling a coroutine does not stop the thread behind `asyncio.to_thread`, so `async with sem:` gave the slot away while `claude` kept running and billing. Dispatches go through `_dispatch_guarded`, which releases from the future's done-callback and `shield`s the await. Never "simplify" it back to `async with`.
+- Tool responses are serialized through `server._dumps`, never bare `json.dumps`: the stdlib default (`ensure_ascii=True`) turns every non-ASCII character into a `\uXXXX` escape, tripling the bytes and tokenizing badly, for no gain — the stdio transport emits raw UTF-8 via pydantic anyway. A real `list_groups()` carried 8520 escapes and weighed 59 KB instead of 25 KB.
+- `agents.yaml` is parsed with libyaml's `CSafeLoader` when available (`config._YamlLoader`), falling back to the pure-Python **safe** loader — never `yaml.Loader`. The config is re-read on every tool call, so this parse is on the hot path of all 21 tools *and* blocks the event-loop thread: 9.80 ms → 0.76 ms on a real 38 KB config.
 - Pydantic does **not** validate on assignment. `Field(ge=...)` guards only the *load* path; every mutation surface (CLI `add`/`update`, MCP `add_agent`/`update_agent`) needs its own boundary check, or the bound escapes as a raw `ValidationError`.
 - Every state file (`agents.yaml`, job files) is written **temp file + `os.replace`**, never in place, and every load/mutate/save is wrapped in `config.ProcessLock` — the CLI and the MCP server are separate processes writing the same files, so a thread lock alone loses updates.
 - Anything that changes an agent's config must call `_invalidate_agent_cache` — the cache key holds the agent *name*, not its directory or permissions.
 - Only *clean* successes are cached: `cache.put` refuses failures, `denied_tools` results, and `budget_exceeded` results, so the documented "grant access, then re-dispatch" recovery is never short-circuited.
 - Remediation text is a contract: a hint that names a flag must name one that exists (`test_printed_budget_hint_is_a_runnable_command` feeds the printed flags back into the CLI). Run the command you print.
+- The config error sets are declared **once** and in two halves: `config.CONFIG_LOAD_ERRORS` (read) and `config.CONFIG_SAVE_ERRORS` (write — `yaml.dump`'s `RepresenterError` is a `yaml.YAMLError`, therefore neither `OSError` nor `ConfigLoadError`, and used to escape both the MCP guard and the CLI's `_save_or_exit`). Two halves, not one set, because the remediations differ: a failed write is atomic so the old config survives, while a failed read needs the YAML fixed.
 - MCP tools that load config carry `@_config_guard` under `@mcp.tool()` so a broken `agents.yaml` — or a failed *write* — returns the `{"error": ...}` envelope instead of a raw traceback. The set of load errors lives in one place (`config.CONFIG_LOAD_ERRORS`) because three surfaces handle it: **`UnicodeDecodeError` is a `ValueError`, not an `OSError`**, and listing types per-site is exactly how a cp1251 config slipped past all three.
 
 - Tests must not touch anything outside `tmp_path`. `test_server.py`'s autouse `_reset_globals` and `test_cli.py`'s `_isolated_config` redirect **both** `AGENT_DISPATCH_CONFIG` and `AGENT_DISPATCH_JOBS_DIR`: a mutation tool that bails out early (unknown agent) still takes `config_lock()` first, which would otherwise create a lock file beside the developer's real config.
 
+- `mcp` is pinned **`>=1.2.0,<2`** deliberately: 2.0 removed `mcp.server.fastmcp`, which `server.py` imports, so an unbounded range gives every fresh install a dead `agent-dispatch serve`. Lifting the cap means porting to `mcp.server.mcpserver.MCPServer` — it is not a dependency bump.
+- Verify packaging in a **clean venv**, never the dev machine: build the wheel, install it fresh, import the server. A stale pin in local site-packages hides exactly the failure a new user hits first.
+- Run **`twine check dist/*`** before cutting the tag, with a *current* twine. The clean-venv check does not cover this: it proves the wheel installs, not that PyPI's uploader will accept its metadata. `python -m build` pulls the newest hatchling at build time, so the emitted `Metadata-Version` climbs on its own, and `pypa/gh-action-pypi-publish` is pinned to a SHA that bundles a fixed twine — v0.13.0's publish failed on exactly that mismatch (hatchling 1.32 → metadata 2.5; pinned twine 6.1.0 → "not a valid metadata version"). When it happens, bump the action pin rather than pinning the backend down.
+
 ## Deliberately not built
 
 These were considered — some fully implemented — and cut on purpose: an agent router / auto-dispatch (`recommend_agent` / `dispatch_auto`, removed before 0.8.0 — a keyword scorer adds little over the calling LLM at a handful of agents, and auto-dispatch can spend money or mutate a repo on a guess); groups as an execution engine (they are a descriptive layer — no routing, no per-group settings); an agent-dispatch-side budget ledger across dispatches (the CLI's own `--max-budget-usd` covers a single run; anything cumulative would need state we deliberately don't keep). Please open an issue with the use case before adding any of them.

{agent_dispatch-0.12.1 → agent_dispatch-0.13.0}/CHANGELOG.md

@@ -7,6 +7,89 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.13.0] - 2026-08-13
+
+An efficiency round, measured against a real 38 KB config (4 agents, 6 groups),
+a 294-record jobs directory and 14 concurrently running servers — not against
+synthetic fixtures. Findings came from a five-axis audit (caller context,
+latency/IO, spend, CPU, concurrency) whose every claim was re-measured
+adversarially before implementation; most were confirmed as real but too small
+to matter next to a 10–120 s subprocess and were deliberately left alone.
+
+### Changed
+- **Tool responses no longer escape non-ASCII, cutting discovery payloads
+  roughly in half.** `json.dumps` defaults to `ensure_ascii=True`, so every
+  Cyrillic character left as a `\uXXXX` escape — 6 bytes for what UTF-8 stores
+  in 2, and a far worse token sequence. One `list_groups()` carried **8520**
+  such escapes: 59 KB where 25 KB was enough. Measured over a full discovery
+  pass (`list_agents` + `list_groups` + `inspect_group` + `inspect_agent`):
+  104 KB → 51 KB, about **13 000 tokens saved per pass**, on every call, in
+  every session. Nothing is lost: the stdio transport serializes the JSON-RPC
+  envelope with pydantic's `model_dump_json`, which already emits raw UTF-8 —
+  which is also why the `dispatch` family never had this problem while every
+  `json.dumps` tool did. All 57 call sites now go through one `_dumps` helper
+  so the two agree. `_dumps` probes encodability and falls back to the escaped
+  form for the one payload that needs it — a **lone surrogate**, which an agent
+  produces by printing a literal `\udXXX` escape in its JSON output (`json.loads`
+  manufactures it from perfectly ASCII input, so the subprocess-level
+  `errors="replace"` cannot help). Unescaped it would raise `UnicodeEncodeError`
+  inside the stdio transport *after* the tool returned — past every guard.
+  The saving is proportional to how much non-ASCII your config and results
+  carry: on an all-ASCII setup it is exactly zero.
+- **`agents.yaml` parses ~13x faster.** The config is re-read on every single
+  tool call (deliberately — that is how a new agent is picked up without a
+  restart), so the parse sits on the hot path of all 21 tools *and* runs on the
+  event-loop thread, where it blocks every other tool. Switching to libyaml's
+  `CSafeLoader` takes the real config from **9.80 ms to 0.76 ms** per call.
+  Falls back to the pure-Python safe loader when PyYAML was built without
+  libyaml; both are the *safe* loader, so a config still cannot construct
+  arbitrary objects.
+
+### Added
+- **`settings.job_retention_days`** — when > 0, terminal job records older than
+  N days are deleted at server start. Every async dispatch and every
+  `return_ref` dispatch leaves a job file that nothing removed on its own, so
+  the directory grew forever while `dispatch_jobs` and stale-job recovery
+  parsed every file in it. **Defaults to `0` (off)**: those records are the
+  user's own dispatch history and deleting them is irreversible, so it is an
+  explicit opt-in rather than something a version bump starts doing to an
+  existing install. An unreadable config is treated as `0`, never guessed.
+
+### Fixed
+- **`max_concurrency` bounds live subprocesses again, not live coroutines.**
+  `async with sem:` released the slot when the *coroutine* unwound, but
+  cancelling a coroutine does not stop the thread behind `asyncio.to_thread` —
+  so an interrupted turn or a closed session handed the slot to the next
+  dispatch while the `claude` subprocess kept running and kept being billed. N
+  cancellations meant up to N extra concurrent subprocesses, and each abandoned
+  worker also held a thread out of the default executor (`min(32, cpu_count+4)`,
+  which `to_thread` needs for *every* dispatch) for the rest of its timeout —
+  up to 7200s. The slot is now tied to the worker's real lifetime via
+  `_dispatch_guarded`; cancellation still reaches the caller immediately.
+- **A legitimately long dispatch is no longer flipped to `failed` by an
+  unrelated server starting up.** `recover_stale` judged abandonment from
+  `started_at` alone, but a dispatch may legitimately run up to the 7200s
+  timeout ceiling — so any of the (routinely 14+) other servers booting would
+  mark a live 2-hour job `failed`, after which `finish()` refuses the real,
+  already-paid-for result. A *running* job whose file was modified within the
+  threshold is now left alone: a live worker rewrites it on every progress
+  flush, so only the file's own age proves abandonment. This can only ever skip
+  a recovery — a genuinely abandoned job is picked up on a later start.
+- **A config that cannot be *rendered* now returns an error envelope instead of
+  a traceback.** `_get_config` wraps read-side YAML failures into
+  `ConfigLoadError`, but `save_config` → `yaml.dump` raises `RepresenterError` —
+  a `yaml.YAMLError`, so neither an `OSError` nor a `ConfigLoadError`. It
+  therefore slipped past *both* arms of the MCP guard on
+  `add_agent`/`update_agent`/`remove_agent` **and** past the CLI's
+  `_save_or_exit`. Unreachable today (only JSON-native types are ever dumped)
+  and closed now because it is the same "an exception type escapes the handler
+  meant to catch it" class that produced the 0.12.0 and 0.12.1 rounds. The set
+  is declared once as `config.CONFIG_SAVE_ERRORS`, next to its read-side twin,
+  so the two surfaces cannot drift.
+- **Stale-job recovery scans the jobs directory once instead of twice.** It
+  called `list()` per status, and `list()` reads and parses every file in the
+  directory (~85 ms at 294 records) — at the start of every server process.
+
 ## [0.12.1] - 2026-07-30
 
 Two holes in 0.12.0's own "tools always return a clean error" fix.

{agent_dispatch-0.12.1 → agent_dispatch-0.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: agent-dispatch
-Version: 0.12.1
+Version: 0.13.0
 Summary: MCP server that lets Claude Code agents delegate tasks to agents in other project directories
 Project-URL: Homepage, https://github.com/ginkida/agent-dispatch
 Project-URL: Repository, https://github.com/ginkida/agent-dispatch
@@ -574,6 +574,7 @@ settings:
   #   - Edit
   max_dispatch_depth: 3     # recursion protection
   max_concurrency: 5        # max parallel claude -p processes (per dispatch path)
+  # job_retention_days: 30  # 0 (default) = never prune. See "Job retention" below.
   cache:
     enabled: true
     ttl: 300                # seconds
@@ -582,6 +583,30 @@ settings:
 
 Config is reloaded on every tool call — add agents without restarting.
 
+### Job retention
+
+Every `dispatch_async` **and** every `dispatch(..., return_ref=True)` writes a
+record to `~/.config/agent-dispatch/jobs/`, and nothing deletes it on its own —
+`dispatch_gc` has to be run by hand. The directory therefore grows without
+bound, and `dispatch_jobs` plus the stale-job recovery that runs at every server
+start read and parse *every* file in it.
+
+Set `job_retention_days` to prune terminal (done/failed/cancelled) records older
+than N days when a server starts:
+
+```yaml
+settings:
+  job_retention_days: 30
+```
+
+It defaults to `0` — **off** — because those records are your own history of
+past dispatches and deleting them cannot be undone. Pending and running jobs are
+never touched.
+
+`agent-dispatch gc --days N` and the `dispatch_gc` tool apply the same rule as a
+one-off. Both *delete* immediately and report the count; neither previews, so
+check what is there first with `agent-dispatch jobs`.
+
 ### Auto-Description
 
 `agent-dispatch add` without `--description` generates one from:

{agent_dispatch-0.12.1 → agent_dispatch-0.13.0}/README.md

@@ -544,6 +544,7 @@ settings:
   #   - Edit
   max_dispatch_depth: 3     # recursion protection
   max_concurrency: 5        # max parallel claude -p processes (per dispatch path)
+  # job_retention_days: 30  # 0 (default) = never prune. See "Job retention" below.
   cache:
     enabled: true
     ttl: 300                # seconds
@@ -552,6 +553,30 @@ settings:
 
 Config is reloaded on every tool call — add agents without restarting.
 
+### Job retention
+
+Every `dispatch_async` **and** every `dispatch(..., return_ref=True)` writes a
+record to `~/.config/agent-dispatch/jobs/`, and nothing deletes it on its own —
+`dispatch_gc` has to be run by hand. The directory therefore grows without
+bound, and `dispatch_jobs` plus the stale-job recovery that runs at every server
+start read and parse *every* file in it.
+
+Set `job_retention_days` to prune terminal (done/failed/cancelled) records older
+than N days when a server starts:
+
+```yaml
+settings:
+  job_retention_days: 30
+```
+
+It defaults to `0` — **off** — because those records are your own history of
+past dispatches and deleting them cannot be undone. Pending and running jobs are
+never touched.
+
+`agent-dispatch gc --days N` and the `dispatch_gc` tool apply the same rule as a
+one-off. Both *delete* immediately and report the count; neither previews, so
+check what is there first with `agent-dispatch jobs`.
+
 ### Auto-Description
 
 `agent-dispatch add` without `--description` generates one from:

{agent_dispatch-0.12.1 → agent_dispatch-0.13.0}/agents.example.yaml

@@ -100,6 +100,12 @@ settings:
   #   - Bash
   #   - Read
   #   - Edit
+  # job_retention_days: 30         # OFF by default (0). When > 0, terminal job records
+                                   # older than this are deleted at server start. Every
+                                   # async and every return_ref dispatch leaves a job
+                                   # file behind and nothing removes it otherwise, so
+                                   # the directory grows forever — but the records are
+                                   # your dispatch history, so pruning is opt-in.
   cache:
     enabled: true
     ttl: 300                       # seconds; identical (agent, task, context) requests are cached

{agent_dispatch-0.12.1 → agent_dispatch-0.13.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agent-dispatch"
-version = "0.12.1"
+version = "0.13.0"
 description = "MCP server that lets Claude Code agents delegate tasks to agents in other project directories"
 readme = "README.md"
 license = "MIT"

{agent_dispatch-0.12.1 → agent_dispatch-0.13.0}/src/agent_dispatch/__init__.py

@@ -1,3 +1,3 @@
 """agent-dispatch: Delegate tasks between Claude Code agents across projects."""
 
-__version__ = "0.12.1"
+__version__ = "0.13.0"

{agent_dispatch-0.12.1 → agent_dispatch-0.13.0}/src/agent_dispatch/cli.py

@@ -13,7 +13,14 @@ import click
 import yaml
 from pydantic import ValidationError
 
-from .config import auto_describe, config_lock, config_path, load_config, save_config
+from .config import (
+    CONFIG_SAVE_ERRORS,
+    auto_describe,
+    config_lock,
+    config_path,
+    load_config,
+    save_config,
+)
 from .jobs import JobStore, default_jobs_dir, is_valid_job_id
 from .models import (
     AgentConfig,
@@ -48,6 +55,18 @@ def _save_or_exit(config: DispatchConfig) -> None:
             )
         )
         raise SystemExit(1) from None
+    except CONFIG_SAVE_ERRORS as e:
+        # A value YAML cannot represent — not an OSError, so the arm above never
+        # saw it and it escaped as a traceback. See config.CONFIG_SAVE_ERRORS.
+        click.echo(
+            click.style(
+                f"Error: could not serialize the config to YAML: {e}\n"
+                "Nothing was changed — the previous config is intact. "
+                "This is a bug: please report the field that failed.",
+                fg="red",
+            )
+        )
+        raise SystemExit(1) from None
 
 
 def _check_budget_or_exit(max_budget: float | None) -> None:

{agent_dispatch-0.12.1 → agent_dispatch-0.13.0}/src/agent_dispatch/config.py

@@ -22,6 +22,19 @@ try:  # pragma: no cover - platform dependent
 except ImportError:  # pragma: no cover - Windows has no fcntl
     fcntl = None  # type: ignore[assignment]
 
+# Parse with libyaml when PyYAML was built against it. Every MCP tool call
+# reloads agents.yaml from scratch (deliberately — that is how a new agent is
+# picked up without a restart), so this parse is on the hot path of all 21
+# tools. On a real 38 KB config the pure-Python SafeLoader takes ~9.8 ms and
+# CSafeLoader ~0.6 ms: a 16x saving repeated on every single call, and it runs
+# on the event-loop thread where it blocks every other tool. The fallback is
+# mandatory — a PyYAML installed from source without libyaml headers has no
+# C extension. Same semantics either way: both are the *safe* loader.
+try:  # pragma: no cover - depends on how PyYAML was built
+    from yaml import CSafeLoader as _YamlLoader
+except ImportError:  # pragma: no cover - pure-Python PyYAML
+    from yaml import SafeLoader as _YamlLoader  # type: ignore[assignment]
+
 logger = logging.getLogger(__name__)
 
 DEFAULT_CONFIG_DIR = Path.home() / ".config" / "agent-dispatch"
@@ -158,13 +171,29 @@ def file_lock(path: Path) -> Iterator[None]:
 # UTF-16 used to escape every one of them as a raw traceback.
 CONFIG_LOAD_ERRORS = (ValidationError, yaml.YAMLError, UnicodeDecodeError, OSError)
 
+# The *write* half, and deliberately not a copy of the read half. `save_config`
+# can fail two ways with two different remediations: OSError (full disk,
+# read-only volume — handled separately, and the atomic rename means the old
+# file survives), or a rendering failure. `yaml.dump` raises RepresenterError —
+# a `yaml.YAMLError`, so neither an OSError nor a ValueError — for any value it
+# cannot represent. That is unreachable today because save_config only ever
+# feeds it `model_dump(mode="json")` output, i.e. JSON-native types. It becomes
+# reachable the moment a field lands whose JSON dump is not one of those, and it
+# would then escape *both* server guards and the CLI's `_save_or_exit` as a raw
+# traceback — the exact "an exception type escapes the handler meant to catch
+# it" class this codebase has been bitten by twice. Declared once, next to its
+# read-side twin, so the two surfaces that handle it cannot drift.
+CONFIG_SAVE_ERRORS = (yaml.YAMLError,)
+
 
 def load_config(path: Path | None = None) -> DispatchConfig:
     """Load config from YAML file. Returns empty config if file missing."""
     p = path or config_path()
     if not p.exists():
         return DispatchConfig()
-    raw = yaml.safe_load(p.read_text(encoding="utf-8"))
+    # yaml.load with the safe loader == yaml.safe_load; _YamlLoader is the C
+    # one when available (see its definition for why this is worth doing).
+    raw = yaml.load(p.read_text(encoding="utf-8"), Loader=_YamlLoader)  # noqa: S506
     if raw is None:
         return DispatchConfig()
     return DispatchConfig.model_validate(raw)

{agent_dispatch-0.12.1 → agent_dispatch-0.13.0}/src/agent_dispatch/jobs.py

@@ -286,6 +286,17 @@ class JobStore:
     # real queue wait reaches instead of the running-job one.
     _PENDING_STALE_MULTIPLIER = 24
 
+    def _touched_after(self, job_id: str, cutoff: float) -> bool:
+        """True if the job file's mtime is newer than *cutoff* (someone is live).
+
+        Best-effort: an unreadable or vanished file reports False so recovery
+        falls back to the timestamp check rather than skipping silently.
+        """
+        try:
+            return self._path(job_id).stat().st_mtime > cutoff
+        except (OSError, ValueError):  # pragma: no cover - racing unlink
+            return False
+
     def recover_stale(self, stale_threshold_seconds: float = 3600) -> int:
         """Mark jobs abandoned in 'running' or 'pending' beyond the threshold as failed.
 
@@ -307,14 +318,35 @@ class JobStore:
         recovered = 0
         stale: list[tuple[Job, float, str]] = []
         with self._lock:
-            for job in self.list(status="running"):
-                age = now - (job.started_at or job.created_at)
-                if age > stale_threshold_seconds:
-                    stale.append((job, age, "running"))
-            for job in self.list(status="pending"):
-                age = now - job.created_at
-                if age > pending_threshold:
-                    stale.append((job, age, "pending"))
+            # ONE scan, not one per status. list() reads and json-parses every
+            # file in the directory (~85ms for 300 jobs), and this runs at the
+            # start of every `serve` process — of which there is one per open
+            # Claude Code session, routinely 14+.
+            for job in self.list():
+                if job.status == "running":
+                    age = now - (job.started_at or job.created_at)
+                    if age <= stale_threshold_seconds:
+                        continue
+                    # `started_at` alone does not prove abandonment: a dispatch
+                    # may legitimately run up to the 7200s timeout ceiling, so
+                    # any other server starting up would flip a live 2-hour job
+                    # to 'failed' — and finish() then refuses it, losing an
+                    # already-paid-for result. A live worker rewrites the file
+                    # at least once per progress interval, so a recently
+                    # *modified* file means someone is still on it. This can
+                    # only ever skip a recovery (a genuinely abandoned job is
+                    # picked up on a later start), never add one. Only 'running'
+                    # gets this check: nothing rewrites a pending job's file, so
+                    # there its mtime is just created_at by another name.
+                    if self._touched_after(job.id, now - stale_threshold_seconds):
+                        continue
+                elif job.status == "pending":
+                    age = now - job.created_at
+                    if age <= pending_threshold:
+                        continue
+                else:
+                    continue
+                stale.append((job, age, job.status))
             for job, age, state in stale:
                 # Count only jobs we actually transitioned (fail() returns
                 # None for a missing/malformed id, e.g. a planted file).

{agent_dispatch-0.12.1 → agent_dispatch-0.13.0}/src/agent_dispatch/models.py

@@ -97,6 +97,16 @@ class Settings(BaseModel):
     max_dispatch_depth: int = Field(default=3, ge=1)
     max_concurrency: int = Field(default=5, ge=1)
     cache: CacheSettings = Field(default_factory=CacheSettings)
+    # Opt-in retention sweep: when > 0, terminal jobs older than this many days
+    # are deleted at server start. Every async dispatch AND every return_ref
+    # dispatch writes a job file that nothing removes on its own — dispatch_gc
+    # has to be called by hand — so the directory only ever grows, and
+    # JobStore.list() (dispatch_jobs, stale-job recovery) parses every file in
+    # it. Defaults to 0 (**off**) on purpose: job records are the user's own
+    # history of past dispatches, and deleting them is not reversible, so it
+    # must be an explicit choice rather than something a version bump starts
+    # doing to an existing install.
+    job_retention_days: int = Field(default=0, ge=0)
 
 
 def validate_agent_name(name: str) -> str: