taskboy 0.1.1__py3-none-any.whl

taskboy/deploy/install.sh

@@ -0,0 +1,101 @@
+#!/usr/bin/env bash
+# host bootstrap for the taskboy host (amazon linux 2023). idempotent; run as root.
+# usage: sudo ./install.sh [pip-spec]
+#   pip-spec: what to install into the venv — "taskboy==X.Y.Z" (recommended: your shell
+#   repo's pinned version), a wheel path, or a checkout directory. defaults to the latest
+#   taskboy release on PyPI.
+# this script ships inside the package; to bootstrap a fresh host without a checkout:
+#   python3.12 -m venv /tmp/bootstrap && /tmp/bootstrap/bin/pip install "taskboy==X.Y.Z"
+#   /tmp/bootstrap/bin/taskboy assets deploy /tmp && sudo bash /tmp/deploy/install.sh "taskboy==X.Y.Z"
+# routine releases do NOT re-run this script; ci invokes remote-update.sh via ssm.
+# re-run this only for host-level changes (users, docker, iptables, units).
+set -euo pipefail
+
+# fixed install layout — not operator knobs
+SLUG="taskboy"
+SVC_USER="taskboy"
+OPT_DIR="/opt/$SLUG"
+ETC_DIR="/etc/$SLUG"
+VAR_DIR="/var/lib/$SLUG"
+RUN_DIR="/run/$SLUG"
+
+PKG="${1:-taskboy}"
+
+echo "== packages =="
+dnf install -y -q docker git python3.12 iptables-nft
+
+echo "== service user + directories =="
+id -u "$SVC_USER" &>/dev/null || useradd --system --home-dir "$VAR_DIR" --shell /sbin/nologin "$SVC_USER"
+install -d -o "$SVC_USER" -g "$SVC_USER" -m 700 "$VAR_DIR" "$VAR_DIR/workspaces" "$VAR_DIR/memory" "$VAR_DIR/repos"
+install -d -o "$SVC_USER" -g "$SVC_USER" -m 755 "$RUN_DIR"
+install -d -m 755 "$ETC_DIR" "$OPT_DIR"
+echo "d $RUN_DIR 0755 $SVC_USER $SVC_USER" > "/etc/tmpfiles.d/$SLUG.conf"
+
+echo "== code + venv =="
+# the application is a pip-installed package; no source checkout lives on the host
+python3.12 -m venv "$OPT_DIR/.venv"
+"$OPT_DIR/.venv/bin/pip" install -q --upgrade pip
+"$OPT_DIR/.venv/bin/pip" install -q --upgrade "$PKG"
+install -d -o "$SVC_USER" -g "$SVC_USER" "$OPT_DIR/skills"
+chown -R "$SVC_USER:$SVC_USER" "$OPT_DIR/.venv"
+# note: the claude cli is bundled inside the claude-agent-sdk package — no separate install
+
+echo "== packaged host files =="
+assets_dir=$(mktemp -d)
+trap 'rm -rf "$assets_dir"' EXIT
+"$OPT_DIR/.venv/bin/taskboy" assets deploy "$assets_dir" > /dev/null
+"$OPT_DIR/.venv/bin/taskboy" assets templates "$assets_dir" > /dev/null
+# host copies of the deploy scripts — ci invokes remote-update.sh via ssm on every release
+install -d "$OPT_DIR/deploy"
+install -m 755 "$assets_dir/deploy/install.sh" "$OPT_DIR/deploy/install.sh"
+install -m 755 "$assets_dir/deploy/remote-update.sh" "$OPT_DIR/deploy/remote-update.sh"
+
+echo "== config =="
+[ -f "$ETC_DIR/env" ] || install -m 640 -g "$SVC_USER" "$assets_dir/deploy/env.example" "$ETC_DIR/env"
+# first install: seed operator config from the packaged example; /etc/taskboy is the
+# live copy from then on. your shell repo's deploy workflow ships config updates via
+# remote-update.sh; releases never overwrite what's here.
+[ -f "$ETC_DIR/config.yaml" ] || install -m 640 -g "$SVC_USER" "$assets_dir/templates/config.example.yaml" "$ETC_DIR/config.yaml"
+[ -f "$ETC_DIR/task_started_messages.yaml" ] || install -m 640 -g "$SVC_USER" "$assets_dir/templates/task_started_messages.yaml" "$ETC_DIR/task_started_messages.yaml"
+
+echo "== task isolation prep =="
+# slot users for sub-agent process separation (activated when the runner moves to systemd-run scopes)
+for i in 0 1 2 3 4 5; do
+  id -u "$SVC_USER-t$i" &>/dev/null || useradd --system --no-create-home --shell /sbin/nologin "$SVC_USER-t$i"
+done
+
+echo "== docker =="
+systemctl enable --now docker
+usermod -aG docker "$SVC_USER"
+for i in 0 1 2 3 4 5; do
+  usermod -aG docker "$SVC_USER-t$i"
+done
+install -d -m 755 /usr/libexec/docker/cli-plugins
+if [ ! -x /usr/libexec/docker/cli-plugins/docker-compose ]; then
+  compose_tmp="$(mktemp)"
+  curl -fsSL "https://github.com/docker/compose/releases/download/v2.27.0/docker-compose-linux-$(uname -m)" -o "$compose_tmp"
+  install -m 755 "$compose_tmp" /usr/libexec/docker/cli-plugins/docker-compose
+  rm -f "$compose_tmp"
+fi
+# block the instance metadata service for task slot users; the orchestrator keeps access (§8.3)
+for i in 0 1 2 3 4 5; do
+  iptables -C OUTPUT -d 169.254.169.254 -m owner --uid-owner "$SVC_USER-t$i" -j REJECT 2>/dev/null ||
+    iptables -A OUTPUT -d 169.254.169.254 -m owner --uid-owner "$SVC_USER-t$i" -j REJECT
+done
+
+echo "== systemd unit =="
+install -m 644 "$assets_dir/deploy/$SLUG.service" "/etc/systemd/system/$SLUG.service"
+# off-peak cli auto-update restart path: the service runs unprivileged (NoNewPrivileges=yes) so it can't
+# sudo/systemctl-restart itself; instead it touches $RUN_DIR/restart-requested and this root-owned
+# path unit restarts it (config cli_update:, taskboy/scheduler.py). replaces the old sudoers drop-in.
+install -m 644 "$assets_dir/deploy/$SLUG-restart.service" "/etc/systemd/system/$SLUG-restart.service"
+install -m 644 "$assets_dir/deploy/$SLUG-restart.path" "/etc/systemd/system/$SLUG-restart.path"
+rm -f "/etc/sudoers.d/$SVC_USER-cli-update"  # remove the old, NoNewPrivileges-incompatible sudo rule if present
+systemctl daemon-reload
+systemctl enable "$SLUG"
+systemctl enable --now "$SLUG-restart.path"
+
+echo "== done. next steps =="
+echo "  1) put secrets in aws secrets manager (TASKBOY_SECRETS_<ENV>), or export them in $ETC_DIR/env for a no-aws install"
+echo "  2) edit $ETC_DIR/config.yaml (or ship your shell repo's config via its deploy workflow)"
+echo "  3) systemctl start $SLUG && journalctl -fu $SLUG"

taskboy/deploy/remote-update.sh

@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+# host-side deploy step, invoked by the shell repo's ci via ssm run command:
+# pip-upgrade the venv from pypi, optionally sync operator config, refresh the
+# packaged host files, restart. restarts are safe — running tasks requeue and
+# resume (REL-002/003). host-level bootstrap changes (users, docker, iptables)
+# still need install.sh.
+# usage: remote-update.sh <pip-spec> [config-bundle-s3-url]
+#   pip-spec:             e.g. "taskboy==X.Y.Z" (the shell repo's pin)
+#   config-bundle-s3-url: optional s3 url of a tarball with config/ and skills/
+#                         directories; config/ syncs to /etc/taskboy and
+#                         skills/ to /opt/taskboy/skills (copy-over, no deletes)
+set -euo pipefail
+
+pip_spec="$1"
+config_url="${2:-}"
+workdir=$(mktemp -d /tmp/taskboy-deploy.XXXXXX)
+trap 'rm -rf "$workdir"' EXIT
+
+echo "== installing $pip_spec =="
+/opt/taskboy/.venv/bin/pip install -q --upgrade "$pip_spec"
+
+if [ -n "$config_url" ]; then
+  echo "== syncing config from $config_url =="
+  aws s3 cp "$config_url" "$workdir/config.tgz" --only-show-errors
+  mkdir "$workdir/bundle"
+  tar xzf "$workdir/config.tgz" -C "$workdir/bundle"
+  if [ -d "$workdir/bundle/config" ]; then
+    find "$workdir/bundle/config" -type f -exec chmod 640 {} +
+    cp -R "$workdir/bundle/config/." /etc/taskboy/
+    find /etc/taskboy -type f -exec chown "root:taskboy" {} + -exec chmod 640 {} +
+  fi
+  if [ -d "$workdir/bundle/skills" ]; then
+    cp -R "$workdir/bundle/skills/." /opt/taskboy/skills/
+    chown -R "taskboy:taskboy" /opt/taskboy/skills
+  fi
+fi
+
+echo "== refreshing packaged host files =="
+/opt/taskboy/.venv/bin/taskboy assets deploy "$workdir" > /dev/null
+install -m 644 "$workdir/deploy/taskboy.service" /etc/systemd/system/taskboy.service
+install -m 644 "$workdir/deploy/taskboy-restart.service" /etc/systemd/system/taskboy-restart.service
+install -m 644 "$workdir/deploy/taskboy-restart.path" /etc/systemd/system/taskboy-restart.path
+# the running copy keeps its inode; the new script takes effect next invocation
+install -m 755 "$workdir/deploy/install.sh" /opt/taskboy/deploy/install.sh
+install -m 755 "$workdir/deploy/remote-update.sh" /opt/taskboy/deploy/remote-update.sh
+systemctl daemon-reload
+
+echo "== restarting =="
+systemctl restart taskboy
+sleep 5
+systemctl is-active taskboy
+echo "deploy ok: $pip_spec"

taskboy/deploy/taskboy-restart.path

@@ -0,0 +1,10 @@
+[Unit]
+Description=watch for taskboy cli auto-update restart requests
+
+[Path]
+# the sandboxed service (NoNewPrivileges=yes) can't restart itself; it touches this flag and we act on it
+PathExists=/run/taskboy/restart-requested
+Unit=taskboy-restart.service
+
+[Install]
+WantedBy=multi-user.target

taskboy/deploy/taskboy-restart.service

@@ -0,0 +1,8 @@
+[Unit]
+Description=restart taskboy after an off-peak cli auto-update
+
+[Service]
+Type=oneshot
+# clear the flag first so the .path unit re-arms for the next update, then restart the service
+ExecStartPre=/usr/bin/rm -f /run/taskboy/restart-requested
+ExecStart=/usr/bin/systemctl restart taskboy.service

taskboy/deploy/taskboy.service

@@ -0,0 +1,22 @@
+[Unit]
+Description=taskboy orchestrator
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+User=taskboy
+Group=taskboy
+WorkingDirectory=/opt/taskboy
+EnvironmentFile=/etc/taskboy/env
+ExecStart=/opt/taskboy/.venv/bin/python -m taskboy.main
+# restarts are safe by design: reconciliation requeues and resumes interrupted tasks
+Restart=on-failure
+RestartSec=5
+# invalid config exits 64: stop instead of crash-looping
+RestartPreventExitStatus=64
+TimeoutStopSec=90
+NoNewPrivileges=yes
+PrivateTmp=yes
+
+[Install]
+WantedBy=multi-user.target

taskboy/hooks.py

@@ -0,0 +1,208 @@
+"""tool policy + audit for sub-agent sessions (TOL-004/005, §8.4).
+
+pure functions decide; the TaskHooks callbacks apply them inside a session. platform
+enforcement (github rulesets, IAM, jira permissions) is always the real control — this
+layer is defense-in-depth and the audit feed. every denial is recorded (§10).
+"""
+
+import re
+
+from claude_agent_sdk import PermissionResultAllow, PermissionResultDeny
+
+from taskboy.models import Task
+from taskboy.store import Store
+
+# read/write classification per tool; unknown tools are conservatively write (TOL-005)
+TOOL_CLASSIFICATION = {
+    "Read": "read",
+    "Grep": "read",
+    "Glob": "read",
+    "WebFetch": "read",
+    "WebSearch": "read",
+    "ToolSearch": "read",  # loads deferred tool schemas only; per-tool allowlisting still gates execution (#94)
+    "Bash": "write",  # conservative: bash can do anything
+    "Write": "write",
+    "Edit": "write",
+    "NotebookEdit": "write",
+    "mcp__harness__report_progress": "read",
+    "mcp__harness__report_blocked": "read",
+    "mcp__harness__request_permission": "read",
+    "mcp__harness__ask_questions": "read",
+    "mcp__issues__list_task_feedback": "read",
+    "mcp__issues__list_failed_tasks": "read",
+    "mcp__issues__list_recent_errors": "read",
+    "mcp__issues__record_issue": "write",
+    "mcp__issues__list_accepted_issues": "read",
+    "mcp__issues__list_existing_issues": "read",
+    "mcp__issues__get_issue": "read",
+    "mcp__issues__update_issue": "write",
+    "mcp__issues__list_issue_comments": "read",
+    "mcp__issues__post_issue_comment": "write",
+    "mcp__issues__update_issue_comment": "write",
+    "mcp__issues__delete_issue_comment": "write",
+    "mcp__issues__resolve_issue_comment": "write",
+    "mcp__issues__finish_issue": "write",
+    "mcp__enqueue__enqueue_spec_pr": "write",
+    "mcp__github__get_pull_request": "read",
+    "mcp__github__list_pull_requests": "read",
+    "mcp__github__list_pr_files": "read",
+    "mcp__github__list_pr_comments": "read",
+    "mcp__github__create_pull_request": "write",
+    "mcp__github__comment_on_pull_request": "write",
+    "mcp__github__create_pr_review": "write",
+    "mcp__github__reply_to_pr_comment": "write",
+    "mcp__github__resolve_pr_thread": "write",
+    "mcp__github__close_pull_request": "write",
+    "mcp__github__delete_branch": "write",
+    "mcp__github__create_release": "write",
+    "mcp__jira__search_issues": "read",
+    "mcp__jira__search_users": "read",
+    "mcp__jira__get_issue": "read",
+    "mcp__jira__list_boards": "read",
+    "mcp__jira__list_sprints": "read",
+    "mcp__jira__create_issue": "write",
+    "mcp__jira__add_comment": "write",
+    "mcp__jira__assign_issue": "write",
+    "mcp__jira__transition_issue": "write",
+    "mcp__jira__move_to_sprint": "write",
+    "mcp__jira__set_epic": "write",
+    "mcp__jira__set_story_points": "write",
+    "mcp__jira__link_pr": "write",
+    "mcp__sentry__list_issues": "read",
+    "mcp__sentry__get_issue": "read",
+    "mcp__sentry__get_latest_event": "read",
+    "mcp__aws__aws_read": "read",
+    "mcp__slack__channel_history": "read",
+    "mcp__slack__thread_replies": "read",
+    "mcp__slack__user_info": "read",
+    "mcp__slack__get_file": "read",
+    "mcp__slack__send_dm": "write",
+    "mcp__confluence__search_pages": "read",
+    "mcp__confluence__get_page": "read",
+}
+
+
+def classify_tool(tool_name: str) -> str:
+    return TOOL_CLASSIFICATION.get(tool_name, "write")
+
+
+def profile_permits_writes(allowed_tools: list[str]) -> bool:
+    """a profile tier is write-capable if its base allowlist holds a *recognized* write tool other than Bash.
+    Bash is present in every tier for investigation and is separately policed (hooks + read-only git token),
+    so its presence does not make an otherwise read-only profile eligible to gain Write/Edit/write-MCP tools.
+    Unrecognized tools are deliberately NOT treated as write here: an unclassified read tool in a read-only
+    profile (e.g. mcp__slack__user_info) must not flip the tier to write-capable and reopen the gate (§8.4)."""
+    return any(TOOL_CLASSIFICATION.get(tool_name) == "write" and tool_name != "Bash" for tool_name in allowed_tools)
+
+
+def tool_grantable(tool_name: str, profile_allowed_tools: list[str]) -> bool:
+    """whether a mid-task grant may admit this tool: it must be recognized, and a read-only profile
+    tier can only ever gain read tools — never a write tool it was deliberately denied (§8.4)."""
+    if tool_name not in TOOL_CLASSIFICATION:
+        return False
+    if classify_tool(tool_name) == "read":
+        return True
+    return profile_permits_writes(profile_allowed_tools)
+
+
+def repo_grantable(target: str, approved_repos: list[str], accessible_repos: set[str] | None) -> bool:
+    """whether an out-of-role-scope repo may be escalated for operator review (issue #39)."""
+    if "/" not in target:
+        return False
+    owner, _, name = target.partition("/")
+    if not owner or not name:
+        return False
+    allowed_orgs = {repo.split("/", 1)[0] for repo in approved_repos if "/" in repo}
+    if owner not in allowed_orgs:
+        return False
+    if accessible_repos is not None and name not in accessible_repos:
+        return False
+    return True
+
+
+# git allows global options between "git" and the subcommand (issue #106); this skips a bounded, quote-aware set of them.
+_GIT_OPT_WORD = r"(?:[^\s'\"]|'[^']*'|\"[^\"]*\")+"
+_GIT_GLOBAL_OPT = rf"(?:-c|-C|--git-dir|--work-tree|--namespace|--config-env|--attr-source)\s+(?!-){_GIT_OPT_WORD}|-{_GIT_OPT_WORD}"
+_GIT_PUSH = rf"\bgit\b(?:\s+(?:{_GIT_GLOBAL_OPT}))*\s+['\"]?push\b"
+
+
+def bash_denial(command: str, protected_branches: list[str]) -> str | None:
+    """returns a denial reason, or None when the command is allowed."""
+    command = command.replace("\\\n", "")  # join backslash-continued lines before scanning
+    command = re.sub(r"\s(?:\d*>{1,2}|&>{1,2})\s*(?:&\d+|[^\s;&|<>]+)", " ", command)  # strip redirects so a redirect target isn't scanned as guard content
+    if "169.254.169.254" in command:
+        return "access to the instance metadata service is blocked"
+    # deliberately non-exhaustive defense-in-depth; host controls remain authoritative.
+    if re.search(r"/proc/(?:self|\d+)/environ\b", command) or ("os.environ" in command and re.search(r"\bpython(?:3(?:\.\d+)?)?\b[^;&|]*\s-c\b", command)):
+        return "dumping the process environment is blocked"
+    if re.search(r"\bprintenv\b", command) or re.search(r"(^|[;&|]\s*)env\s*($|[;&|>])", command.strip()):
+        return "dumping the process environment is blocked"
+    # a wildcard refspec updates a protected branch without naming it, exactly like --all/--mirror
+    if re.search(rf"{_GIT_PUSH}[^;&|\n]*\s['\"]?(?:--(?:all|mirror)\b|\S*\*)", command):
+        return "pushing with --all, --mirror, or a wildcard refspec is blocked"
+    if re.search(rf"{_GIT_PUSH}[^;&|\n]*(?:\s['\"]?--force\b|\s['\"]?-\w*f\w*\b|\s['\"]?\+\S)", command):
+        return "force pushes are blocked"
+    # --no-verify (git accepts unambiguous abbreviations) or a hook-config override would dodge the workspace pre-push hook
+    if re.search(r"\bgit\b[^;&|\n]*\bpush\b[^;&|\n]*\s--no-veri[a-z]*\b", command):
+        return "pushing with --no-verify is blocked"
+    if (
+        re.search(r"(?:-c\s*[\"']?|--config-env=)core\.hookspath=", command, re.IGNORECASE)
+        or re.search(r"\bgit\b[^;&|\n]*\bconfig\b[^;&|\n]*core\.hookspath", command, re.IGNORECASE)
+        or re.search(r"(?:^|[;&|(\n])\s*(?:(?:env|export)\s+|\w+=\S*\s+)*GIT_CONFIG_\w+=", command)
+        or re.search(r"\benv\s+-u\s+GIT_CONFIG_\w+", command)
+    ):
+        return "overriding git hook configuration is blocked"
+    for branch in protected_branches:
+        # a protected name inside a longer ref (agent/t123-main-guard-fix) is not a push to it.
+        if re.search(rf"{_GIT_PUSH}[^;&|\n]*(?<![\w.-]){re.escape(branch)}(?![\w.-])", command):
+            return f"pushing to protected branch '{branch}' is blocked"
+    return None
+
+
+class TaskHooks:
+    """per-session policy + audit, wired as a PreToolUse hook.
+
+    NOT can_use_tool: allowed_tools entries auto-approve whole tools before that callback
+    is consulted (CanUseToolShadowedWarning), which would silently skip audit and denials.
+    a PreToolUse hook fires for every call regardless of allow rules.
+    """
+
+    def __init__(self, store: Store, task: Task, protected_branches: list[str], allowed_tools: list[str] | None = None):
+        self.store = store
+        self.task = task
+        self.protected_branches = protected_branches
+        self.allowed_tools = allowed_tools  # None = no profile restriction; otherwise deny anything off-list
+
+    def _decide(self, tool_name: str, tool_input: dict) -> str | None:
+        """audit the call and return a denial reason, or None to allow."""
+        if self.allowed_tools is not None and tool_name not in self.allowed_tools:
+            # the profile allowlist is the contract; without this, non-allowlisted tools
+            # (e.g. Task, which spawns sub-agents) fall through to the callback and slip past
+            reason = f"tool {tool_name} is not in this task's profile"
+            self.store.add_event(self.task.task_id, "security_denial", {"reason": reason, "input": _digest(tool_input)}, tool_name=tool_name, is_write=True)
+            return reason
+        if tool_name == "Bash":
+            bash_reason = bash_denial(str(tool_input.get("command", "")), self.protected_branches)
+            if bash_reason:
+                self.store.add_event(self.task.task_id, "security_denial", {"reason": bash_reason, "input": _digest(tool_input)}, tool_name=tool_name, is_write=True)
+                return bash_reason
+        self.store.add_event(self.task.task_id, "tool_call", {"input": _digest(tool_input)}, tool_name=tool_name, is_write=classify_tool(tool_name) == "write")
+        return None
+
+    async def pre_tool_use(self, input_data: dict, tool_use_id=None, context=None) -> dict:
+        reason = self._decide(str(input_data.get("tool_name", "")), input_data.get("tool_input") or {})
+        if reason:
+            return {"hookSpecificOutput": {"hookEventName": "PreToolUse", "permissionDecision": "deny", "permissionDecisionReason": reason}}
+        return {}
+
+    async def can_use_tool(self, tool_name: str, tool_input: dict, context=None) -> PermissionResultAllow | PermissionResultDeny:
+        # backstop for calls that reach the permission callback (non-allowlisted tools)
+        reason = self._decide(tool_name, tool_input)
+        if reason:
+            return PermissionResultDeny(message=reason)
+        return PermissionResultAllow()
+
+
+def _digest(tool_input: dict) -> str:
+    # bounded before it enters the audit trail (TOL-006); store redacts on write
+    return str(tool_input)[:300]

taskboy/issue_runs.py

@@ -0,0 +1,203 @@
+"""issues triggers: run the discovery/implementation skills on demand as the system identity.
+
+used by the dashboard's "Run discovery"/"Implement approved" buttons. recurring runs go through the
+general task scheduler (taskboy/scheduler.py), which seeds the daily discovery/implementation jobs.
+"""
+
+import re
+import uuid
+from datetime import datetime, timedelta, timezone
+
+from taskboy.config import Config
+from taskboy.models import BLOCKED, FAILED, Task, utcnow
+from taskboy.orchestrator import accept_task
+from taskboy.store import Store, TransitionRaced
+
+# system-owned tasks reuse the "github" identity, which the default config maps to the read/standard system role
+SYSTEM_TEAM = "github"
+SYSTEM_USER = "github"
+
+GITHUB_API = "https://api.github.com"
+# not end-anchored so a /files, ?query, or #fragment suffix still parses (#87)
+PR_URL_RE = re.compile(r"^https://github\.com/([^/\s]+/[^/\s]+)/pull/(\d+)")
+
+# a batch this size keeps a run's PRs reviewable (also enforced by the coordinator only seeing its reserved rows)
+IMPLEMENTATION_BATCH_SIZE = 5
+STALLED_COORDINATOR_MAX_AGE_HOURS = 24
+
+
+async def start_issue_task(store: Store, config: Config, notifier, skill: str, args: str = "", *, source: str):
+    """enqueue one issues skill task as the system identity. returns (task, status) from accept_task."""
+    channel = str(((config.raw.get("issues") or {}).get("notify_channel")) or "")
+    key = f"issues:{skill}:{source}@{utcnow()}"
+    text = f"/{skill}"
+    if args.strip():
+        text += f" {args.strip()}"
+    return await accept_task(
+        store,
+        config,
+        notifier,
+        team_id=SYSTEM_TEAM,
+        channel_id=channel,
+        thread_ts=key,
+        message_ts=key,
+        user_id=SYSTEM_USER,
+        text=text,
+    )
+
+
+async def start_refine_task(store: Store, config: Config, notifier, issue_id: int, *, source: str) -> tuple[Task | None, str, str | None]:
+    """start one refine task per issue, returning the active task id when one already exists."""
+    existing = store.active_refine_task(issue_id)
+    if existing is not None:
+        return None, "already_running", existing
+    task, status = await start_issue_task(store, config, notifier, "refineissue", str(issue_id), source=source)
+    return task, status, None
+
+
+async def start_implementation_run(
+    store: Store,
+    config: Config,
+    notifier,
+    *,
+    thread_key: str,
+    request_text: str = "/implementapprovedissues",
+    user_id: str = SYSTEM_USER,
+    channel_id: str | None = None,
+    model_override: str | None = None,
+    effort_override: str | None = None,
+    schedule_name: str | None = None,
+    issue_ids: list[int] | None = None,
+    actor: str | None = None,
+) -> tuple[Task | None, str, str | None]:
+    """with `issue_ids` omitted, reserves up to IMPLEMENTATION_BATCH_SIZE approved issues top-priority-first;
+    with `issue_ids` given, approves any of those still `proposed` (as `actor`) and reserves exactly that set.
+    Returns (task, status, active_task_id): status is "already_running", "no_approved_issues", or whatever
+    accept_task reports ("created" or a refusal like "paused"/"queue_full"/"duplicate")."""
+    existing = store.active_implementation_run()
+    if existing is not None:
+        return None, "already_running", existing
+    if store.has_pending_implementation_reservation():
+        return None, "already_running", None
+
+    marker = f"pending:{uuid.uuid4().hex[:12]}"
+    auto_approved_ids: list[int] = []
+    if issue_ids is not None:
+        for issue_id in issue_ids:
+            issue = store.get_issue(issue_id)
+            if issue is not None and issue["status"] == "proposed":
+                store.decide_issue(issue_id, "approved", actor or user_id)
+                auto_approved_ids.append(issue_id)
+        reserved = store.reserve_issues_by_id(marker, issue_ids)
+    else:
+        reserved = store.reserve_issues(marker, IMPLEMENTATION_BATCH_SIZE)
+    if not reserved:
+        return None, "no_approved_issues", None
+    # only the ones we actually reserved under this marker count — a row that missed reservation
+    # (e.g. denied by someone else in between) was never ours to roll back
+    reserved_ids = {row["id"] for row in reserved}
+    auto_approved_ids = [issue_id for issue_id in auto_approved_ids if issue_id in reserved_ids]
+
+    channel = channel_id if channel_id is not None else str(((config.raw.get("issues") or {}).get("notify_channel")) or "")
+    assigned = False
+    try:
+        task, status = await accept_task(
+            store,
+            config,
+            notifier,
+            team_id=SYSTEM_TEAM,
+            channel_id=channel,
+            thread_ts=thread_key,
+            message_ts=thread_key,
+            user_id=user_id,
+            text=request_text,
+            model_override=model_override,
+            effort_override=effort_override,
+            schedule_name=schedule_name,
+        )
+        if status != "created" or task is None:
+            return task, status, None
+        store.assign_reservation(marker, task.task_id)
+        assigned = True
+        return task, "created", None
+    finally:
+        # covers accept_task raising (incl. cancellation) and the plain refusal case above — either way, don't
+        # strand the reservation under a marker no coordinator will ever claim
+        if not assigned:
+            store.release_reserved_issues(marker)
+            # release_reserved_issues put these back to approved; anything we auto-approved from proposed
+            # goes back to proposed instead, so a failed rocket click doesn't leave it eligible for the next batch run
+            for issue_id in auto_approved_ids:
+                store.decide_issue(issue_id, "proposed", actor or user_id)
+
+
+def fail_stalled_implementation_run(store: Store) -> str | None:
+    """fail a coordinator left blocked for over a day and release its reserved issues."""
+    task_id = store.blocked_implementation_run()
+    if task_id is None:
+        return None
+    task = store.get_task(task_id)
+    cutoff = datetime.now(timezone.utc) - timedelta(hours=STALLED_COORDINATOR_MAX_AGE_HOURS)
+    if task is None or task.state != BLOCKED or datetime.fromisoformat(task.updated_at) >= cutoff:
+        return None
+    try:
+        store.transition(
+            task_id,
+            BLOCKED,
+            FAILED,
+            "recovery: implementation coordinator stalled",
+            error="implementation coordinator stalled in blocked for over 24h",
+            finished_at=utcnow(),
+        )
+    except TransitionRaced:
+        return None
+    store.add_event(task_id, "recovery", {"action": "failed_stalled_coordinator"})
+    return task_id
+
+
+async def _get_pr(repo: str, number: int, token: str) -> dict:
+    """the github http seam for sync_in_review — patched in unit tests."""
+    import aiohttp
+
+    from taskboy.adapters.github_api import GitHubStatusError
+    from taskboy.redact import redactor
+
+    headers = {"Authorization": f"Bearer {token}", "Accept": "application/vnd.github+json"}
+    async with aiohttp.ClientSession() as session:
+        async with session.get(f"{GITHUB_API}/repos/{repo}/pulls/{number}", headers=headers) as response:
+            if response.status >= 300:
+                body = redactor.redact(await response.text())[:300]
+                raise GitHubStatusError(response.status, f"github api GET pulls/{number} failed: {response.status} — {body}")
+            return await response.json()
+
+
+async def sync_in_review(store: Store, broker) -> int:
+    """resolve issues whose PR has since merged (-> done) or closed unmerged (-> failed); still-open PRs
+    are left alone. called hourly from housekeeping_loop. one row's error is recorded and skipped, not raised,
+    so it never blocks the rest of the sweep."""
+    updated = 0
+    tokens: dict[str, str] = {}
+    for row in store.list_issues(status="in_review"):
+        pr_url = row.get("pr_url")
+        if not pr_url:
+            continue
+        match = PR_URL_RE.match(pr_url)
+        if not match:
+            store.add_error("issue_runs", "BadPrUrl", f"issue #{row['id']} has an unparseable pr_url: {pr_url}", context={"issue_id": row["id"]})
+            continue
+        repo, number = match.group(1), int(match.group(2))
+        try:
+            if repo not in tokens:
+                token, _ = await broker.read_token([repo], permissions={"pull_requests": "read", "metadata": "read"})
+                tokens[repo] = token
+            pr = await _get_pr(repo, number, tokens[repo])
+        except Exception as e:
+            store.add_error("issue_runs", type(e).__name__, str(e), context={"issue_id": row["id"], "repository": repo})
+            continue
+        if pr.get("merged"):
+            store.finish_issue(row["id"], "done", pr_url)
+            updated += 1
+        elif pr.get("state") == "closed":
+            store.finish_issue(row["id"], "failed", pr_url)
+            updated += 1
+    return updated