taskops-cli 0.2.0__py3-none-any.whl

taskops/usecases/report.py

@@ -0,0 +1,87 @@
+"""`taskops_report` — the projections, and the window parsing that feeds them.
+
+The reports are generated from the log and never written by hand, which is the whole
+claim: a standup nobody typed cannot be out of date, and it cannot flatter anybody
+either. What this module owns is turning a human's `24h` into a timestamp.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from .._clock import now
+from .._errors import BadRequest
+from ..contracts import Activity, Board, DayReport, Fleet, PeriodReport, Standup
+from ..engine import activity as build_activity
+from ..engine import board as build_board
+from ..engine import day_report as build_day
+from ..engine import fleet as build_fleet
+from ..engine import period_report as build_period
+from ..engine import standup as build_standup
+from ._project import project
+from ._range import Selector, parse_date, resolve
+
+__all__ = ["board", "standup", "fleet", "activity", "day", "period", "parse_window",
+           "parse_date", "DEFAULT_WINDOW", "HISTORY_WINDOW"]
+
+DEFAULT_WINDOW = "24h"
+
+HISTORY_WINDOW = "30d"
+"""The activity view's default. Wider than a standup's on purpose: one asks what happened since
+yesterday, the other is where somebody goes to find out what was ever done here."""
+
+_UNITS = {"m": 60.0, "h": 3600.0, "d": 86400.0, "w": 604800.0}
+
+
+def board(start: Path | str) -> Board:
+    with project(start) as store:
+        return build_board(store)
+
+
+def standup(start: Path | str, *, since: str = DEFAULT_WINDOW, actor: str = "") -> Standup:
+    with project(start) as store:
+        return build_standup(store, since=now() - parse_window(since), actor=actor)
+
+
+def activity(start: Path | str, *, since: str = HISTORY_WINDOW) -> Activity:
+    with project(start) as store:
+        return build_activity(store, since=now() - parse_window(since))
+
+
+def fleet(start: Path | str) -> Fleet:
+    with project(start) as store:
+        return build_fleet(store)
+
+
+def day(start: Path | str, date_text: str = "") -> DayReport:
+    with project(start) as store:
+        return build_day(store, parse_date(date_text))
+
+
+def period(start: Path | str, sel: Selector | None = None) -> PeriodReport:
+    """The report over whatever window the selector names — a day, a week, or all of it.
+
+    `day` above is this with both ends on the same date; keeping it as its own name is for
+    the callers that only ever want one, not a second code path.
+    """
+    with project(start) as store:
+        return build_period(store, *resolve(store, sel or Selector()))
+
+
+
+
+def parse_window(text: str) -> float:
+    """`24h` -> 86400.0. Raises on anything it cannot read.
+
+    Strict rather than defaulting, unlike most readers here: a window silently read as
+    24 hours when the caller wrote `7days` produces a report that is WRONG and looks
+    right, and a standup that quietly covers the wrong period is worse than an error.
+    """
+    raw = text.strip().lower()
+    if not raw:
+        return parse_window(DEFAULT_WINDOW)
+    number, unit = raw[:-1], raw[-1:]
+    if unit not in _UNITS or not number.isdigit() or int(number) <= 0:
+        raise BadRequest(f"`{text}` is not a window — use a positive number then "
+                         f"one of {', '.join(sorted(_UNITS))}, e.g. 24h or 7d")
+    return int(number) * _UNITS[unit]

taskops/usecases/reportfile.py

@@ -0,0 +1,106 @@
+"""Moving a written report between machines WITHOUT losing a narration.
+
+The dossier in a report is regenerable — it is a rendering of the log, and the log replicates.
+The NARRATION is not. It is prose a model wrote once, or a person edited by hand, and there is
+no second copy anywhere. So this is the one thing in taskops that syncs with a rule instead of
+a union, and the rule is built to fail LOUD rather than to be clever.
+
+The rule, in the order it is applied:
+
+1. The server does not have the file → store it.
+2. Byte-identical to what we have → store it (a no-op, so a re-push is quiet).
+3. Both sides carry a stamp and theirs is HIGHER → store it. A higher `max_seq` means that
+   copy was generated over more of the log, so it is the later account of the same day.
+4. Anything else → `ReportConflict`, carrying both stamps. That covers theirs being older,
+   the two being equal but different, and either side being UNSTAMPED — an unstamped file was
+   written or edited outside taskops, which is precisely the copy nobody may clobber.
+
+`force` skips straight to storing, and the refusal says what would be lost so the person
+choosing has the sentence in front of them.
+
+**The server NEVER regenerates.** It serves the bytes it has. Regenerating belongs to the
+machine that owns the store, because a regeneration here would replace somebody's prose with a
+fresh dossier and report success.
+
+**The honest limit of comparing stamps.** `max_seq` is each sqlite's own numbering, so two
+machines' stamps are not rigorously comparable. In the real flow they are close enough to be
+useful — a report is narrated against ONE store, and after a sync the server's seqs dominate —
+which makes rule 3 a heuristic for "who saw more". The pathological case is two independent
+narrations of the same day written on two machines that never synced; those land in rule 4,
+which is the honest answer, and `force` is the valve.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from .._errors import BadRequest, ReportConflict
+from ..engine import NO_STAMP, stamped_seq
+from ._project import project
+from .dossier import report_path
+
+__all__ = ["read_report_file", "write_report_file"]
+
+_ALLOWED = set("0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ-_.")
+"""Labels are `2026-07-28`, `2026-07-22..2026-07-28`, `all`. A separator can never appear, so
+a label from the network cannot address a path outside `.taskops/reports/`."""
+
+
+def read_report_file(start: Path | str, label: str) -> dict[str, Any] | None:
+    """The bytes on disk for one label, with the stamp they carry. None if there is no file.
+
+    None and not a generated dossier: the caller is a replication client deciding whether to
+    push, and answering with a report this server never wrote would make it believe there is
+    something here to lose.
+    """
+    with project(start) as store:
+        path = report_path(store.root, _checked(label))
+        if not path.is_file():
+            return None
+        content = path.read_text(encoding="utf-8")
+        return {"label": label, "content": content, "max_seq": stamped_seq(content)}
+
+
+def write_report_file(start: Path | str, label: str, content: str, *,
+                      force: bool = False) -> dict[str, bool]:
+    """Apply the rule above. Returns `{"stored": True}` or raises `ReportConflict`."""
+    with project(start) as store:
+        path = report_path(store.root, _checked(label))
+        current = path.read_text(encoding="utf-8") if path.is_file() else None
+        if force or current is None or current == content:
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_text(content, encoding="utf-8")
+            return {"stored": True}
+        ours, theirs = stamped_seq(current), stamped_seq(content)
+        if ours != NO_STAMP and theirs > ours:
+            path.write_text(content, encoding="utf-8")
+            return {"stored": True}
+        raise _conflict(label, ours=ours, theirs=theirs)
+
+
+def _conflict(label: str, *, ours: int, theirs: int) -> ReportConflict:
+    """The refusal, with the sentence that names what the caller is actually looking at."""
+    clash = ReportConflict(f"{label}: {_why(ours, theirs)} — read this server's copy first, "
+                           f"or push again with force (its narration is then lost)")
+    clash.ours, clash.theirs = ours, theirs
+    return clash
+
+
+def _why(ours: int, theirs: int) -> str:
+    if NO_STAMP in (ours, theirs):
+        return ("one of the two copies carries no taskops stamp, so it was written or edited "
+                "by hand and nothing can tell which is newer")
+    if ours == theirs:
+        return (f"two different narrations of the same report, both generated at seq {ours} — "
+                f"prose cannot be merged and nobody here can pick")
+    return (f"this server's copy was generated at seq {ours} and yours at {theirs}, so yours "
+            f"saw LESS of the log")
+
+
+def _checked(label: str) -> str:
+    text = label.strip()
+    if not text or text.startswith(".") or not set(text) <= _ALLOWED:
+        raise BadRequest(f"{label!r} is not a report label — it names a file in "
+                         f".taskops/reports/, like `2026-07-28` or `all`")
+    return text

taskops/usecases/session.py

@@ -0,0 +1,134 @@
+"""A session opening and closing — and how a message reaches another agent.
+
+Claude Code cannot be pushed to mid-turn: a session only ever "listens" when a hook
+fires. That is the constraint the whole delivery design follows from, and it is worth
+stating plainly rather than pretending otherwise.
+
+```
+SessionStart  -> brief()     the agent starts knowing its tasks and its messages
+PostToolUse   -> inbox()     anything that arrived since lands in its next tool call
+Stop          -> checkout()  its work becomes a comment on the task, unprompted
+```
+
+So "real time" here means: within one tool call of the sender writing it, which for a
+working agent is seconds. The human-facing real time is the studio, which sees the
+event the moment it is committed.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from .._clock import now
+from ..contracts import Event, Inbox, Lease
+from ..engine import record
+from ..storage import Store
+from ._project import caller, heartbeat, project
+from .view import inbox_for
+
+__all__ = ["brief", "inbox", "checkout", "track", "Brief"]
+
+
+class Brief:
+    """What a session needs to know before its first prompt."""
+
+    def __init__(self, *, actor: str, session: str, held: list[Lease],
+                 messages: list[Event], ready: int) -> None:
+        self.actor = actor
+        self.session = session
+        self.held = held
+        self.messages = messages
+        self.ready = ready
+
+
+def brief(start: Path | str, *, session: str = "", actor: str = "") -> Brief:
+    """The SessionStart read: who am I, what do I hold, who spoke to me.
+
+    Leases held by this SESSION are re-associated on resume: Claude Code re-runs
+    SessionStart with `source=resume`, and without this an agent that resumed would
+    look like a new actor holding nothing while its claims sat there.
+    """
+    with project(start) as store:
+        who = caller(store, actor)["id"]
+        heartbeat(store, who)
+        held = store.leases.of_actor(who, now())
+        if session:
+            _adopt(store, held, session)
+        return Brief(actor=who, session=session, held=held,
+                     messages=inbox_for(store, who)["messages"],
+                     ready=len(store.tasks.with_status(("ready",))))
+
+
+def _adopt(store: Store, held: list[Lease], session: str) -> None:
+    """Point this actor's leases at the session that is now running them.
+
+    A resumed session gets a NEW id, so the lease's old one names a process that is gone
+    — and the live board would show a claim whose transcript nobody can open.
+    """
+    for lease in held:
+        if lease["session"] != session:
+            store.leases.set_session(task_id=lease["task"], session=session)
+
+
+def inbox(start: Path | str, *, actor: str = "") -> Inbox:
+    """The PostToolUse read: messages this actor has not seen, marked delivered.
+
+    Cheap on purpose — one indexed query and usually zero rows. It runs after every
+    tool call an agent makes, so anything expensive here is a tax on all of its work.
+    """
+    with project(start) as store:
+        who = caller(store, actor)["id"]
+        heartbeat(store, who)
+        return inbox_for(store, who)
+
+
+def track(start: Path | str, *, summary: str, task: str = "", actor: str = "",
+          session: str = "") -> Event | None:
+    """The heartbeat with content: what tool touched what file, for the live board.
+
+    It also STAMPS the session id onto the actor's leases, and that half is what makes a conversation
+    findable. A dispatched worker is easy — it runs in a per-card worktree, so its transcript has a
+    directory of its own. A card worked on interactively has neither, and every `claimed` event in a
+    real project turned out to carry an empty `session`, because nothing was passing one: the tool
+    accepts it and no caller supplied it. This hook receives it on every tool call, so stamping it
+    here costs nothing and closes the gap.
+
+    Local-only (`LOCAL_ONLY_KINDS`), so it never reaches the committed log. Without a task it is
+    dropped rather than filed under an empty id: an activity event nobody can attribute is noise that
+    would still cost a row per tool call.
+    """
+    with project(start) as store:
+        who = caller(store, actor)["id"]
+        heartbeat(store, who)
+        held = store.leases.of_actor(who, now())
+        if session:
+            _stamp(store, held, session)
+        target = task or (held[0]["task"] if len(held) == 1 else "")
+        if not target:
+            return None
+        return record(store, task=target, actor=who, kind="activity",
+                      body={"summary": summary, "session": session})
+
+
+def _stamp(store: Store, held: list[Lease], session: str) -> None:
+    """Record which session is working each held card. Cheap, idempotent, and only writes on change."""
+    for lease in held:
+        if lease["session"] != session:
+            store.leases.set_session(task_id=lease["task"], session=session)
+
+
+def checkout(start: Path | str, *, summary: str, session: str = "",
+             actor: str = "") -> list[Event]:
+    """The Stop read: the session's own account of itself, on every task it holds.
+
+    An auto-standup, and the reason a task's thread is worth reading at 9am: an agent
+    that was killed mid-thought still leaves what it had. Leases are deliberately NOT
+    released — a session ending is not the same as work being handed back, and Claude
+    Code ends a session every time a developer closes a terminal.
+    """
+    with project(start) as store:
+        who = caller(store, actor)["id"]
+        heartbeat(store, who)
+        return [record(store, task=lease["task"], actor=who, kind="comment",
+                       body={"text": summary, "session": session, "auto": True})
+                for lease in store.leases.of_actor(who, now())]

taskops/usecases/setup.py

@@ -0,0 +1,92 @@
+"""`taskops init` — making a repository coordinated.
+
+Three things, and the order is deliberate: the project directory, the gitignore entry,
+then the git hooks. If hook installation fails the project still works — every hook here
+is an optimisation of something the MCP tools already do — so a partial init leaves a
+usable system rather than a broken one.
+
+Existing hooks are CHAINED, never overwritten. A repository's `post-commit` may already
+run a linter somebody depends on, and a coordination tool that silently deleted it would
+deserve everything that followed.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ..storage import GUIDE_FILE, LOG_FILE, PROJECT_DIR, Store, find_root
+from ._gitignore import ignore
+from .hooks import install_hooks
+
+__all__ = ["init", "InitReport"]
+
+_GUIDE_SOURCE = Path(__file__).resolve().parents[1] / "assets" / "GUIDE.md"
+
+class InitReport:
+    """What init actually did, so the CLI can report it instead of claiming success."""
+
+    def __init__(self, *, root: Path, created: bool, hooks: list[str],
+                 skipped: list[str], adopted: int = 0) -> None:
+        self.root = root
+        self.created = created
+        self.hooks = hooks
+        self.skipped = skipped
+        self.adopted = adopted
+        """Tasks materialised from a log that was already in the working tree.
+
+        Non-zero on a FRESH CLONE, which is the case this exists for. Following the usage guide
+        end to end, a teammate cloned, ran `taskops init`, and saw an empty board: the log was
+        sitting right there in the checkout and nothing had read it. Now init reads it.
+        """
+
+
+def init(start: Path | str, *, install_git_hooks: bool = True) -> InitReport:
+    """Create `.taskops/`, ignore the cache, install the hooks. Idempotent.
+
+    Re-running is safe and is the supported way to repair a project whose hooks were
+    lost — which happens on every fresh clone, because `.git/hooks` is not tracked.
+    """
+    root = Path(start).expanduser().resolve()
+    existing = find_root(root)
+    created = existing is None
+    root = existing or root
+    (root / PROJECT_DIR).mkdir(parents=True, exist_ok=True)
+    ignore(root)
+    _guide(root)
+    (root / LOG_FILE).touch(exist_ok=True)
+    adopted = _adopt(root)
+    hooks, skipped = install_hooks(root) if install_git_hooks else ([], [])
+    return InitReport(root=root, created=created, hooks=hooks, skipped=skipped,
+                      adopted=adopted)
+
+
+def _adopt(root: Path) -> int:
+    """Open the database (which applies the schema) and read whatever log is already here.
+
+    THE fresh-clone step, and it was missing: a teammate cloned a repository whose checkout
+    carried the whole event log, ran `taskops init`, and saw an empty board — the log was sitting
+    right there and nothing had read it. Adoption is just an import+replay, both idempotent, so on
+    a brand-new project this is a no-op and on a re-run it changes nothing.
+    """
+    from ..engine import replay, unblock
+    from ..storage import import_events
+
+    with Store(root) as store:
+        applied = replay.apply(store, import_events(store))
+        unblock(store)
+        return applied
+
+
+def _guide(root: Path) -> None:
+    """Copy the agent-facing manual into the project, OVERWRITING it every init.
+
+    Overwriting on purpose, unlike `.gitignore`: this file ships with the package and
+    describes what this version of the tools actually does. A stale copy that survived an
+    upgrade would be a document telling agents to use a rule that no longer exists — and
+    since it is committed, everyone on the team would read the wrong one. Anything a project
+    wants to add about its own conventions belongs in CLAUDE.md, which taskops never touches.
+    """
+    destination = root / GUIDE_FILE
+    if _GUIDE_SOURCE.is_file():
+        destination.write_text(_GUIDE_SOURCE.read_text(encoding="utf-8"),
+                               encoding="utf-8")

taskops/usecases/sync.py

@@ -0,0 +1,78 @@
+"""`taskops sync` — reconciling with what git brought in.
+
+Four steps, and the order is the design:
+
+```
+  import   the log's new events into the local cache        (storage)
+  replay   those events into tasks and dependencies         (engine)
+  unblock  re-derive what is now pickable                   (engine)
+  export   this machine's new events into the log           (storage)
+```
+
+**Replay is the step that was missing**, and its absence was a real bug: following the usage guide,
+a teammate's `git pull` imported every event and left them looking at an empty board. Events are the
+source of truth, so something has to turn them into rows — see `engine.replay`.
+
+Import before export, deliberately: importing can close a task whose dependents this machine is
+about to be asked about, and exporting first would publish a view of the graph that was already
+stale when it was written.
+
+Every step is idempotent, so a developer who runs this in a loop out of nervousness costs themselves
+nothing.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ..engine import replay, unblock
+from ..storage import all_events, export_events, import_events
+from ._project import project
+
+__all__ = ["sync", "rebuild", "SyncReport"]
+
+
+class SyncReport:
+    """What moved, in both directions, plus what the import actually changed."""
+
+    def __init__(self, *, imported: int, applied: int, exported: int,
+                 unblocked: list[str]) -> None:
+        self.imported = imported
+        self.applied = applied
+        """Events that changed local state. Lower than `imported` and that is normal — a comment is
+        worth keeping and says nothing about what a task IS."""
+
+        self.exported = exported
+        self.unblocked = unblocked
+
+
+def sync(start: Path | str) -> SyncReport:
+    """Pull the log into the cache, apply it, re-derive readiness, push local events out.
+
+    `unblock` at the end is the point of the whole operation: a teammate finishing a task is only
+    useful here once the tasks waiting on it become pickable, and that promotion happens now rather
+    than at the next `next` call — so somebody who just ran `git pull` sees the real queue.
+    """
+    with project(start) as store:
+        fresh = import_events(store)
+        applied = replay.apply(store, fresh)
+        freed = unblock(store)
+        return SyncReport(imported=len(fresh), applied=applied,
+                          exported=export_events(store), unblocked=freed)
+
+
+def rebuild(start: Path | str) -> SyncReport:
+    """Re-apply the ENTIRE log. The disaster-recovery path, for a deleted cache.
+
+    Different from `sync` in one way that matters: it replays every event rather than only the new
+    ones, because after `rm .taskops/db.sqlite` nothing is new — the log is all there is.
+
+    Additive, never a truncate-and-replay: leases are live state the log does not describe, so
+    wiping rows to rebuild them would drop every agent's claim to recreate what the log can
+    reconcile anyway.
+    """
+    with project(start) as store:
+        imported = len(import_events(store))
+        applied = replay.apply(store, all_events(store.root))
+        return SyncReport(imported=imported, applied=applied,
+                          exported=export_events(store), unblocked=unblock(store))

taskops/usecases/update.py

@@ -0,0 +1,123 @@
+"""`taskops_update` — a transition, a comment and a notification, in one call.
+
+One call because they are one event in the agent's head: "I finished this, here is what
+happened, tell Ana's agent". Three calls would mean three chances to do two of the
+three, and the missing one is always the comment.
+
+This is the only place that assembles `Facts` for the state machine. Everything the
+guards ask about — a live lease, the commits bound to the task, its open children — is
+read here and handed over as data, which is what lets those rules be tested from
+literals.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from .._clock import now
+from .._errors import BadRequest
+from .._types import Status
+from ..contracts import Task, UpdateResult
+from ..engine import check_move, record, unblock
+from ..storage import Store
+from ._facts import facts_for
+from ._project import caller, heartbeat, project
+from ._routing import routed, update_remotely, whoami
+
+__all__ = ["update", "RELEASE"]
+
+RELEASE = "released"
+"""Not a status — the WORD an agent uses to hand work back. It maps to `ready` plus
+dropping the lease, and it reads as an action because that is what the agent is doing.
+Spelling it `ready` in the tool would invite an agent to "set ready" as a way of
+skipping the queue."""
+
+
+def update(start: Path | str, task_id: str, *, actor: str = "", status: str = "",
+           comment: str = "", mentions: tuple[str, ...] = (), blocked_on: str = "",
+           no_code: bool = False, local: bool = False) -> UpdateResult:
+    """Apply whatever was asked, in the order that keeps the graph honest.
+
+    `local` is the server's flag, exactly as in `next_task`: a project with a remote runs
+    its transitions THERE, so the lease guard that refuses a `done` from a machine that
+    never held the lease is checked against the one database everybody writes to.
+    """
+    if not (status or comment or blocked_on):
+        raise BadRequest("nothing to do — pass a `status`, a `comment`, or `blocked_on`")
+    if (remote := routed(start, local)) is not None:
+        return update_remotely(start, remote, {
+            "task": task_id, "actor": whoami(start, actor), "status": status,
+            "comment": comment, "mentions": list(mentions),
+            "blocked_on": blocked_on, "no_code": no_code})
+    with project(start) as store:
+        who = caller(store, actor)["id"]
+        heartbeat(store, who)
+        task = store.tasks.need(task_id)
+        if comment or mentions:
+            _say(store, task_id, who, comment, mentions)
+        if blocked_on:
+            _block_on(store, task, who, blocked_on)
+        if status:
+            task = _move(store, task, who, status, comment, no_code)
+        freed = unblock(store)
+        return UpdateResult(task=store.tasks.need(task_id),
+                            unblocked=[store.tasks.need(i) for i in freed],
+                            notified=list(mentions))
+
+
+def _say(store: Store, task_id: str, who: str, text: str, mentions: tuple[str, ...]) -> None:
+    """Record the comment. Mentions make it a `message`, which is what an inbox reads.
+
+    The kind carries the routing rather than a separate flag: `delivered.pending`
+    selects on kind and body, so a comment nobody was addressed in cannot end up in
+    anybody's inbox by accident.
+    """
+    record(store, task=task_id, actor=who,
+           kind="message" if mentions else "comment",
+           body={"text": text, "mentions": list(mentions)})
+
+
+def _block_on(store: Store, task: Task, who: str, blocker: str) -> None:
+    """Add the edge a discovery revealed, and say so in the log.
+
+    The edge is added even when the task is not moved to `blocked`: the graph is the
+    thing other agents schedule against, and a dependency that lived only in a comment
+    is a dependency the scheduler will hand somebody straight into.
+    """
+    store.tasks.need(blocker)
+    if blocker == task["id"]:
+        raise BadRequest(f"{blocker} cannot block itself")
+    store.deps.add(blocker, task["id"])
+    record(store, task=task["id"], actor=who, kind="blocked", body={"on": blocker})
+
+
+def _move(store: Store, task: Task, who: str, asked: str, comment: str,
+          no_code: bool) -> Task:
+    """Check the move, then apply it. `released` also drops the lease."""
+    target: Status = "ready" if asked == RELEASE else _status(asked)
+    facts = facts_for(store, task, who, no_code=no_code, justification=comment)
+    check_move(facts, target)
+    if target in ("ready", "done", "cancelled"):
+        store.leases.release(task["id"])
+    store.tasks.set_status(task["id"], target, when=now())
+    record(store, task=task["id"], actor=who,
+           kind="done" if target == "done" else "status",
+           body={"from": task["status"], "to": target, "released": asked == RELEASE,
+                 "unpushed": facts.unpushed})
+    return store.tasks.need(task["id"])
+
+
+def _status(asked: str) -> Status:
+    """A caller's word -> a status the machine knows.
+
+    Validated here rather than trusted from the schema: the CLI and the HTTP surface
+    reach this too, and only MCP hosts enforce an enum.
+    """
+    known = ("backlog", "ready", "claimed", "in_progress", "blocked", "review",
+             "done", "cancelled")
+    if asked not in known:
+        raise BadRequest(f"`{asked}` is not a status — use one of "
+                         f"{', '.join(known)}, or `{RELEASE}` to hand the task back")
+    return asked            # type: ignore[return-value]
+
+