backburner-mcp 0.1.0__tar.gz

backburner_mcp-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.pytest_cache/
+.venv/
+venv/
+.idea/
+.vscode/
+CLAUDE.md

backburner_mcp-0.1.0/LICENSE

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

backburner_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: backburner-mcp
+Version: 0.1.0
+Summary: An MCP server that lets AI agents run long jobs in the background and collect results later
+Author: Rohit Yajee
+License: MIT
+License-File: LICENSE
+Keywords: agents,background-jobs,mcp,model-context-protocol,tasks
+Requires-Python: >=3.10
+Requires-Dist: mcp>=1.26.0
+Description-Content-Type: text/markdown
+
+# backburner
+
+**Put your AI agent's slow work on the back burner. Keep cooking.**
+
+`backburner` is an MCP server that gives any AI assistant (Claude, and any
+other MCP client) the ability to run long shell commands as **background
+tasks** — start a test suite, a build, a scrape, a batch job — then keep
+working and check back for the results, instead of sitting frozen until
+it finishes.
+
+```
+agent: start_task("pytest -q")        ->  { task_id: "a1b2c3d4", status: "working" }
+        ... agent does other useful work ...
+agent: task_status("a1b2c3d4")        ->  { status: "completed", duration_seconds: 312 }
+agent: task_result("a1b2c3d4")        ->  { output: "418 passed in 311.2s" }
+```
+
+## Why
+
+AI agents are bad at waiting. A tool call that takes 10 minutes blocks the
+whole conversation — or times out and loses the work entirely. The MCP
+specification is formalizing a Tasks pattern for exactly this problem
+(extension finalized in the 2026-07-28 spec release); `backburner` brings
+that workflow to every client **today** via plain tools, with first-class
+Tasks-extension support on the roadmap.
+
+## Tools
+
+| Tool | What it does |
+|------|--------------|
+| `start_task(command, cwd?, timeout_seconds?)` | Run a shell command in the background, returns a task id immediately |
+| `task_status(task_id)` | `working` / `completed` / `failed` / `cancelled` / `timed_out` / `interrupted` |
+| `task_result(task_id, tail_lines?)` | Captured output — works mid-run too, so you can peek at progress |
+| `cancel_task(task_id)` | Kill the task and its whole process tree |
+| `list_tasks(limit?)` | Recent tasks, newest first |
+
+## Features
+
+- **Survives restarts** — tasks are tracked in SQLite under `~/.backburner/`;
+  output is captured to per-task log files. If the server dies mid-task,
+  orphaned tasks are honestly marked `interrupted`, never silently lost.
+- **Real cancellation** — kills the full process tree (worker processes
+  included), on Windows and Unix.
+- **Peek at live progress** — `task_result` on a running task returns the
+  output so far.
+- **Timeouts** — pass `timeout_seconds` and a runaway task is killed and
+  honestly marked `timed_out` instead of hanging forever.
+- **Command policy** — restrict what the AI may run with environment
+  variables (regexes, comma-separated; deny always wins):
+
+  ```bash
+  BACKBURNER_ALLOW="^pytest,^npm (test|run build)"   # only these may run
+  BACKBURNER_DENY="rm -rf,shutdown,format"           # these never run
+  ```
+- **Zero infrastructure** — stdlib only (SQLite, subprocess, threads).
+  No Redis, no Celery, no Docker.
+- **Tested** — a pytest suite covers the full job lifecycle: completion,
+  failure, cancellation, timeouts, crash recovery, and the command policy.
+
+## Install
+
+```bash
+pip install -e .
+```
+
+### Claude Code
+
+```bash
+claude mcp add backburner -- python -m backburner.server
+```
+
+### Claude Desktop / other clients
+
+```json
+{
+  "mcpServers": {
+    "backburner": {
+      "command": "python",
+      "args": ["-m", "backburner.server"]
+    }
+  }
+}
+```
+
+## Security note
+
+`backburner` executes the shell commands the AI sends it, with your user's
+permissions. That is its job — but treat it like giving your agent a
+terminal. Run it only with clients whose tool-use you review/approve,
+prefer permission modes that require confirmation for `start_task`, and
+use `BACKBURNER_ALLOW` / `BACKBURNER_DENY` to scope what may run.
+
+## Roadmap
+
+- [x] Task timeouts and max-runtime limits
+- [x] Allowlist/denylist for commands
+- [ ] MCP Tasks extension support (spec 2026-07-28) — native `tasks/get`,
+      `tasks/cancel` alongside the plain tools
+- [ ] Structured progress reporting (parse % / step markers from output)
+- [ ] PyPI release
+
+## License
+
+MIT

backburner_mcp-0.1.0/README.md

@@ -0,0 +1,104 @@
+# backburner
+
+**Put your AI agent's slow work on the back burner. Keep cooking.**
+
+`backburner` is an MCP server that gives any AI assistant (Claude, and any
+other MCP client) the ability to run long shell commands as **background
+tasks** — start a test suite, a build, a scrape, a batch job — then keep
+working and check back for the results, instead of sitting frozen until
+it finishes.
+
+```
+agent: start_task("pytest -q")        ->  { task_id: "a1b2c3d4", status: "working" }
+        ... agent does other useful work ...
+agent: task_status("a1b2c3d4")        ->  { status: "completed", duration_seconds: 312 }
+agent: task_result("a1b2c3d4")        ->  { output: "418 passed in 311.2s" }
+```
+
+## Why
+
+AI agents are bad at waiting. A tool call that takes 10 minutes blocks the
+whole conversation — or times out and loses the work entirely. The MCP
+specification is formalizing a Tasks pattern for exactly this problem
+(extension finalized in the 2026-07-28 spec release); `backburner` brings
+that workflow to every client **today** via plain tools, with first-class
+Tasks-extension support on the roadmap.
+
+## Tools
+
+| Tool | What it does |
+|------|--------------|
+| `start_task(command, cwd?, timeout_seconds?)` | Run a shell command in the background, returns a task id immediately |
+| `task_status(task_id)` | `working` / `completed` / `failed` / `cancelled` / `timed_out` / `interrupted` |
+| `task_result(task_id, tail_lines?)` | Captured output — works mid-run too, so you can peek at progress |
+| `cancel_task(task_id)` | Kill the task and its whole process tree |
+| `list_tasks(limit?)` | Recent tasks, newest first |
+
+## Features
+
+- **Survives restarts** — tasks are tracked in SQLite under `~/.backburner/`;
+  output is captured to per-task log files. If the server dies mid-task,
+  orphaned tasks are honestly marked `interrupted`, never silently lost.
+- **Real cancellation** — kills the full process tree (worker processes
+  included), on Windows and Unix.
+- **Peek at live progress** — `task_result` on a running task returns the
+  output so far.
+- **Timeouts** — pass `timeout_seconds` and a runaway task is killed and
+  honestly marked `timed_out` instead of hanging forever.
+- **Command policy** — restrict what the AI may run with environment
+  variables (regexes, comma-separated; deny always wins):
+
+  ```bash
+  BACKBURNER_ALLOW="^pytest,^npm (test|run build)"   # only these may run
+  BACKBURNER_DENY="rm -rf,shutdown,format"           # these never run
+  ```
+- **Zero infrastructure** — stdlib only (SQLite, subprocess, threads).
+  No Redis, no Celery, no Docker.
+- **Tested** — a pytest suite covers the full job lifecycle: completion,
+  failure, cancellation, timeouts, crash recovery, and the command policy.
+
+## Install
+
+```bash
+pip install -e .
+```
+
+### Claude Code
+
+```bash
+claude mcp add backburner -- python -m backburner.server
+```
+
+### Claude Desktop / other clients
+
+```json
+{
+  "mcpServers": {
+    "backburner": {
+      "command": "python",
+      "args": ["-m", "backburner.server"]
+    }
+  }
+}
+```
+
+## Security note
+
+`backburner` executes the shell commands the AI sends it, with your user's
+permissions. That is its job — but treat it like giving your agent a
+terminal. Run it only with clients whose tool-use you review/approve,
+prefer permission modes that require confirmation for `start_task`, and
+use `BACKBURNER_ALLOW` / `BACKBURNER_DENY` to scope what may run.
+
+## Roadmap
+
+- [x] Task timeouts and max-runtime limits
+- [x] Allowlist/denylist for commands
+- [ ] MCP Tasks extension support (spec 2026-07-28) — native `tasks/get`,
+      `tasks/cancel` alongside the plain tools
+- [ ] Structured progress reporting (parse % / step markers from output)
+- [ ] PyPI release
+
+## License
+
+MIT

backburner_mcp-0.1.0/backburner/jobs.py

@@ -0,0 +1,261 @@
+"""
+The job engine: start shell commands as background jobs, track them in
+SQLite, capture their output to log files, and cancel them on demand.
+
+This is deliberately independent of MCP — it's a plain Python library,
+so it can be tested alone and later exposed through any protocol.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import signal
+import sqlite3
+import subprocess
+import sys
+import threading
+import time
+import uuid
+from dataclasses import dataclass
+from pathlib import Path
+
+# All job state lives under the user's home dir so it survives restarts
+# and works no matter where the server is launched from.
+DATA_DIR = Path(os.environ.get("BACKBURNER_HOME", Path.home() / ".backburner"))
+LOG_DIR = DATA_DIR / "logs"
+DB_PATH = DATA_DIR / "jobs.db"
+
+WORKING = "working"
+COMPLETED = "completed"
+FAILED = "failed"
+CANCELLED = "cancelled"
+TIMED_OUT = "timed_out"
+INTERRUPTED = "interrupted"  # was running when the server died
+
+
+def check_command_allowed(command: str) -> None:
+    """Enforce the operator's command policy, set via environment variables.
+
+    BACKBURNER_DENY  — comma-separated regexes; a command matching ANY is refused.
+    BACKBURNER_ALLOW — comma-separated regexes; if set, a command must match at
+                      least one or it is refused. Deny wins over allow.
+
+    Both are matched case-insensitively anywhere in the command
+    (e.g. BACKBURNER_ALLOW="^pytest,^npm (test|run build)").
+    Raises PermissionError with a clear message when a command is refused.
+    """
+    deny = [p.strip() for p in os.environ.get("BACKBURNER_DENY", "").split(",") if p.strip()]
+    for pattern in deny:
+        if re.search(pattern, command, re.IGNORECASE):
+            raise PermissionError(
+                f"command refused: matches deny pattern {pattern!r} (BACKBURNER_DENY)"
+            )
+    allow = [p.strip() for p in os.environ.get("BACKBURNER_ALLOW", "").split(",") if p.strip()]
+    if allow and not any(re.search(p, command, re.IGNORECASE) for p in allow):
+        raise PermissionError(
+            "command refused: does not match any allow pattern (BACKBURNER_ALLOW)"
+        )
+
+
+@dataclass
+class Job:
+    id: str
+    command: str
+    cwd: str
+    status: str
+    created_at: float
+    finished_at: float | None
+    exit_code: int | None
+    pid: int | None
+    log_path: str
+
+    def to_dict(self) -> dict:
+        d = {
+            "task_id": self.id,
+            "command": self.command,
+            "cwd": self.cwd,
+            "status": self.status,
+            "created_at": time.strftime("%Y-%m-%d %H:%M:%S", time.localtime(self.created_at)),
+        }
+        if self.status == WORKING:
+            d["running_for_seconds"] = round(time.time() - self.created_at)
+        if self.finished_at is not None:
+            d["duration_seconds"] = round(self.finished_at - self.created_at)
+        if self.exit_code is not None:
+            d["exit_code"] = self.exit_code
+        return d
+
+
+class JobManager:
+    def __init__(self) -> None:
+        DATA_DIR.mkdir(parents=True, exist_ok=True)
+        LOG_DIR.mkdir(parents=True, exist_ok=True)
+        self._lock = threading.Lock()
+        self._procs: dict[str, subprocess.Popen] = {}
+        self._init_db()
+        self._mark_orphans()
+
+    # ---------------------------------------------------------------- db
+    def _db(self) -> sqlite3.Connection:
+        conn = sqlite3.connect(DB_PATH)
+        conn.row_factory = sqlite3.Row
+        return conn
+
+    def _init_db(self) -> None:
+        with self._db() as conn:
+            conn.execute(
+                """CREATE TABLE IF NOT EXISTS jobs (
+                       id TEXT PRIMARY KEY,
+                       command TEXT NOT NULL,
+                       cwd TEXT NOT NULL,
+                       status TEXT NOT NULL,
+                       created_at REAL NOT NULL,
+                       finished_at REAL,
+                       exit_code INTEGER,
+                       pid INTEGER,
+                       log_path TEXT NOT NULL
+                   )"""
+            )
+
+    def _mark_orphans(self) -> None:
+        # Jobs still marked 'working' from a previous run can't be ours —
+        # their monitor threads died with the old process.
+        with self._db() as conn:
+            conn.execute(
+                "UPDATE jobs SET status = ?, finished_at = ? WHERE status = ?",
+                (INTERRUPTED, time.time(), WORKING),
+            )
+
+    def _row_to_job(self, row: sqlite3.Row) -> Job:
+        return Job(
+            id=row["id"], command=row["command"], cwd=row["cwd"],
+            status=row["status"], created_at=row["created_at"],
+            finished_at=row["finished_at"], exit_code=row["exit_code"],
+            pid=row["pid"], log_path=row["log_path"],
+        )
+
+    def _get(self, job_id: str) -> Job:
+        with self._db() as conn:
+            row = conn.execute("SELECT * FROM jobs WHERE id = ?", (job_id,)).fetchone()
+        if row is None:
+            raise KeyError(f"no task with id '{job_id}'")
+        return self._row_to_job(row)
+
+    # ------------------------------------------------------------- public
+    def start(
+        self, command: str, cwd: str | None = None,
+        timeout_seconds: float | None = None,
+    ) -> Job:
+        check_command_allowed(command)
+        job_id = uuid.uuid4().hex[:8]
+        cwd = str(Path(cwd).resolve()) if cwd else os.getcwd()
+        if not Path(cwd).is_dir():
+            raise ValueError(f"working directory does not exist: {cwd}")
+        if timeout_seconds is not None and timeout_seconds <= 0:
+            raise ValueError("timeout_seconds must be positive")
+        log_path = str(LOG_DIR / f"{job_id}.log")
+
+        log_file = open(log_path, "w", encoding="utf-8", errors="replace")
+        # Children buffer stdout when it's a file, which would make live
+        # peeking useless; force line-buffering where the runtime honors it.
+        env = {**os.environ, "PYTHONUNBUFFERED": "1"}
+        # New process group so cancel() can kill the command AND any
+        # children it spawned (e.g. pytest workers), not just the shell.
+        if sys.platform == "win32":
+            proc = subprocess.Popen(
+                command, shell=True, cwd=cwd, env=env,
+                stdout=log_file, stderr=subprocess.STDOUT,
+                stdin=subprocess.DEVNULL,
+                creationflags=subprocess.CREATE_NEW_PROCESS_GROUP,
+            )
+        else:
+            proc = subprocess.Popen(
+                command, shell=True, cwd=cwd, env=env,
+                stdout=log_file, stderr=subprocess.STDOUT,
+                stdin=subprocess.DEVNULL,
+                start_new_session=True,
+            )
+
+        now = time.time()
+        with self._db() as conn:
+            conn.execute(
+                "INSERT INTO jobs VALUES (?, ?, ?, ?, ?, NULL, NULL, ?, ?)",
+                (job_id, command, cwd, WORKING, now, proc.pid, log_path),
+            )
+        with self._lock:
+            self._procs[job_id] = proc
+
+        threading.Thread(
+            target=self._watch, args=(job_id, proc, log_file), daemon=True
+        ).start()
+        if timeout_seconds is not None:
+            timer = threading.Timer(
+                timeout_seconds, self._finish_early, args=(job_id, TIMED_OUT)
+            )
+            timer.daemon = True
+            timer.start()
+        return self._get(job_id)
+
+    def _watch(self, job_id: str, proc: subprocess.Popen, log_file) -> None:
+        exit_code = proc.wait()
+        log_file.close()
+        with self._lock:
+            self._procs.pop(job_id, None)
+        with self._db() as conn:
+            # Don't overwrite a 'cancelled' status written by cancel().
+            conn.execute(
+                "UPDATE jobs SET status = CASE WHEN status = ? THEN ? ELSE status END,"
+                " finished_at = ?, exit_code = ? WHERE id = ?",
+                (WORKING, COMPLETED if exit_code == 0 else FAILED,
+                 time.time(), exit_code, job_id),
+            )
+
+    def status(self, job_id: str) -> Job:
+        return self._get(job_id)
+
+    def result(self, job_id: str, tail_lines: int = 100) -> dict:
+        job = self._get(job_id)
+        out = job.to_dict()
+        try:
+            text = Path(job.log_path).read_text(encoding="utf-8", errors="replace")
+            lines = text.splitlines()
+            out["output_total_lines"] = len(lines)
+            out["output"] = "\n".join(lines[-tail_lines:]) if lines else ""
+        except FileNotFoundError:
+            out["output"] = ""
+            out["output_total_lines"] = 0
+        return out
+
+    def cancel(self, job_id: str) -> Job:
+        return self._finish_early(job_id, CANCELLED)
+
+    def _finish_early(self, job_id: str, final_status: str) -> Job:
+        """Kill a working job's process tree and record why (cancel/timeout)."""
+        job = self._get(job_id)
+        if job.status != WORKING:
+            return job  # already finished; nothing to do
+        with self._db() as conn:
+            conn.execute(
+                "UPDATE jobs SET status = ?, finished_at = ? WHERE id = ? AND status = ?",
+                (final_status, time.time(), job_id, WORKING),
+            )
+        with self._lock:
+            proc = self._procs.get(job_id)
+        if proc is not None and proc.poll() is None:
+            if sys.platform == "win32":
+                # /T kills the whole process tree.
+                subprocess.run(
+                    ["taskkill", "/PID", str(proc.pid), "/T", "/F"],
+                    capture_output=True,
+                )
+            else:
+                os.killpg(os.getpgid(proc.pid), signal.SIGTERM)
+        return self._get(job_id)
+
+    def list(self, limit: int = 20) -> list[Job]:
+        with self._db() as conn:
+            rows = conn.execute(
+                "SELECT * FROM jobs ORDER BY created_at DESC LIMIT ?", (limit,)
+            ).fetchall()
+        return [self._row_to_job(r) for r in rows]

backburner_mcp-0.1.0/backburner/server.py

@@ -0,0 +1,77 @@
+"""
+backburner — an MCP server that lets AI agents run long jobs in the
+background and collect the results later, instead of blocking.
+
+Run:  python -m backburner.server
+"""
+
+from mcp.server.fastmcp import FastMCP
+
+from backburner.jobs import JobManager
+
+mcp = FastMCP(
+    "backburner",
+    instructions=(
+        "Run long shell commands as background tasks. Start a task, keep "
+        "working on other things, then poll its status and fetch the output "
+        "when it's done. Ideal for test suites, builds, scrapes, batch jobs — "
+        "anything too slow to wait for."
+    ),
+)
+manager = JobManager()
+
+
+@mcp.tool()
+def start_task(
+    command: str, cwd: str | None = None, timeout_seconds: float | None = None
+) -> dict:
+    """Start a shell command as a background task and return immediately.
+
+    Args:
+        command: The shell command to run (e.g. "pytest -q" or "npm run build").
+        cwd: Working directory for the command. Defaults to the server's cwd.
+        timeout_seconds: If set, the task is killed and marked 'timed_out'
+            when it runs longer than this. Recommended for unattended jobs.
+
+    Returns the new task's id and initial status. The command keeps running
+    after this call returns — use task_status / task_result to follow it.
+    """
+    return manager.start(command, cwd, timeout_seconds).to_dict()
+
+
+@mcp.tool()
+def task_status(task_id: str) -> dict:
+    """Check on a task: working, completed, failed, cancelled, timed_out, or interrupted."""
+    return manager.status(task_id).to_dict()
+
+
+@mcp.tool()
+def task_result(task_id: str, tail_lines: int = 100) -> dict:
+    """Get a task's captured output (stdout+stderr merged).
+
+    Args:
+        task_id: The task to inspect. Works for finished AND still-running
+            tasks, so you can peek at live progress.
+        tail_lines: How many trailing lines of output to return.
+    """
+    return manager.result(task_id, tail_lines)
+
+
+@mcp.tool()
+def cancel_task(task_id: str) -> dict:
+    """Cancel a running task, killing its whole process tree."""
+    return manager.cancel(task_id).to_dict()
+
+
+@mcp.tool()
+def list_tasks(limit: int = 20) -> list[dict]:
+    """List recent tasks, newest first."""
+    return [j.to_dict() for j in manager.list(limit)]
+
+
+def main() -> None:
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

backburner_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,20 @@
+[project]
+name = "backburner-mcp"
+version = "0.1.0"
+description = "An MCP server that lets AI agents run long jobs in the background and collect results later"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Rohit Yajee" }]
+keywords = ["mcp", "model-context-protocol", "background-jobs", "tasks", "agents"]
+dependencies = ["mcp>=1.26.0"]
+
+[project.scripts]
+backburner = "backburner.server:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["backburner"]

backburner_mcp-0.1.0/tests/conftest.py

@@ -0,0 +1,7 @@
+"""Point backburner at a throwaway data dir BEFORE the package is imported,
+so tests never touch the real ~/.backburner database."""
+
+import os
+import tempfile
+
+os.environ["BACKBURNER_HOME"] = tempfile.mkdtemp(prefix="backburner-test-")

backburner_mcp-0.1.0/tests/test_jobs.py

@@ -0,0 +1,161 @@
+import sys
+import time
+
+import pytest
+
+from backburner import jobs
+from backburner.jobs import (
+    CANCELLED, COMPLETED, FAILED, INTERRUPTED, TIMED_OUT, WORKING,
+    JobManager, check_command_allowed,
+)
+
+PY = sys.executable
+
+
+def wait_until_done(m: JobManager, job_id: str, timeout: float = 20.0):
+    deadline = time.time() + timeout
+    while time.time() < deadline:
+        job = m.status(job_id)
+        if job.status != WORKING:
+            return job
+        time.sleep(0.1)
+    pytest.fail(f"job {job_id} still working after {timeout}s")
+
+
+@pytest.fixture()
+def manager():
+    return JobManager()
+
+
+# --------------------------------------------------------------- lifecycle
+def test_successful_job_completes_with_output(manager):
+    job = manager.start(f'{PY} -c "print(\'hello quest\')"')
+    assert job.status == WORKING
+    done = wait_until_done(manager, job.id)
+    assert done.status == COMPLETED
+    assert done.exit_code == 0
+    result = manager.result(job.id)
+    assert "hello quest" in result["output"]
+
+
+def test_failing_job_reports_failed_and_exit_code(manager):
+    job = manager.start(f'{PY} -c "raise SystemExit(3)"')
+    done = wait_until_done(manager, job.id)
+    assert done.status == FAILED
+    assert done.exit_code == 3
+
+
+def test_cancel_kills_running_job(manager):
+    job = manager.start(f'{PY} -c "import time; time.sleep(60)"')
+    time.sleep(1.0)  # let the process actually start
+    manager.cancel(job.id)
+    done = wait_until_done(manager, job.id, timeout=10)
+    assert done.status == CANCELLED
+
+
+def test_cancel_finished_job_is_noop(manager):
+    job = manager.start(f'{PY} -c "print(1)"')
+    done = wait_until_done(manager, job.id)
+    again = manager.cancel(job.id)
+    assert again.status == done.status == COMPLETED
+
+
+def test_timeout_marks_job_timed_out(manager):
+    job = manager.start(
+        f'{PY} -c "import time; time.sleep(60)"', timeout_seconds=2
+    )
+    done = wait_until_done(manager, job.id, timeout=15)
+    assert done.status == TIMED_OUT
+
+
+def test_fast_job_beats_its_timeout(manager):
+    job = manager.start(f'{PY} -c "print(\'quick\')"', timeout_seconds=30)
+    done = wait_until_done(manager, job.id)
+    assert done.status == COMPLETED
+    # the pending timer must NOT later flip a finished job's status
+    time.sleep(0.5)
+    assert manager.status(job.id).status == COMPLETED
+
+
+# ------------------------------------------------------------- validation
+def test_unknown_task_id_raises(manager):
+    with pytest.raises(KeyError):
+        manager.status("nope1234")
+
+
+def test_bad_cwd_raises(manager):
+    with pytest.raises(ValueError):
+        manager.start("echo hi", cwd="Z:/definitely/not/a/dir")
+
+
+def test_nonpositive_timeout_raises(manager):
+    with pytest.raises(ValueError):
+        manager.start("echo hi", timeout_seconds=0)
+
+
+# ------------------------------------------------------------ result tail
+def test_result_tail_lines(manager):
+    job = manager.start(f'{PY} -c "[print(i) for i in range(50)]"')
+    wait_until_done(manager, job.id)
+    result = manager.result(job.id, tail_lines=5)
+    assert result["output_total_lines"] == 50
+    assert result["output"].splitlines() == ["45", "46", "47", "48", "49"]
+
+
+# ----------------------------------------------------------------- listing
+def test_list_returns_newest_first(manager):
+    a = manager.start(f'{PY} -c "print(\'a\')"')
+    time.sleep(0.05)
+    b = manager.start(f'{PY} -c "print(\'b\')"')
+    wait_until_done(manager, a.id)
+    wait_until_done(manager, b.id)
+    listed = [j.id for j in manager.list(limit=50)]
+    assert listed.index(b.id) < listed.index(a.id)
+
+
+# ------------------------------------------------------------ crash honesty
+def test_orphaned_jobs_marked_interrupted(manager):
+    job = manager.start(f'{PY} -c "import time; time.sleep(60)"')
+    # Simulate a server restart: a fresh manager finds the 'working' row
+    # but owns no process handle for it.
+    fresh = JobManager()
+    assert fresh.status(job.id).status == INTERRUPTED
+    manager.cancel(job.id)  # clean up the real process
+
+
+# ---------------------------------------------------------- command policy
+def test_deny_pattern_blocks_command(monkeypatch):
+    monkeypatch.setenv("BACKBURNER_DENY", r"rm\s+-rf,format")
+    with pytest.raises(PermissionError, match="deny pattern"):
+        check_command_allowed("rm -rf /")
+
+
+def test_allowlist_blocks_unlisted_command(monkeypatch):
+    monkeypatch.setenv("BACKBURNER_ALLOW", r"^pytest,^npm (test|run build)")
+    with pytest.raises(PermissionError, match="allow pattern"):
+        check_command_allowed("curl http://evil.example")
+
+
+def test_allowlist_permits_listed_command(monkeypatch):
+    monkeypatch.setenv("BACKBURNER_ALLOW", r"^pytest,^npm (test|run build)")
+    check_command_allowed("pytest -q tests/")
+    check_command_allowed("npm run build")
+
+
+def test_deny_wins_over_allow(monkeypatch):
+    monkeypatch.setenv("BACKBURNER_ALLOW", r".*")
+    monkeypatch.setenv("BACKBURNER_DENY", r"shutdown")
+    with pytest.raises(PermissionError):
+        check_command_allowed("shutdown /s /t 0")
+
+
+def test_no_policy_allows_anything(monkeypatch):
+    monkeypatch.delenv("BACKBURNER_ALLOW", raising=False)
+    monkeypatch.delenv("BACKBURNER_DENY", raising=False)
+    check_command_allowed("echo unrestricted")
+
+
+def test_start_enforces_policy(manager, monkeypatch):
+    monkeypatch.setenv("BACKBURNER_DENY", "forbidden")
+    with pytest.raises(PermissionError):
+        manager.start("echo forbidden-thing")

backburner_mcp-0.1.0/tests/test_server.py

@@ -0,0 +1,28 @@
+"""The MCP layer is thin by design; verify the contract it exposes."""
+
+import asyncio
+
+from backburner.server import mcp
+
+EXPECTED_TOOLS = {
+    "start_task", "task_status", "task_result", "cancel_task", "list_tasks",
+}
+
+
+def test_all_tools_registered():
+    tools = asyncio.run(mcp.list_tools())
+    assert {t.name for t in tools} == EXPECTED_TOOLS
+
+
+def test_every_tool_has_a_description():
+    tools = asyncio.run(mcp.list_tools())
+    for tool in tools:
+        assert tool.description and len(tool.description) > 20, tool.name
+
+
+def test_start_task_accepts_timeout_parameter():
+    tools = {t.name: t for t in asyncio.run(mcp.list_tools())}
+    props = tools["start_task"].inputSchema["properties"]
+    assert "timeout_seconds" in props
+    assert "command" in props
+    assert "cwd" in props