taskboy 0.1.1__py3-none-any.whl

taskboy/scheduler.py

@@ -0,0 +1,301 @@
+"""dashboard-defined task scheduler: fire due schedules as tasks, then advance them.
+
+deterministic Python like the rest of the orchestrator — the loop only enqueues tasks; the classifier
+and runner do the model work. schedules run as the system identity (team 'github') with requester 'cli'
+so an explicit model choice is honored like any operator-initiated task; lifecycle posts land top-level
+in the debug channel with a "Scheduled Task Started" announcement instead of the quip pool.
+"""
+
+import asyncio
+import logging
+import sys
+import traceback
+from datetime import datetime, time, timedelta, timezone
+from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
+
+from taskboy.config import Config
+from taskboy.issue_runs import start_implementation_run
+from taskboy.models import utcnow
+from taskboy.orchestrator import _notify_safe, accept_task, intake_paused, queue_at_capacity
+from taskboy.store import Store
+
+logger = logging.getLogger("taskboy.scheduler")
+
+TICK_SECONDS = 30
+SCHEDULE_TEAM = "github"  # notifier treats github-team tasks as silent when no channel is set
+SCHEDULE_USER = "cli"  # the operator-task identity; its role permits the model dropdown's overrides
+
+CLI_UPDATE_NEXT_RUN_META_KEY = "cli_update_next_run_at"
+CLI_UPDATE_PACKAGE = "claude-agent-sdk"  # bundles the claude cli (see the packaged install.sh)
+CLI_UPDATE_SERVICE_UNIT = "taskboy"
+# NoNewPrivileges=yes blocks sudo/setuid, so we can't restart the unit from inside this process. instead
+# touch this flag; the root-owned taskboy-restart.path unit watches it and restarts us (packaged install.sh)
+CLI_UPDATE_RESTART_FLAG = "/run/taskboy/restart-requested"
+
+
+def _zone(name: str | None):
+    if not name:
+        return timezone.utc
+    try:
+        return ZoneInfo(name)
+    except (ZoneInfoNotFoundError, ValueError):
+        return timezone.utc
+
+
+def next_run_after(kind: str, *, interval_minutes: int | None, at_time: str | None, run_at: str | None, tzname: str | None, after: datetime) -> datetime | None:
+    """the next UTC fire time strictly after `after`, or None when the schedule has no future run (a one-off already due).
+
+    `after` must be an aware UTC datetime. used both to seed a schedule's first run (after=now) and to advance it after a fire."""
+    if kind == "once":
+        target = datetime.fromisoformat(run_at) if run_at else None
+        return target if target is not None and target > after else None
+    if kind == "interval":
+        minutes = max(int(interval_minutes or 0), 1)
+        return after + timedelta(minutes=minutes)
+    if kind == "daily":
+        tz = _zone(tzname)
+        local = after.astimezone(tz)
+        hour, minute = (int(part) for part in str(at_time or "00:00").split(":"))
+        target = datetime.combine(local.date(), time(hour, minute), tzinfo=tz)
+        if target <= local:
+            target = datetime.combine(local.date() + timedelta(days=1), time(hour, minute), tzinfo=tz)
+        return target.astimezone(timezone.utc)
+    raise ValueError(f"unknown schedule kind {kind!r}")
+
+
+def _now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def _is_implementation_run(request_text: str) -> bool:
+    # matches store.active_implementation_run()'s own LIKE '/implementapprovedissues%' check
+    return request_text.strip().startswith("/implementapprovedissues")
+
+
+async def fire_due(store: Store, config: Config, notifier, now: datetime) -> int:
+    """fire every schedule due at `now`, advancing each. returns how many fired."""
+    fired = 0
+    for schedule in store.due_schedules(now.isoformat(timespec="seconds")):
+        try:
+            # key the task to the slot that triggered it so a double-tick can't create two tasks for one slot
+            slot = str(schedule["next_run_at"])
+            notify_key = f"schedule_fire_refused:{schedule['id']}"
+            # slot + hour bucket: a schedule stuck for days still re-pages every hour instead of paging once ever
+            notify_value = f"{slot}@{now:%Y-%m-%dT%H}"
+            gate_status = "paused" if intake_paused(store) else "queue_full" if queue_at_capacity(store, config) else None
+            if gate_status is not None:
+                # gated before the attempt so a known-refused schedule never re-enters accept_task (and its
+                # own error-row write, or the implementation path's reserve/release of a batch) every tick
+                if store.meta_get(notify_key) != notify_value:
+                    store.meta_set(notify_key, notify_value)
+                    detail = f"schedule {schedule['id']} ({schedule['name']}) fire refused ({gate_status}); slot not consumed, will retry next tick"
+                    store.add_error("scheduler", "fire_refused", detail, context={"schedule_id": schedule["id"], "schedule_name": schedule["name"], "status": gate_status})
+                    debug = getattr(notifier, "debug", None)
+                    if debug is not None:
+                        await _notify_safe(debug.system_error, "scheduler", detail)
+                    logger.warning("schedule %s fire refused (%s); slot %s not consumed", schedule["id"], gate_status, slot)
+                continue
+            if _is_implementation_run(schedule["request_text"]):
+                # reserve the batch before the coordinator exists so an empty queue never starts one
+                task, status, _active = await start_implementation_run(
+                    store,
+                    config,
+                    notifier,
+                    request_text=schedule["request_text"],
+                    user_id=SCHEDULE_USER,
+                    channel_id=config.slack.debug_channel,
+                    thread_key=f"schedule:{schedule['id']}@{slot}",
+                    model_override=schedule["model_alias"] or None,
+                    effort_override=schedule["effort"] or None,
+                    schedule_name=schedule["name"],
+                )
+            else:
+                task, status = await accept_task(
+                    store,
+                    config,
+                    notifier,
+                    team_id=SCHEDULE_TEAM,
+                    channel_id=config.slack.debug_channel,
+                    thread_ts=f"schedule:{schedule['id']}@{slot}",
+                    message_ts=f"schedule:{schedule['id']}@{slot}",
+                    user_id=SCHEDULE_USER,
+                    text=schedule["request_text"],
+                    model_override=schedule["model_alias"] or None,
+                    effort_override=schedule["effort"] or None,
+                    schedule_name=schedule["name"],
+                )
+            task_id = task.task_id if task else None
+            nxt = next_run_after(schedule["kind"], interval_minutes=schedule["interval_minutes"], at_time=schedule["at_time"], run_at=schedule["run_at"], tzname=schedule["timezone"], after=now)
+            run_count_after = int(schedule["run_count"]) + 1
+            exhausted = schedule["max_runs"] is not None and run_count_after >= int(schedule["max_runs"])
+            enabled = nxt is not None and not exhausted
+            store.record_schedule_fire(schedule["id"], task_id, nxt.isoformat(timespec="seconds") if nxt else slot, enabled)
+            fired += 1
+            logger.info("schedule %s fired -> task %s (%s), next=%s enabled=%s", schedule["id"], task_id, status, nxt, enabled)
+        except Exception as e:
+            # advance past this slot so a broken schedule doesn't refire every tick; keep it enabled for a retry next slot
+            nxt = next_run_after(schedule["kind"], interval_minutes=schedule["interval_minutes"], at_time=schedule["at_time"], run_at=schedule["run_at"], tzname=schedule["timezone"], after=now)
+            store.record_schedule_fire(schedule["id"], None, nxt.isoformat(timespec="seconds") if nxt else str(schedule["next_run_at"]), enabled=nxt is not None)
+            store.add_error("scheduler", type(e).__name__, str(e), traceback=traceback.format_exc(), context={"schedule_id": schedule["id"]})
+            logger.exception("schedule %s failed to fire", schedule["id"])
+    return fired
+
+
+async def fire_schedule_now(store: Store, config: Config, notifier, schedule: dict):
+    """fire a schedule immediately without advancing its next_run_at (a manual run-now from the dashboard)."""
+    slot = utcnow()
+    if _is_implementation_run(schedule["request_text"]):
+        task, status, _active = await start_implementation_run(
+            store,
+            config,
+            notifier,
+            request_text=schedule["request_text"],
+            user_id=SCHEDULE_USER,
+            channel_id=config.slack.debug_channel,
+            thread_key=f"schedule:{schedule['id']}:manual@{slot}",
+            model_override=schedule["model_alias"] or None,
+            effort_override=schedule["effort"] or None,
+            schedule_name=schedule["name"],
+        )
+        return task, status
+    return await accept_task(
+        store,
+        config,
+        notifier,
+        team_id=SCHEDULE_TEAM,
+        channel_id=config.slack.debug_channel,
+        thread_ts=f"schedule:{schedule['id']}:manual@{slot}",
+        message_ts=f"schedule:{schedule['id']}:manual@{slot}",
+        user_id=SCHEDULE_USER,
+        text=schedule["request_text"],
+        model_override=schedule["model_alias"] or None,
+        effort_override=schedule["effort"] or None,
+        schedule_name=schedule["name"],
+    )
+
+
+def cli_update_due(next_run_iso: str | None, at_time: str, tzname: str, now: datetime) -> tuple[bool, str]:
+    """pure scheduling decision for the off-peak cli auto-update: whether it is due now, and the next_run_at
+    to persist either way. `next_run_iso` is None on the very first check (seeds a run time without firing)."""
+    if next_run_iso is None:
+        nxt = next_run_after("daily", interval_minutes=None, at_time=at_time, run_at=None, tzname=tzname, after=now)
+        assert nxt is not None  # "daily" always has a next run
+        return False, nxt.isoformat(timespec="seconds")
+    next_run = datetime.fromisoformat(next_run_iso)
+    if now < next_run:
+        return False, next_run_iso
+    # advance immediately, before the upgrade runs, so a slow or crashing upgrade can't refire the same slot
+    nxt = next_run_after("daily", interval_minutes=None, at_time=at_time, run_at=None, tzname=tzname, after=now)
+    assert nxt is not None
+    return True, nxt.isoformat(timespec="seconds")
+
+
+async def _run_subprocess(*args: str) -> tuple[bool, str]:
+    """the process-execution seam — patched in unit tests so they never actually pip install."""
+    proc = await asyncio.create_subprocess_exec(*args, stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.STDOUT)
+    stdout, _ = await proc.communicate()
+    output = (stdout or b"").decode(errors="replace")
+    return proc.returncode == 0, output
+
+
+def _request_restart() -> tuple[bool, str]:
+    """the restart seam — patched in unit tests. touches the flag the root-side path unit watches; this needs
+    no privileges (NoNewPrivileges-safe), unlike sudo/systemctl from inside the sandboxed service process."""
+    try:
+        with open(CLI_UPDATE_RESTART_FLAG, "w") as flag:
+            flag.write(utcnow())
+        return True, CLI_UPDATE_RESTART_FLAG
+    except OSError as e:
+        return False, str(e)
+
+
+async def run_cli_update(store: Store) -> None:
+    """off-peak upgrade of the claude-agent-sdk package (which bundles the claude cli, packaged install.sh)
+    straight from pypi, always the latest release and ungated by ci, then a self-restart so the new version
+    takes effect (restarts are safe: reconciliation requeues/resumes interrupted tasks, REL-002/003). a failed
+    pip pull is recorded and must never restart the service (a broken upgrade should stay visibly broken, not
+    take down a working deployment)."""
+    ok, output = await _run_subprocess(sys.executable, "-m", "pip", "install", "--upgrade", CLI_UPDATE_PACKAGE)
+    if not ok:
+        store.add_error("cli_update", "pip_upgrade_failed", output[-2000:])
+        logger.error("cli auto-update: pip upgrade of %s failed: %s", CLI_UPDATE_PACKAGE, output[-500:])
+        return
+    if "Successfully installed" not in output:
+        # pip exits 0 for a no-op upgrade too ("Requirement already satisfied") — only a real
+        # version bump needs a restart; skip it so an already-current install doesn't interrupt tasks nightly
+        logger.info("cli auto-update: %s already up to date, no restart needed", CLI_UPDATE_PACKAGE)
+        return
+    logger.info("cli auto-update: %s upgraded; requesting restart of %s", CLI_UPDATE_PACKAGE, CLI_UPDATE_SERVICE_UNIT)
+    # sudo/systemctl can't work here (NoNewPrivileges=yes); the root-side taskboy-restart.path unit watches
+    # this flag and does the restart outside our sandbox (packaged install.sh)
+    requested, restart_output = _request_restart()
+    if not requested:
+        store.add_error("cli_update", "restart_failed", restart_output[-2000:])
+        logger.error("cli auto-update: upgraded %s but restart request failed: %s", CLI_UPDATE_PACKAGE, restart_output[-500:])
+
+
+async def maybe_run_cli_update(store: Store, config: Config, now: datetime) -> bool:
+    """checked every scheduler tick; fires at most once per configured window, off by default (config.cli_update)."""
+    cli_update = config.cli_update
+    if not cli_update.enabled:
+        return False
+    due, next_run_at = cli_update_due(store.meta_get(CLI_UPDATE_NEXT_RUN_META_KEY), cli_update.at_time, cli_update.tzname, now)
+    store.meta_set(CLI_UPDATE_NEXT_RUN_META_KEY, next_run_at)
+    if not due:
+        return False
+    await run_cli_update(store)
+    return True
+
+
+async def scheduler_loop(store: Store, config: Config, notifier) -> None:
+    while True:
+        try:
+            await fire_due(store, config, notifier, _now())
+            await maybe_run_cli_update(store, config, _now())
+        except Exception as e:
+            store.add_error("scheduler", type(e).__name__, str(e), traceback=traceback.format_exc())
+            logger.exception("scheduler tick failed")
+        await asyncio.sleep(TICK_SECONDS)
+
+
+# shipped defaults, all daily Pacific with the model left blank: discovery/implementation route via the skills'
+# own frontmatter; the warm-up is a trivial question that routes to haiku and opens the Claude Max usage
+# window before the workday (it replaces the former one-off warmup config — edit or disable it in the UI).
+SEED_SCHEDULES = [
+    {"seed_key": "implementapprovedissues-daily", "name": "Implement approved issues (daily)", "request_text": "/implementapprovedissues", "at_time": "03:00"},
+    {"seed_key": "warmup-daily", "name": "Claude usage-window warm-up (daily)", "request_text": "What does the HTTP status code 200 mean?", "at_time": "04:00"},
+]
+SEED_TIMEZONE = "America/Los_Angeles"
+
+
+def seed_default_schedules(store: Store, self_repo: str = "", github_enabled: bool = True) -> None:
+    """install the shipped issues schedules exactly once, so an operator can later edit or delete them."""
+    if store.meta_get("schedules_seeded") == "1":
+        return
+    now = _now()
+    seeds = list(SEED_SCHEDULES)
+    if not github_enabled:
+        # the issues pipeline needs github; a github-less install only gets the warm-up
+        seeds = [seed for seed in seeds if seed["seed_key"] == "warmup-daily"]
+    # daily issue discovery only makes sense against a repo; default to the agent's own when configured
+    if self_repo and github_enabled:
+        seeds.insert(0, {"seed_key": "discoverissues-daily", "name": "Discover issues (daily)", "request_text": f"/discoverissues {self_repo}", "at_time": "00:00"})
+    for seed in seeds:
+        nxt = next_run_after("daily", interval_minutes=None, at_time=seed["at_time"], run_at=None, tzname=SEED_TIMEZONE, after=now)
+        assert nxt is not None
+        store.seed_schedule_once(
+            seed["seed_key"],
+            name=seed["name"],
+            request_text=seed["request_text"],
+            model_alias=None,
+            kind="daily",
+            interval_minutes=None,
+            at_time=seed["at_time"],
+            run_at=None,
+            timezone=SEED_TIMEZONE,
+            max_runs=None,
+            next_run_at=nxt.isoformat(timespec="seconds"),
+            created_by="system",
+        )
+    store.meta_set("schedules_seeded", "1")
+    logger.info("seeded default issues schedules")

taskboy/secrets.py

@@ -0,0 +1,83 @@
+"""credential loading: env vars for local dev, one aws secrets manager json bundle on the host (§8.2).
+
+rotation = update the secret + restart the service; nothing here touches disk. every loaded
+credential is registered with the redactor so it cannot survive any output sink (AC-17).
+"""
+
+import json
+import os
+from dataclasses import dataclass
+
+from taskboy import settings
+from taskboy.redact import redactor
+
+
+@dataclass
+class Secrets:
+    slack_bot_token: str = ""
+    slack_app_token: str = ""
+    github_app_id: str = ""
+    github_installation_id: str = ""
+    github_app_private_key: str = ""
+    reviewer_github_app_id: str = ""
+    reviewer_github_installation_id: str = ""
+    reviewer_github_app_private_key: str = ""
+    jira_email: str = ""
+    jira_api_token: str = ""
+    sentry_token: str = ""
+    claude_oauth_token: str = ""  # populated from the bundle on the host; local dev exports it directly
+    dashboard_github_token: str = ""  # contents-only pat for dashboard commits straight to protected main
+
+    @property
+    def github_enabled(self) -> bool:
+        return bool(self.github_app_id and self.github_installation_id and self.github_app_private_key)
+
+    @property
+    def reviewer_github_enabled(self) -> bool:
+        return bool(self.reviewer_github_app_id and self.reviewer_github_installation_id and self.reviewer_github_app_private_key)
+
+    @property
+    def jira_enabled(self) -> bool:
+        return bool(self.jira_email and self.jira_api_token)
+
+
+def load_secrets() -> Secrets:
+    # local dev never touches secrets manager: env vars only, missing values stay empty
+    if settings.ENVIRONMENT == "local" or os.environ.get("SLACK_BOT_TOKEN") or os.environ.get("GITHUB_APP_ID") or os.environ.get("REVIEWER_GITHUB_APP_ID"):
+        secrets = Secrets(
+            slack_bot_token=os.environ.get("SLACK_BOT_TOKEN", ""),
+            slack_app_token=os.environ.get("SLACK_APP_TOKEN", ""),
+            github_app_id=os.environ.get("GITHUB_APP_ID", ""),
+            github_installation_id=os.environ.get("GITHUB_INSTALLATION_ID", ""),
+            github_app_private_key=os.environ.get("GITHUB_APP_PRIVATE_KEY", ""),
+            reviewer_github_app_id=os.environ.get("REVIEWER_GITHUB_APP_ID", ""),
+            reviewer_github_installation_id=os.environ.get("REVIEWER_GITHUB_INSTALLATION_ID", ""),
+            reviewer_github_app_private_key=os.environ.get("REVIEWER_GITHUB_APP_PRIVATE_KEY", ""),
+            jira_email=os.environ.get("JIRA_EMAIL", ""),
+            jira_api_token=os.environ.get("JIRA_API_TOKEN", ""),
+            sentry_token=os.environ.get("SENTRY_TOKEN", ""),
+            dashboard_github_token=os.environ.get("DASHBOARD_GITHUB_TOKEN", ""),
+        )
+    else:
+        import boto3  # lazy: only needed on the ec2 host
+
+        client = boto3.client("secretsmanager", region_name=settings.REGION)
+        blob = json.loads(client.get_secret_value(SecretId=settings.SECRETS_NAME)["SecretString"])
+        secrets = Secrets(
+            slack_bot_token=blob.get("slack_bot_token", ""),
+            slack_app_token=blob.get("slack_app_token", ""),
+            github_app_id=blob.get("github_app_id", ""),
+            github_installation_id=blob.get("github_installation_id", ""),
+            github_app_private_key=blob.get("github_app_private_key", ""),
+            reviewer_github_app_id=blob.get("reviewer_github_app_id", ""),
+            reviewer_github_installation_id=blob.get("reviewer_github_installation_id", ""),
+            reviewer_github_app_private_key=blob.get("reviewer_github_app_private_key", ""),
+            jira_email=blob.get("jira_email", ""),
+            jira_api_token=blob.get("jira_api_token", ""),
+            sentry_token=blob.get("sentry_token", ""),
+            claude_oauth_token=blob.get("claude_oauth_token", ""),
+            dashboard_github_token=blob.get("dashboard_github_token", ""),
+        )
+    for value in (secrets.slack_bot_token, secrets.slack_app_token, secrets.github_app_private_key, secrets.reviewer_github_app_private_key, secrets.jira_api_token, secrets.sentry_token, secrets.claude_oauth_token, secrets.dashboard_github_token):
+        redactor.register(value)
+    return secrets

taskboy/settings.py

@@ -0,0 +1,19 @@
+"""deployment-level settings from the environment. operator policy lives in config.yaml; credentials arrive via secrets manager in phase 2."""
+
+import os
+
+from taskboy import assets
+
+ENVIRONMENT = os.environ.get("ENVIRONMENT", "local")
+DB_PATH = os.environ.get("TASKBOY_DB_PATH", "local/taskboy.db")
+CONFIG_PATH = os.environ.get("TASKBOY_CONFIG_PATH", "config/config.yaml")
+WORKSPACES_ROOT = os.environ.get("TASKBOY_WORKSPACES_ROOT", "local/workspaces")
+REPOS_ROOT = os.environ.get("TASKBOY_REPOS_ROOT", "local/repos")
+MEMORY_ROOT = os.environ.get("TASKBOY_MEMORY_ROOT", "local/memory")
+SKILLS_ROOT = os.environ.get("TASKBOY_SKILLS_ROOT", "skills")
+UI_DIST = os.environ.get("TASKBOY_UI_DIST", str(assets.UI_DIST))
+REGION = os.environ.get("AWS_REGION", "us-east-1")
+SECRETS_NAME = os.environ.get("TASKBOY_SECRETS_NAME", f"TASKBOY_SECRETS_{ENVIRONMENT.upper()}")
+BROKER_SOCKET = os.environ.get("TASKBOY_BROKER_SOCKET", "local/broker.sock")
+REVIEWER_BROKER_SOCKET = os.environ.get("TASKBOY_REVIEWER_BROKER_SOCKET", "local/broker-reviewer.sock")
+GIT_CRED_HELPER = os.environ.get("TASKBOY_GIT_CRED_HELPER", str(assets.GIT_CRED_HELPER))

taskboy/setup_checks.py

@@ -0,0 +1,184 @@
+"""live credential validators for the setup wizard and `taskboy setup --check`.
+
+each check is a plain synchronous function returning (ok, detail). they use urllib so the
+wizard works before any optional dependency is installed, and never log or return the
+credential itself — only identifiers safe to echo.
+"""
+
+import base64
+import json
+import time
+import urllib.error
+import urllib.request
+
+USER_AGENT = "taskboy-setup"
+
+
+def _get_json(url: str, headers: dict[str, str]) -> tuple[int, dict]:
+    request = urllib.request.Request(url, headers={"User-Agent": USER_AGENT, **headers})
+    try:
+        with urllib.request.urlopen(request, timeout=15) as response:
+            return response.status, json.loads(response.read().decode() or "{}")
+    except urllib.error.HTTPError as e:
+        try:
+            return e.code, json.loads(e.read().decode() or "{}")
+        except (ValueError, OSError):
+            return e.code, {}
+
+
+def _post_json(url: str, headers: dict[str, str], body: dict | None = None) -> tuple[int, dict]:
+    data = json.dumps(body or {}).encode()
+    request = urllib.request.Request(url, data=data, method="POST", headers={"User-Agent": USER_AGENT, "Content-Type": "application/json", **headers})
+    try:
+        with urllib.request.urlopen(request, timeout=15) as response:
+            return response.status, json.loads(response.read().decode() or "{}")
+    except urllib.error.HTTPError as e:
+        try:
+            return e.code, json.loads(e.read().decode() or "{}")
+        except (ValueError, OSError):
+            return e.code, {}
+
+
+def _basic_auth(email: str, api_token: str) -> str:
+    return "Basic " + base64.b64encode(f"{email}:{api_token}".encode()).decode()
+
+
+def check_claude(token: str) -> tuple[bool, str]:
+    """one tiny haiku call through the sdk — proves headless auth works before anything else."""
+    if not token:
+        return False, "no token provided"
+    import asyncio
+    import os
+    import tempfile
+
+    async def probe() -> str:
+        from claude_agent_sdk import ClaudeAgentOptions, query
+
+        options = ClaudeAgentOptions(model="haiku", max_turns=3, allowed_tools=[], setting_sources=[], cwd=tempfile.mkdtemp())
+        result = ""
+        async for message in query(prompt="Reply with exactly: GO", options=options):
+            result = str(getattr(message, "result", "") or result)
+        return result
+
+    previous = os.environ.get("CLAUDE_CODE_OAUTH_TOKEN")
+    os.environ["CLAUDE_CODE_OAUTH_TOKEN"] = token
+    try:
+        result = asyncio.run(probe())
+    except Exception as e:
+        return False, f"{type(e).__name__}: {e}"
+    finally:
+        if previous is None:
+            os.environ.pop("CLAUDE_CODE_OAUTH_TOKEN", None)
+        else:
+            os.environ["CLAUDE_CODE_OAUTH_TOKEN"] = previous
+    if "GO" in result:
+        return True, "claude answered"
+    return False, f"unexpected reply: {result[:80]!r}"
+
+
+def check_slack(bot_token: str, team_id: str = "") -> tuple[bool, str]:
+    status, body = _post_json("https://slack.com/api/auth.test", {"Authorization": f"Bearer {bot_token}"})
+    if status != 200 or not body.get("ok"):
+        return False, f"auth.test failed: {body.get('error', status)}"
+    if team_id and body.get("team_id") != team_id:
+        return False, f"token belongs to team {body.get('team_id')}, not {team_id}"
+    return True, f"authed as @{body.get('user')} in team {body.get('team_id')}"
+
+
+def check_slack_channel(bot_token: str, channel_id: str) -> tuple[bool, str]:
+    status, body = _get_json(f"https://slack.com/api/conversations.info?channel={channel_id}", {"Authorization": f"Bearer {bot_token}"})
+    if status != 200 or not body.get("ok"):
+        return False, f"{channel_id}: {body.get('error', status)}"
+    return True, f"{channel_id} = #{(body.get('channel') or {}).get('name', '?')}"
+
+
+def check_slack_app_token(app_token: str) -> tuple[bool, str]:
+    if not app_token.startswith("xapp-"):
+        return False, "app-level token must start with xapp-"
+    return True, "app token format ok"
+
+
+def github_app_jwt(app_id: str, private_key_pem: str) -> str:
+    import jwt
+
+    now = int(time.time())
+    return jwt.encode({"iat": now - 60, "exp": now + 540, "iss": app_id}, private_key_pem, algorithm="RS256")
+
+
+def check_github_app(app_id: str, installation_id: str, private_key_pem: str, approved_repos: list[str] | None = None) -> tuple[bool, str]:
+    try:
+        token_jwt = github_app_jwt(app_id, private_key_pem)
+    except Exception as e:
+        return False, f"could not sign app jwt: {e}"
+    status, app = _get_json("https://api.github.com/app", {"Authorization": f"Bearer {token_jwt}", "Accept": "application/vnd.github+json"})
+    if status != 200:
+        return False, f"GET /app failed ({status}) — wrong app id or private key"
+    status, minted = _post_json(f"https://api.github.com/app/installations/{installation_id}/access_tokens", {"Authorization": f"Bearer {token_jwt}", "Accept": "application/vnd.github+json"})
+    if status != 201:
+        return False, f"token mint failed ({status}) — wrong installation id?"
+    installation_token = str(minted.get("token", ""))
+    status, repos = _get_json("https://api.github.com/installation/repositories?per_page=100", {"Authorization": f"Bearer {installation_token}", "Accept": "application/vnd.github+json"})
+    if status != 200:
+        return False, f"listing installation repositories failed ({status})"
+    accessible = {str(repo.get("full_name", "")) for repo in repos.get("repositories") or []}
+    missing = [repo for repo in (approved_repos or []) if repo not in accessible]
+    if missing:
+        return False, f"app '{app.get('slug')}' cannot access: {', '.join(missing)} — install it on those repositories"
+    return True, f"app '{app.get('slug')}' ok, {len(accessible)} repositories accessible"
+
+
+def check_github_pat_repo(token: str, repo: str) -> tuple[bool, str]:
+    status, body = _get_json(f"https://api.github.com/repos/{repo}", {"Authorization": f"Bearer {token}", "Accept": "application/vnd.github+json"})
+    if status != 200:
+        return False, f"GET /repos/{repo} failed ({status})"
+    return True, f"{repo} reachable"
+
+
+def check_jira(site: str, email: str, api_token: str) -> tuple[bool, str]:
+    status, body = _get_json(f"{site.rstrip('/')}/rest/api/3/myself", {"Authorization": _basic_auth(email, api_token)})
+    if status != 200:
+        return False, f"/myself failed ({status})"
+    return True, f"authed as {body.get('displayName')} ({body.get('emailAddress')})"
+
+
+def check_jira_project(site: str, email: str, api_token: str, key: str) -> tuple[bool, str]:
+    status, body = _get_json(f"{site.rstrip('/')}/rest/api/3/project/{key}", {"Authorization": _basic_auth(email, api_token)})
+    if status != 200:
+        return False, f"project {key}: {status}"
+    return True, f"project {key} = {body.get('name')}"
+
+
+def check_confluence(site: str, email: str, api_token: str) -> tuple[bool, str]:
+    status, body = _get_json(f"{site.rstrip('/')}/wiki/rest/api/space?limit=1", {"Authorization": _basic_auth(email, api_token)})
+    if status != 200:
+        return False, f"space list failed ({status})"
+    return True, "confluence reachable"
+
+
+def check_sentry(organization: str, token: str) -> tuple[bool, str]:
+    status, body = _get_json(f"https://sentry.io/api/0/organizations/{organization}/", {"Authorization": f"Bearer {token}"})
+    if status != 200:
+        return False, f"org fetch failed ({status})"
+    return True, f"org '{body.get('slug')}' reachable"
+
+
+def check_aws_role(role_arn: str, external_id: str) -> tuple[bool, str]:
+    try:
+        import boto3
+
+        sts = boto3.client("sts")
+        sts.assume_role(RoleArn=role_arn, RoleSessionName="taskboy-setup-check", ExternalId=external_id, DurationSeconds=900)
+    except Exception as e:
+        return False, f"{type(e).__name__}: {e}"
+    return True, f"assumed {role_arn.rsplit('/', 1)[-1]}"
+
+
+def check_aws_secret(secret_name: str, region: str) -> tuple[bool, str]:
+    try:
+        import boto3
+
+        client = boto3.client("secretsmanager", region_name=region)
+        blob = json.loads(client.get_secret_value(SecretId=secret_name)["SecretString"])
+    except Exception as e:
+        return False, f"{type(e).__name__}: {e}"
+    return True, f"{secret_name}: {len(blob)} keys"