lemming-cli 0.3.4__tar.gz → 0.4.0__tar.gz

{lemming_cli-0.3.4 → lemming_cli-0.4.0}/.gitignore

@@ -5,6 +5,7 @@ dist/
 build/
 *.egg-info/
 tasks.yml
+tasks.yml.corrupt*
 *.swp
 node_modules/
 .biome/

{lemming_cli-0.3.4 → lemming_cli-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: lemming-cli
-Version: 0.3.4
+Version: 0.4.0
 Summary: An autonomous, iterative task runner for AI coding agents.
 Project-URL: Homepage, https://github.com/owahltinez/lemming
 Project-URL: Repository, https://github.com/owahltinez/lemming
@@ -15,7 +15,7 @@ Requires-Dist: fastapi>=0.124.4
 Requires-Dist: markdownify>=0.14.1
 Requires-Dist: pydantic>=2.12.5
 Requires-Dist: pyyaml>=6.0.3
-Requires-Dist: readability-cli>=0.5.0
+Requires-Dist: readability-cli>=0.7.0
 Requires-Dist: requests>=2.32.3
 Requires-Dist: uvicorn>=0.33.0
 Description-Content-Type: text/markdown
@@ -102,6 +102,71 @@ lemming run -- --model claude-3-5-sonnet
 
 ---
 
+## One-Off Tasks Without a Roadmap
+
+`lemming exec` runs a single task and exits. It is the same agent-CLI
+normalization the orchestrator uses, addressable on its own: name a task and a
+runner, and the agent's closing message comes back on stdout.
+
+```bash
+# Delegate one task to a different agent, e.g. to spare another's quota
+lemming exec "Fix the flaky test in runner_test.py" --runner codex
+
+# Pipe a longer handoff instead of fighting shell quoting
+cat handoff.md | lemming exec -f - --runner agy
+```
+
+With no description there is nothing for a task runner to do, so only the
+reviews run — against work that already exists.
+
+```bash
+# Review uncommitted work before opening a pull request
+lemming exec --review readability
+
+# Review someone else's branch, checked out in a worktree
+lemming exec -C ../review-worktree --review testing --scope main...HEAD
+
+# Do the work, then gate it
+lemming exec "Add pagination to the tasks API" --review all
+```
+
+`--scope` takes paths, which pass through untouched, or a git revision range,
+which is resolved to the files it changed. It defaults to uncommitted work, or
+to the whole tree outside a git repository.
+
+Each run is self-contained: nothing is read from the project's roadmap or its
+local hooks, one agent run is attempted, and the run's state directory is
+removed unless it failed — in which case it is kept, and its path printed, so
+the log can be read. Kept directories live in `~/.local/lemming/exec-*` and
+are retired automatically a week later, so a recent failure is always still
+there to inspect. Stdout carries the agent's message alone and everything
+else goes to stderr, so the output can be consumed directly.
+
+Note that the agent runs unattended (`--yolo` by default), so it does not
+inherit the permission prompts of whatever launched it.
+
+### Teaching Your Agent to Use It
+
+Lemming ships an Agent Skill so that an agent already running — Claude Code,
+Gemini CLI, Cursor — can reach any other agent CLI without knowing how each
+one spells its flags. Install it once:
+
+```bash
+# Cross-tool location (~/.agents/skills), and report any tool-specific ones
+lemming skill install
+
+# Cover every agent tool detected on this machine
+lemming skill install --all
+
+# This repository only
+lemming skill install --to .agents/skills
+```
+
+`lemming skill uninstall` reverses it. Both refuse to touch a directory that
+does not hold this skill, so a mistyped `--to` fails instead of deleting work.
+
+---
+
 ## The Web Dashboard
 
 Lemming includes a modern, fast Web UI to monitor your projects.
@@ -244,6 +309,17 @@ See [docs/EVALS.md](docs/EVALS.md) for details.
 
 ## Command Reference
 
+### Global Options
+
+These come before the subcommand and apply to all of them.
+
+- **`-C, --project-dir <dir>`**: Run as if invoked from `<dir>`, addressing
+  that project's roadmap. Relative paths in other options resolve against it.
+  See [Working across projects](#working-across-projects).
+- **`--tasks-file <path>`**: Point at a specific tasks file instead of the one
+  derived from the current directory.
+- **`-v, --verbose`**: Show verbose output.
+
 ### Roadmap Management
 
 - **`status [<id>]`**: Queue/history overview or deep-dive into a specific
@@ -317,6 +393,33 @@ See [docs/EVALS.md](docs/EVALS.md) for details.
   - `--no-defaults`: Skip default flag injection for known runners.
   - `--`: Use `--` to pass any flag directly to the underlying runner. A
     per-task `--runner`/`--model` overrides anything passed here.
+- **`exec [<description>]`**: Run one task, or one set of reviews, outside any
+  roadmap. Prints the agent's closing message to stdout and everything else to
+  stderr. Exits non-zero if the task did not complete. See
+  [One-off tasks](#one-off-tasks-without-a-roadmap).
+  - `-f/--file`: Read the description from a file, or `-` for stdin. Unlike
+    `add`, there is no length cap.
+  - `--review <names>`: Reviews to run after the task, comma-separated or
+    repeated; `all` selects every one. With no description, only the reviews
+    run. Hooks that revise the roadmap cannot be selected.
+  - `--scope <path|range>`: What the reviews look at. Paths pass through; a
+    git revision range is resolved to the files it changed. Defaults to
+    uncommitted work, or the whole tree outside a repository.
+  - `--runner`, `--model`: Which agent CLI and model to use.
+  - `--time-limit`: Minutes before the agent is killed (default 60, 0 for no
+    limit).
+  - `--yolo/--no-yolo`: Run the agent unattended (default: True).
+  - `--keep`: Keep the run's state directory even when it succeeds.
+- **`skill install`**: Install the packaged Agent Skill so agents discover
+  Lemming. Writes to `~/.agents/skills` by default and names any tool-specific
+  directories it found.
+  - `--to <dir>`: Install into a specific skills directory.
+  - `--all`: Also cover every detected tool's own skills directory.
+  - `--link`: Symlink instead of copying, so upgrades take effect immediately.
+  - `--force`: Replace an existing installation of this skill.
+  - `--dry-run`: Print what would happen, refusals included.
+- **`skill uninstall`**: Remove it again. Same `--to`, `--all`, and
+  `--dry-run`.
 - **`stop`**: Stop the running loop and its runner.
   - `--after-current-task`: Drain instead — let the running task finish, then
     stop before claiming another. This is the safe way to change the runner
@@ -331,6 +434,36 @@ See [docs/EVALS.md](docs/EVALS.md) for details.
 
 ---
 
+## Working across projects
+
+When work on one project turns up something that belongs to another — a bug in
+a dependency you also maintain, a doc fix in a sibling repo — file it directly
+on that project's roadmap with `-C` instead of routing it through an external
+issue tracker:
+
+```bash
+# From inside project A, queue work on project B
+lemming -C ~/src/other-project add "check --fix drops the trailing newline"
+
+# Attach the evidence; the brief has no length cap
+lemming -C ~/src/other-project brief <id> --file repro.md
+
+# Read the other project's roadmap without leaving yours
+lemming -C ~/src/other-project status
+```
+
+`-C` works whether or not the target keeps a `tasks.yml` in its repo, so you
+never have to know where its isolated state lives. Because it changes the
+working directory, everything else follows too: the target's `.env`, its
+`.lemming/hooks`, and the directory the runner executes in.
+
+When an agent files a task this way from inside a `lemming run`, the new task
+records the task it came from via `parent` and `parent_tasks_file`. The
+downstream runner then sees a **Parent Task Context** section in its prompt
+describing why the work was requested, so the report doesn't lose its origin.
+
+---
+
 ## Advanced: Runner Customization
 
 Lemming uses **fuzzy matching** to automatically inject the correct "YOLO"

{lemming_cli-0.3.4 → lemming_cli-0.4.0}/README.md

@@ -80,6 +80,71 @@ lemming run -- --model claude-3-5-sonnet
 
 ---
 
+## One-Off Tasks Without a Roadmap
+
+`lemming exec` runs a single task and exits. It is the same agent-CLI
+normalization the orchestrator uses, addressable on its own: name a task and a
+runner, and the agent's closing message comes back on stdout.
+
+```bash
+# Delegate one task to a different agent, e.g. to spare another's quota
+lemming exec "Fix the flaky test in runner_test.py" --runner codex
+
+# Pipe a longer handoff instead of fighting shell quoting
+cat handoff.md | lemming exec -f - --runner agy
+```
+
+With no description there is nothing for a task runner to do, so only the
+reviews run — against work that already exists.
+
+```bash
+# Review uncommitted work before opening a pull request
+lemming exec --review readability
+
+# Review someone else's branch, checked out in a worktree
+lemming exec -C ../review-worktree --review testing --scope main...HEAD
+
+# Do the work, then gate it
+lemming exec "Add pagination to the tasks API" --review all
+```
+
+`--scope` takes paths, which pass through untouched, or a git revision range,
+which is resolved to the files it changed. It defaults to uncommitted work, or
+to the whole tree outside a git repository.
+
+Each run is self-contained: nothing is read from the project's roadmap or its
+local hooks, one agent run is attempted, and the run's state directory is
+removed unless it failed — in which case it is kept, and its path printed, so
+the log can be read. Kept directories live in `~/.local/lemming/exec-*` and
+are retired automatically a week later, so a recent failure is always still
+there to inspect. Stdout carries the agent's message alone and everything
+else goes to stderr, so the output can be consumed directly.
+
+Note that the agent runs unattended (`--yolo` by default), so it does not
+inherit the permission prompts of whatever launched it.
+
+### Teaching Your Agent to Use It
+
+Lemming ships an Agent Skill so that an agent already running — Claude Code,
+Gemini CLI, Cursor — can reach any other agent CLI without knowing how each
+one spells its flags. Install it once:
+
+```bash
+# Cross-tool location (~/.agents/skills), and report any tool-specific ones
+lemming skill install
+
+# Cover every agent tool detected on this machine
+lemming skill install --all
+
+# This repository only
+lemming skill install --to .agents/skills
+```
+
+`lemming skill uninstall` reverses it. Both refuse to touch a directory that
+does not hold this skill, so a mistyped `--to` fails instead of deleting work.
+
+---
+
 ## The Web Dashboard
 
 Lemming includes a modern, fast Web UI to monitor your projects.
@@ -222,6 +287,17 @@ See [docs/EVALS.md](docs/EVALS.md) for details.
 
 ## Command Reference
 
+### Global Options
+
+These come before the subcommand and apply to all of them.
+
+- **`-C, --project-dir <dir>`**: Run as if invoked from `<dir>`, addressing
+  that project's roadmap. Relative paths in other options resolve against it.
+  See [Working across projects](#working-across-projects).
+- **`--tasks-file <path>`**: Point at a specific tasks file instead of the one
+  derived from the current directory.
+- **`-v, --verbose`**: Show verbose output.
+
 ### Roadmap Management
 
 - **`status [<id>]`**: Queue/history overview or deep-dive into a specific
@@ -295,6 +371,33 @@ See [docs/EVALS.md](docs/EVALS.md) for details.
   - `--no-defaults`: Skip default flag injection for known runners.
   - `--`: Use `--` to pass any flag directly to the underlying runner. A
     per-task `--runner`/`--model` overrides anything passed here.
+- **`exec [<description>]`**: Run one task, or one set of reviews, outside any
+  roadmap. Prints the agent's closing message to stdout and everything else to
+  stderr. Exits non-zero if the task did not complete. See
+  [One-off tasks](#one-off-tasks-without-a-roadmap).
+  - `-f/--file`: Read the description from a file, or `-` for stdin. Unlike
+    `add`, there is no length cap.
+  - `--review <names>`: Reviews to run after the task, comma-separated or
+    repeated; `all` selects every one. With no description, only the reviews
+    run. Hooks that revise the roadmap cannot be selected.
+  - `--scope <path|range>`: What the reviews look at. Paths pass through; a
+    git revision range is resolved to the files it changed. Defaults to
+    uncommitted work, or the whole tree outside a repository.
+  - `--runner`, `--model`: Which agent CLI and model to use.
+  - `--time-limit`: Minutes before the agent is killed (default 60, 0 for no
+    limit).
+  - `--yolo/--no-yolo`: Run the agent unattended (default: True).
+  - `--keep`: Keep the run's state directory even when it succeeds.
+- **`skill install`**: Install the packaged Agent Skill so agents discover
+  Lemming. Writes to `~/.agents/skills` by default and names any tool-specific
+  directories it found.
+  - `--to <dir>`: Install into a specific skills directory.
+  - `--all`: Also cover every detected tool's own skills directory.
+  - `--link`: Symlink instead of copying, so upgrades take effect immediately.
+  - `--force`: Replace an existing installation of this skill.
+  - `--dry-run`: Print what would happen, refusals included.
+- **`skill uninstall`**: Remove it again. Same `--to`, `--all`, and
+  `--dry-run`.
 - **`stop`**: Stop the running loop and its runner.
   - `--after-current-task`: Drain instead — let the running task finish, then
     stop before claiming another. This is the safe way to change the runner
@@ -309,6 +412,36 @@ See [docs/EVALS.md](docs/EVALS.md) for details.
 
 ---
 
+## Working across projects
+
+When work on one project turns up something that belongs to another — a bug in
+a dependency you also maintain, a doc fix in a sibling repo — file it directly
+on that project's roadmap with `-C` instead of routing it through an external
+issue tracker:
+
+```bash
+# From inside project A, queue work on project B
+lemming -C ~/src/other-project add "check --fix drops the trailing newline"
+
+# Attach the evidence; the brief has no length cap
+lemming -C ~/src/other-project brief <id> --file repro.md
+
+# Read the other project's roadmap without leaving yours
+lemming -C ~/src/other-project status
+```
+
+`-C` works whether or not the target keeps a `tasks.yml` in its repo, so you
+never have to know where its isolated state lives. Because it changes the
+working directory, everything else follows too: the target's `.env`, its
+`.lemming/hooks`, and the directory the runner executes in.
+
+When an agent files a task this way from inside a `lemming run`, the new task
+records the task it came from via `parent` and `parent_tasks_file`. The
+downstream runner then sees a **Parent Task Context** section in its prompt
+describing why the work was requested, so the report doesn't lose its origin.
+
+---
+
 ## Advanced: Runner Customization
 
 Lemming uses **fuzzy matching** to automatically inject the correct "YOLO"

lemming_cli-0.4.0/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: lemming
+description: Delegate a single coding task to another AI agent CLI (agy, claude, codex) through one interface, or run a code review — readability, testing, UX — over changed files, a PR branch, or a path. Use when handing work to a different agent to spare a quota or play to its strengths, or when reviewing a diff before opening a pull request. Not for driving a multi-task project; that is a roadmap.
+license: MIT
+---
+
+# lemming
+
+One interface over several agent CLIs. You do not need to know how `agy`,
+`claude`, or `codex` spell their flags — only `lemming exec`.
+
+## Delegate one task
+
+```sh
+lemming exec "Fix the flaky heartbeat test in src/runner_test.py" --runner codex
+```
+
+The agent's closing message comes back on **stdout**; progress and the event
+trace go to stderr. Exit code is 0 only if the task completed. That message is
+the return value — read it instead of hunting through logs.
+
+Pipe a longer handoff rather than fighting shell quoting. There is no length
+limit, unlike a roadmap task description:
+
+```sh
+cat handoff.md | lemming exec -f - --runner agy
+```
+
+Delegate when another agent's quota, price, or strengths suit the work better
+than yours. Give the task everything it needs: it starts with an empty context
+and sees nothing of your conversation.
+
+## Run a review
+
+With no description there is nothing for a task runner to do, so only the
+reviews run — against work that already exists.
+
+```sh
+lemming exec --review readability          # uncommitted work
+lemming exec --review testing --scope main...HEAD
+lemming exec --review all --scope src/api/
+lemming exec "Add pagination" --review all # do the work, then gate it
+```
+
+`--scope` takes paths, which pass through untouched, or a git revision range,
+which is resolved to the files it changed. It defaults to uncommitted work.
+A clean tree stops the run rather than reviewing everything.
+
+Reviews **edit the workspace**: readability applies fixes and reruns checks.
+That is the point — but it means a review is not read-only.
+
+## Reviewing someone else's branch
+
+Check it out in a worktree so your own tree is untouched, and point `-C` at it:
+
+```sh
+git worktree add /tmp/pr-123 && (cd /tmp/pr-123 && gh pr checkout 123)
+lemming -C /tmp/pr-123 exec --review testing --scope main...HEAD
+```
+
+## What to know before running it
+
+- **The agent runs unattended.** `--yolo` is the default, so it does not
+  inherit the permission prompts of whatever launched it. Treat `lemming exec`
+  as granting an agent unsupervised write access to the working directory.
+- **One agent run, no retry.** A failure is final; it does not silently try
+  again. `--time-limit` caps the wall clock (default 60 minutes).
+- **Interrupting leaves partial edits.** The workspace is not restored, so
+  there is no atomicity to rely on.
+- **Failures keep their log.** The state directory path is printed on stderr;
+  read it with `lemming logs` pointed at that tasks file.
+
+## Running several at once
+
+Concurrent runs in one checkout will interleave their edits. Give each write
+task its own worktree and address it with `-C`. Read-only work parallelizes
+safely as-is.
+
+## When not to use it
+
+`exec` is for one unit of work. Anything needing more context than a single
+agent run can hold — a migration across a large codebase, a multi-step feature
+— belongs on a roadmap: `lemming add`, then `lemming run`. In particular,
+`--scope .` over a large repository *samples*; it does not cover.
+
+Run `lemming exec --help` for the full flag list.

{lemming_cli-0.3.4 → lemming_cli-0.4.0}/docs/HOOKS.md

@@ -158,6 +158,9 @@ Your hook template can use the following placeholders:
   description, recent progress, and a recent execution-log excerpt capped at
   16 KiB).
 - `{{finished_task_id}}`: The ID of the task that just finished.
+- `{{scope}}`: What the hook should look at, and how broadly. Under `lemming
+  run` this names the work the finished task left behind; under `lemming exec
+  --review` it is whatever `--scope` resolved to.
 - `{{tasks_file_name}}`: The filename of the tasks YAML file.
 - `{{tasks_file_path}}`: The full path to the tasks YAML file.
 
@@ -166,6 +169,12 @@ over older completed history. Readability, testing, and UX hooks receive a
 smaller roadmap summary because their primary context is the finished task and
 the workspace.
 
+A review hook should take its breadth from `{{scope}}` rather than narrowing
+itself in prose. Hardcoding "the files changed in the last task" makes the hook
+unusable outside the orchestrator loop, where there is no last task. Depth
+limits are different and belong in the prompt: "verification, not a security
+audit" describes the kind of review, not its extent.
+
 ## Developer Ergonomics
 
 ### Listing Hooks

{lemming_cli-0.3.4 → lemming_cli-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "lemming-cli"
-version = "0.3.4"
+version = "0.4.0"
 description = "An autonomous, iterative task runner for AI coding agents."
 readme = "README.md"
 authors = [
@@ -20,7 +20,7 @@ dependencies = [
     "markdownify>=0.14.1",
     "pydantic>=2.12.5",
     "pyyaml>=6.0.3",
-    "readability-cli>=0.5.0",
+    "readability-cli>=0.7.0",
     "requests>=2.32.3",
     "uvicorn>=0.33.0",
 ]
@@ -50,6 +50,11 @@ allow-direct-references = true
 [tool.hatch.build.targets.wheel]
 packages = ["src/lemming"]
 
+# SKILL.md is authored at the repository root, where it stays visible, and
+# mapped into the package so `lemming skill install` can find it in a wheel.
+[tool.hatch.build.targets.wheel.force-include]
+"SKILL.md" = "lemming/skills/lemming/SKILL.md"
+
 [tool.ruff]
 line-length = 80
 

lemming_cli-0.4.0/src/lemming/api/auth.py

@@ -0,0 +1,57 @@
+"""Share-token authentication middleware for remotely shared servers."""
+
+import secrets
+
+import fastapi
+
+
+def _token_matches(candidate: str | None, share_token: str) -> bool:
+    """Compares a client-supplied token against the share token.
+
+    Args:
+        candidate: Token from the request, or None when absent.
+        share_token: The token this server requires.
+
+    Returns:
+        True when the candidate matches.
+    """
+    if candidate is None:
+        return False
+
+    # Encode first: compare_digest rejects non-ASCII str outright, which a
+    # client could otherwise turn into a 500 by sending one.
+    return secrets.compare_digest(candidate.encode(), share_token.encode())
+
+
+async def share_token_middleware(request: fastapi.Request, call_next):
+    """Require a share token for every request when one is configured.
+
+    Accepts the token via the ``token`` query parameter (persisting it in a
+    cookie) or via the ``lemming_share_token`` cookie. Returns 401 when the
+    token is missing or invalid.
+
+    There is deliberately no local-request exemption. A token is only set in
+    tunnel mode, so this is already inert locally, and both a client-supplied
+    ``Host`` header and the peer address are forgeable or misleading behind a
+    tunnel (the tunnel daemon reaches the origin over loopback, so every
+    public request also appears to come from 127.0.0.1). Requiring the token
+    unconditionally keeps correctness independent of how each tunnel provider
+    handles those.
+    """
+    share_token = getattr(request.app.state, "share_token", None)
+    if not share_token:
+        return await call_next(request)
+
+    token = request.query_params.get("token")
+    if _token_matches(token, share_token):
+        response = await call_next(request)
+        response.set_cookie(
+            key="lemming_share_token", value=token, httponly=True
+        )
+        return response
+
+    cookie_token = request.cookies.get("lemming_share_token")
+    if _token_matches(cookie_token, share_token):
+        return await call_next(request)
+
+    return fastapi.Response("Unauthorized", status_code=401)

lemming_cli-0.4.0/src/lemming/api/auth_test.py

@@ -0,0 +1,73 @@
+import fastapi.testclient
+
+from lemming import api
+
+
+def test_share_token_middleware():
+    # Setup test client
+    original_token = getattr(api.app.state, "share_token", None)
+    try:
+        api.app.state.share_token = "secret123"
+        # We need a fresh client for each test that modifies app state
+        # middleware if it uses the app state, but here TestClient is
+        # created with api.app
+        client = fastapi.testclient.TestClient(api.app)
+
+        # Missing token -> 401
+        response = client.get("/api/data")
+        assert response.status_code == 401
+
+        # Valid token via query
+        response = client.get("/api/data?token=secret123")
+        assert response.status_code == 200
+        assert "lemming_share_token=secret123" in response.headers.get(
+            "set-cookie", ""
+        )
+
+        # Valid token via cookie
+        client.cookies.set("lemming_share_token", "secret123")
+        response = client.get("/api/data")
+        assert response.status_code == 200
+
+        # A client-supplied local host header must not bypass the token
+        client.cookies.clear()
+        for host in ("127.0.0.1:8999", "localhost:8999", "localhost"):
+            response = client.get("/api/data", headers={"host": host})
+            assert response.status_code == 401, host
+    finally:
+        # Restore
+        api.app.state.share_token = original_token
+
+
+def test_share_token_middleware_rejects_exotic_tokens():
+    """Odd tokens must be rejected, not crash the comparison."""
+    original_token = getattr(api.app.state, "share_token", None)
+    try:
+        api.app.state.share_token = "secret123"
+        client = fastapi.testclient.TestClient(api.app)
+
+        # Non-ASCII and differing lengths must stay a clean 401. A digest
+        # comparison rejects both only if the values are encoded first.
+        for token in ("sécret123", "secret1234567890", "s", ""):
+            response = client.get("/api/data", params={"token": token})
+            assert response.status_code == 401, token
+    finally:
+        # Restore
+        api.app.state.share_token = original_token
+
+
+def test_share_token_middleware_inert_without_token():
+    """Local (non-tunnel) mode sets no share token, so nothing is required."""
+    original_token = getattr(api.app.state, "share_token", None)
+    try:
+        api.app.state.share_token = None
+        client = fastapi.testclient.TestClient(api.app)
+
+        response = client.get("/api/data")
+        assert response.status_code == 200
+        assert "lemming_share_token" not in response.headers.get(
+            "set-cookie", ""
+        )
+    finally:
+        # Restore
+        api.app.state.share_token = original_token

{lemming_cli-0.3.4 → lemming_cli-0.4.0}/src/lemming/api/main.py

@@ -1,16 +1,19 @@
 """FastAPI application setup: middleware, routers, and static files."""
 
 import importlib.resources
+import logging
 import pathlib
 
 import fastapi
 import fastapi.responses
 import fastapi.staticfiles
 
-from .. import paths
+from .. import paths, persistence
 from . import auth, config, directories, files, hooks, tasks
 from . import logging as lemming_logging
 
+logger = logging.getLogger(__name__)
+
 # Re-exported so logging configs can reference lemming.api.QuietPollFilter
 QuietPollFilter = lemming_logging.QuietPollFilter
 
@@ -40,6 +43,22 @@ app.include_router(directories.router)
 app.include_router(hooks.router)
 app.include_router(config.router)
 
+
+@app.exception_handler(persistence.CorruptedTasksError)
+def handle_corrupted_tasks(
+    request: fastapi.Request, exc: Exception
+) -> fastapi.responses.JSONResponse:
+    """Reports an unreadable tasks file in the shape the UI already expects.
+
+    Without this every route touching the roadmap would answer a corrupt file
+    with a raw stack trace instead of an actionable message.
+    """
+    logger.error("%s could not read the tasks file: %s", request.url.path, exc)
+    return fastapi.responses.JSONResponse(
+        status_code=500, content={"detail": str(exc)}
+    )
+
+
 # Static files and root routes
 web_dir = pathlib.Path(
     str(importlib.resources.files("lemming").joinpath("web"))