ahub 3.0.0__tar.gz

ahub-3.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Takeh1ko
+
+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.

ahub-3.0.0/PKG-INFO

@@ -0,0 +1,147 @@
+Metadata-Version: 2.4
+Name: ahub
+Version: 3.0.0
+Summary: Service through which Claude Code and a human hand tasks to cheap worker models and accept the results
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Takeh1ko/agent-hub
+Project-URL: Issues, https://github.com/Takeh1ko/agent-hub/issues
+Keywords: agents,orchestrator,llm,telegram
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: textual>=0.80
+Requires-Dist: psutil>=5.9; sys_platform != "linux"
+Provides-Extra: telegram
+Requires-Dist: aiogram>=3.13; extra == "telegram"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
+Requires-Dist: psutil>=5.9; extra == "dev"
+Requires-Dist: aiogram>=3.13; extra == "dev"
+Dynamic: license-file
+
+<p align="center"><img src="https://raw.githubusercontent.com/Takeh1ko/agent-hub/main/docs/assets/banner.png" alt="agent-hub" width="100%"></p>
+
+<p align="center"><a href="https://github.com/Takeh1ko/agent-hub/actions/workflows/ci.yml"><img src="https://github.com/Takeh1ko/agent-hub/actions/workflows/ci.yml/badge.svg" alt="CI"></a> <a href="https://pypi.org/project/ahub/"><img src="https://img.shields.io/pypi/v/ahub" alt="PyPI"></a> <img src="https://img.shields.io/badge/python-3.11%E2%80%933.13-blue" alt="Python 3.11–3.13"> <img src="https://img.shields.io/badge/license-MIT-green" alt="MIT"></p>
+
+<p align="center"><a href="https://github.com/Takeh1ko/agent-hub/blob/main/README.ru.md">Русская версия</a></p>
+
+Let Claude Code hand work to cheap models — and only spend its own tokens on decisions.
+
+agent-hub is a local service between an orchestrator (Claude Code, or any CLI agent) and worker models
+(opencode: Muse Spark, free models; Gemini via Antigravity). Claude files a task, goes quiet, and is woken by
+one line when there is something to decide: accept, send back with notes, or reject. Everything in between —
+running the worker in its own copy of the repo, checking its work, review by other models, retries, budgets —
+the hub does without Claude.
+
+
+## Why
+
+- **Claude's context is the expensive part.** A delegated task costs Claude about 2 KB of text for the whole
+  cycle: one event line, a summary capped at 4 KB, a one-word decision. Reports, diffs and logs are there on
+  request, never pushed.
+- **Cheap models are good enough when the work is checked.** A task is not "done" because the model says so:
+  the commit exists, the diff stays inside the allowed files, the acceptance tests pass under a project lock,
+  and one or more reviewer models (in fresh sessions) agree. Typical costs on Muse Spark: recon $0.004–0.06,
+  code with review $0.02–0.13.
+- **Nothing gets lost.** Events are stored until acknowledged, so a restarted Claude session, a restarted hub or a
+  dead terminal does not drop a "done". Worker processes outlive service restarts; orphaned tasks are picked up
+  again; an observer watches the hub itself.
+
+## What it does
+
+| | |
+|---|---|
+| Task kinds | `scout` (report only), `code` (branch + gates + review), `routine` (light changes), `review` (of a branch/commit/range) |
+| Isolation | a git worktree per task, secrets hidden from the copy, clean environment for the worker |
+| Gates | commit present, diff ⊆ allowed paths, structured result, acceptance tests under a shared lock |
+| Review | panel of reviewer models in new sessions; disputes count only with file, line and reason; N rounds |
+| Merge | `ahub accept` merges `--no-ff`, re-runs acceptance, rolls back if red |
+| Failures | network error → retry; silence → one nudge; quota/timeout/budget → "needs decision"; never a silent hang |
+| Budgets | per task (including review); at 100 % the worker is asked to save and stop, extension is one command |
+| Waking Claude | `ahub watch` for Claude Code's Monitor, `ahub wait`; stable codes `DONE` `DECISION` `ERROR` `OWNER` `ANSWER` `ALARM` |
+| Pulse | 🟢 working · 🟡 waiting for a reason · 🔴 silent · ⚫ dead · ⚪ no data — from the provider, processes and locks |
+| Observer | code checks every 5 min, a model review every 30 min, escalation to Claude, then to you |
+| Human | `ahub top` terminal UI; optional Telegram bot that talks to Claude (and starts Claude if no session is live) |
+| Other agents | the same handles over MCP (`ahub mcp`) |
+| Languages | English and Russian (`AHUB_LANG`, `lang` in config, or the locale) |
+
+## How it compares
+
+Several projects connect Claude Code to other agents. Most are thin bridges (start a session, poll its status).
+agent-hub is narrower in scope and deeper in the task lifecycle:
+
+| | agent-hub | thin MCP bridges (opencode-mcp, agent-delegation-mcp, agy bridges) | fleet orchestrators (claw-orchestrator, Composio agent-orchestrator) |
+|---|---|---|---|
+| Focus | Claude decides, cheap models work | pass a prompt, return output | many agents in parallel, dashboards, PR loops |
+| Gates and acceptance tests before "done" | yes | no | partly |
+| Review by other models | yes | no | yes |
+| Orchestrator token budget as a design rule | yes (hard size limits) | no | no |
+| Events survive restarts (ack) | yes | no | partly |
+| Observer of the hub itself | yes | no | no |
+| Web dashboard | no (terminal UI + Telegram) | no | yes |
+| Number of supported agents | opencode, agy | one | many |
+
+If you want a dashboard for twenty parallel agents with PR automation, use a fleet orchestrator. If you want
+Claude Code to stop burning its context on work a cheaper model can do — and to trust the result — this is it.
+
+<details>
+<summary>See it work: a real task on Muse Spark ($0.007)</summary>
+
+<img src="https://raw.githubusercontent.com/Takeh1ko/agent-hub/main/docs/demo.gif" alt="demo">
+</details>
+
+## Install
+
+Requires Python 3.11+, git, and at least one provider: [opencode](https://opencode.ai) (free models work) or
+Google Antigravity CLI (`agy`).
+
+```
+pipx install ahub
+ahub setup                 # language, project, providers, models, service, Claude skill, Telegram (optional)
+ahub doctor                # what is wrong and how to fix it
+```
+
+`ahub setup --yes` takes all defaults without questions. Telegram is optional: `pipx install 'ahub[telegram]'`.
+
+Platforms: Linux (systemd), macOS (launchd; tested in CI), Windows via WSL2 only.
+
+## Use
+
+In Claude Code (after `ahub setup` installs the skill):
+
+```
+ahub task new --kind code --title "add retry to the payment client" \
+  --spec-file spec.md --paths "app/payments/**,tests/**" --accept "tests/test_payments.py"
+```
+
+Claude keeps a Monitor on `ahub watch`; when a line like `DONE T12 …` arrives it runs `ahub status T12` and decides:
+`ahub accept T12`, `ahub rework T12 --notes "…"`, or `ahub reject T12`.
+
+You: `ahub top` to watch (press `c` for control mode, `?` for help), `ahub status`, `ahub history`.
+Plain-language tasks: `ahub draft new "what you want, in your words"` → preview → `ahub draft start N`.
+
+Everything else: `ahub --help`.
+
+## Documentation
+
+- [docs/ARCHITECTURE.md](https://github.com/Takeh1ko/agent-hub/blob/main/docs/ARCHITECTURE.md) — code map, start here
+- [docs/architecture.md](https://github.com/Takeh1ko/agent-hub/blob/main/docs/architecture.md) — design
+- [docs/contracts.md](https://github.com/Takeh1ko/agent-hub/blob/main/docs/contracts.md) — interfaces between the parts
+
+## Development
+
+```
+python -m venv .venv && .venv/bin/pip install -e '.[dev]'
+.venv/bin/python -m pytest -q          # ~2.5 min, no network, HOME is faked
+AHUB_LIVE=1 .venv/bin/python -m pytest -m live   # real providers, costs money
+```
+
+## License
+
+MIT

ahub-3.0.0/README.md

@@ -0,0 +1,120 @@
+<p align="center"><img src="https://raw.githubusercontent.com/Takeh1ko/agent-hub/main/docs/assets/banner.png" alt="agent-hub" width="100%"></p>
+
+<p align="center"><a href="https://github.com/Takeh1ko/agent-hub/actions/workflows/ci.yml"><img src="https://github.com/Takeh1ko/agent-hub/actions/workflows/ci.yml/badge.svg" alt="CI"></a> <a href="https://pypi.org/project/ahub/"><img src="https://img.shields.io/pypi/v/ahub" alt="PyPI"></a> <img src="https://img.shields.io/badge/python-3.11%E2%80%933.13-blue" alt="Python 3.11–3.13"> <img src="https://img.shields.io/badge/license-MIT-green" alt="MIT"></p>
+
+<p align="center"><a href="https://github.com/Takeh1ko/agent-hub/blob/main/README.ru.md">Русская версия</a></p>
+
+Let Claude Code hand work to cheap models — and only spend its own tokens on decisions.
+
+agent-hub is a local service between an orchestrator (Claude Code, or any CLI agent) and worker models
+(opencode: Muse Spark, free models; Gemini via Antigravity). Claude files a task, goes quiet, and is woken by
+one line when there is something to decide: accept, send back with notes, or reject. Everything in between —
+running the worker in its own copy of the repo, checking its work, review by other models, retries, budgets —
+the hub does without Claude.
+
+
+## Why
+
+- **Claude's context is the expensive part.** A delegated task costs Claude about 2 KB of text for the whole
+  cycle: one event line, a summary capped at 4 KB, a one-word decision. Reports, diffs and logs are there on
+  request, never pushed.
+- **Cheap models are good enough when the work is checked.** A task is not "done" because the model says so:
+  the commit exists, the diff stays inside the allowed files, the acceptance tests pass under a project lock,
+  and one or more reviewer models (in fresh sessions) agree. Typical costs on Muse Spark: recon $0.004–0.06,
+  code with review $0.02–0.13.
+- **Nothing gets lost.** Events are stored until acknowledged, so a restarted Claude session, a restarted hub or a
+  dead terminal does not drop a "done". Worker processes outlive service restarts; orphaned tasks are picked up
+  again; an observer watches the hub itself.
+
+## What it does
+
+| | |
+|---|---|
+| Task kinds | `scout` (report only), `code` (branch + gates + review), `routine` (light changes), `review` (of a branch/commit/range) |
+| Isolation | a git worktree per task, secrets hidden from the copy, clean environment for the worker |
+| Gates | commit present, diff ⊆ allowed paths, structured result, acceptance tests under a shared lock |
+| Review | panel of reviewer models in new sessions; disputes count only with file, line and reason; N rounds |
+| Merge | `ahub accept` merges `--no-ff`, re-runs acceptance, rolls back if red |
+| Failures | network error → retry; silence → one nudge; quota/timeout/budget → "needs decision"; never a silent hang |
+| Budgets | per task (including review); at 100 % the worker is asked to save and stop, extension is one command |
+| Waking Claude | `ahub watch` for Claude Code's Monitor, `ahub wait`; stable codes `DONE` `DECISION` `ERROR` `OWNER` `ANSWER` `ALARM` |
+| Pulse | 🟢 working · 🟡 waiting for a reason · 🔴 silent · ⚫ dead · ⚪ no data — from the provider, processes and locks |
+| Observer | code checks every 5 min, a model review every 30 min, escalation to Claude, then to you |
+| Human | `ahub top` terminal UI; optional Telegram bot that talks to Claude (and starts Claude if no session is live) |
+| Other agents | the same handles over MCP (`ahub mcp`) |
+| Languages | English and Russian (`AHUB_LANG`, `lang` in config, or the locale) |
+
+## How it compares
+
+Several projects connect Claude Code to other agents. Most are thin bridges (start a session, poll its status).
+agent-hub is narrower in scope and deeper in the task lifecycle:
+
+| | agent-hub | thin MCP bridges (opencode-mcp, agent-delegation-mcp, agy bridges) | fleet orchestrators (claw-orchestrator, Composio agent-orchestrator) |
+|---|---|---|---|
+| Focus | Claude decides, cheap models work | pass a prompt, return output | many agents in parallel, dashboards, PR loops |
+| Gates and acceptance tests before "done" | yes | no | partly |
+| Review by other models | yes | no | yes |
+| Orchestrator token budget as a design rule | yes (hard size limits) | no | no |
+| Events survive restarts (ack) | yes | no | partly |
+| Observer of the hub itself | yes | no | no |
+| Web dashboard | no (terminal UI + Telegram) | no | yes |
+| Number of supported agents | opencode, agy | one | many |
+
+If you want a dashboard for twenty parallel agents with PR automation, use a fleet orchestrator. If you want
+Claude Code to stop burning its context on work a cheaper model can do — and to trust the result — this is it.
+
+<details>
+<summary>See it work: a real task on Muse Spark ($0.007)</summary>
+
+<img src="https://raw.githubusercontent.com/Takeh1ko/agent-hub/main/docs/demo.gif" alt="demo">
+</details>
+
+## Install
+
+Requires Python 3.11+, git, and at least one provider: [opencode](https://opencode.ai) (free models work) or
+Google Antigravity CLI (`agy`).
+
+```
+pipx install ahub
+ahub setup                 # language, project, providers, models, service, Claude skill, Telegram (optional)
+ahub doctor                # what is wrong and how to fix it
+```
+
+`ahub setup --yes` takes all defaults without questions. Telegram is optional: `pipx install 'ahub[telegram]'`.
+
+Platforms: Linux (systemd), macOS (launchd; tested in CI), Windows via WSL2 only.
+
+## Use
+
+In Claude Code (after `ahub setup` installs the skill):
+
+```
+ahub task new --kind code --title "add retry to the payment client" \
+  --spec-file spec.md --paths "app/payments/**,tests/**" --accept "tests/test_payments.py"
+```
+
+Claude keeps a Monitor on `ahub watch`; when a line like `DONE T12 …` arrives it runs `ahub status T12` and decides:
+`ahub accept T12`, `ahub rework T12 --notes "…"`, or `ahub reject T12`.
+
+You: `ahub top` to watch (press `c` for control mode, `?` for help), `ahub status`, `ahub history`.
+Plain-language tasks: `ahub draft new "what you want, in your words"` → preview → `ahub draft start N`.
+
+Everything else: `ahub --help`.
+
+## Documentation
+
+- [docs/ARCHITECTURE.md](https://github.com/Takeh1ko/agent-hub/blob/main/docs/ARCHITECTURE.md) — code map, start here
+- [docs/architecture.md](https://github.com/Takeh1ko/agent-hub/blob/main/docs/architecture.md) — design
+- [docs/contracts.md](https://github.com/Takeh1ko/agent-hub/blob/main/docs/contracts.md) — interfaces between the parts
+
+## Development
+
+```
+python -m venv .venv && .venv/bin/pip install -e '.[dev]'
+.venv/bin/python -m pytest -q          # ~2.5 min, no network, HOME is faked
+AHUB_LIVE=1 .venv/bin/python -m pytest -m live   # real providers, costs money
+```
+
+## License
+
+MIT

ahub-3.0.0/ahub/__init__.py

@@ -0,0 +1,3 @@
+"""agent-hub v2: the service through which the orchestrator and humans hand work to worker models."""
+
+__version__ = "3.0.0"

ahub-3.0.0/ahub/__main__.py

@@ -0,0 +1,3 @@
+from ahub.cli import main
+
+raise SystemExit(main())

ahub-3.0.0/ahub/accept.py

@@ -0,0 +1,257 @@
+"""Decisions on results (V15–V18, architecture §6.7–§6.8): accept/merge, rework, reject, orchestrator edit,
+path extension, budget top-up, model change, resume with a new brief.
+
+Merge: task → "accepting" (lease held by whoever accepts; a second "accept" is refused) → gates at the copy's
+current HEAD (orchestrator edit — if HEAD ≠ worker result commit: legitimate, with an event) → in the project root
+`git merge --no-ff` into the work branch → acceptance under the test resource → red — roll the merge back →
+push per config → "accepted", task_cleanup hook, copy and branch removed, archived.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ahub import archive, events, gates, prepare, registry, tasks, transitions, workspace
+from ahub import log as hublog
+from ahub.config import ProjectConfig
+from ahub.engine import owner_token
+from ahub.i18n import t as _t
+from ahub.model import CHANGES_FILES, Ev, Kind, State
+from ahub.store import Store, Task
+
+_log = hublog.get("accept")
+
+
+class DecisionError(RuntimeError):
+    """Action impossible (one line for the orchestrator)."""
+
+
+def _get(store: Store, task_id: int) -> Task:
+    t = store.get_task(task_id)
+    if t is None:
+        raise DecisionError(_t("trans.no_task", id=task_id))
+    return t
+
+
+def _root_ready(project: ProjectConfig) -> None:
+    cur = workspace.git(project.root, "rev-parse", "--abbrev-ref", "HEAD").stdout.strip()
+    if cur != project.work_branch:
+        raise DecisionError(_t("accept.root_branch", cur=cur, branch=project.work_branch))
+    dirty = [ln for ln in workspace.git(project.root, "status", "--porcelain", "--untracked-files=no").stdout
+             .splitlines() if ln.strip()]
+    if dirty:
+        raise DecisionError(_t("accept.root_dirty", files=", ".join(x[3:] for x in dirty[:5])))
+
+
+def accept(store: Store, project: ProjectConfig, task_id: int, *, by: str = "orchestrator") -> str:
+    t = _get(store, task_id)
+    if t.kind not in CHANGES_FILES:
+        if t.state not in (State.DONE, State.NEEDS_DECISION):
+            raise DecisionError(_t("accept.can_accept", label=t.label, state=t.state.value))
+        transitions.move(store, t.id, State.ACCEPTED, reason=_t("accept.accepted"), by=by)
+        events.ack_task(store, t.id)
+        archive.write_task(store, project, t.id)
+        workspace.remove(project, t.id, delete_branch=True)
+        return _t("accept.accepted_msg", label=t.label)
+    if t.state not in (State.DONE, State.NEEDS_DECISION, State.ACCEPTING):
+        raise DecisionError(_t("accept.can_accept", label=t.label, state=t.state.value))
+    if not t.worktree or not Path(t.worktree).is_dir():
+        raise DecisionError(_t("accept.no_worktree", label=t.label, wt=t.worktree or "—"))
+    _root_ready(project)
+    owner = owner_token()
+    if t.state is not State.ACCEPTING:
+        transitions.move(store, t.id, State.ACCEPTING, reason=_t("accept.accepting"), by=by,
+                         expect_from={State.DONE, State.NEEDS_DECISION})
+    if not transitions.acquire(store, t.id, owner, pid=None):
+        raise DecisionError(_t("accept.busy", label=t.label))
+    try:
+        return _merge(store, project, _get(store, t.id), owner, by)
+    except DecisionError as e:
+        _back(store, t.id, owner, str(e))
+        raise
+    except Exception as e:
+        _log.exception("accept T%d failed", t.id, extra={"task": t.id})
+        _back(store, t.id, owner, _t("accept.fail", err=f"{type(e).__name__}: {e}"))
+        raise DecisionError(_t("accept.fail", err=e)) from e
+    finally:
+        transitions.release(store, t.id, owner)
+
+
+def _back(store: Store, task_id: int, owner: str, reason: str) -> None:
+    t = store.get_task(task_id)
+    if t is not None and t.state is State.ACCEPTING:
+        transitions.move(store, task_id, State.NEEDS_DECISION, reason=reason[:500], by="accept", owner=owner)
+        events.ack_task(store, task_id)  # the orchestrator saw the refusal in the command output
+
+
+def _merge(store: Store, project: ProjectConfig, t: Task, owner: str, by: str) -> str:
+    res = archive.read_json(Path(t.worktree) / workspace.AHUB_DIR / "result.json")
+    head = workspace.head(t.worktree)
+    orch_edit = not res.get("commit") or not head.startswith(str(res.get("commit"))[:7])
+    if orch_edit and not t.limits.get("orch_edit"):
+        store.add_event(Ev.ORCH_EDIT, task_id=t.id, project=t.project,
+                        payload={"head": head[:12], "worker_commit": str(res.get("commit", ""))[:12], "by": by})
+    g = gates.check(project, t, run_tests=False, orch_edit=orch_edit)
+    problems = g.fatal + [p for p in g.repairable if not (orch_edit and p.startswith("result.json"))]
+    if problems:
+        raise DecisionError(_t("accept.gates_head", problems="; ".join(problems)))
+    title = t.title.replace('"', "'")[:100]
+    r = workspace.git(project.root, "merge", "--no-ff", "-m", f"merge {t.label}: {title}", t.branch, check=False)
+    if r.returncode != 0:
+        conflicts = workspace.git(project.root, "diff", "--name-only", "--diff-filter=U", check=False).stdout.split()
+        workspace.git(project.root, "merge", "--abort", check=False)
+        raise DecisionError(_t("accept.conflict", info=", ".join(conflicts[:10]) or (r.stderr or r.stdout)[-300:]))
+    merged = workspace.git(project.root, "rev-parse", "HEAD").stdout.strip()
+    nodes = list(t.limits.get("accept") or [])
+    if t.kind is Kind.CODE and nodes:
+        ok, tail, cmd = gates.run_acceptance(project, project.root, nodes, task_label=t.label)
+        if not ok:
+            head_now = workspace.git(project.root, "rev-parse", "HEAD").stdout.strip()
+            if head_now != merged:  # someone committed into the work branch meanwhile — leave foreign commits alone
+                raise DecisionError(_t("accept.root_moved", now=head_now[:10], merged=merged[:10]))
+            workspace.git(project.root, "reset", "--keep", "HEAD~1", check=False)  # --keep leaves foreign dirt alone
+            raise DecisionError(_t("accept.red_rolled_back", cmd=cmd, tail=tail[-600:]))
+    note = ""
+    if project.push.strip():
+        parts = project.push.split()
+        pr = workspace.git(project.root, "push", *parts, check=False, timeout=300)
+        if pr.returncode != 0:
+            note = _t("accept.push_fail", err=(pr.stderr or pr.stdout).strip()[-200:])
+            _log.warning("push T%d: %s", t.id, note, extra={"task": t.id})
+    transitions.move(store, t.id, State.ACCEPTED, reason=_t("accept.merged_reason", branch=project.work_branch,
+                                                             note=note), by=by, owner=owner,
+                     fields={"accepted_sha": merged})
+    events.ack_task(store, t.id)
+    try:
+        prepare.run_hook(project, "task_cleanup", t, t.worktree)
+    except prepare.PrepareError as e:
+        _log.warning("hook task_cleanup T%d: %s", t.id, e, extra={"task": t.id})
+    archive.write_task(store, project, t.id)
+    workspace.remove(project, t.id, delete_branch=True)
+    return _t("accept.merged_msg", label=t.label, branch=project.work_branch, sha=merged[:10], note=note)
+
+
+def reject(store: Store, project: ProjectConfig, task_id: int, *, reason: str = "", by: str = "orchestrator",
+           keep: bool = False) -> str:
+    t = _get(store, task_id)
+    try:
+        transitions.move(store, t.id, State.REJECTED, reason=reason or _t("accept.rejected_default"), by=by)
+    except (transitions.TransitionError, transitions.ConflictError) as e:
+        raise DecisionError(f"{e}{_t('accept.active_first')}") from e
+    events.ack_task(store, t.id)
+    archive.write_task(store, project, t.id)
+    if not keep:
+        workspace.remove(project, t.id, delete_branch=True)
+    return _t("accept.rejected_msg", label=t.label)
+
+
+def rework(store: Store, task_id: int, notes: str, *, by: str = "orchestrator") -> str:
+    """Send back for rework with notes: same executor session, new round."""
+    t = _get(store, task_id)
+    if t.state not in (State.DONE, State.NEEDS_DECISION, State.ERROR, State.STOPPED):
+        raise DecisionError(_t("accept.rework_state", label=t.label, state=t.state.value))
+    if not notes.strip():
+        raise DecisionError(_t("accept.need_notes"))
+    lim = dict(t.limits)
+    lim["rework_notes"] = notes.strip()
+    store.update_task(t.id, limits=lim)
+    transitions.move(store, t.id, State.QUEUED, reason=_t("accept.rework"), by=by, fields={"round": t.round + 1},
+                     payload={"notes": notes[:500]})
+    events.ack_task(store, t.id)
+    return _t("accept.rework_msg", label=t.label, round=t.round + 1)
+
+
+def continue_task(store: Store, task_id: int, *, by: str = "orchestrator") -> str:
+    t = _get(store, task_id)
+    if t.state not in (State.STOPPED, State.ERROR, State.NEEDS_DECISION):
+        raise DecisionError(_t("accept.continue_state", label=t.label, state=t.state.value))
+    transitions.move(store, t.id, State.QUEUED, reason=_t("accept.continue"), by=by)
+    events.ack_task(store, t.id)
+    return _t("accept.continued_msg", label=t.label)
+
+
+def edit(store: Store, project: ProjectConfig, task_id: int, *, spec: str | None = None,
+         title: str | None = None, by: str = "orchestrator") -> str:
+    """New brief: on resume — a fresh executor session (different fingerprint)."""
+    t = _get(store, task_id)
+    if t.state in (State.ACCEPTED, State.REJECTED) or t.state in transitions.ACTIVE:
+        raise DecisionError(_t("accept.edit_state", label=t.label))
+    new = tasks.TaskSpec(project=t.project, kind=t.kind, title=title if title is not None else t.title,
+                         spec=spec if spec is not None else t.spec, result_format=t.result_format,
+                         paths=list(t.limits.get("paths") or []), accept=list(t.limits.get("accept") or []),
+                         review_input=str(t.limits.get("input") or ""))
+    h = tasks.spec_hash(new)
+    if h == t.spec_hash:
+        return _t("accept.edit_same", label=t.label)
+    lim = dict(t.limits)
+    lim["fresh_session"] = True
+    store.update_task(t.id, title=new.title, spec=new.spec, spec_hash=h, limits=lim)
+    store.add_event(Ev.STATE, task_id=t.id, project=t.project, payload={"edit": _t("accept.edit_text"), "by": by})
+    return _t("accept.edit_msg", label=t.label)
+
+
+def extend_paths(store: Store, project: ProjectConfig, task_id: int, paths: list[str], *,
+                 by: str = "orchestrator") -> str:
+    t = _get(store, task_id)
+    bad = [p for p in paths if tasks._path_escapes(p) or not tasks._glob_allowed(p, project.allowed_paths)]
+    if bad:
+        raise DecisionError(_t("accept.paths_outside", items=", ".join(bad)))
+    cur = list(t.limits.get("paths") or [])
+    added = [p for p in paths if p not in cur]
+    if not added:
+        return _t("accept.paths_same", label=t.label)
+    lim = dict(t.limits)
+    lim["paths"] = cur + added
+    store.update_task(t.id, limits=lim)
+    store.add_event(Ev.PATHS_EXTENDED, task_id=t.id, project=t.project, payload={"added": added, "by": by})
+    return _t("accept.paths_added", label=t.label, items=", ".join(added))
+
+
+def _stopped_by_budget(store: Store, task_id: int) -> bool:
+    """Task parked on budget: after a hard budget stop (budget_hard) it never left "needs decision"."""
+    stopped = False
+    for e in store.events(task_id=task_id):
+        if e.kind == Ev.BUDGET_HARD.value:
+            stopped = True
+        elif e.kind == Ev.STATE.value and (e.payload or {}).get("to") != State.NEEDS_DECISION.value:
+            stopped = False
+    return stopped
+
+
+def extend_budget(store: Store, task_id: int, *, add: float | None = None, set_to: float | None = None,
+                  add_usd: float | None = None, by: str = "orchestrator") -> str:
+    """Top up the budget in one move: raised + resumed (if the task was parked on budget).
+
+    add/set_to — Go counter (subscription); add_usd — real money (default 0 = no spending).
+    """
+    t = _get(store, task_id)
+    new = set_to if set_to is not None else t.budget_go + (add or 0.0)
+    new_usd = t.budget_usd + (add_usd or 0.0)
+    if new <= t.budget_go and set_to is None and new_usd <= t.budget_usd:
+        raise DecisionError(_t("accept.budget_need"))
+    store.update_task(t.id, budget_go=float(new), budget_usd=float(new_usd))
+    store.add_event(Ev.BUDGET_EXTENDED, task_id=t.id, project=t.project,
+                    payload={"from": t.budget_go, "to": new, "usd_from": t.budget_usd, "usd_to": new_usd, "by": by})
+    msg = _t("accept.budget_msg", label=t.label, old=f"{t.budget_go:g}", new=f"{new:g}") + (
+        _t("accept.budget_usd", old=f"{t.budget_usd:g}", new=f"{new_usd:g}")
+        if new_usd != t.budget_usd else "")
+    if t.state is State.NEEDS_DECISION and _stopped_by_budget(store, t.id):
+        transitions.move(store, t.id, State.QUEUED, reason=_t("accept.budget_long"), by=by)
+        events.ack_task(store, t.id)
+        msg += _t("accept.budget_resumed")
+    return msg
+
+
+def change_model(store: Store, project: ProjectConfig, task_id: int, alias: str, *, by: str = "orchestrator") -> str:
+    t = _get(store, task_id)
+    if t.state in transitions.ACTIVE:
+        raise DecisionError(_t("accept.model_active", label=t.label))
+    try:
+        registry.check(store, alias, project)
+    except registry.RegistryError as e:
+        raise DecisionError(str(e)) from e
+    lim = dict(t.limits)
+    lim["fresh_session"] = True  # never resume another model's session
+    store.update_task(t.id, executor=alias, limits=lim)
+    store.add_event(Ev.MODEL_CHANGED, task_id=t.id, project=t.project, payload={"from": t.executor, "to": alias, "by": by})
+    return _t("accept.model_msg", label=t.label, old=t.executor, new=alias)