clanker-saddle/test/web_stack_test.py

#!/usr/bin/env python3
"""Self-contained web-stack feature tests: app + fake saddle daemon.

Unlike integration_test.py (which needs a real saddle daemon and a mock
LLM), this suite spawns everything it needs:

- the clanker-saddle app binary (path from argv[1], or builddir default)
  in a scratch directory with its own web-config.json (statum keys copied
  from the repo, plus `saddle_callback_base_url`) and SQLite database
- an in-process fake saddle daemon speaking the wire contract: POST
  /start (captures the payload), GET /status (scripted state machine),
  GET /output (empty), GET /log?since= (raw PTY chunks, one new chunk
  per request so since-paging is exercised)

It then drives the app the way statum.js does (entrypoint loads + action
POSTs) and asserts the Workstream B features against the wire contract:

3. plan-review blocks hide their duplicate body preview
5. rules CRUD/attach + the effective `rules` array in /start
6. project notes, POST /api/saddle/note, `project_notes` + `callback`
   in /start
   plus the raw-log side: session_raw_log polling + terminal raw view

Prints PASS/FAIL lines Statum-style; exits non-zero on any failure.
"""
import json
import os
import shutil
import socket
import sqlite3
import subprocess
import sys
import threading
import time
import urllib.error
import urllib.parse
import urllib.request
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer

REPO = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
APP = os.path.abspath(sys.argv[1]) if len(sys.argv) > 1 else os.path.join(REPO, "builddir", "clanker-saddle")
WORK = os.environ.get("WEBSTACK_WORK", "/tmp/kilo/webstack-e2e")
DB_PATH = os.path.join(WORK, "web.sqlite")

passes = 0
failures = 0


def check(condition, label):
    global passes, failures
    if condition:
        passes += 1
        print("PASS %s" % label)
    else:
        failures += 1
        print("FAIL %s" % label)


def free_port():
    with socket.socket() as sock:
        sock.bind(("127.0.0.1", 0))
        return sock.getsockname()[1]


APP_PORT = free_port()
DAEMON_PORT = free_port()
WEB = "http://127.0.0.1:%d" % APP_PORT


def http(method, url, data=None, headers=None, timeout=30):
    body = None
    if data is not None:
        pairs = []
        for k, v in data.items():
            for item in (v if isinstance(v, (list, tuple)) else [v]):
                pairs.append((k, item))
        body = "&".join("%s=%s" % (k, urllib.parse.quote(str(item))) for k, item in pairs).encode()
    request = urllib.request.Request(WEB + url if url.startswith("/") else url,
                                     data=body, method=method)
    if data is not None:
        request.add_header("Content-Type", "application/x-www-form-urlencoded")
    for key, value in (headers or {}).items():
        request.add_header(key, value)
    # Retry dropped/refused connections: the freshly started app can
    # close a very early keep-alive connection once while warming up,
    # and its first seconds can wobble under load.
    for attempt in range(3):
        try:
            with urllib.request.urlopen(request, timeout=timeout) as response:
                return response.status, response.read().decode()
        except urllib.error.HTTPError as error:
            return error.code, error.read().decode()
        except (urllib.error.URLError, OSError):
            if attempt >= 2:
                raise
            time.sleep(0.75)


def directives(uri, auth=None):
    headers = {}
    if auth:
        headers["X-Statum-Slot"] = "key=%s; as_at=%s" % (auth["key"], auth["as_at"])
    status, body = http("GET", "/_statum/entrypoint?uri=" + urllib.parse.quote(uri.split("?")[0]),
                        headers=headers)
    if status != 200:
        raise SystemExit("entrypoint %s -> HTTP %d: %s" % (uri, status, body[:300]))
    return json.loads(body)


def slot_public(auth, uri, type_name):
    for directive in directives(uri, auth):
        if directive["type"] == "set":
            content = json.loads(directive["snapshot_frame"]["content"])
            if content["slot"]["type"] == type_name:
                return content["public"]
    raise SystemExit("no %s slot in entrypoint state for %s" % (type_name, uri))


def act(auth, action, fields):
    headers = {"X-Statum-Slot": "key=%s; as_at=%s" % (auth["key"], auth["as_at"])}
    if action.get("private"):
        headers["X-Statum-Private"] = action["private"]
    status, body = http(action.get("method", "POST"), action["uri"], fields, headers)
    if status != 200:
        raise SystemExit("action %s -> HTTP %d: %s" % (action["uri"], status, body[:300]))
    return json.loads(body)


def login(username, password):
    frames = directives("/login")
    content = json.loads(frames[0]["snapshot_frame"]["content"])
    action = content["public"]["login"]
    status, body = http(action.get("method", "POST"), action["uri"],
                        {"username": username, "password": password})
    if status != 200:
        raise SystemExit("login -> HTTP %d: %s" % (status, body[:300]))
    for directive in json.loads(body):
        if directive["type"] == "set":
            frame = json.loads(directive["snapshot_frame"]["content"])
            if frame["slot"]["type"] == "auth":
                return {"key": frame["slot"]["key"], "as_at": frame["as_at"]}
    raise SystemExit("login response carried no auth slot: " + body[:300])


def wait_for(predicate, timeout=60, what="condition", interval=0.5):
    deadline = time.monotonic() + timeout
    last = None
    while time.monotonic() < deadline:
        last = predicate()
        if last is not False and last is not None:
            return last
        time.sleep(interval)
    print("  (timeout waiting for %s; last: %s)" % (what, last))
    return None


def task_state(auth, task_id):
    return slot_public(auth, "/tasks/%d" % task_id, "task")


def wait_task_done(auth, task_id, timeout=90):
    return wait_for(lambda: task_state(auth, task_id).get("status") == "done" or False,
                    timeout=timeout, what="task %d -> done" % task_id)


def task_id_of(title):
    conn = db()
    try:
        return conn.execute("select id from tasks where title = ?", (title,)).fetchone()[0]
    finally:
        conn.close()


def saddle_api(method, path, token, payload=None):
    """Raw call against the saddle ingest API; returns (status, json)."""
    request = urllib.request.Request(WEB + path,
                                     data=json.dumps(payload or {}).encode(), method=method)
    request.add_header("Content-Type", "application/json")
    if token is not None:
        request.add_header("Authorization", "Bearer " + token)
    try:
        with urllib.request.urlopen(request, timeout=15) as response:
            return response.status, json.loads(response.read().decode() or "{}")
    except urllib.error.HTTPError as error:
        body = error.read().decode()
        try:
            return error.code, json.loads(body)
        except ValueError:
            return error.code, {"raw": body}


def db():
    return sqlite3.connect(DB_PATH)


class FakeSaddle:
    """In-process saddle daemon implementing the wire contract."""

    PROMPT = "bbarrow@fedora:/workspace/task-1$ "

    def __init__(self):
        self.lock = threading.Lock()
        self.start_payloads = []       # captured POST /start bodies
        self.chunks = []               # [{seq, text}] — the raw log ring
        self.next_seq = 1
        self.state = "idle"
        self.summary = ""
        self.state_entered = time.monotonic()
        self.fail_next = False          # next /start drives the task to failed
        self.start_counts = {}          # task id -> /start count
        self.resumed_pending = False    # crash-resume flag on the next /status
        self.suspend_after_start = False  # next task parks as suspended
        self.pending_output = []        # entries drained by the next /output poll
        self.output_seq = 100
        self.subtask_status_events = []  # recorded POST /subtask-status payloads
        self.fail_subtask_status = False  # exercise the web's retry path

    def set_state(self, state, summary=None):
        """Advances the scripted lifecycle.

        Time-based on purpose: the web app may probe /status more than
        once per tick (status polls, stale-busy healing, manual
        refreshes), and a poll-counted machine would conflate them and
        race dependent sections.
        """
        self.state = state
        if summary is not None:
            self.summary = summary
        self.state_entered = time.monotonic()

    def queue_output(self, entry_type, command, output):
        """Queues a typed entry for the dispatcher's next /output poll."""
        with self.lock:
            self.pending_output.append({
                "id": self.output_seq,
                "command": command,
                "output": output,
                "exit_code": 1,
                "type": entry_type,
                "timestamp": "2026-09-06T00:00:00Z",
            })
            self.output_seq += 1

    def append_chunk(self, text):
        with self.lock:
            self.chunks.append({"seq": self.next_seq, "text": text})
            self.next_seq += 1

    def log_since(self, since):
        with self.lock:
            # `since` is the inclusive resume point (wire contract: a
            # response ending at seq 12 carries next=13, and polling
            # with since=13 must still deliver the chunk numbered 13).
            chunks = [c for c in self.chunks if c["seq"] >= since]
            return chunks, self.next_seq

    class Handler(BaseHTTPRequestHandler):
        daemon = None  # set on the class before serving
        protocol_version = "HTTP/1.1"

        def log_message(self, fmt, *args):
            pass

        def _send(self, status, obj):
            body = json.dumps(obj).encode()
            self.send_response(status)
            self.send_header("Content-Type", "application/json")
            self.send_header("Content-Length", str(len(body)))
            self.end_headers()
            self.wfile.write(body)

        def do_POST(self):
            length = int(self.headers.get("Content-Length") or 0)
            raw = self.rfile.read(length).decode() if length else "{}"
            if self.path == "/start":
                try:
                    payload = json.loads(raw)
                except ValueError:
                    payload = {"raw": raw}
                self.daemon.start_payloads.append(payload)
                task_id = (payload.get("task") or {}).get("id")
                count = self.daemon.start_counts.get(task_id, 0) + 1
                self.daemon.start_counts[task_id] = count
                if count > 1:
                    # Crash-resume contract: re-pushing a task whose
                    # workspace still exists restores it; the first
                    # /status after the restore reports "resumed": true.
                    self.daemon.resumed_pending = True
                self.daemon.append_chunk(self.daemon.PROMPT)
                self.daemon.append_chunk("echo hello\r\n")
                self.daemon.append_chunk("hello\r\n")
                self.daemon.set_state("failing" if self.daemon.fail_next else "working")
                self.daemon.fail_next = False
                self._send(200, {})
            elif self.path == "/answer":
                self._send(200, {})
            elif self.path == "/subtask-status":
                try:
                    payload = json.loads(raw)
                except ValueError:
                    self._send(400, {"error": "bad json"})
                    return
                if self.daemon.fail_subtask_status:
                    self._send(500, {"error": "simulated failure"})
                    return
                self.daemon.subtask_status_events.append(payload)
                self._send(200, {"ok": True})
            else:
                self._send(404, {"error": "no such route"})

        def do_GET(self):
            if self.path == "/status":
                response = {"state": self.daemon.state, "summary": self.daemon.summary}
                if self.daemon.resumed_pending:
                    response["resumed"] = True
                    self.daemon.resumed_pending = False
                if self.daemon.state == "failing":
                    # Fails fast (a rejected /start script).
                    if time.monotonic() - self.daemon.state_entered >= 1:
                        self.daemon.set_state("failed",
                                              "bash -n rejected the script (simulated)")
                elif self.daemon.state == "working":
                    # Time-based, not poll-based: whoever probes /status
                    # (dispatcher polls, stale-busy healing, refreshes)
                    # must not advance the lifecycle.
                    if time.monotonic() - self.daemon.state_entered >= 8:
                        if self.daemon.suspend_after_start:
                            # `saddle suspend`: park until a fresh /start
                            # resumes the workspace (one-shot flag).
                            self.daemon.set_state("suspended")
                            self.daemon.suspend_after_start = False
                        else:
                            self.daemon.set_state("done", "fake daemon finished")
                self._send(200, response)
            elif self.path.startswith("/output"):
                with self.daemon.lock:
                    entries = self.daemon.pending_output
                    self.daemon.pending_output = []
                self._send(200, entries)
            elif self.path.startswith("/log"):
                query = urllib.parse.urlparse(self.path).query
                since = int(urllib.parse.parse_qs(query).get("since", ["0"])[0])
                # Simulate the live PTY: each poll produces one more chunk
                # (before slicing, so the poller actually sees it).
                self.daemon.append_chunk("stream-line-%d\r\n" % self.daemon.next_seq)
                chunks, nxt = self.daemon.log_since(since)
                self._send(200, {"chunks": chunks, "next": nxt})
            else:
                self._send(404, {"error": "no such route"})
                self.close_connection = True

    def serve(self):
        handler = type("BoundHandler", (FakeSaddle.Handler,), {"daemon": self})
        server = ThreadingHTTPServer(("127.0.0.1", DAEMON_PORT), handler)
        threading.Thread(target=server.serve_forever, daemon=True).start()
        return server


def start_app():
    config = json.load(open(os.path.join(REPO, "web-config.json")))
    config["saddle_callback_base_url"] = WEB
    with open(os.path.join(WORK, "web-config.json"), "w") as handle:
        json.dump(config, handle)

    env = dict(os.environ)
    env.update({
        "SPRY_DB_PATH": DB_PATH,
        "SPRY_SEED_ADMIN_USERNAME": "admin",
        "SPRY_SEED_ADMIN_PASSWORD": "adminpass123",
        "SADDLE_LLM_BASE_URL": "http://127.0.0.1:%d" % DAEMON_PORT,
        "SADDLE_PROJECTS_ROOT": os.path.join(WORK, "workspace"),
    })
    log = open(os.path.join(WORK, "app.log"), "w")
    command = [APP, str(APP_PORT)]
    if os.environ.get("WEBSTACK_GDB"):
        # Debugging aid: run the app under gdb; a crash backtrace lands in
        # app.log. WEBSTACK_GDB=1 meson test ... to enable.
        command = ["gdb", "-batch", "-quiet",
                   "-ex", "handle SIGPIPE nostop noprint pass",
                   "-ex", "run", "-ex", "bt", "--args", APP, str(APP_PORT)]
    process = subprocess.Popen(command, cwd=WORK, env=env,
                               stdout=log, stderr=subprocess.STDOUT)
    outcome = wait_for(lambda: (app_ready() and "ready")
                       or (process.poll() is not None and "app-exited-%d" % process.poll())
                       or False, timeout=30, what="app ready")
    if outcome is None:
        raise SystemExit("app did not come up; see %s/app.log" % WORK)
    if str(outcome).startswith("app-exited-"):
        raise SystemExit("app exited during startup (%s); see %s/app.log"
                         % outcome, WORK)
    return process


def app_ready():
    try:
        status, _ = http("GET", "/login", timeout=3)
        return status == 200
    except (urllib.error.URLError, OSError):
        return False


def dump_app_stacks(pid):
    """Best-effort thread backtrace of the (possibly wedged) app."""
    try:
        fds = os.listdir("/proc/%d/fd" % pid)
        print("(app open fds at dump: %d)" % len(fds))
        kinds = {}
        for fd in fds[:1200]:
            try:
                target = os.readlink("/proc/%d/fd/%s" % (pid, fd))
            except OSError:
                continue
            key = target.split(":", 1)[0] if ":" in target else target
            kinds[key] = kinds.get(key, 0) + 1
        print("(fd kinds: %s)" % sorted(kinds.items(), key=lambda kv: -kv[1])[:6])
    except OSError:
        pass
    for command in (["eu-stack", "-p", str(pid)],
                    ["gdb", "-batch", "-quiet", "-p", str(pid),
                     "-ex", "thread apply all bt"]):
        try:
            out = subprocess.run(command, capture_output=True, timeout=60)
            text = out.stdout.decode(errors="replace") + out.stderr.decode(errors="replace")
            if text.strip():
                print("(app stacks via %s)\n%s" % (command[0], text[:12000]))
                return
        except (OSError, subprocess.SubprocessError):
            continue


def main():
    if not os.path.exists(APP):
        raise SystemExit("app binary not found at %s (build first)" % APP)

    fake = FakeSaddle()
    fake.serve()

    # A rare framework-level crash (stack corruption in Statum slot
    # signing during the FIRST login — shared-library codegen bug, moved
    # twice already) kills the app before any test runs; a clean restart
    # sidesteps it. Only tolerated while nothing has been checked yet.
    auth = None
    app = None
    for attempt in range(3):
        if os.path.exists(WORK):
            shutil.rmtree(WORK)
        os.makedirs(os.path.join(WORK, "workspace"))
        try:
            app = start_app()
            auth = login("admin", "adminpass123")
            break
        except (SystemExit, OSError, urllib.error.URLError):
            if passes > 0:
                raise
            if app is not None and app.poll() is None:
                app.terminate()
                try:
                    app.wait(timeout=5)
                except subprocess.TimeoutExpired:
                    app.kill()
            app = None
            print("(app died before login; restarting cleanly, attempt %d)" % (attempt + 1))
    if app is None or auth is None:
        raise SystemExit("app never came up; see %s/app.log" % WORK)

    try:
        check(True, "login yields an auth slot")
        print("== feature 3: plan review hides duplicate body ==")
        state = slot_public(auth, "/projects", "projects")
        act(auth, state["create"], {
            "name": "demo",
            "git_url": "https://example.com/demo.git",
            "default_branch": "main",
        })
        conn = db()
        conn.execute("insert into tasks (project_id, title, status, priority,"
                     " is_design_task, plan, created_at)"
                     " values (1, 'Plan review task', 'working', 5, 1, '# The plan\n\n1. Do it',"
                     " strftime('%s','now'))")
        conn.commit()
        plan_task = conn.execute("select max(id) from tasks").fetchone()[0]

        saddles_state = slot_public(auth, "/saddles", "saddles")
        act(auth, saddles_state["register"], {"name": "fake-saddle",
                                              "host": "127.0.0.1:%d" % DAEMON_PORT})
        registered = [s for s in slot_public(auth, "/saddles", "saddles")["saddles"]
                      if s["name"] == "fake-saddle"]
        check(len(registered) == 1 and registered[0]["token"].startswith("saddle-"),
              "fake saddle registered with an API token")
        fake_id = int(registered[0]["id"])
        fake_token = registered[0]["token"]

        conn.execute("insert into sessions (task_id, saddle_id, started_at, ended_at, outcome)"
                     " values (?, ?, strftime('%s','now'), strftime('%s','now'), 'done')",
                     (plan_task, fake_id))
        conn.commit()
        session_id = conn.execute("select max(id) from sessions").fetchone()[0]
        conn.close()

        status, body = saddle_api("POST", "/api/saddle/%d/update" % fake_id, fake_token,
                                  {"type": "block", "session_id": session_id, "data": {
                                      "question": "Plan submitted for review",
                                      "type": "rfc",
                                      "body": "# The plan\n\n1. Do it"}})
        check(status == 200 and body.get("block_id"), "plan-review block raised")
        status, _ = saddle_api("POST", "/api/saddle/%d/update" % fake_id, fake_token,
                               {"type": "block", "session_id": session_id, "data": {
                                   "question": "Which database?",
                                   "type": "question",
                                   "options": ["SQLite", "Postgres"],
                                   "body": "# Storage choice"}})
        check(status == 200, "question block raised")

        detail = task_state(auth, plan_task)
        blocks = {b["block_type"]: b for b in detail["blocks"]}
        check(blocks["rfc"].get("is_plan_review") is True,
              "rfc block flagged as the plan review")
        check(blocks["rfc"].get("show_body") is False,
              "pending plan review hides the duplicate body preview")
        check(blocks["question"].get("show_body") is True,
              "question block keeps its body preview")

        act(auth, blocks["rfc"]["answer_action"], {"answer": "Plan approved. Proceed."})
        detail = task_state(auth, plan_task)
        rfc = [b for b in detail["blocks"] if b["block_type"] == "rfc"][0]
        check(rfc.get("show_body") is True,
              "answered plan review shows the body again (review section gone)")

        print("== B1: highlight-to-comment quote dialog ==")
        status, page = http("GET", "/tasks/%d" % plan_task, timeout=15)
        check(status == 200 and "quote-comment-dialog" in page and "quote-text" in page,
              "task page carries the quote-comment dialog the popover opens")
        check('name="quote"' in page and 'name="return_to"' in page,
              "quote dialog posts the quote and return-to fields")
        status, page = http("GET", "/tasks/%d/terminal" % plan_task, timeout=15)
        check(status == 200 and "quote-comment-dialog" in page,
              "terminal page keeps its quote dialog")

        print("== B3: review section hides the duplicate body ==")
        status, body = saddle_api("POST", "/api/saddle/%d/update" % fake_id, fake_token,
                                  {"type": "block", "session_id": session_id, "data": {
                                      "question": "Review the diff",
                                      "type": "review",
                                      "body": "# The change\n\nReworks the flange module."}})
        check(status == 200 and body.get("block_id"), "review block raised")
        detail = task_state(auth, plan_task)
        review_block = [b for b in detail["blocks"] if b["block_type"] == "review"][0]
        check(detail.get("review_pending") is True,
              "review section shows while the review is unanswered")
        check(review_block.get("show_body") is False,
              "pending review block hides its duplicate body preview")
        check(review_block.get("body", "").startswith("# The change"),
              "review body itself still arrives in state (B2 counterpart)")
        act(auth, review_block["answer_action"], {"answer": "Human approved the review"})
        detail = task_state(auth, plan_task)
        review_block = [b for b in detail["blocks"] if b["block_type"] == "review"][0]
        check(review_block.get("show_body") is True,
              "answered review shows the body again (banner gone)")

        print("== B2: question block body above options ==")
        # Contract side (A2 will restore bodies end-to-end): a question
        # block raised with a heredoc body carries it; the body preview
        # rides above the options (template order) and survives answering
        # alongside the selected answer.
        detail = task_state(auth, plan_task)
        question = [b for b in detail["blocks"] if b["block_type"] == "question"][0]
        check(question.get("body") == "# Storage choice"
              and question.get("show_body") is True,
              "question block keeps its body markdown with the preview on")
        act(auth, question["answer_action"], {"option": "SQLite"})
        detail = task_state(auth, plan_task)
        question = [b for b in detail["blocks"] if b["block_type"] == "question"][0]
        check(question.get("answered") is True and question.get("answer") == "SQLite"
              and question.get("body") == "# Storage choice"
              and question.get("show_body") is True,
              "answered question shows body + selected answer")

        print("== B5: compare-changes SSH -> HTTPS ==")
        def diff_url_for_project(git_url, suffix):
            state = slot_public(auth, "/projects", "projects")
            act(auth, state["create"], {"name": "diff-%s" % suffix, "git_url": git_url})
            project_id = int([p["id"] for p in slot_public(auth, "/projects", "projects")["projects"]
                              if p["name"] == "diff-%s" % suffix][0])
            conn = db()
            conn.execute("insert into tasks (project_id, title, status, task_branch,"
                         " branch_from, created_at) values (?, ?, 'working', 'feature/x',"
                         " 'main', strftime('%s','now'))", (project_id, "Diff %s" % suffix))
            conn.commit()
            task_id = conn.execute("select max(id) from tasks").fetchone()[0]
            conn.execute("insert into sessions (task_id, saddle_id, started_at, ended_at,"
                         " outcome) values (?, ?, strftime('%s','now'), strftime('%s','now'),"
                         " 'done')", (task_id, fake_id))
            conn.commit()
            session = conn.execute("select max(id) from sessions").fetchone()[0]
            conn.close()
            saddle_api("POST", "/api/saddle/%d/update" % fake_id, fake_token,
                       {"type": "block", "session_id": session, "data": {
                           "question": "Review the diff", "type": "review"}})
            return task_state(auth, task_id).get("review_diff_url") or ""

        check(diff_url_for_project("ssh://fabrica.unitatem.net:222/clanker/clanker-saddle.git",
                                   "fabrica")
              == "https://fabrica.unitatem.net/clanker/clanker-saddle/compare/main...feature/x",
              "ssh://git@host:port/owner/repo.git translates (port dropped)")
        check(diff_url_for_project("git@github.com:acme/widgets.git", "scp")
              == "https://github.com/acme/widgets/compare/main...feature/x",
              "git@host:owner/repo.git translates to the browse host")
        check(diff_url_for_project("https://example.com/plain/repo", "plain")
              == "https://example.com/plain/repo/compare/main...feature/x",
              "HTTPS URLs pass through unchanged")

        print("== feature 5: rules ==")
        rules_state = slot_public(auth, "/rules", "rules")
        for name, body in [
            ("Use Invercargill", "Never use libgee; use Invercargill enumerables."),
            ("Write Vala docs", "Every public class carries a doc comment."),
            ("Prefer meson", "Builds go through meson; no makefiles."),
            ("Co-dev rule", "Keep the wire contract exactly."),
            ("Reference rule", "Must never ride along."),
        ]:
            act(auth, rules_state["create"], {"name": name, "body": body})
        listed = {r["name"]: r for r in slot_public(auth, "/rules", "rules")["rules"]}
        check(len(listed) == 5, "five rules created and listed on /rules")

        def rule_id(name):
            rows = [r for r in slot_public(auth, "/rules", "rules")["rules"] if r["name"] == name]
            return int(rows[0]["id"])

        state = slot_public(auth, "/projects", "projects")
        act(auth, state["create"], {"name": "co", "git_url": "https://example.com/co.git"})
        act(auth, state["create"], {"name": "ref", "git_url": "https://example.com/ref.git"})
        co_id = int([p["id"] for p in slot_public(auth, "/projects", "projects")["projects"]
                     if p["name"] == "co"][0])
        ref_id = int([p["id"] for p in slot_public(auth, "/projects", "projects")["projects"]
                      if p["name"] == "ref"][0])

        project = slot_public(auth, "/projects/1", "project")
        act(auth, project["add_link"], {"linked_project_id": str(co_id),
                                        "relationship": "co-developed"})
        act(auth, project["add_link"], {"linked_project_id": str(ref_id),
                                        "relationship": "reference"})
        act(auth, project["attach_rule"], {"rule_id": str(rule_id("Use Invercargill"))})
        act(auth, project["attach_rule"], {"rule_id": str(rule_id("Prefer meson"))})
        project = slot_public(auth, "/projects/1", "project")
        check(sorted(r["name"] for r in project["rules"]) == ["Prefer meson", "Use Invercargill"],
              "project page lists its attached rules")

        co_project = slot_public(auth, "/projects/%d" % co_id, "project")
        act(auth, co_project["attach_rule"], {"rule_id": str(rule_id("Co-dev rule"))})
        ref_project = slot_public(auth, "/projects/%d" % ref_id, "project")
        act(auth, ref_project["attach_rule"], {"rule_id": str(rule_id("Reference rule"))})

        tasks_state = slot_public(auth, "/tasks", "tasks")
        act(auth, tasks_state["create"], {
            "project_id": "1",
            "title": "Rules dispatch",
            "description": "Effective rule set rides the /start payload.",
            "priority": "2",
        })
        rule_task = int([t["id"] for t in slot_public(auth, "/tasks", "tasks")["tasks"]
                         if t["title"] == "Rules dispatch"][0])
        detail = task_state(auth, rule_task)
        act(auth, detail["attach_rule"], {"rule_id": str(rule_id("Write Vala docs"))})
        act(auth, detail["attach_rule"], {"rule_id": str(rule_id("Use Invercargill"))})
        detail = task_state(auth, rule_task)
        check(sorted(r["name"] for r in detail["rules"]) == ["Use Invercargill", "Write Vala docs"],
              "task page lists its attached rules")

        check(wait_for(lambda: len(fake.start_payloads) > 0 or False,
                       timeout=30, what="/start push") is not None,
              "dispatcher pushes the task to the fake saddle")
        payload = fake.start_payloads[-1]
        rule_names = [r["name"] for r in payload.get("rules", [])]
        check(rule_names == ["Write Vala docs", "Use Invercargill", "Prefer meson", "Co-dev rule"],
              "effective rules in /start: task, primary, co-developed order (%s)" % rule_names)
        check(all(r.get("body") for r in payload.get("rules", [])),
              "rules carry their bodies")
        check("Reference rule" not in rule_names,
              "reference project rules excluded")

        detail = task_state(auth, rule_task)
        act(auth, detail["rules"][0]["detach"], {})
        check([r["name"] for r in task_state(auth, rule_task)["rules"]] == ["Use Invercargill"],
              "detached task rule disappears")

        rules_rows = slot_public(auth, "/rules", "rules")["rules"]
        docs_row = [r for r in rules_rows if r["name"] == "Write Vala docs"][0]
        act(auth, docs_row["update"], {"name": "Write Vala docs", "body": "Doc comments or bust."})
        check(any(r["body"] == "Doc comments or bust."
                  for r in slot_public(auth, "/rules", "rules")["rules"]),
              "rule edit saves the body")

        check(wait_task_done(auth, rule_task, timeout=60) is not None,
              "dispatched task completes against the fake daemon")

        print("== feature 6: project notes + callback ==")
        conn = db()
        callback_rows = conn.execute(
            "select token from api_tokens where saddle_id = 0").fetchall()
        conn.close()
        check(len(callback_rows) == 1 and callback_rows[0][0].startswith("saddle-callback-"),
              "dedicated saddle-callback token minted at startup")
        callback_token = callback_rows[0][0]

        status, _ = saddle_api("POST", "/api/saddle/note", None,
                               {"project": "demo", "body": "x"})
        check(status == 401, "note endpoint rejects a missing token")
        status, _ = saddle_api("POST", "/api/saddle/note", "saddle-callback-not-real",
                               {"project": "demo", "body": "x"})
        check(status == 401, "note endpoint rejects a wrong token")

        status, body = saddle_api("POST", "/api/saddle/note", callback_token,
                                  {"task_id": rule_task, "project": "demo",
                                   "body": "style.css tokens live in :root"})
        check(status == 200 and body.get("ok") is True, "note accepted with the callback token")
        status, _ = saddle_api("POST", "/api/saddle/note", callback_token,
                               {"project": "no-such-project", "body": "x"})
        check(status == 400, "unknown project rejected")
        status, _ = saddle_api("POST", "/api/saddle/note", callback_token,
                               {"project": "demo", "body": "   "})
        check(status == 400, "empty note body rejected")

        project = slot_public(auth, "/projects/1", "project")
        check(any("style.css tokens" in n["body"] and int(n["source_task_id"]) == rule_task
                  for n in project["notes"]),
              "project page lists the note with its source task")
        act(auth, [n for n in project["notes"] if "style.css tokens" in n["body"]][0]["delete"], {})
        check(all("style.css tokens" not in n["body"]
                  for n in slot_public(auth, "/projects/1", "project")["notes"]),
              "note deleted from the project page")

        # /start payload: notes of primary + co-developed (not reference),
        # oldest first; callback carries the configured base URL + token.
        saddle_api("POST", "/api/saddle/note", callback_token,
                   {"project": "demo", "body": "note-one"})
        saddle_api("POST", "/api/saddle/note", callback_token,
                   {"project": "demo", "body": "note-two"})
        saddle_api("POST", "/api/saddle/note", callback_token,
                   {"project": "co", "body": "co-note"})
        conn = db()
        conn.execute("insert into project_notes (project_id, body, created_at)"
                     " values (?, 'ref-note-must-not-ship', strftime('%s','now'))", (ref_id,))
        conn.commit()
        conn.close()

        act(auth, slot_public(auth, "/tasks", "tasks")["create"], {
            "project_id": "1",
            "title": "Notes dispatch",
            "description": "Project notes ride the /start payload.",
            "priority": "2",
        })
        check(wait_for(lambda: len(fake.start_payloads) >= 2 or False,
                       timeout=30, what="second /start push") is not None,
              "dispatcher pushes the notes task")
        payload = fake.start_payloads[-1]
        notes = payload.get("project_notes", [])
        check([n["body"] for n in notes] == ["note-one", "note-two", "co-note"],
              "project_notes: primary + co-developed, oldest first (%s)" % [n["body"] for n in notes])
        check(all(n.get("project") for n in notes)
              and notes[2]["project"] == "co",
              "project_notes carry the project name")
        check("ref-note-must-not-ship" not in [n["body"] for n in notes],
              "reference project notes excluded")
        callback = payload.get("callback", {})
        check(callback.get("base_url") == WEB and callback.get("token") == callback_token,
              "callback carries the configured base URL and the minted token")

        # entry cap: 30 of 33 candidates
        conn = db()
        for i in range(33):
            conn.execute("insert into project_notes (project_id, body, created_at)"
                         " values (?, ?, strftime('%s','now'))", (1, "bulk-%02d" % i))
        conn.commit()
        conn.close()
        act(auth, slot_public(auth, "/tasks", "tasks")["create"], {
            "project_id": "1",
            "title": "Entry cap dispatch",
            "priority": "2",
        })
        check(wait_for(lambda: len(fake.start_payloads) >= 3 or False,
                       timeout=30, what="third /start push") is not None,
              "dispatcher pushes the entry-cap task")
        notes = fake.start_payloads[-1].get("project_notes", [])
        check(len(notes) == 30 and notes[0]["body"] == "note-one" and notes[1]["body"] == "note-two",
              "project_notes capped at 30 entries, oldest kept (%d)" % len(notes))

        # char cap: the giant note is truncated so the total stays <= 20000
        conn = db()
        conn.execute("delete from project_notes where body like 'bulk-%' or body = 'co-note'")
        conn.execute("insert into project_notes (project_id, body, created_at)"
                     " values (?, ?, strftime('%s','now'))", (1, "giant!" + "x" * 25000,))
        conn.commit()
        conn.close()
        act(auth, slot_public(auth, "/tasks", "tasks")["create"], {
            "project_id": "1",
            "title": "Char cap dispatch",
            "priority": "2",
        })
        check(wait_for(lambda: len(fake.start_payloads) >= 4 or False,
                       timeout=30, what="fourth /start push") is not None,
              "dispatcher pushes the char-cap task")
        notes = fake.start_payloads[-1].get("project_notes", [])
        total = sum(len(n["body"]) for n in notes)
        check(len(notes) == 3 and total == 20000 and notes[2]["body"].startswith("giant!"),
              "project_notes char cap: head kept, giant truncated (entries=%d, chars=%d)"
              % (len(notes), total))

        print("== raw log polling + terminal raw view ==")
        # Wait for the last dispatch to finish so its final polls ran.
        check(wait_task_done(auth, task_id_of("Char cap dispatch"), timeout=60) is not None,
              "char-cap task completes")
        conn = db()
        raw_session = conn.execute(
            "select s.id from sessions s join tasks t on t.id = s.task_id"
            " where t.title = 'Char cap dispatch' order by s.id desc limit 1").fetchone()[0]
        rows = conn.execute("select seq, chunk from session_raw_log where session_id = ?"
                            " order by seq", (raw_session,)).fetchall()
        conn.close()
        check(len(rows) >= 3, "session_raw_log captured the daemon's chunks (%d)" % len(rows))
        seqs = [r[0] for r in rows]
        check(seqs == sorted(seqs) and len(set(seqs)) == len(seqs),
              "raw chunks stored once, seq strictly increasing")
        text = "".join(r[1] for r in rows)
        check(fake.PROMPT in text and "echo hello" in text and "hello" in text,
              "raw log keeps the prompt and echoed output byte-exact")
        check("stream-line-" in text, "incremental /log polls append later chunks")

        terminal = slot_public(auth, "/tasks/%d/terminal" % task_id_of("Char cap dispatch"),
                               "terminal")
        check(terminal.get("has_raw_log") is True and int(terminal["session_id"]) == raw_session,
              "terminal view selects raw rendering for the raw session")

        # Old sessions (typed entries, no raw rows) keep the fallback view.
        conn = db()
        conn.execute("insert into session_commands (session_id, command_text, output_text,"
                     " type, started_at) values (?, 'ls', 'old-output', 'command',"
                     " strftime('%s','now'))", (session_id,))
        conn.commit()
        conn.close()
        legacy = slot_public(auth, "/tasks/%d/terminal" % plan_task, "terminal")
        check(legacy.get("has_raw_log") is False,
              "legacy session falls back to the entry-type terminal view")

        request = urllib.request.Request(WEB + "/terminal-stream/%d" % raw_session)
        with urllib.request.urlopen(request, timeout=15) as stream:
            raw_events = []
            deadline = time.monotonic() + 8
            while time.monotonic() < deadline and len(raw_events) < 3:
                line = stream.readline().decode().strip()
                if not line.startswith("data: ") or line == "data: ping":
                    continue
                event = json.loads(line[6:])
                if event.get("type") == "raw":
                    raw_events.append(event)
            check(len(raw_events) >= 3 and raw_events[0]["text"] == fake.PROMPT
                  and raw_events[0]["seq"] < raw_events[1]["seq"],
                  "terminal stream serves raw chunks in seq order (prompt first)")

        print("== capabilities: tag-based routing ==")
        saddles_state = slot_public(auth, "/saddles", "saddles")
        act(auth, saddles_state["create_capability"], {"name": "gpu"})
        act(auth, saddles_state["create_capability"], {"name": "bigmem"})
        saddles_state = slot_public(auth, "/saddles", "saddles")
        caps = {c["name"]: c for c in saddles_state["capabilities"]}
        check(len(caps) == 2 and all(int(c["saddle_count"]) == 0 and int(c["task_count"]) == 0
                                     for c in caps.values()),
              "capabilities created and listed with zero usage")

        def saddle_card(name):
            rows = [s for s in slot_public(auth, "/saddles", "saddles")["saddles"]
                    if s["name"] == name]
            return rows[0]

        fake_card = saddle_card("fake-saddle")
        check(fake_card["capabilities"] == [],
              "saddle card starts with no capability chips")

        # A task requiring 'gpu' waits while the only idle saddle lacks it;
        # a later task without requirements still dispatches (skip-and-continue).
        tasks_state = slot_public(auth, "/tasks", "tasks")
        act(auth, tasks_state["create"], {
            "project_id": "1",
            "title": "GPU task",
            "priority": "2",
        })
        gpu_task = int([t["id"] for t in slot_public(auth, "/tasks", "tasks")["tasks"]
                        if t["title"] == "GPU task"][0])
        detail = task_state(auth, gpu_task)
        act(auth, detail["attach_capability"], {"capability_id": str(int(caps["gpu"]["id"]))})
        detail = task_state(auth, gpu_task)
        check([c["name"] for c in detail["capabilities"]] == ["gpu"],
              "task page lists the required capability")
        # The only idle saddle lacks the tag, so the queue flags the wait
        # (read before any other task claims the idle saddle).
        queue = [t for t in slot_public(auth, "/tasks", "tasks")["tasks"]
                 if int(t["id"]) == gpu_task][0]
        check(queue["status"] == "queued" and queue["capabilities"] == ["gpu"]
              and queue.get("waiting_for_saddle") is True,
              "queue row shows the waiting task with its tag and wait flag")

        act(auth, tasks_state["create"], {
            "project_id": "1",
            "title": "Any-saddle task",
            "priority": "3",
        })
        any_task = int([t["id"] for t in slot_public(auth, "/tasks", "tasks")["tasks"]
                        if t["title"] == "Any-saddle task"][0])

        check(wait_for(lambda: task_state(auth, any_task).get("status") != "queued" or False,
                       timeout=30, what="uncapable task dispatches") is not None,
              "task without requirements dispatches past the waiting task")
        with open(os.path.join(WORK, "app.log")) as handle:
            app_log = handle.read()
        check("waits for a capable saddle" in app_log and "requires: gpu" in app_log,
              "dispatcher logs the capability wait")

        # Attaching the tag to the saddle releases the task.
        fake_card = saddle_card("fake-saddle")
        act(auth, fake_card["attach_capability"], {"capability_id": str(int(caps["gpu"]["id"]))})
        fake_card = saddle_card("fake-saddle")
        check([c["name"] for c in fake_card["capabilities"]] == ["gpu"],
              "saddle card shows the attached chip")
        check(wait_task_done(auth, gpu_task, timeout=60) is not None,
              "task dispatches once the saddle carries the required tag")
        queue = [t for t in slot_public(auth, "/tasks", "tasks")["tasks"]
                 if int(t["id"]) == gpu_task][0]
        check(queue.get("waiting_for_saddle") is not True,
              "wait flag clears once dispatched")

        # Multi-tag: gpu + bigmem required, only gpu carried → waits; adding
        # bigmem completes the superset.
        act(auth, tasks_state["create"], {
            "project_id": "1",
            "title": "Big task",
            "priority": "2",
        })
        big_task = int([t["id"] for t in slot_public(auth, "/tasks", "tasks")["tasks"]
                        if t["title"] == "Big task"][0])
        detail = task_state(auth, big_task)
        act(auth, detail["attach_capability"], {"capability_id": str(int(caps["gpu"]["id"]))})
        act(auth, detail["attach_capability"], {"capability_id": str(int(caps["bigmem"]["id"]))})
        check(wait_for(lambda: ([t for t in slot_public(auth, "/tasks", "tasks")["tasks"]
                                 if int(t["id"]) == big_task][0].get("waiting_for_saddle")
                                is True) or False, timeout=30, what="big task waits") is not None,
              "task waits when the saddle's tags are not a superset")
        fake_card = saddle_card("fake-saddle")
        act(auth, fake_card["attach_capability"], {"capability_id": str(int(caps["bigmem"]["id"]))})
        check(wait_task_done(auth, big_task, timeout=60) is not None,
              "task dispatches once the superset is complete")

        # Detach a requirement; delete a capability everywhere.
        detail = task_state(auth, big_task)
        act(auth, [c for c in detail["capabilities"] if c["name"] == "bigmem"][0]["detach"], {})
        check([c["name"] for c in task_state(auth, big_task)["capabilities"]] == ["gpu"],
              "detached requirement disappears from the task")
        bigmem_row = [c for c in slot_public(auth, "/saddles", "saddles")["capabilities"]
                      if c["name"] == "bigmem"][0]
        act(auth, bigmem_row["delete"], {})
        saddles_state = slot_public(auth, "/saddles", "saddles")
        check(all(c["name"] != "bigmem" for c in saddles_state["capabilities"]),
              "deleted capability gone from the catalogue")
        check([c["name"] for c in task_state(auth, big_task)["capabilities"]] == ["gpu"],
              "deleting a capability drops its task requirements")
        check(all(c["name"] != "bigmem"
                  for c in saddle_card("fake-saddle")["capabilities"]),
              "deleting a capability drops it from saddles")

        print("== B4: required capabilities on the create form ==")
        tasks_state = slot_public(auth, "/tasks", "tasks")
        gpu_option = [o for o in tasks_state.get("capability_options", [])
                      if o["name"] == "gpu"][0]
        check(len(tasks_state.get("capability_options", [])) >= 1,
              "queue page offers capability options in the create form")

        conn = db()
        before = conn.execute("select count(*) from tasks").fetchone()[0]
        conn.close()
        act(auth, tasks_state["create"], {
            "project_id": "1",
            "title": "Bad cap task",
            "capability_id": [gpu_option["id"], "999"],
        })
        conn = db()
        after = conn.execute("select count(*) from tasks").fetchone()[0]
        conn.close()
        check(after == before, "unknown capability id rejects the create")

        act(auth, tasks_state["create"], {
            "project_id": "1",
            "title": "Cap-on-create task",
            "capability_id": [gpu_option["id"]],
        })
        cap_create = int([t["id"] for t in slot_public(auth, "/tasks", "tasks")["tasks"]
                          if t["title"] == "Cap-on-create task"][0])
        detail = task_state(auth, cap_create)
        check([c["name"] for c in detail["capabilities"]] == ["gpu"],
              "capabilities from the create form land on the task")
        queue = [t for t in slot_public(auth, "/tasks", "tasks")["tasks"]
                 if int(t["id"]) == cap_create][0]
        check(queue["capabilities"] == ["gpu"],
              "queue row shows the created task's requirements")
        # The waiting flag must hold it back until the capable saddle frees
        # up (the fake saddle still carries gpu from the routing checks).
        check(queue.get("waiting_for_saddle") is not True,
              "capable saddle available: no wait flag on the new task")

        print("== B6: computed display state ==")
        conn = db()
        conn.execute("insert into tasks (project_id, title, status, priority, created_at)"
                     " values (1, 'Parent', 'done', 5, strftime('%s','now'))")
        parent6 = conn.execute("select max(id) from tasks").fetchone()[0]
        # The post-mortem case: stored done WITH an unanswered review block.
        conn.execute("insert into sessions (task_id, saddle_id, started_at, ended_at, outcome)"
                     " values (?, ?, strftime('%s','now'), strftime('%s','now'), 'done')",
                     (parent6, fake_id))
        session6 = conn.execute("select max(id) from sessions").fetchone()[0]
        conn.commit()
        conn.close()
        saddle_api("POST", "/api/saddle/%d/update" % fake_id, fake_token,
                   {"type": "block", "session_id": session6, "data": {
                       "question": "Review the final diff", "type": "review"}})

        detail = task_state(auth, parent6)
        check(detail.get("display") == "review requested" and detail.get("terminal") is True,
              "unanswered review overrides the stored done status (terminal flag keeps stored truth)")
        queue = [t for t in slot_public(auth, "/tasks", "tasks")["tasks"]
                 if int(t["id"]) == parent6][0]
        check(queue["display"] == "review requested",
              "queue row shows the computed review-requested display")

        # Delegation: with the review answered, open subtasks delegate.
        conn = db()
        conn.execute("update task_blocks set answered_at = strftime('%s','now'),"
                     " answer = 'Human approved the review' where task_id = ?", (parent6,))
        conn.execute("insert into tasks (project_id, title, status, priority, parent_task_id,"
                     " created_at) values (1, 'Sub A', 'working', 5, ?, strftime('%s','now'))",
                     (parent6,))
        conn.execute("insert into tasks (project_id, title, status, priority, parent_task_id,"
                     " created_at) values (1, 'Sub B', 'done', 5, ?, strftime('%s','now'))",
                     (parent6,))
        conn.commit()
        conn.close()
        detail = task_state(auth, parent6)
        check(detail.get("display") == "delegating 1/2" and detail.get("subtask_open") == 1,
              "open subtasks show the delegating breakdown (%s)" % detail.get("display"))

        # Flags track the stored status once the display falls through
        # (subtasks terminal first — delegating leads while any are open).
        conn = db()
        conn.execute("update tasks set status = 'failed', completed_at = strftime('%s','now')"
                     " where id = ?", (parent6,))
        conn.execute("update tasks set status = 'failed', completed_at = strftime('%s','now')"
                     " where title = 'Sub A'")
        conn.commit()
        conn.close()
        detail = task_state(auth, parent6)
        check(detail.get("display") == "failed" and detail.get("failed") is True
              and detail.get("terminal") is True,
              "failed task with answered review and terminal subtasks shows failed + terminal flags")

        print("== retry + resume ==")
        # A daemon-side failure fails the task with its explanation.
        fake.fail_next = True
        act(auth, slot_public(auth, "/tasks", "tasks")["create"], {
            "project_id": "1",
            "title": "Flaky task",
            "priority": "2",
        })
        flaky = int([t["id"] for t in slot_public(auth, "/tasks", "tasks")["tasks"]
                     if t["title"] == "Flaky task"][0])
        check(wait_for(lambda: task_state(auth, flaky).get("status") == "failed" or False,
                       timeout=60, what="flaky task fails") is not None,
              "daemon failure fails the task")
        detail = task_state(auth, flaky)
        check("bash -n rejected" in (detail.get("summary") or ""),
              "failure summary shows the daemon's explanation")

        # Retry: summary moves into a comment and clears, task requeues,
        # history stays, and the re-dispatch restores the workspace.
        comments_before = len(detail.get("comments", []))
        progress_before = len(detail.get("progress", []))
        act(auth, detail["retry"], {})
        detail = task_state(auth, flaky)
        check(detail["status"] == "queued" and (detail.get("summary") or "") == "",
              "retry requeues the task and clears the stale summary")
        check(any("bash -n rejected" in c["body"] for c in detail["comments"]),
              "failure explanation kept as a bot comment")
        check(any(c["body"] == "Task retried by user" for c in detail["comments"]),
              "retry lands its audit comment")
        check(len(detail["comments"]) >= comments_before + 1,
              "retry keeps the comment history")
        check(wait_task_done(auth, flaky, timeout=60) is not None,
              "retried task dispatches again and completes")
        detail = task_state(auth, flaky)
        check(any("restored the session context" in p["summary"]
                  for p in detail.get("progress", [])),
              "daemon resume reported on the first status after the restore")
        check(len(detail["progress"]) > progress_before,
              "resume note appended to the progress timeline")

        # Manual resume: a task stuck working on an offline saddle.
        act(auth, slot_public(auth, "/tasks", "tasks")["create"], {
            "project_id": "1",
            "title": "Stuck task",
            "priority": "2",
        })
        stuck = int([t["id"] for t in slot_public(auth, "/tasks", "tasks")["tasks"]
                     if t["title"] == "Stuck task"][0])
        check(wait_for(lambda: task_state(auth, stuck).get("status") == "working" or False,
                       timeout=60, what="stuck task starts working") is not None,
              "stuck task reaches working")
        conn = db()
        conn.execute("update saddles set status = 'offline' where name = 'fake-saddle'")
        conn.commit()
        conn.close()
        detail = task_state(auth, stuck)
        check(detail.get("resume_available") is True,
              "task page offers resume while its saddle is offline")
        act(auth, detail["resume"], {})
        detail = task_state(auth, stuck)
        check(detail["status"] == "queued",
              "manual resume requeues the stuck task")
        check(any(c["body"] == "Saddle became unreachable; task requeued"
                  for c in detail["comments"]),
              "manual resume lands the interruption comment")
        check(all(s["status"] == "offline"
                  for s in slot_public(auth, "/saddles", "saddles")["saddles"]),
              "saddle stays offline after the manual requeue")

        # Bringing the saddle back lets the requeued task resume and finish.
        fake.state = "idle"
        fake_card = saddle_card("fake-saddle")
        act(auth, fake_card["refresh"], {})
        check(any(s["status"] == "idle"
                  for s in slot_public(auth, "/saddles", "saddles")["saddles"]
                  if s["name"] == "fake-saddle"),
              "refreshed saddle returns idle")
        check(wait_task_done(auth, stuck, timeout=60) is not None,
              "requeued task resumes on the refreshed saddle and completes")

        print("== rejected entries (non-fatal) ==")
        # Ingest API: a rejected entry stores on the session and streams
        # through SSE; the task is untouched.
        status, _ = saddle_api("POST", "/api/saddle/%d/update" % fake_id, fake_token,
                               {"type": "output", "session_id": session_id, "data": {
                                   "command": "bash -n script.sh",
                                   "output": "syntax error near line 3 (recoverable)",
                                   "exit_code": 1,
                                   "type": "rejected"}})
        check(status == 200, "rejected entry accepted by the ingest API")
        request = urllib.request.Request(WEB + "/terminal-stream/%d" % session_id)
        with urllib.request.urlopen(request, timeout=15) as stream:
            rejected_event = None
            deadline = time.monotonic() + 8
            while time.monotonic() < deadline and rejected_event is None:
                line = stream.readline().decode().strip()
                if not line.startswith("data: ") or line == "data: ping":
                    continue
                event = json.loads(line[6:])
                if event.get("type") == "rejected":
                    rejected_event = event
            check(rejected_event is not None
                  and "syntax error near line 3" in (rejected_event.get("output") or ""),
                  "terminal stream carries rejected entries with their reason")

        # The page template renders them with the distinct non-fatal style.
        status, page = http("GET", "/tasks/%d/terminal" % stuck, timeout=15)
        check(status == 200 and "term-rejected" in page,
              "terminal page renders rejected entries in their own style")

        print("== B8: ANSI SGR in the terminal view ==")
        # Byte-exact SGR delivery: the daemon's coloured chunks flow through
        # the store + SSE untouched (the client renderer styles them).
        coloured = "\x1b[1;32mbold green\x1b[0m then \x1b[38;5;196m256-red\x1b[0m\n"
        conn = db()
        conn.execute("insert into session_raw_log (session_id, seq, chunk)"
                     " values (?, 900, ?)", (session_id, coloured))
        conn.commit()
        conn.close()
        request = urllib.request.Request(WEB + "/terminal-stream/%d" % session_id)
        with urllib.request.urlopen(request, timeout=15) as stream:
            coloured_event = None
            deadline = time.monotonic() + 8
            while time.monotonic() < deadline and coloured_event is None:
                line = stream.readline().decode().strip()
                if not line.startswith("data: ") or line == "data: ping":
                    continue
                event = json.loads(line[6:])
                if event.get("type") == "raw" and "\x1b[1;32m" in (event.get("text") or ""):
                    coloured_event = event
            check(coloured_event is not None
                  and "\x1b[38;5;196m" in coloured_event["text"],
                  "SGR sequences stream byte-exact to the client renderer")
        status, page = http("GET", "/tasks/%d/terminal" % stuck, timeout=15)
        check(status == 200 and "makeAnsiRenderer" in page and "colour256" in page,
              "terminal page embeds the ANSI renderer (SGR + 256-colour palette)")

        # Dispatch path: a rejected entry from /output flows into the audit
        # trail without failing (or finishing) the task.
        fake.queue_output("rejected", "echo 'too long' | saddle",
                          "max_tokens exceeded (recoverable)")
        act(auth, slot_public(auth, "/tasks", "tasks")["create"], {
            "project_id": "1",
            "title": "Rejected ride",
            "priority": "2",
        })
        rejected_task = int([t["id"] for t in slot_public(auth, "/tasks", "tasks")["tasks"]
                             if t["title"] == "Rejected ride"][0])
        check(wait_task_done(auth, rejected_task, timeout=60) is not None,
              "task completes normally past rejected entries")
        conn = db()
        stored = conn.execute(
            "select count(*) from session_commands sc join sessions s on s.id = sc.session_id"
            " where s.task_id = ? and sc.type = 'rejected'", (rejected_task,)).fetchone()[0]
        conn.close()
        check(stored >= 1,
              "rejected entries stored in the audit trail (%d rows)" % stored)
        check(task_state(auth, rejected_task)["status"] == "done"
              and "fake daemon finished" in (task_state(auth, rejected_task).get("summary") or ""),
              "rejected entries never fail the task")
        print("== B7: suspended state + per-subtask resume ==")
        fake.suspend_after_start = True
        pushes_before = len(fake.start_payloads)
        act(auth, slot_public(auth, "/tasks", "tasks")["create"], {
            "project_id": "1",
            "title": "Suspend parent",
            "priority": "2",
        })
        parent7 = int([t["id"] for t in slot_public(auth, "/tasks", "tasks")["tasks"]
                       if t["title"] == "Suspend parent"][0])
        check(wait_for(lambda: task_state(auth, parent7).get("status") == "suspended"
                       or False, timeout=60, what="parent parks as suspended") is not None,
              "daemon 'suspended' state parks the task")
        detail = task_state(auth, parent7)
        check(detail.get("display") == "waiting on subtasks",
              "suspended task displays as waiting on subtasks")
        check(any(s["status"] == "idle"
                  for s in slot_public(auth, "/saddles", "saddles")["saddles"]),
              "suspension frees the saddle")
        first_push = fake.start_payloads[pushes_before]
        check(first_push.get("subtasks") == [],
              "the /start payload carries the subtasks array (empty here)")

        # Two subtask events land while parked (staged, not dispatched):
        # both must coalesce into one resume with a full report.
        conn = db()
        conn.execute("insert into tasks (project_id, title, status, priority, parent_task_id,"
                     " summary, completed_at, created_at) values (1, 'Child one', 'done', 5, ?,"
                     " 'built and verified the flange', strftime('%s','now','+1 second'),"
                     " strftime('%s','now'))", (parent7,))
        conn.execute("insert into tasks (project_id, title, status, priority, parent_task_id,"
                     " summary, completed_at, created_at) values (1, 'Child two', 'failed', 5, ?,"
                     " 'the harness refused to start', strftime('%s','now','+1 second'),"
                     " strftime('%s','now'))", (parent7,))
        conn.commit()
        conn.close()

        def parent_push_count():
            return len([p for p in fake.start_payloads
                        if int(p.get("task", {}).get("id") or 0) == parent7])

        check(wait_for(lambda: parent_push_count() >= 2 or False,
                       timeout=45, what="suspended parent resumes") is not None,
              "subtask events resume the suspended parent")
        parent_pushes = [p for p in fake.start_payloads
                         if int(p.get("task", {}).get("id") or 0) == parent7]
        check(len(parent_pushes) >= 2,
              "the parent's resume is a fresh /start for the same task")
        resume_push = parent_pushes[-1]
        notice = resume_push.get("resume_notice") or ""
        check("Child one" in notice and "completed" in notice
              and "built and verified the flange" in notice,
              "resume notice reports the finished subtask with its summary")
        check("Child two" in notice and "failed" in notice
              and "the harness refused to start" in notice,
              "coalesced: the second event rides the same resume notice")
        subtask_entries = {(s["title"], s["status"]) for s in resume_push.get("subtasks", [])}
        check(("Child one", "done") in subtask_entries
              and ("Child two", "failed") in subtask_entries,
              "subtasks array carries the children's states at dispatch time")
        check(wait_task_done(auth, parent7, timeout=60) is not None,
              "resumed parent completes")
        detail = task_state(auth, parent7)
        check(any("restored the session context" in p["summary"]
                  for p in detail.get("progress", [])),
              "resumed flag reported on the first status after the restore")




        print("== R3 B1: subtask status push ==")
        # A parked (suspended) parent gives delivery a stable open session.
        fake.suspend_after_start = True
        act(auth, slot_public(auth, "/tasks", "tasks")["create"], {
            "project_id": "1",
            "title": "Push parent",
            "priority": "2",
        })
        push_parent = int([t["id"] for t in slot_public(auth, "/tasks", "tasks")["tasks"]
                           if t["title"] == "Push parent"][0])
        check(wait_for(lambda: task_state(auth, push_parent).get("status") == "suspended"
                       or False, timeout=60, what="push parent parks") is not None,
              "push parent parks with an open session")

        act(auth, slot_public(auth, "/tasks", "tasks")["create"], {
            "project_id": "1",
            "title": "Push child",
            "parent_task_id": str(push_parent),
        })
        push_child = int([t["id"] for t in slot_public(auth, "/tasks", "tasks")["tasks"]
                          if t["title"] == "Push child"][0])

        def events_for(subtask_id):
            return [e for e in fake.subtask_status_events
                    if int(e.get("subtask_id") or 0) == subtask_id]

        check(wait_for(lambda: len(events_for(push_child)) > 0 or False,
                       timeout=30, what="queued subtask event") is not None,
              "subtask creation pushes a queued status event")
        first_event = events_for(push_child)[0]
        check(int(first_event.get("parent_task_id") or 0) == push_parent
              and first_event.get("title") == "Push child"
              and first_event.get("status") in ("queued", "working"),
              "status event carries parent id, title and a wire status (%s)"
              % first_event.get("status"))

        # Real lifecycle: the child dispatches (working) and completes (done
        # with summary) — the parent's daemon hears every transition.
        check(wait_for(lambda: any(e.get("status") == "done" and "finished" in (e.get("summary") or "")
                                   for e in events_for(push_child)) or False,
                       timeout=90, what="done subtask event") is not None,
              "subtask completion pushes done with the summary")
        check(any(e.get("status") == "working" for e in events_for(push_child)),
              "dispatch pushes a working status event")

        # Best-effort retry: while the daemon 500s, events stay queued and
        # land once it recovers.
        fake.fail_subtask_status = True
        act(auth, slot_public(auth, "/tasks", "tasks")["create"], {
            "project_id": "1",
            "title": "Push child two",
            "parent_task_id": str(push_parent),
        })
        push_child_two = int([t["id"] for t in slot_public(auth, "/tasks", "tasks")["tasks"]
                              if t["title"] == "Push child two"][0])
        time.sleep(7)
        check(len(events_for(push_child_two)) == 0,
              "failed pushes stay queued (no event delivered)")
        fake.fail_subtask_status = False
        check(wait_for(lambda: len(events_for(push_child_two)) > 0 or False,
                       timeout=30, what="retried subtask event") is not None,
              "recovered pushes deliver on a later tick")


        print("== R3 B2: stale-busy saddle healing ==")
        # The observed incident: a saddle left busy with current_task_id 0.
        conn = db()
        conn.execute("update saddles set status = 'busy', current_task_id = 0,"
                     " allocated_at = strftime('%s','now') where name = 'fake-saddle'")
        conn.commit()
        conn.close()
        act(auth, slot_public(auth, "/tasks", "tasks")["create"], {
            "project_id": "1",
            "title": "Heal dispatch",
            "priority": "2",
        })
        heal_task = int([t["id"] for t in slot_public(auth, "/tasks", "tasks")["tasks"]
                         if t["title"] == "Heal dispatch"][0])
        check(wait_task_done(auth, heal_task, timeout=60) is not None,
              "busy-without-task heals and the queued task dispatches")
        with open(os.path.join(WORK, "app.log")) as handle:
            app_log = handle.read()
        check("Healing stale-busy saddle" in app_log
              and "busy with no current task" in app_log,
              "the busy@0 heal is logged")

        # Contradiction: the daemon reports idle while the web believes the
        # saddle is running the orphaned task.
        conn = db()
        conn.execute("insert into tasks (project_id, title, status, priority, created_at)"
                     " values (1, 'Orphan task', 'working', 2, strftime('%s','now'))")
        orphan = conn.execute("select max(id) from tasks").fetchone()[0]
        conn.execute("update saddles set status = 'busy', current_task_id = ?,"
                     " allocated_at = strftime('%s','now') where name = 'fake-saddle'",
                     (orphan,))
        conn.commit()
        conn.close()
        fake.state = "idle"
        check(wait_task_done(auth, orphan, timeout=60) is not None,
              "contradicted saddle heals, orphan requeues and completes")
        with open(os.path.join(WORK, "app.log")) as handle:
            app_log = handle.read()
        check("daemon idle while the web believes" in app_log,
              "the contradiction heal is logged")


        print("== R4 B1: synchronous subtask callback ==")
        conn = db()
        callback_rows = conn.execute(
            "select token from api_tokens where saddle_id = 0"
            " and token like 'saddle-callback-%'").fetchall()
        conn.close()
        r4_token = callback_rows[0][0] if callback_rows else callback_token

        # Parent with a live parked session (suspended) hosts the callback.
        fake.suspend_after_start = True
        act(auth, slot_public(auth, "/tasks", "tasks")["create"], {
            "project_id": "1",
            "title": "Callback parent",
            "priority": "2",
        })
        cb_parent = int([t["id"] for t in slot_public(auth, "/tasks", "tasks")["tasks"]
                         if t["title"] == "Callback parent"][0])
        check(wait_for(lambda: task_state(auth, cb_parent).get("status") == "suspended"
                       or False, timeout=60, what="callback parent parks") is not None,
              "callback parent parks")

        status, _ = saddle_api("POST", "/api/saddle/subtask", None,
                               {"parent_task_id": cb_parent, "title": "no token"})
        check(status == 401, "subtask callback rejects a missing token")

        anchor = int([t["id"] for t in slot_public(auth, "/tasks", "tasks")["tasks"]
                      if t["title"] == "Heal dispatch"][0])
        status, body = saddle_api("POST", "/api/saddle/subtask", r4_token, {
            "parent_task_id": cb_parent,
            "title": "Wire the flange",
            "description": "torque to spec",
            "depends_on": [anchor],
            "session_id": 1,
        })
        check(status == 200 and body.get("ok") is True and int(body.get("task_id") or 0) > 0,
              "callback creates the subtask synchronously")
        subtask_id = int(body.get("task_id"))
        detail = task_state(auth, subtask_id)
        check(detail["title"] == "Wire the flange" and int(detail["project_id"]) == 1
              and int(detail["parent_task_id"]) == cb_parent,
              "subtask row inherits the parent's project and linkage")
        check(detail.get("task_branch") == task_state(auth, cb_parent).get("task_branch"),
              "subtask shares the parent's task branch")
        conn = db()
        dep_rows = conn.execute(
            "select depends_on_task_id from task_dependencies where task_id = ?",
            (subtask_id,)).fetchall()
        conn.close()
        check([r[0] for r in dep_rows] == [anchor],
              "depends_on wired as task_dependencies")

        # Idempotency + entry-poll fallback dedup.
        status, body2 = saddle_api("POST", "/api/saddle/subtask", r4_token, {
            "parent_task_id": cb_parent, "title": "Wire the flange"})
        check(status == 200 and int(body2.get("task_id") or 0) == subtask_id,
              "retried callback returns the same task id")
        conn = db()
        before = conn.execute("select count(*) from tasks where parent_task_id = ?",
                              (cb_parent,)).fetchone()[0]
        conn.close()
        conn = db()
        cb_session = conn.execute(
            "select id from sessions where task_id = ? and ended_at is null",
            (cb_parent,)).fetchone()[0]
        conn.close()
        saddle_api("POST", "/api/saddle/%d/update" % fake_id, fake_token,
                   {"type": "subtask", "session_id": cb_session, "data": {
                       "title": "Wire the flange", "description": "again"}})
        conn = db()
        after = conn.execute("select count(*) from tasks where parent_task_id = ?",
                             (cb_parent,)).fetchone()[0]
        timeline = conn.execute(
            "select count(*) from session_commands where session_id = ?"
            " and type = 'subtask'", (cb_session,)).fetchone()[0]
        conn.close()
        check(after == before,
              "entry-poll fallback dedupes against the callback's row")
        check(timeline >= 1, "timeline entry recorded on the parent's session")

        # Validation: unknown parent, unknown depends_on, ancestor cycle.
        status, body = saddle_api("POST", "/api/saddle/subtask", r4_token,
                                  {"parent_task_id": 99999, "title": "ghost"})
        check(status == 400, "unknown parent rejected")
        status, body = saddle_api("POST", "/api/saddle/subtask", r4_token,
                                  {"parent_task_id": cb_parent, "title": "bad dep",
                                   "depends_on": [99999]})
        check(status == 400 and "unknown task" in body.get("error", ""),
              "unknown depends_on id rejected with a clear error")
        status, body = saddle_api("POST", "/api/saddle/subtask", r4_token,
                                  {"parent_task_id": cb_parent, "title": "cycle dep",
                                   "depends_on": [cb_parent]})
        check(status == 400 and "cycle" in body.get("error", ""),
              "depending on an ancestor rejected as a cycle")

    finally:
        # Exit-code diagnostic: distinguishes a crashed app (negative
        # returncode, e.g. -11 SIGSEGV) from a clean shutdown. When
        # tearing down mid-exception, also capture the still-alive
        # app's stacks before killing it (a wedged-but-alive server
        # otherwise leaves no evidence).
        print("(app returncode at teardown: %s)" % app.poll())
        if app.poll() is None and sys.exc_info()[0] is not None:
            dump_app_stacks(app.pid)
        app.terminate()
        try:
            app.wait(timeout=5)
        except subprocess.TimeoutExpired:
            app.kill()

    print("%d passed, %d failed" % (passes, failures))
    return 1 if failures else 0


if __name__ == "__main__":
    sys.exit(main())