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

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

@@ -28,7 +28,7 @@ pip install -e ".[dev]"
 
 ```bash
 ruff check src/ tests/
-python3 -m pytest tests/ -v   # 561 tests, ~4s
+python3 -m pytest tests/ -v   # 578 tests, ~5s
 ```
 
 Tests must **never** invoke the real `claude` CLI. Runner tests mock `shutil.which` + `subprocess.run`/`Popen`; server tests mock `_get_config` + `runner.dispatch`. The one exception is `TestStreamPipeHandling`, which spawns a short-lived *python* subprocess: a pipe deadlock lives in the OS pipe buffer, so a mocked `Popen` structurally cannot reproduce it.
@@ -58,7 +58,7 @@ Tests must **never** invoke the real `claude` CLI. Runner tests mock `shutil.whi
 - 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.
-- MCP tools that load config carry `@_config_guard` under `@mcp.tool()` so a broken `agents.yaml` returns the `{"error": ...}` envelope instead of a raw traceback.
+- 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.
 
@@ -76,4 +76,4 @@ Python ≥ 3.10 · `from __future__ import annotations` everywhere · Pydantic v
 
 ## More detail
 
-[README.md](README.md) documents every MCP tool with parameter tables, response shapes, and the error-recovery map — it doubles as the behavioral spec. The test suite (`tests/`, 561 tests) encodes the exact expected behavior of every layer: when in doubt, read the tests for the module you're touching (`test_runner.py`, `test_server.py`, `test_cli.py`, ...).
+[README.md](README.md) documents every MCP tool with parameter tables, response shapes, and the error-recovery map — it doubles as the behavioral spec. The test suite (`tests/`, 578 tests) encodes the exact expected behavior of every layer: when in doubt, read the tests for the module you're touching (`test_runner.py`, `test_server.py`, `test_cli.py`, ...).

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

@@ -7,6 +7,51 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.12.1] - 2026-07-30
+
+Two holes in 0.12.0's own "tools always return a clean error" fix.
+
+### Fixed
+- **A non-UTF-8 `agents.yaml` no longer crashes every surface.** `UnicodeDecodeError`
+  is a `ValueError`, not an `OSError`, so a config saved as cp1251/UTF-16 slipped
+  past all three handlers added in 0.12.0 and raised a bare traceback out of every
+  MCP tool, `agent-dispatch list` — and `doctor`, the command you run *because*
+  the config is broken. The set of load errors is now declared once
+  (`config.CONFIG_LOAD_ERRORS`) and shared by all three, and `doctor` reports the
+  encoding (and an unreadable file) as a normal FAIL with a fix. The shared set
+  lives in `config.CONFIG_LOAD_ERRORS`; the CLI still branches per type because
+  each one deserves a different remediation line.
+- **An undecodable byte from the `claude` CLI no longer kills a paid-for
+  dispatch.** `text=True` decodes strictly, so one invalid byte on stdout raised
+  `UnicodeDecodeError` — a `ValueError`, caught by nothing in the runner — out of
+  `dispatch`, `dispatch_stream`, the MCP tools and `agent-dispatch test`. Both
+  spawn sites now decode with `errors="replace"`, so a mangled byte becomes
+  U+FFFD instead of discarding the run. (Present since the initial commit.)
+- **`dispatch` classifies spawn failures like `dispatch_stream` already did.**
+  A directory that passes `is_dir()` but cannot be entered — or that vanishes
+  between the check and the spawn — made `subprocess.run` raise straight through
+  the `except subprocess.TimeoutExpired`. It now returns `not_found` /
+  `permission` / `cli_error` like the streaming path.
+- **The six job tools got the I/O envelope too.** `dispatch_status`, `_wait`,
+  `_cancel`, `_jobs`, `fetch_result` and `dispatch_gc` never load config, so they
+  carried no guard — an unwritable or misconfigured jobs directory raised out of
+  them. The guard is now split (`_io_guard` / `_config_guard`) and both halves
+  are applied where each is needed.
+- **`add_agent` reports an unresolvable path** (`~unknown-user`) as an error
+  envelope instead of raising `RuntimeError`.
+- **A failed config *write* is reported, not raised.** The same contract had the
+  other half missing: a full disk or a read-only volume made `save_config`
+  raise OSError straight out of `add_agent`/`update_agent`/`remove_agent` and out
+  of the matching CLI commands. Both surfaces now report it — the CLI adds that
+  the previous config is intact, which the atomic write guarantees.
+
+### Changed
+- Docs corrected against the code: stale-job recovery now documents the
+  `pending` sweep and its 24h threshold; the config-lock guarantee is stated as
+  best-effort (it proceeds unlocked after 10s rather than freezing the server);
+  `add_agent(timeout=0)` documents that it stores the literal 300, not
+  `settings.default_timeout`.
+
 ## [0.12.0] - 2026-07-29
 
 Reliability pass over the streaming path, config durability, and the tool
@@ -546,7 +591,8 @@ cache bounding, and stale-job recovery.
 - Dependabot for `pip` + `github-actions`, GitHub Actions pinned to
   commit SHAs for supply-chain integrity.
 
-[Unreleased]: https://github.com/ginkida/agent-dispatch/compare/v0.12.0...HEAD
+[Unreleased]: https://github.com/ginkida/agent-dispatch/compare/v0.12.1...HEAD
+[0.12.1]: https://github.com/ginkida/agent-dispatch/compare/v0.12.0...v0.12.1
 [0.12.0]: https://github.com/ginkida/agent-dispatch/compare/v0.11.0...v0.12.0
 [0.11.0]: https://github.com/ginkida/agent-dispatch/compare/v0.10.0...v0.11.0
 [0.10.0]: https://github.com/ginkida/agent-dispatch/compare/v0.9.0...v0.10.0

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-dispatch
-Version: 0.12.0
+Version: 0.12.1
 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
@@ -388,8 +388,8 @@ Register a new project directory as an agent. Description is auto-generated from
 | `name` | string | yes | Agent name (letters, digits, hyphens, underscores) |
 | `directory` | string | yes | Path to an existing project directory (`~` is expanded, relative paths resolved) |
 | `description` | string | no | What this agent can do — auto-generated if empty |
-| `timeout` | int | no | Timeout in seconds (0 = use global default) |
-| `max_budget_usd` | float | no | Max cost in USD per dispatch (0 = no limit) |
+| `timeout` | int | no | Timeout in seconds (0 = 300; this is a literal default, not `settings.default_timeout`) |
+| `max_budget_usd` | float | no | Max cost in USD per dispatch (0 = inherit `settings.default_max_budget_usd`; no cap only when that is unset too) |
 | `permission_mode` | string | no | Permission mode (e.g. `default`, `plan`, `bypassPermissions`) |
 | `allowed_tools` | string | no | Comma-separated allowed tools (e.g. `"Bash,Read,Edit"`) |
 | `disallowed_tools` | string | no | Comma-separated disallowed tools |
@@ -405,7 +405,7 @@ Update an existing agent's configuration. Only non-empty fields are changed. Pas
 | `name` | string | yes | Agent name to update |
 | `description` | string | no | New description |
 | `timeout` | int | no | New timeout (0 = don't change) |
-| `max_budget_usd` | float | no | New budget limit (0 = don't change, negative = clear the limit) |
+| `max_budget_usd` | float | no | New budget limit (0 = don't change; negative clears the *per-agent* cap, after which `settings.default_max_budget_usd` applies) |
 | `model` | string | no | Model override. `"none"` to clear |
 | `permission_mode` | string | no | Permission mode. `"none"` to clear |
 | `allowed_tools` | string | no | Comma-separated. `"none"` to clear |
@@ -474,7 +474,7 @@ Async workers run with streaming under the hood: the job file keeps a rolling ta
 
 `dispatch_jobs(status?)` lists recent jobs as summaries (filter by `pending` / `running` / `done` / `failed` / `cancelled`). `dispatch_gc(max_age_days=7)` purges terminal jobs older than the threshold — pending and running jobs are never deleted.
 
-Job state persists to disk at `~/.config/agent-dispatch/jobs/` (override with `AGENT_DISPATCH_JOBS_DIR`). One JSON file per job, written owner-only (`0o600`) with atomic writes — safe to read or `ls` while jobs are in flight. Caller-supplied `job_id`s are validated as 32-char hex before any file access (no path traversal). On startup the server marks jobs left in `running` by a crashed instance as `failed` once they are stale (stuck for over an hour).
+Job state persists to disk at `~/.config/agent-dispatch/jobs/` (override with `AGENT_DISPATCH_JOBS_DIR`). One JSON file per job, written owner-only (`0o600`) with atomic writes — safe to read or `ls` while jobs are in flight. Caller-supplied `job_id`s are validated as 32-char hex before any file access (no path traversal). On startup the server recovers jobs a crashed instance abandoned: `running` ones stuck over an hour, and `pending` ones over 24 hours, are marked `failed` so they stop being polled forever and become collectable by `dispatch_gc`. (The `pending` threshold is deliberately long — the jobs directory is shared by every running server, so a job queued behind another server's concurrency limit must not be swept.)
 
 | When to use async | When to use `dispatch` |
 |-------------------|------------------------|
@@ -635,7 +635,7 @@ agent-dispatch MCP server
 - **Concurrency** — `max_concurrency` (default: 5) caps parallel `claude -p` processes. Note: the sync and async dispatch paths use separate semaphores, so the worst-case total is `2 × max_concurrency`.
 - **Timeout** — per-agent or global (default: 300s). A streaming dispatch runs the agent in its own process group, so the deadline kills the whole tree: a process the agent left running in the background can't hold the dispatch (and its concurrency slot) open past the timeout.
 - **Caching** — identical `(agent, task, context, caller, goal, response_format)` requests return cached results, bounded by `cache.max_size` (oldest entry evicted first). Only clean successes are cached: failures, results with `denied_tools`, and results flagged `budget_exceeded` are not, so the documented "grant access / raise the cap, then re-dispatch" recovery is never served a stale crippled answer. Changing an agent's config invalidates its entries. Sessions and dialogues are never cached. A `group=` dispatch folds the group's `shared_context` into `context`, so different groups cache separately and a plain dispatch is unaffected.
-- **Durable config** — `agents.yaml` is written atomically (temp file + rename), and every mutation path (CLI and MCP server alike) holds a cross-process advisory lock, so concurrent edits cannot truncate the file or silently drop one another's agents.
+- **Durable config** — `agents.yaml` is written atomically (temp file + rename), so an interrupted write can never truncate it. Every mutation path (CLI and MCP server alike) also takes a cross-process advisory lock, so concurrent edits don't drop one another's agents. The lock is best-effort by design: after waiting 10 seconds it logs a warning and proceeds anyway, because a wedged lock holder must not freeze the MCP server — so on a heavily contended config a lost update is possible, while a truncated one is not.
 
 See [SECURITY.md](SECURITY.md) for the full threat model (including the `bypassPermissions` escalation risk and on-disk job files).
 

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

@@ -358,8 +358,8 @@ Register a new project directory as an agent. Description is auto-generated from
 | `name` | string | yes | Agent name (letters, digits, hyphens, underscores) |
 | `directory` | string | yes | Path to an existing project directory (`~` is expanded, relative paths resolved) |
 | `description` | string | no | What this agent can do — auto-generated if empty |
-| `timeout` | int | no | Timeout in seconds (0 = use global default) |
-| `max_budget_usd` | float | no | Max cost in USD per dispatch (0 = no limit) |
+| `timeout` | int | no | Timeout in seconds (0 = 300; this is a literal default, not `settings.default_timeout`) |
+| `max_budget_usd` | float | no | Max cost in USD per dispatch (0 = inherit `settings.default_max_budget_usd`; no cap only when that is unset too) |
 | `permission_mode` | string | no | Permission mode (e.g. `default`, `plan`, `bypassPermissions`) |
 | `allowed_tools` | string | no | Comma-separated allowed tools (e.g. `"Bash,Read,Edit"`) |
 | `disallowed_tools` | string | no | Comma-separated disallowed tools |
@@ -375,7 +375,7 @@ Update an existing agent's configuration. Only non-empty fields are changed. Pas
 | `name` | string | yes | Agent name to update |
 | `description` | string | no | New description |
 | `timeout` | int | no | New timeout (0 = don't change) |
-| `max_budget_usd` | float | no | New budget limit (0 = don't change, negative = clear the limit) |
+| `max_budget_usd` | float | no | New budget limit (0 = don't change; negative clears the *per-agent* cap, after which `settings.default_max_budget_usd` applies) |
 | `model` | string | no | Model override. `"none"` to clear |
 | `permission_mode` | string | no | Permission mode. `"none"` to clear |
 | `allowed_tools` | string | no | Comma-separated. `"none"` to clear |
@@ -444,7 +444,7 @@ Async workers run with streaming under the hood: the job file keeps a rolling ta
 
 `dispatch_jobs(status?)` lists recent jobs as summaries (filter by `pending` / `running` / `done` / `failed` / `cancelled`). `dispatch_gc(max_age_days=7)` purges terminal jobs older than the threshold — pending and running jobs are never deleted.
 
-Job state persists to disk at `~/.config/agent-dispatch/jobs/` (override with `AGENT_DISPATCH_JOBS_DIR`). One JSON file per job, written owner-only (`0o600`) with atomic writes — safe to read or `ls` while jobs are in flight. Caller-supplied `job_id`s are validated as 32-char hex before any file access (no path traversal). On startup the server marks jobs left in `running` by a crashed instance as `failed` once they are stale (stuck for over an hour).
+Job state persists to disk at `~/.config/agent-dispatch/jobs/` (override with `AGENT_DISPATCH_JOBS_DIR`). One JSON file per job, written owner-only (`0o600`) with atomic writes — safe to read or `ls` while jobs are in flight. Caller-supplied `job_id`s are validated as 32-char hex before any file access (no path traversal). On startup the server recovers jobs a crashed instance abandoned: `running` ones stuck over an hour, and `pending` ones over 24 hours, are marked `failed` so they stop being polled forever and become collectable by `dispatch_gc`. (The `pending` threshold is deliberately long — the jobs directory is shared by every running server, so a job queued behind another server's concurrency limit must not be swept.)
 
 | When to use async | When to use `dispatch` |
 |-------------------|------------------------|
@@ -605,7 +605,7 @@ agent-dispatch MCP server
 - **Concurrency** — `max_concurrency` (default: 5) caps parallel `claude -p` processes. Note: the sync and async dispatch paths use separate semaphores, so the worst-case total is `2 × max_concurrency`.
 - **Timeout** — per-agent or global (default: 300s). A streaming dispatch runs the agent in its own process group, so the deadline kills the whole tree: a process the agent left running in the background can't hold the dispatch (and its concurrency slot) open past the timeout.
 - **Caching** — identical `(agent, task, context, caller, goal, response_format)` requests return cached results, bounded by `cache.max_size` (oldest entry evicted first). Only clean successes are cached: failures, results with `denied_tools`, and results flagged `budget_exceeded` are not, so the documented "grant access / raise the cap, then re-dispatch" recovery is never served a stale crippled answer. Changing an agent's config invalidates its entries. Sessions and dialogues are never cached. A `group=` dispatch folds the group's `shared_context` into `context`, so different groups cache separately and a plain dispatch is unaffected.
-- **Durable config** — `agents.yaml` is written atomically (temp file + rename), and every mutation path (CLI and MCP server alike) holds a cross-process advisory lock, so concurrent edits cannot truncate the file or silently drop one another's agents.
+- **Durable config** — `agents.yaml` is written atomically (temp file + rename), so an interrupted write can never truncate it. Every mutation path (CLI and MCP server alike) also takes a cross-process advisory lock, so concurrent edits don't drop one another's agents. The lock is best-effort by design: after waiting 10 seconds it logs a warning and proceeds anyway, because a wedged lock holder must not freeze the MCP server — so on a heavily contended config a lost update is possible, while a truncated one is not.
 
 See [SECURITY.md](SECURITY.md) for the full threat model (including the `bypassPermissions` escalation risk and on-disk job files).
 

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

@@ -1,6 +1,6 @@
 [project]
 name = "agent-dispatch"
-version = "0.12.0"
+version = "0.12.1"
 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.0 → agent_dispatch-0.12.1}/src/agent_dispatch/__init__.py

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

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

@@ -29,6 +29,27 @@ def _parse_csv(value: str | None) -> list[str] | None:
     return [t.strip() for t in value.split(",") if t.strip()] if value else None
 
 
+def _save_or_exit(config: DispatchConfig) -> None:
+    """Persist the config, turning an I/O failure into a message, not a traceback.
+
+    A full disk or a read-only volume makes `save_config` raise OSError. The
+    write is atomic, so the previous config survives — say so, since that is the
+    one thing the user needs to know.
+    """
+    try:
+        save_config(config)
+    except OSError as e:
+        click.echo(
+            click.style(
+                f"Error: could not write {config_path()}: {e}\n"
+                "Nothing was changed — the previous config is intact "
+                "(the write is atomic). Check free space and permissions.",
+                fg="red",
+            )
+        )
+        raise SystemExit(1) from None
+
+
 def _check_budget_or_exit(max_budget: float | None) -> None:
     """Reject a negative spend cap before it reaches `AgentConfig` (ge=0).
 
@@ -75,6 +96,15 @@ def _load_or_exit() -> DispatchConfig:
         click.echo(click.style(f"Error: config at {config_path()} is not valid YAML:", fg="red"))
         click.echo(str(e))
         raise SystemExit(1) from None
+    except UnicodeDecodeError as e:
+        click.echo(
+            click.style(
+                f"Error: config at {config_path()} is not valid UTF-8 (re-save it as UTF-8):",
+                fg="red",
+            )
+        )
+        click.echo(str(e))
+        raise SystemExit(1) from None
     except OSError as e:
         click.echo(click.style(f"Error: config at {config_path()} could not be read:", fg="red"))
         click.echo(str(e))
@@ -236,7 +266,7 @@ def add(
         if warning := check_permission_mode(permission_mode):
             click.echo(click.style(f"Warning: {warning}", fg="yellow"))
 
-        save_config(config)
+        _save_or_exit(config)
     click.echo(f"Added agent '{name}' -> {dir_path}")
 
 
@@ -251,7 +281,7 @@ def remove(name: str) -> None:
             raise SystemExit(1)
 
         del config.agents[name]
-        save_config(config)
+        _save_or_exit(config)
     click.echo(f"Removed agent '{name}'.")
 
 
@@ -381,7 +411,7 @@ def update(
             click.echo("Nothing to update. Pass at least one option (see --help).")
             raise SystemExit(1)
 
-        save_config(config)
+        _save_or_exit(config)
     click.echo(f"Updated agent '{name}': {', '.join(updated)}")
 
 
@@ -639,7 +669,7 @@ def group_add(name: str, description: str, shared_context: str, members: tuple[s
             shared_context=shared_context,
             members=member_objs,
         )
-        save_config(config)
+        _save_or_exit(config)
     click.echo(f"Added group '{name}' ({len(member_objs)} member(s)).")
     if not member_objs:
         click.echo(
@@ -737,7 +767,7 @@ def group_update(name: str, description: str | None, shared_context: str | None)
             click.echo("Nothing to update. Pass --description and/or --shared-context.")
             raise SystemExit(1)
 
-        save_config(config)
+        _save_or_exit(config)
     click.echo(f"Updated group '{name}': {', '.join(updated)}")
 
 
@@ -752,7 +782,7 @@ def group_remove(name: str) -> None:
             raise SystemExit(1)
 
         del config.groups[name]
-        save_config(config)
+        _save_or_exit(config)
     click.echo(f"Removed group '{name}'.")
 
 
@@ -807,6 +837,15 @@ def doctor() -> None:
         except yaml.YAMLError as e:
             fail(f"Config not valid YAML: {cp}")
             click.echo(f"    {e}")
+        except UnicodeDecodeError as e:
+            # A ValueError, not an OSError — it slipped past both handlers above
+            # and crashed the one command meant to diagnose a broken config.
+            fail(f"Config is not valid UTF-8: {cp}")
+            click.echo(f"    {e}")
+            click.echo("    Re-save the file as UTF-8.")
+        except OSError as e:
+            fail(f"Config could not be read: {cp}")
+            click.echo(f"    {e}")
 
     section("MCP registration")
     if claude_path is None:

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

@@ -13,6 +13,7 @@ from collections.abc import Iterator
 from pathlib import Path
 
 import yaml
+from pydantic import ValidationError
 
 from .models import DispatchConfig
 
@@ -150,6 +151,14 @@ def file_lock(path: Path) -> Iterator[None]:
         _release_lock(fd)
 
 
+# Everything load_config() can raise for a config a human can plausibly produce.
+# Listed once because three surfaces handle it independently (server._get_config,
+# cli._load_or_exit, cli.doctor) and they must not drift: UnicodeDecodeError, in
+# particular, is a ValueError — NOT an OSError — so a file saved in cp1251 or
+# UTF-16 used to escape every one of them as a raw traceback.
+CONFIG_LOAD_ERRORS = (ValidationError, yaml.YAMLError, UnicodeDecodeError, OSError)
+
+
 def load_config(path: Path | None = None) -> DispatchConfig:
     """Load config from YAML file. Returns empty config if file missing."""
     p = path or config_path()

{agent_dispatch-0.12.0 → agent_dispatch-0.12.1}/src/agent_dispatch/runner.py

@@ -638,6 +638,13 @@ def dispatch(
                 cwd=str(agent.directory),
                 capture_output=True,
                 text=True,
+                # Decoding must be total. `text=True` alone decodes strictly, so
+                # a single undecodable byte on stdout/stderr raises
+                # UnicodeDecodeError — a ValueError, caught by nothing here — and
+                # an already-billed dispatch escapes as a raw exception instead
+                # of a DispatchResult. Same rule as _read_preview.
+                encoding="utf-8",
+                errors="replace",
                 timeout=timeout,
                 env=env,
             )
@@ -650,6 +657,25 @@ def dispatch(
                 error=_timeout_error(agent_name, timeout, session_uuid),
                 error_type="timeout",
             )
+        # Spawn failures, classified exactly as dispatch_stream does — the
+        # is_dir() check above does not prove the child can chdir into it, and
+        # the directory can vanish between the check and the spawn.
+        except FileNotFoundError as e:
+            return DispatchResult(
+                agent=agent_name, success=False, result="", error=str(e), error_type="not_found"
+            )
+        except PermissionError as e:
+            return DispatchResult(
+                agent=agent_name,
+                success=False,
+                result="",
+                error=f"{e}{_permission_hint(agent_name)}",
+                error_type="permission",
+            )
+        except OSError as e:
+            return DispatchResult(
+                agent=agent_name, success=False, result="", error=str(e), error_type="cli_error"
+            )
         # Self-heal on old claude CLIs that don't know --session-id: strip the
         # flag and retry once. Timed-out dispatches lose resumability, but
         # every dispatch working beats 100% failing with "unknown option".
@@ -869,6 +895,8 @@ def dispatch_stream(
             stdout=subprocess.PIPE,
             stderr=subprocess.PIPE,
             text=True,
+            encoding="utf-8",
+            errors="replace",  # see dispatch(): strict decoding raises mid-stream
             env=env,
             # Own process group, so the timeout can take the whole tree down
             # (see _kill_process_tree). Without it a backgrounded grandchild

{agent_dispatch-0.12.0 → agent_dispatch-0.12.1}/src/agent_dispatch/server.py

@@ -14,13 +14,12 @@ import time
 from collections.abc import Awaitable, Callable
 from typing import Any
 
-import yaml
 from mcp.server.fastmcp import Context, FastMCP
-from pydantic import ValidationError
 
 from . import runner
 from .cache import DispatchCache
 from .config import (
+    CONFIG_LOAD_ERRORS,
     auto_describe,
     collect_mcp_servers,
     config_lock,
@@ -123,10 +122,40 @@ def _get_config() -> DispatchConfig:
     """Load config fresh each call so new agents are picked up immediately."""
     try:
         return load_config()
-    except (ValidationError, yaml.YAMLError, OSError) as e:
+    except CONFIG_LOAD_ERRORS as e:
         raise ConfigLoadError(f"Config at {config_path()} could not be loaded: {e}") from e
 
 
+def _io_guard(
+    fn: Callable[..., Awaitable[str]],
+) -> Callable[..., Awaitable[str]]:
+    """Return the documented ``{"error": ...}`` envelope for a filesystem failure.
+
+    Reading a broken config is not the only way a tool fails on I/O: a full disk,
+    a read-only volume or an uncreatable jobs directory makes ``save_config`` and
+    ``JobStore`` raise, and that used to escape as a raw exception. Runner-level
+    I/O never reaches here — it is already turned into a ``DispatchResult``.
+    """
+
+    @functools.wraps(fn)
+    async def wrapper(*args: Any, **kwargs: Any) -> str:
+        try:
+            return await fn(*args, **kwargs)
+        except OSError as e:
+            logger.warning("%s: I/O error: %s", fn.__name__, e)
+            return json.dumps(
+                {
+                    "error": f"{fn.__name__} failed on I/O: {e}",
+                    "hint": "Check free space and permissions on the config and jobs "
+                    "directories (~/.config/agent-dispatch, or AGENT_DISPATCH_CONFIG / "
+                    "AGENT_DISPATCH_JOBS_DIR).",
+                },
+                indent=2,
+            )
+
+    return wrapper
+
+
 def _config_guard(
     fn: Callable[..., Awaitable[str]],
 ) -> Callable[..., Awaitable[str]]:
@@ -153,7 +182,8 @@ def _config_guard(
                 indent=2,
             )
 
-    return wrapper
+    # The I/O arm is identical for every tool — reuse it instead of duplicating.
+    return _io_guard(wrapper)
 
 
 def _get_cache(config: DispatchConfig) -> DispatchCache | None:
@@ -1399,7 +1429,9 @@ async def add_agent(
         directory: Absolute path to the project directory.
         description: What this agent can do. Leave empty for auto-generation.
         timeout: Timeout in seconds (0 uses global default of 300).
-        max_budget_usd: Max cost in USD per dispatch (0 or omitted = no limit).
+        max_budget_usd: Max cost in USD per dispatch. 0 or omitted inherits
+            settings.default_max_budget_usd — that is "no limit" only when the
+            setting is unset too.
         permission_mode: Permission mode for the claude CLI
             (e.g. default, plan, bypassPermissions). Leave empty for default.
         allowed_tools: Comma-separated list of allowed tools
@@ -1419,7 +1451,13 @@ async def add_agent(
 
     from pathlib import Path
 
-    dir_path = Path(directory).expanduser().resolve()
+    try:
+        # expanduser raises RuntimeError for an unresolvable "~unknown-user",
+        # and resolve() can raise OSError — neither is a directory-missing error,
+        # and both used to escape the tool as a raw exception.
+        dir_path = Path(directory).expanduser().resolve()
+    except (OSError, RuntimeError, ValueError) as e:
+        return json.dumps({"error": f"Invalid directory {directory!r}: {e}"})
     if not dir_path.is_dir():
         return json.dumps({"error": f"Directory does not exist: {dir_path}"})
 
@@ -1533,8 +1571,9 @@ async def update_agent(
         name: Agent name to update.
         description: New description.
         timeout: New timeout in seconds (0 = don't change).
-        max_budget_usd: New max cost in USD per dispatch (0 = don't change;
-            pass a negative number to clear the limit).
+        max_budget_usd: New max cost in USD per dispatch (0 = don't change).
+            A negative number clears the *per-agent* cap, after which
+            settings.default_max_budget_usd applies (if set).
         model: Model override. Pass "none" to clear.
         permission_mode: Permission mode. Pass "none" to clear.
         allowed_tools: Comma-separated allowed tools. Pass "none" to clear.
@@ -1813,6 +1852,7 @@ async def dispatch_async(
 
 
 @mcp.tool()
+@_io_guard
 async def dispatch_status(
     job_id: str,
     ctx: Context | None = None,
@@ -1836,6 +1876,7 @@ async def dispatch_status(
 
 
 @mcp.tool()
+@_io_guard
 async def dispatch_wait(
     job_id: str,
     timeout_seconds: int = 60,
@@ -1876,6 +1917,7 @@ async def dispatch_wait(
 
 
 @mcp.tool()
+@_io_guard
 async def dispatch_cancel(
     job_id: str,
     ctx: Context | None = None,
@@ -1935,6 +1977,7 @@ async def dispatch_cancel(
 
 
 @mcp.tool()
+@_io_guard
 async def dispatch_jobs(
     status: str = "",
     limit: int = 50,
@@ -1991,6 +2034,7 @@ async def dispatch_jobs(
 
 
 @mcp.tool()
+@_io_guard
 async def fetch_result(
     ref: str,
     max_chars: int = 0,
@@ -2030,6 +2074,7 @@ async def fetch_result(
 
 
 @mcp.tool()
+@_io_guard
 async def dispatch_gc(
     max_age_days: float = 7,
     ctx: Context | None = None,

{agent_dispatch-0.12.0 → agent_dispatch-0.12.1}/tests/test_cli.py

@@ -1434,3 +1434,61 @@ class TestAddBudgetGuard:
         assert "--max-budget" in result.output
         assert not isinstance(result.exception, ValidationError)
         assert not _isolated_config.exists()
+
+
+class TestNonUtf8Config:
+    def _write_cp1251(self, path: Path) -> None:
+        path.write_bytes(
+            'agents:\n  infra:\n    directory: /tmp\n    description: "Инфраструктура"\n'.encode(
+                "cp1251"
+            )
+        )
+
+    def test_list_reports_encoding_not_traceback(self, _isolated_config):
+        self._write_cp1251(_isolated_config)
+        result = runner.invoke(cli, ["list"])
+        assert result.exit_code == 1
+        assert "UTF-8" in result.output
+        assert not isinstance(result.exception, UnicodeDecodeError)
+
+    def test_doctor_diagnoses_instead_of_crashing(self, _isolated_config):
+        # doctor is the command you reach for when the config is broken — it
+        # must never be the one that crashes on it.
+        self._write_cp1251(_isolated_config)
+        result = runner.invoke(cli, ["doctor"])
+        assert not isinstance(result.exception, UnicodeDecodeError)
+        assert "not valid UTF-8" in result.output
+        assert "Re-save the file as UTF-8" in result.output
+
+    def test_unreadable_config_is_reported_by_doctor(self, _isolated_config, monkeypatch):
+        _isolated_config.write_text("agents: {}\n")
+        monkeypatch.setattr(
+            "agent_dispatch.cli.load_config",
+            lambda *a, **kw: (_ for _ in ()).throw(OSError("permission denied")),
+        )
+        result = runner.invoke(cli, ["doctor"])
+        assert not isinstance(result.exception, OSError)
+        assert "could not be read" in result.output
+
+
+class TestWriteFailureMessages:
+    def test_add_reports_write_failure_without_traceback(self, tmp_path: Path, _isolated_config):
+        project = tmp_path / "proj"
+        project.mkdir()
+        with patch(
+            "agent_dispatch.cli.save_config", side_effect=OSError(28, "No space left on device")
+        ):
+            result = runner.invoke(cli, ["add", "proj", str(project), "-d", "t"])
+        assert result.exit_code == 1
+        assert "could not write" in result.output
+        assert "previous config is intact" in result.output
+        assert not isinstance(result.exception, OSError)
+
+    def test_previous_config_survives_a_failed_write(self, tmp_path: Path, _isolated_config):
+        project = tmp_path / "proj"
+        project.mkdir()
+        runner.invoke(cli, ["add", "keep", str(project), "-d", "t"])
+        with patch("agent_dispatch.cli.save_config", side_effect=OSError("disk full")):
+            runner.invoke(cli, ["remove", "keep"])
+        # The write is atomic, so the agent must still be there.
+        assert "keep" in load_config(_isolated_config).agents

{agent_dispatch-0.12.0 → agent_dispatch-0.12.1}/tests/test_runner.py

@@ -1866,3 +1866,73 @@ class TestDispatchPayloadRobustness:
         assert cmd[2] == "--output-format"  # prompt untouched
         assert cmd[cmd.index("--output-format", 3) + 1] == "stream-json"
         assert result.success
+
+
+class TestUndecodableOutput:
+    """`text=True` decodes strictly: one bad byte used to raise UnicodeDecodeError
+    (a ValueError — caught by nothing) out of an already-billed dispatch."""
+
+    @staticmethod
+    def _cli(tmp_path: Path, body: str) -> Path:
+        script = tmp_path / "bad_cli.py"
+        script.write_text(body)
+        launcher = tmp_path / "bad_cli"
+        launcher.write_text(f'#!/bin/sh\nexec "{sys.executable}" "{script}" "$@"\n')
+        launcher.chmod(0o755)
+        return launcher
+
+    def test_dispatch_survives_an_undecodable_byte(self, tmp_path: Path):
+        cli = self._cli(
+            tmp_path,
+            "import sys\n"
+            "sys.stdout.buffer.write(b'{\"result\":\"caf\\xe9 ok\",\"is_error\":false}')\n",
+        )
+        agent = AgentConfig(directory=tmp_path, description="t", timeout=10)
+        with patch("agent_dispatch.runner.shutil.which", return_value=str(cli)):
+            result = dispatch("test", "hello", agent, Settings())
+        assert result.success
+        assert "ok" in result.result  # the bad byte became U+FFFD, nothing raised
+
+    def test_stream_survives_an_undecodable_byte(self, tmp_path: Path):
+        cli = self._cli(
+            tmp_path,
+            "import sys\n"
+            "sys.stdout.buffer.write(b'{\"type\":\"result\",\"is_error\":false,"
+            "\"result\":\"caf\\xe9 ok\"}\\n')\n",
+        )
+        agent = AgentConfig(directory=tmp_path, description="t", timeout=10)
+        with patch("agent_dispatch.runner.shutil.which", return_value=str(cli)):
+            result = dispatch_stream("test", "hello", agent, Settings())
+        assert result.success
+        assert "ok" in result.result
+
+
+class TestSpawnFailureClassification:
+    """dispatch_stream classified spawn errors; dispatch let them escape raw."""
+
+    def setup_method(self):
+        self.settings = Settings()
+
+    @patch("agent_dispatch.runner.shutil.which", return_value="/usr/bin/claude")
+    @patch("agent_dispatch.runner.subprocess.run", side_effect=FileNotFoundError("gone"))
+    def test_missing_cwd_at_spawn_is_not_found(self, _run, _which):
+        # is_dir() passing does not prove the child can chdir there, and the
+        # directory can vanish between the check and the spawn.
+        result = dispatch("test", "hi", AgentConfig(directory="/tmp", timeout=10), self.settings)
+        assert not result.success
+        assert result.error_type == "not_found"
+
+    @patch("agent_dispatch.runner.shutil.which", return_value="/usr/bin/claude")
+    @patch("agent_dispatch.runner.subprocess.run", side_effect=PermissionError("denied"))
+    def test_unexecutable_cwd_is_permission(self, _run, _which):
+        result = dispatch("test", "hi", AgentConfig(directory="/tmp", timeout=10), self.settings)
+        assert not result.success
+        assert result.error_type == "permission"
+        assert "Hint" in result.error
+
+    @patch("agent_dispatch.runner.shutil.which", return_value="/usr/bin/claude")
+    @patch("agent_dispatch.runner.subprocess.run", side_effect=OSError("too many open files"))
+    def test_other_oserror_is_cli_error(self, _run, _which):
+        result = dispatch("test", "hi", AgentConfig(directory="/tmp", timeout=10), self.settings)
+        assert not result.success
+        assert result.error_type == "cli_error"

{agent_dispatch-0.12.0 → agent_dispatch-0.12.1}/tests/test_server.py

@@ -3002,3 +3002,101 @@ class TestUpdateAgentLockDiscipline:
         saved = load_config(cfg_file)
         assert saved.agents["infra"].description == "from-A"
         assert saved.agents["db"].description == "from-B"
+
+
+class TestNonUtf8Config:
+    """UnicodeDecodeError is a ValueError, not an OSError — it slipped past every
+    handler and crashed all 21 tools (and `doctor`, the diagnosis command)."""
+
+    @pytest.fixture()
+    def cp1251_config(self, tmp_path: Path, monkeypatch):
+        cfg = tmp_path / "agents.yaml"
+        cfg.write_bytes(
+            'agents:\n  infra:\n    directory: /tmp\n    description: "Инфраструктура"\n'.encode(
+                "cp1251"
+            )
+        )
+        monkeypatch.setenv("AGENT_DISPATCH_CONFIG", str(cfg))
+        return cfg
+
+    @pytest.mark.asyncio
+    async def test_list_agents_returns_error_envelope(self, cp1251_config):
+        data = json.loads(await server.list_agents(ctx=None))
+        assert "could not be loaded" in data["error"]
+
+    @pytest.mark.asyncio
+    async def test_dispatch_returns_error_envelope(self, cp1251_config):
+        data = json.loads(await server.dispatch("infra", "task", ctx=None))
+        assert "could not be loaded" in data["error"]
+
+
+class TestWriteFailureEnvelope:
+    """The load half of the contract was fixed first; a failed *write* (full
+    disk, read-only volume) escaped the same tools as a raw OSError."""
+
+    @pytest.mark.asyncio
+    async def test_add_agent_reports_io_failure_as_json(self, tmp_path: Path, monkeypatch):
+        project = tmp_path / "proj"
+        project.mkdir()
+        monkeypatch.setenv("AGENT_DISPATCH_CONFIG", str(tmp_path / "agents.yaml"))
+        boom = OSError(28, "No space left on device")
+        with patch.object(server, "save_config", side_effect=boom):
+            raw = await server.add_agent("new", str(project))
+        data = json.loads(raw)
+        assert "I/O" in data["error"]
+        assert "No space left" in data["error"]
+        assert "hint" in data
+
+    @pytest.mark.asyncio
+    async def test_update_agent_reports_io_failure_as_json(self, tmp_path: Path, monkeypatch):
+        config = _make_config(tmp_path)
+        from agent_dispatch.config import save_config as real_save
+
+        cfg = tmp_path / "agents.yaml"
+        real_save(config, cfg)
+        monkeypatch.setenv("AGENT_DISPATCH_CONFIG", str(cfg))
+        with patch.object(server, "save_config", side_effect=OSError("read-only file system")):
+            data = json.loads(await server.update_agent("infra", description="x"))
+        assert "I/O" in data["error"]
+
+
+class TestJobToolsIoGuard:
+    """The six job tools never load config, so @_config_guard was not applied —
+    leaving their I/O failures escaping raw."""
+
+    @pytest.mark.asyncio
+    async def test_unusable_jobs_dir_returns_envelope(self, tmp_path: Path, monkeypatch):
+        blocked = tmp_path / "blocked"
+        blocked.write_text("this is a file, not a directory")
+        monkeypatch.setenv("AGENT_DISPATCH_JOBS_DIR", str(blocked / "jobs"))
+        server._job_store = None
+        data = json.loads(await server.dispatch_jobs())
+        assert "I/O" in data["error"]
+        assert "hint" in data
+
+    @pytest.mark.asyncio
+    async def test_all_job_tools_are_guarded(self):
+        import inspect
+
+        for name in (
+            "dispatch_status",
+            "dispatch_wait",
+            "dispatch_cancel",
+            "dispatch_jobs",
+            "fetch_result",
+            "dispatch_gc",
+        ):
+            fn = getattr(server, name)
+            src = inspect.getsource(inspect.unwrap(fn))
+            assert hasattr(fn, "__wrapped__"), f"{name} is not wrapped by a guard"
+            assert src  # sanity
+
+
+class TestAddAgentBadDirectory:
+    @pytest.mark.asyncio
+    async def test_unresolvable_home_returns_envelope(self, tmp_path: Path, monkeypatch):
+        monkeypatch.setenv("AGENT_DISPATCH_CONFIG", str(tmp_path / "agents.yaml"))
+        # expanduser raises RuntimeError for an unknown user — not a
+        # directory-missing error, and it used to escape the tool.
+        data = json.loads(await server.add_agent("z", "~nonexistentuser12345/proj"))
+        assert "Invalid directory" in data["error"]