agent-dispatch 0.4.0__tar.gz → 0.5.0__tar.gz

{agent_dispatch-0.4.0 → agent_dispatch-0.5.0}/.github/workflows/ci.yml

@@ -6,6 +6,10 @@ on:
   pull_request:
     branches: [main]
 
+# Least privilege: CI only needs to read the repo.
+permissions:
+  contents: read
+
 jobs:
   test:
     runs-on: ubuntu-latest

{agent_dispatch-0.4.0 → agent_dispatch-0.5.0}/.github/workflows/publish.yml

@@ -4,12 +4,16 @@ on:
   release:
     types: [published]
 
+# Default to no privileges; the publish job opts into exactly what it needs.
+permissions: {}
+
 jobs:
   publish:
     runs-on: ubuntu-latest
     environment: pypi
     permissions:
-      id-token: write
+      id-token: write   # OIDC token for PyPI Trusted Publisher
+      contents: read    # checkout the tagged source
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
 

{agent_dispatch-0.4.0 → agent_dispatch-0.5.0}/CHANGELOG.md

@@ -7,6 +7,68 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-06-01
+
+Security-hardening release. A multi-agent audit of the codebase surfaced
+several issues; the confirmed ones are fixed here, plus job cancellation,
+cache bounding, and stale-job recovery.
+
+### Security
+- **Path traversal in async jobs (fixed).** `dispatch_status`, `dispatch_wait`,
+  and `fetch_result` accept a caller-supplied `job_id`/`ref` that flowed
+  straight into `JobStore`'s file-path construction. A crafted value such as
+  `../../secret` could read any Job-shaped `.json` file outside the jobs
+  directory. Job ids are now validated against `^[0-9a-f]{32}$` at the tool
+  boundary (`_validate_ref`), in `JobStore.get`, and in `JobStore._path`
+  (defense in depth). Malformed ids are rejected without touching the
+  filesystem. New helper `jobs.is_valid_job_id`.
+- **Argument/flag injection via structured CLI fields (fixed).** A
+  `session_id` (caller-controlled in `dispatch_session`) — or a misconfigured
+  `model`, `permission_mode`, or tool name — that started with `-` was placed
+  in the argument position after a flag (e.g. `--resume <session_id>`) and the
+  `claude` CLI parsed it as a *new* flag, allowing options like
+  `--permission-mode bypassPermissions` to be smuggled in. `_build_command`
+  now rejects any such value via `_reject_flaglike` (raising
+  `runner.ArgInjectionError`); `dispatch`/`dispatch_stream` surface it as a
+  clean failed result, never spawning a subprocess.
+- **Tightened file permissions.** Job files are written `0o600` and the jobs
+  directory is created `0o700` (they hold full task/context/result payloads
+  that may contain secrets). `save_config` now writes `agents.yaml` `0o600`
+  and its parent directory `0o700`. All `chmod`s are best-effort (skipped on
+  platforms without POSIX modes).
+
+### Added
+- `dispatch_cancel(job_id)` MCP tool — cancel a *pending* async job before it
+  starts. Running jobs are left to finish (their subprocess can't be safely
+  interrupted); the tool reports an `outcome` of `cancelled`, `running`,
+  `already_terminal`, or `not_found`. Makes the previously-unreachable
+  `cancelled` job status real. Backed by `JobStore.cancel`, and the
+  cancel/start race is closed by `mark_running` refusing a cancelled job.
+- Cache size bound — `CacheSettings.max_size` (default 1000) caps the
+  in-memory dispatch cache, evicting the oldest entry first (FIFO by insertion
+  time; read access does not refresh, since the timestamp also drives TTL),
+  preventing unbounded memory growth from many unique requests. `cache_stats`
+  now reports `max_size` and `evictions`.
+- Stale-job recovery — on startup the server marks jobs abandoned in
+  `running` (older than 1h, e.g. from a crashed prior run) as `failed` so
+  callers don't poll them forever (`JobStore.recover_stale`).
+
+### Changed
+- Input bounds hardened across MCP tools: `dispatch_jobs(limit)` clamped to
+  `[1, 1000]`; `dispatch_gc(max_age_days)` rejects non-finite values;
+  `summary_chars` (in `dispatch` and per-item `dispatch_parallel`) clamped to
+  `[0, 100000]`; `dispatch_parallel` rejects more than
+  `max(100, max_concurrency * 20)` items to bound subprocess fan-out.
+- Async job worker now logs lifecycle transitions (running / finished) with
+  the job id for easier production debugging.
+- Type hints filled in (`_ref_payload`, `_run_job`, `_run_one`).
+- Lint surface expanded — ruff now enforces bugbear (`B`), bandit security
+  (`S`), import order (`I`), and pyupgrade (`UP`) in addition to the defaults,
+  with documented ignores for the trusted `claude` subprocess calls.
+- `SECURITY.md` rewritten: accurate supported-versions table and an expanded
+  threat model (bypassPermissions, on-disk job files, env inheritance,
+  best-effort recursion depth, argument-injection mitigation).
+
 ## [0.4.0] - 2026-05-15
 
 ### Added
@@ -152,7 +214,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Dependabot for `pip` + `github-actions`, GitHub Actions pinned to
   commit SHAs for supply-chain integrity.
 
-[Unreleased]: https://github.com/ginkida/agent-dispatch/compare/v0.4.0...HEAD
+[Unreleased]: https://github.com/ginkida/agent-dispatch/compare/v0.5.0...HEAD
+[0.5.0]: https://github.com/ginkida/agent-dispatch/compare/v0.4.0...v0.5.0
 [0.4.0]: https://github.com/ginkida/agent-dispatch/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/ginkida/agent-dispatch/compare/v0.2.2...v0.3.0
 [0.2.2]: https://github.com/ginkida/agent-dispatch/compare/v0.2.1...v0.2.2

{agent_dispatch-0.4.0 → agent_dispatch-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-dispatch
-Version: 0.4.0
+Version: 0.5.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
@@ -339,7 +339,7 @@ fetch_result(ref="8f3a...e1", max_chars=2000)  -> truncated, plus {"truncated":
 
 Refs reuse the same storage as `dispatch_async` jobs (under `~/.config/agent-dispatch/jobs/`), so any `job_id` returned by `dispatch_async` is also a valid `ref` for `fetch_result`. `parsed_result` (when `response_format="json"` is set) is small and is always inlined directly in the ref response — no second fetch needed.
 
-### Async dispatch — `dispatch_async`, `dispatch_status`, `dispatch_wait`, `dispatch_jobs`, `dispatch_gc`
+### Async dispatch — `dispatch_async`, `dispatch_status`, `dispatch_wait`, `dispatch_cancel`, `dispatch_jobs`, `dispatch_gc`
 
 When a dispatched task is going to take a while, you don't want to block your own tool slot for minutes. Async dispatch returns a `job_id` immediately and lets you check back when you're ready.
 
@@ -360,9 +360,11 @@ dispatch_wait(job_id="8f3a...e1", timeout_seconds=120)
   -> {"id": "...", "status": "running", "timed_out_waiting": true}
 ```
 
+`dispatch_cancel(job_id)` cancels a job that is still **pending** (before its subprocess starts) — a running job is left to finish, since its `claude` subprocess can't be safely interrupted. The response carries an `outcome` of `cancelled`, `running`, `already_terminal`, or `not_found`.
+
 `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, atomic writes — safe to read or `ls` while jobs are in flight.
+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 abandoned in `running` by a prior crashed instance as `failed`.
 
 | When to use async | When to use `dispatch` |
 |-------------------|------------------------|
@@ -418,10 +420,11 @@ settings:
   #   - Read
   #   - Edit
   max_dispatch_depth: 3     # recursion protection
-  max_concurrency: 5        # max parallel claude -p processes
+  max_concurrency: 5        # max parallel claude -p processes (per dispatch path)
   cache:
     enabled: true
     ttl: 300                # seconds
+    max_size: 1000          # max cached entries; oldest evicted first (FIFO)
 ```
 
 Config is reloaded on every tool call — add agents without restarting.
@@ -459,11 +462,16 @@ agent-dispatch MCP server
 
 ## Safety
 
-- **Recursion protection** — `AGENT_DISPATCH_DEPTH` env var tracks nesting. Default limit: 3.
+- **Recursion protection** — `AGENT_DISPATCH_DEPTH` env var tracks nesting. Default limit: 3. Best-effort across the subprocess boundary (see [SECURITY.md](SECURITY.md)).
+- **Argument-injection guard** — structured CLI fields (`session_id`, `model`, `permission_mode`, tool names) that start with `-` are rejected so they can't smuggle extra `claude` flags.
+- **Path-traversal guard** — caller-supplied `job_id`/`ref` values are validated as 32-char hex before any filesystem access.
+- **Owner-only state** — job files (`0o600`) and `agents.yaml` (`0o600`) are written for the owner only; their directories are `0o700`.
 - **Cost control** — `max_budget_usd` per agent or globally.
-- **Concurrency** — `max_concurrency` (default: 5) limits parallel `claude -p` processes.
+- **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). Orphaned processes are cleaned up.
-- **Caching** — identical `(agent, task, context)` requests return cached results. Only successes are cached. Sessions and dialogues are never cached.
+- **Caching** — identical `(agent, task, context, caller, goal, response_format)` requests return cached results, bounded by `cache.max_size` (oldest entry evicted first). Only successes are cached. Sessions and dialogues are never cached.
+
+See [SECURITY.md](SECURITY.md) for the full threat model (including the `bypassPermissions` escalation risk and on-disk job files).
 
 ## CLI
 

{agent_dispatch-0.4.0 → agent_dispatch-0.5.0}/README.md

@@ -309,7 +309,7 @@ fetch_result(ref="8f3a...e1", max_chars=2000)  -> truncated, plus {"truncated":
 
 Refs reuse the same storage as `dispatch_async` jobs (under `~/.config/agent-dispatch/jobs/`), so any `job_id` returned by `dispatch_async` is also a valid `ref` for `fetch_result`. `parsed_result` (when `response_format="json"` is set) is small and is always inlined directly in the ref response — no second fetch needed.
 
-### Async dispatch — `dispatch_async`, `dispatch_status`, `dispatch_wait`, `dispatch_jobs`, `dispatch_gc`
+### Async dispatch — `dispatch_async`, `dispatch_status`, `dispatch_wait`, `dispatch_cancel`, `dispatch_jobs`, `dispatch_gc`
 
 When a dispatched task is going to take a while, you don't want to block your own tool slot for minutes. Async dispatch returns a `job_id` immediately and lets you check back when you're ready.
 
@@ -330,9 +330,11 @@ dispatch_wait(job_id="8f3a...e1", timeout_seconds=120)
   -> {"id": "...", "status": "running", "timed_out_waiting": true}
 ```
 
+`dispatch_cancel(job_id)` cancels a job that is still **pending** (before its subprocess starts) — a running job is left to finish, since its `claude` subprocess can't be safely interrupted. The response carries an `outcome` of `cancelled`, `running`, `already_terminal`, or `not_found`.
+
 `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, atomic writes — safe to read or `ls` while jobs are in flight.
+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 abandoned in `running` by a prior crashed instance as `failed`.
 
 | When to use async | When to use `dispatch` |
 |-------------------|------------------------|
@@ -388,10 +390,11 @@ settings:
   #   - Read
   #   - Edit
   max_dispatch_depth: 3     # recursion protection
-  max_concurrency: 5        # max parallel claude -p processes
+  max_concurrency: 5        # max parallel claude -p processes (per dispatch path)
   cache:
     enabled: true
     ttl: 300                # seconds
+    max_size: 1000          # max cached entries; oldest evicted first (FIFO)
 ```
 
 Config is reloaded on every tool call — add agents without restarting.
@@ -429,11 +432,16 @@ agent-dispatch MCP server
 
 ## Safety
 
-- **Recursion protection** — `AGENT_DISPATCH_DEPTH` env var tracks nesting. Default limit: 3.
+- **Recursion protection** — `AGENT_DISPATCH_DEPTH` env var tracks nesting. Default limit: 3. Best-effort across the subprocess boundary (see [SECURITY.md](SECURITY.md)).
+- **Argument-injection guard** — structured CLI fields (`session_id`, `model`, `permission_mode`, tool names) that start with `-` are rejected so they can't smuggle extra `claude` flags.
+- **Path-traversal guard** — caller-supplied `job_id`/`ref` values are validated as 32-char hex before any filesystem access.
+- **Owner-only state** — job files (`0o600`) and `agents.yaml` (`0o600`) are written for the owner only; their directories are `0o700`.
 - **Cost control** — `max_budget_usd` per agent or globally.
-- **Concurrency** — `max_concurrency` (default: 5) limits parallel `claude -p` processes.
+- **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). Orphaned processes are cleaned up.
-- **Caching** — identical `(agent, task, context)` requests return cached results. Only successes are cached. Sessions and dialogues are never cached.
+- **Caching** — identical `(agent, task, context, caller, goal, response_format)` requests return cached results, bounded by `cache.max_size` (oldest entry evicted first). Only successes are cached. Sessions and dialogues are never cached.
+
+See [SECURITY.md](SECURITY.md) for the full threat model (including the `bypassPermissions` escalation risk and on-disk job files).
 
 ## CLI
 

agent_dispatch-0.5.0/SECURITY.md

@@ -0,0 +1,77 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability, please report it via [GitHub Security Advisories](https://github.com/ginkida/agent-dispatch/security/advisories/new).
+
+**Do not** open a public issue for security vulnerabilities.
+
+## Supported Versions
+
+| Version | Supported |
+|---------|-----------|
+| 0.5.x   | Yes       |
+| 0.4.x   | Yes       |
+| ≤ 0.3.x | No        |
+
+## Threat Model
+
+`agent-dispatch` runs `claude -p` subprocesses in configured directories on
+behalf of a calling Claude Code agent. The MCP caller and the agent
+configurations are part of the same trust domain as the user running the
+server — this is a developer tool, not a multi-tenant service. With that in
+mind, the security-relevant areas are:
+
+### Subprocess execution
+- Tasks/context strings are passed as **argument-list** elements to
+  `subprocess.run`/`Popen` (never `shell=True`), so there is no shell
+  injection.
+- **Argument injection is guarded.** Structured fields placed next to a CLI
+  flag (`session_id` → `--resume`, `model` → `--model`, `permission_mode`,
+  and tool names) are rejected if they start with `-`, which the `claude`
+  CLI would otherwise parse as a *separate* flag. See
+  `runner._reject_flaglike` / `runner.ArgInjectionError`.
+
+### Permission escalation (`bypassPermissions`)
+- Setting `permission_mode: bypassPermissions` (or a permissive
+  `default_permission_mode`) disables Claude Code's permission prompts for
+  that agent — it can use any tool without confirmation. Only enable it for
+  agents whose project directories you trust. Prefer `allowed_tools` /
+  `disallowed_tools` for least privilege.
+- A dispatched agent running with broad permissions can, in principle, start
+  its own `claude`/dispatch chain. Recursion depth (`AGENT_DISPATCH_DEPTH`,
+  bounded by `max_dispatch_depth`) is **best-effort**: it crosses the process
+  boundary via an environment variable, so a deliberately hostile agent that
+  clears its environment can reset the counter. It protects against accidental
+  A→B→A loops, not against an adversarial agent.
+
+### On-disk state
+- Async/`return_ref` job records persist to
+  `~/.config/agent-dispatch/jobs/<job_id>.json` (override with
+  `AGENT_DISPATCH_JOBS_DIR`). They contain the full task, context, and result,
+  which may include sensitive output. Files are written `0o600` and the
+  directory `0o700` (owner-only). Call `dispatch_gc()` periodically to purge
+  old results.
+- `agents.yaml` is written `0o600`. It records project paths and permission
+  settings.
+- `job_id`s are unauthenticated 32-char hex UUIDs — anyone who can call the
+  MCP tools and knows a `job_id` can read its result. Don't relay `job_id`s
+  over untrusted channels. Caller-supplied `job_id`/`ref` values are validated
+  (`^[0-9a-f]{32}$`) before any filesystem access, blocking path traversal.
+
+### Environment & directories
+- The dispatched subprocess inherits the **full parent environment**
+  (`os.environ.copy()`) — necessary for `claude` to find its credentials.
+  Keep secrets you don't want dispatched agents to see out of the shell that
+  launches the server.
+- Agent directories are resolved to absolute paths via `Path.resolve()` and
+  must exist at registration time.
+
+### Cost
+- `max_budget_usd` (per agent or as a default) caps spend per dispatch.
+
+## Reproducibility & CI
+
+Third-party GitHub Actions are pinned to commit SHAs; workflows run with
+least-privilege `permissions`. Releases publish to PyPI via OIDC Trusted
+Publishing (no long-lived tokens).

{agent_dispatch-0.4.0 → agent_dispatch-0.5.0}/agents.example.yaml

@@ -45,3 +45,4 @@ settings:
   cache:
     enabled: true
     ttl: 300                       # seconds; identical (agent, task, context) requests are cached
+    max_size: 1000                 # max cached entries; oldest is evicted first (FIFO)

{agent_dispatch-0.4.0 → agent_dispatch-0.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agent-dispatch"
-version = "0.4.0"
+version = "0.5.0"
 description = "MCP server that lets Claude Code agents delegate tasks to agents in other project directories"
 readme = "README.md"
 license = "MIT"
@@ -47,6 +47,28 @@ asyncio_mode = "auto"
 target-version = "py310"
 line-length = 100
 
+[tool.ruff.lint]
+select = [
+    "E", "W",  # pycodestyle
+    "F",       # pyflakes
+    "B",       # flake8-bugbear (likely bugs)
+    "I",       # isort (import order)
+    "UP",      # pyupgrade (modern syntax)
+    "S",       # flake8-bandit (security)
+]
+ignore = [
+    # The dispatch family shells out to the trusted `claude` CLI with argument
+    # lists (never shell=True); see runner._build_command and the arg-injection
+    # guard (_reject_flaglike). Partial path is intentional — `claude` is
+    # resolved from PATH.
+    "S603",  # subprocess call with possibly-untrusted input
+    "S607",  # starting a process with a partial executable path
+]
+
+[tool.ruff.lint.per-file-ignores]
+# Tests legitimately assert and use throwaway /tmp paths.
+"tests/**" = ["S101", "S108"]
+
 [project.optional-dependencies]
 dev = [
     "pytest>=8.0",

{agent_dispatch-0.4.0 → agent_dispatch-0.5.0}/src/agent_dispatch/__init__.py

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

{agent_dispatch-0.4.0 → agent_dispatch-0.5.0}/src/agent_dispatch/cache.py

@@ -23,12 +23,14 @@ class DispatchCache:
     requests with different framing would collide and return the wrong response.
     """
 
-    def __init__(self, ttl: int = 300) -> None:
+    def __init__(self, ttl: int = 300, max_size: int = 1000) -> None:
         self._ttl = ttl
+        self._max_size = max_size
         self._store: dict[str, tuple[float, DispatchResult]] = {}
         self._lock = threading.Lock()
         self._hits = 0
         self._misses = 0
+        self._evictions = 0
 
     @staticmethod
     def _make_key(
@@ -89,6 +91,15 @@ class DispatchCache:
             return  # don't cache failures
         key = self._make_key(agent, task, context, caller, goal, response_format)
         with self._lock:
+            # Bound memory: when at capacity and inserting a new key, evict the
+            # oldest entry by insertion time (FIFO). We intentionally do NOT
+            # refresh timestamps on read — the timestamp also drives TTL expiry,
+            # so touching it on access would turn TTL into idle-time. Refreshing
+            # an existing key never triggers eviction.
+            if key not in self._store and len(self._store) >= self._max_size:
+                oldest = min(self._store, key=lambda k: self._store[k][0])
+                del self._store[oldest]
+                self._evictions += 1
             self._store[key] = (time.monotonic(), result)
 
     def clear(self) -> int:
@@ -97,6 +108,7 @@ class DispatchCache:
             self._store.clear()
             self._hits = 0
             self._misses = 0
+            self._evictions = 0
             return count
 
     def evict_expired(self) -> int:
@@ -112,8 +124,10 @@ class DispatchCache:
             total = self._hits + self._misses
             return {
                 "size": len(self._store),
+                "max_size": self._max_size,
                 "hits": self._hits,
                 "misses": self._misses,
+                "evictions": self._evictions,
                 "hit_rate": round(self._hits / total, 3) if total else 0.0,
                 "ttl": self._ttl,
             }

{agent_dispatch-0.4.0 → agent_dispatch-0.5.0}/src/agent_dispatch/cli.py

@@ -25,13 +25,13 @@ def _load_or_exit() -> DispatchConfig:
             f"Error: config at {config_path()} has an invalid schema:", fg="red"
         ))
         click.echo(str(e))
-        raise SystemExit(1)
+        raise SystemExit(1) from None
     except yaml.YAMLError as e:
         click.echo(click.style(
             f"Error: config at {config_path()} is not valid YAML:", fg="red"
         ))
         click.echo(str(e))
-        raise SystemExit(1)
+        raise SystemExit(1) from None
 
 
 @click.group()
@@ -94,7 +94,10 @@ def init() -> None:
 @cli.command()
 @click.argument("name")
 @click.argument("directory", type=click.Path(exists=True, file_okay=False, resolve_path=True))
-@click.option("-d", "--description", default=None, help="Agent description. Auto-generated if omitted.")
+@click.option(
+    "-d", "--description", default=None,
+    help="Agent description. Auto-generated if omitted.",
+)
 @click.option("--timeout", default=300, help="Timeout in seconds (default: 300).")
 @click.option("--model", default=None, help="Model override for this agent.")
 @click.option("--max-budget", default=None, type=float, help="Max cost in USD per dispatch.")
@@ -126,7 +129,7 @@ def add(
         validate_agent_name(name)
     except ValueError as e:
         click.echo(f"Error: {e}")
-        raise SystemExit(1)
+        raise SystemExit(1) from None
 
     config = _load_or_exit()
     dir_path = Path(directory).resolve()

{agent_dispatch-0.4.0 → agent_dispatch-0.5.0}/src/agent_dispatch/config.py

@@ -33,15 +33,25 @@ def load_config(path: Path | None = None) -> DispatchConfig:
     return DispatchConfig.model_validate(raw)
 
 
+def _chmod_quiet(path: Path, mode: int) -> None:
+    """Best-effort chmod. Silently ignores platforms/filesystems without it."""
+    try:
+        os.chmod(path, mode)
+    except OSError as e:  # pragma: no cover - platform dependent
+        logger.debug("chmod %s to %o failed: %s", path, mode, e)
+
+
 def save_config(config: DispatchConfig, path: Path | None = None) -> None:
-    """Save config to YAML file."""
+    """Save config to YAML file (owner-only perms — it records project paths)."""
     p = path or config_path()
-    p.parent.mkdir(parents=True, exist_ok=True)
+    p.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+    _chmod_quiet(p.parent, 0o700)
     data = config.model_dump(mode="json", exclude_none=True)
     p.write_text(
         yaml.dump(data, default_flow_style=False, allow_unicode=True, sort_keys=False),
         encoding="utf-8",
     )
+    _chmod_quiet(p, 0o600)
 
 
 def _collect_mcp_servers(directory: Path) -> list[str]:

{agent_dispatch-0.4.0 → agent_dispatch-0.5.0}/src/agent_dispatch/jobs.py

@@ -9,6 +9,7 @@ from __future__ import annotations
 
 import logging
 import os
+import re
 import threading
 import time
 import uuid
@@ -24,6 +25,24 @@ logger = logging.getLogger(__name__)
 JobStatus = Literal["pending", "running", "done", "failed", "cancelled"]
 _TERMINAL_STATUSES: frozenset[str] = frozenset({"done", "failed", "cancelled"})
 
+# Job IDs are uuid4().hex — 32 lowercase hex chars. Anything else (notably
+# values containing "/" or "..") is rejected so a caller-supplied ref/job_id
+# can never escape the jobs directory via path traversal.
+_JOB_ID_RE = re.compile(r"^[0-9a-f]{32}$")
+
+
+def is_valid_job_id(job_id: str) -> bool:
+    """Return True if *job_id* is a well-formed uuid4 hex string."""
+    return isinstance(job_id, str) and bool(_JOB_ID_RE.match(job_id))
+
+
+def _chmod_quiet(path: Path, mode: int) -> None:
+    """Best-effort chmod. Silently ignores platforms/filesystems without it."""
+    try:
+        os.chmod(path, mode)
+    except OSError as e:  # pragma: no cover - platform dependent
+        logger.debug("chmod %s to %o failed: %s", path, mode, e)
+
 
 class Job(BaseModel):
     """Persistent record of an async dispatch."""
@@ -50,16 +69,24 @@ class JobStore:
 
     def __init__(self, directory: Path):
         self.directory = Path(directory).expanduser()
-        self.directory.mkdir(parents=True, exist_ok=True)
+        # Owner-only (0o700): job files hold full task/context/result payloads
+        # that may contain secrets — keep them off other local users' radar.
+        self.directory.mkdir(parents=True, exist_ok=True, mode=0o700)
+        _chmod_quiet(self.directory, 0o700)
         self._lock = threading.RLock()
 
     def _path(self, job_id: str) -> Path:
+        # Defense-in-depth: validate before building any path so a crafted
+        # job_id ("../../etc/foo") can never resolve outside self.directory.
+        if not is_valid_job_id(job_id):
+            raise ValueError(f"Invalid job_id: {job_id!r}")
         return self.directory / f"{job_id}.json"
 
     def _write(self, job: Job) -> None:
         path = self._path(job.id)
         tmp = path.with_suffix(".tmp")
         tmp.write_text(job.model_dump_json(indent=2, exclude_none=True), encoding="utf-8")
+        _chmod_quiet(tmp, 0o600)  # owner-only before it becomes visible
         os.replace(tmp, path)
 
     def create(
@@ -118,7 +145,12 @@ class JobStore:
         return job
 
     def get(self, job_id: str) -> Job | None:
-        """Read a job by id. Returns None if not found or unreadable."""
+        """Read a job by id. Returns None if not found, invalid, or unreadable."""
+        if not is_valid_job_id(job_id):
+            # Malformed/hostile id (e.g. path traversal attempt) — treat as
+            # "not found" without touching the filesystem.
+            logger.debug("Rejecting malformed job_id: %r", job_id)
+            return None
         path = self._path(job_id)
         if not path.exists():
             return None
@@ -143,16 +175,73 @@ class JobStore:
         return jobs
 
     def mark_running(self, job_id: str) -> Job | None:
-        """Mark job as running. Returns updated job or None if not found."""
+        """Mark a pending job as running.
+
+        Returns the updated job, or None if the job is missing OR has already
+        been cancelled. Refusing to run a cancelled job closes the race with
+        ``cancel()``: both take ``self._lock``, so whichever wins, the worker
+        either sees ``cancelled`` (and skips) or sets ``running`` first (and
+        cancel then refuses).
+        """
         with self._lock:
             job = self.get(job_id)
             if job is None:
                 return None
+            if job.status == "cancelled":
+                return None
             job.status = "running"
             job.started_at = time.time()
             self._write(job)
             return job
 
+    def cancel(self, job_id: str) -> tuple[Job | None, str]:
+        """Attempt to cancel a job.
+
+        Only *pending* jobs can be cancelled — a running job's subprocess is
+        already in flight and is left to finish. Returns ``(job, outcome)``
+        where outcome is one of: ``cancelled`` (was pending, now cancelled),
+        ``running`` (in flight, untouched), ``already_terminal`` (done/failed/
+        already cancelled), or ``not_found``.
+        """
+        with self._lock:
+            job = self.get(job_id)
+            if job is None:
+                return None, "not_found"
+            if job.is_terminal():
+                return job, "already_terminal"
+            if job.status == "running":
+                return job, "running"
+            # pending -> cancelled
+            job.status = "cancelled"
+            job.completed_at = time.time()
+            job.error = "Cancelled before execution"
+            self._write(job)
+            return job, "cancelled"
+
+    def recover_stale(self, stale_threshold_seconds: float = 3600) -> int:
+        """Mark jobs stuck in 'running' beyond the threshold as failed.
+
+        Async workers are daemon threads — if the server dies mid-dispatch the
+        job file is left in ``running`` forever. Call this on startup to flip
+        such orphans to ``failed`` so callers don't poll them indefinitely.
+        Returns the count recovered.
+        """
+        now = time.time()
+        recovered = 0
+        with self._lock:
+            for job in self.list(status="running"):
+                age = now - (job.started_at or job.created_at)
+                if age > stale_threshold_seconds:
+                    # Count only jobs we actually transitioned (fail() returns
+                    # None for a missing/malformed id, e.g. a planted file).
+                    if self.fail(
+                        job.id,
+                        f"Abandoned in 'running' for {age:.0f}s — likely a "
+                        "server restart. Re-dispatch if still needed.",
+                    ) is not None:
+                        recovered += 1
+        return recovered
+
     def finish(
         self,
         job_id: str,

{agent_dispatch-0.4.0 → agent_dispatch-0.5.0}/src/agent_dispatch/models.py

@@ -55,6 +55,7 @@ class CacheSettings(BaseModel):
 
     enabled: bool = True
     ttl: int = Field(default=300, ge=0)  # seconds; 0 effectively disables
+    max_size: int = Field(default=1000, ge=1)  # entries before oldest-first eviction
 
     @field_validator("ttl", mode="after")
     @classmethod