okstra 0.214.1 → 0.216.0

package/runtime/python/okstra_ctl/phases/discussion/workflow.py

@@ -0,0 +1,667 @@
+"""토론의 조사·반박·질문 순환 — 주기 열기, 결과 정산, 주기 종료, 직접 질문, 실패 복구.
+
+워커 실행은 공통 배정·디스패치 경로(`agent-prompt materialize` 다음 `worker-dispatch`
+또는 `team dispatch`)가, 근거 판정은 수렴 엔진(`convergence_engine`)이 맡는다. 여기는 그 앞뒤에서 토론 기록을 읽고 쓰는 일만 한다.
+
+조사 주기 하나는 run 하나다. 수렴 상태·그룹 경로가 run 마다 하나로 고정되어 있어
+(`paths.py` 의 `convergence-<task-type>-<seq>.json`) 한 run 안에서 두 번째 수렴을
+열 자리가 없다. 다음 주기와 참여자 교체는 `--discussion-start <task-key>` 로 준비한
+이어가기 run 에서 연다.
+"""
+from __future__ import annotations
+
+import hashlib
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Mapping
+
+from okstra_ctl.convergence_engine import validate_final_state
+from okstra_ctl.dispatch_core import CLI_BATCH_LAUNCH_FAILURE
+from okstra_ctl.dispatch_state import dispatch_worker_key, worker_dispatch_records
+from okstra_ctl.execution_manifest import read_execution_manifest
+from okstra_ctl.json_boundary import JsonBoundaryError, load_owned_object, write_owned_object_atomic
+from okstra_ctl.report_finalize import run_seq
+from okstra_ctl.worker_prompt_policy import (
+    ANALYSIS_DUTY_BY_TASK_TYPE,
+    DISCUSSION_QUESTION_DISPATCH_KIND,
+)
+
+from .store import (
+    LEADER,
+    USER,
+    DiscussionStore,
+    DiscussionStoreError,
+    SourceRun,
+    read_draft,
+    render_draft_text,
+    resolve_source_run,
+    same_task,
+    transaction,
+)
+
+RESEARCH_DISPATCH_KIND = "initial"
+CHOICES = ("retry", "replace", "reduce")
+_QUESTION_CHOICES = ("retry", "reduce")
+_DUTY = ANALYSIS_DUTY_BY_TASK_TYPE["discussion"]
+
+
+class DiscussionWorkflowError(DiscussionStoreError):
+    pass
+
+
+@dataclass(frozen=True)
+class DiscussionRun:
+    source: SourceRun
+    project_root: Path
+    manifest: Mapping[str, Any]
+    seq: str
+
+    @property
+    def run_dir(self) -> Path:
+        return self.project_root / str(self.manifest["runDirectoryPath"])
+
+    @property
+    def analysers(self) -> tuple[dict[str, str], ...]:
+        return tuple(
+            {"worker": str(row["workerId"]), "model": f"{row['provider']}/{row['model']}"}
+            for row in self.manifest.get("workerAssignments") or []
+            if isinstance(row, dict) and row.get("role") == "analyser"
+        )
+
+    def project_path(self, value: str) -> Path:
+        path = Path(value)
+        return path if path.is_absolute() else self.project_root / path
+
+    def relative(self, path: Path) -> str:
+        try:
+            return path.resolve().relative_to(self.project_root.resolve()).as_posix()
+        except ValueError:
+            # expected-miss: 프로젝트 밖 경로는 받은 그대로 기록한다.
+            return str(path)
+
+
+def load_run(store: DiscussionStore, manifest_path: str) -> DiscussionRun:
+    source = resolve_source_run(store, manifest_path)
+    path = store.project_root / source.manifest
+    try:
+        manifest = load_owned_object(path, artifact="discussion run manifest")
+    except JsonBoundaryError as exc:
+        raise DiscussionWorkflowError(str(exc)) from exc
+    return DiscussionRun(source, store.project_root, manifest, run_seq(manifest))
+
+
+def _digest(data: bytes) -> str:
+    return "sha256:" + hashlib.sha256(data).hexdigest()
+
+
+def _cycle_of_run(draft: Mapping[str, Any], run: DiscussionRun) -> dict[str, Any] | None:
+    mine = [cycle for cycle in draft["cycles"] if cycle["sourceRun"] == run.source.manifest]
+    return mine[-1] if mine else None
+
+
+def _last_closed(draft: Mapping[str, Any]) -> dict[str, Any] | None:
+    closed = [cycle for cycle in draft["cycles"] if cycle["status"] == "closed"]
+    return closed[-1] if closed else None
+
+
+def _claims(draft: Mapping[str, Any], ids: list[str]) -> list[dict[str, Any]]:
+    by_id = {claim["recordId"]: claim for cycle in draft["cycles"] for claim in cycle["claims"]}
+    return [
+        {key: by_id[claim_id][key] for key in ("recordId", "standing", "classification", "summary", "author")}
+        for claim_id in ids
+    ]
+
+
+def _present_options(draft: Mapping[str, Any], cycle: Mapping[str, Any]) -> dict[str, Any]:
+    return {
+        "action": "present-options",
+        "reason": (
+            f"the research input references equal those of {cycle['recordId']}; no new "
+            "evidence, user answer or alternative arrived, so research is not dispatched again"
+        ),
+        "remainingDisagreements": _claims(draft, draft["remainingDisagreements"]),
+        "alternatives": [
+            {"recordId": row["recordId"], "text": row["text"], "author": row["author"]}
+            for row in draft["materials"] if row["materialKind"] == "alternative"
+        ],
+        "userOptions": [
+            "choose a direction and record it with `okstra discussion decide`",
+            "bring new evidence or an alternative with `okstra discussion add-material`, then research again",
+            "ask one participant directly with `okstra discussion address`",
+        ],
+    }
+
+
+def _waiting(draft: Mapping[str, Any]) -> dict[str, Any] | None:
+    if draft["unrecoveredFailures"]:
+        return {"action": "await-recovery", "failures": draft["unrecoveredFailures"]}
+    if draft["pendingForUser"]:
+        return {"action": "await-user", "nextForUser": draft["nextForUser"]}
+    if draft["pendingForParticipants"]:
+        return {"action": "await-participant", "questions": draft["pendingForParticipants"]}
+    return None
+
+
+def _research_instruction(cycle_id: str, draft: Mapping[str, Any]) -> str:
+    refs = ", ".join(draft["inputRefs"]) or "none"
+    return (
+        f"# Discussion research — {cycle_id}\n\n"
+        "Research the confirmed subject and question of the discussion record below.\n\n"
+        "- Read the whole record first: every user answer, every participant answer and "
+        "every user decision. A user decision stands; do not argue it away with a fact check.\n"
+        "- Report each factual claim about the code or an external source as a numbered "
+        "finding with its evidence location, and say what the evidence could not reach.\n"
+        "- For each alternative direction, state what it requires, what it excludes and the "
+        "risk it carries, without ranking it into a decision.\n"
+        "- List the questions only the user can answer (intent, scope, priority, acceptable "
+        "risk) under the heading `Questions for the user`; do not report them as findings.\n"
+        "- A claim already in the record is new only with new evidence: name the record it "
+        "extends or refutes.\n\n"
+        f"Input references of this cycle: {refs}\n\n"
+        + render_draft_text(draft)
+    )
+
+
+def open_cycle(store: DiscussionStore, run: DiscussionRun) -> dict[str, Any]:
+    with transaction(store) as txn:
+        draft = txn.draft()
+        if draft["subject"] is None:
+            raise DiscussionWorkflowError(
+                "confirm the subject and the question with the user first (`okstra discussion confirm-subject`)"
+            )
+        if draft["completedRevision"] is not None:
+            return {
+                "action": "completed",
+                "revisionId": draft["completedRevision"],
+                "reason": "the user completed the discussion; `okstra discussion reopen` opens a new draft",
+            }
+        if draft["unrecoveredFailures"]:
+            return _waiting(draft)
+        mine = _cycle_of_run(draft, run)
+        if mine is not None:
+            return _cycle_of_this_run(store, run, draft, mine)
+        waiting = _waiting(draft)
+        if waiting is not None:
+            return waiting
+        closed = _last_closed(draft)
+        if closed is not None and closed["inputRefs"] == draft["inputRefs"]:
+            return _present_options(draft, closed)
+        cycle_id = f"R-{1 + len(draft['cycles']):04d}"
+        text = _research_instruction(cycle_id, draft)
+        path = run.run_dir / "prompts" / f"discussion-research-discussion-{run.seq}.md"
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(text, encoding="utf-8")
+        record, created = txn.append(
+            "cycle",
+            {
+                "inputRefs": draft["inputRefs"],
+                "roster": list(run.analysers),
+                "instructionPath": run.relative(path),
+                "instructionDigest": _digest(text.encode("utf-8")),
+            },
+            author=LEADER,
+            source_run=run.source,
+        )
+    return _dispatch_payload(run, record, created)
+
+
+def _cycle_of_this_run(
+    store: DiscussionStore, run: DiscussionRun, draft: Mapping[str, Any], cycle: Mapping[str, Any],
+) -> dict[str, Any]:
+    if cycle["status"] == "open":
+        path = run.project_path(cycle["instructionPath"])
+        if not path.is_file() or _digest(path.read_bytes()) != cycle["instructionDigest"]:
+            raise DiscussionWorkflowError(
+                f"the research instruction of {cycle['recordId']} ({cycle['instructionPath']}) is "
+                "missing or changed since the cycle opened; it is the input the cycle recorded"
+            )
+        return _dispatch_payload(run, cycle, False)
+    if cycle["status"] == "closed" and draft["inputRefs"] == cycle["inputRefs"]:
+        return _present_options(draft, cycle)
+    reason = (
+        "the user chose to replace a participant"
+        if cycle["status"] == "superseded"
+        else f"new input arrived after {cycle['recordId']} closed"
+    )
+    return {
+        "action": "prepare-run",
+        "reason": f"{reason}; one run holds one research cycle",
+        "discussionStart": store.task_key,
+    }
+
+
+def _dispatch_payload(run: DiscussionRun, cycle: Mapping[str, Any], created: bool) -> dict[str, Any]:
+    return {
+        "action": "dispatch",
+        "created": created,
+        "cycle": cycle["recordId"],
+        "inputRefs": cycle["inputRefs"],
+        "instructionPath": cycle["instructionPath"],
+        "dispatchKind": RESEARCH_DISPATCH_KIND,
+        "audience": _DUTY,
+        "workers": [row["worker"] for row in run.analysers],
+    }
+
+
+def _team_state(run: DiscussionRun) -> Mapping[str, Any]:
+    try:
+        return load_owned_object(run.project_path(str(run.manifest["teamStatePath"])), artifact="team state")
+    except JsonBoundaryError as exc:
+        raise DiscussionWorkflowError(str(exc)) from exc
+
+
+def _final_rows(rows: list[Mapping[str, Any]]) -> list[Mapping[str, Any]]:
+    """invocation 마다 마지막 시도 행 — 앞 시도의 실패는 기존 재시도 루프 안의 일이다."""
+    latest: dict[str, Mapping[str, Any]] = {}
+    for row in rows:
+        latest[str(row.get("invocationId") or row.get("promptPath"))] = row
+    return list(latest.values())
+
+
+def _cli_outcome(run: DiscussionRun, row: Mapping[str, Any]) -> dict[str, Any]:
+    status = str(row.get("status") or "")
+    outcome = {
+        "label": str(row.get("invocationId") or row.get("promptPath")),
+        "invocationId": str(row.get("invocationId") or ""),
+        "dispatch": str(row.get("dispatchId") or f"{row.get('promptPath')}#{row.get('attempt')}"),
+        "attempts": int(row.get("attempt") or 1),
+    }
+    if status == "running":
+        return {**outcome, "state": "running"}
+    if status == "completed":
+        result = str(row.get("workerResultPath") or row.get("resultPath"))
+        return {**outcome, "state": "completed", "resultPath": run.relative(run.project_path(result))}
+    reason = str(row.get("reason") or status)
+    return {
+        **outcome,
+        "state": "failed",
+        "stage": "start" if reason.startswith(CLI_BATCH_LAUNCH_FAILURE) else "after-retries",
+        "status": status,
+        "reason": reason,
+    }
+
+
+def _native_outcomes(
+    run: DiscussionRun, team_state: Mapping[str, Any], worker: str, kind: str,
+) -> list[dict[str, Any]]:
+    """호스트 네이티브 세션 디스패치 — 결과는 링크로, 결과 없는 종결은 시도 원장으로 안다."""
+    rows = [
+        row for row in team_state.get("agentDispatches") or []
+        if isinstance(row, Mapping) and row.get("dispatchKind") == kind
+        and dispatch_worker_key(row) == worker
+    ]
+    if not rows:
+        return []
+    links = {
+        link["dispatchId"]: link for link in team_state.get("agentResultLinks") or []
+        if isinstance(link, Mapping) and not link.get("supersededBy")
+    }
+    attempts = {
+        (attempt.invocation_ref, attempt.attempt): attempt
+        for attempt in read_execution_manifest(run.project_root / run.source.manifest).attempts
+    }
+    outcomes = []
+    for row in _final_rows(rows):
+        outcome = {
+            "label": str(row["invocationId"]),
+            "invocationId": str(row["invocationId"]),
+            "dispatch": str(row["dispatchId"]),
+            "attempts": int(row.get("attempt") or 1),
+        }
+        link = links.get(row["dispatchId"])
+        attempt = attempts.get((row.get("invocationRef"), row.get("attempt")))
+        if link is not None:
+            outcomes.append({**outcome, "state": "completed", "resultPath": str(link["resultPath"])})
+        elif attempt is None or attempt.finished_at is None:
+            outcomes.append({**outcome, "state": "running"})
+        else:
+            outcomes.append({
+                **outcome, "state": "failed", "stage": "after-retries", "status": attempt.status,
+                "reason": f"the attempt closed as {attempt.status} without a linked result",
+            })
+    return outcomes
+
+
+def _outcomes(
+    run: DiscussionRun, team_state: Mapping[str, Any], worker: str, kind: str,
+) -> list[dict[str, Any]]:
+    cli_rows = [row for row in worker_dispatch_records(team_state, worker) if row.get("kind") == kind]
+    outcomes = [_cli_outcome(run, row) for row in _final_rows(cli_rows)]
+    outcomes += _native_outcomes(run, team_state, worker, kind)
+    running = [outcome["label"] for outcome in outcomes if outcome["state"] == "running"]
+    if running:
+        raise DiscussionWorkflowError(
+            f"{', '.join(running)} of {worker} is still running; wait for it "
+            "(`okstra team await` or the host's own completion) before settling"
+        )
+    return outcomes
+
+
+def _settled_fields(outcome: Mapping[str, Any]) -> tuple[str, dict[str, Any]]:
+    if outcome["state"] == "completed":
+        return "result", {"dispatch": outcome["dispatch"], "resultPath": outcome["resultPath"]}
+    return "failure", {
+        key: outcome[key] for key in ("dispatch", "stage", "attempts", "status", "reason")
+    }
+
+
+def settle_cycle(store: DiscussionStore, run: DiscussionRun) -> dict[str, Any]:
+    team_state = _team_state(run)
+    with transaction(store) as txn:
+        cycle = _cycle_of_run(txn.draft(), run)
+        if cycle is None or cycle["status"] != "open":
+            raise DiscussionWorkflowError(
+                "this run has no open research cycle; run `okstra discussion cycle-open` first"
+            )
+        not_dispatched = []
+        for analyser in run.analysers:
+            worker = analyser["worker"]
+            outcomes = _outcomes(run, team_state, worker, RESEARCH_DISPATCH_KIND)
+            if not outcomes:
+                not_dispatched.append(worker)
+            for outcome in outcomes:
+                kind, fields = _settled_fields(outcome)
+                txn.append(kind, {"cycleId": cycle["recordId"], **fields}, author=worker, source_run=run.source)
+        draft = txn.draft()
+    settled = next(c for c in draft["cycles"] if c["recordId"] == cycle["recordId"])
+    return {
+        "cycle": cycle["recordId"],
+        "results": [row["recordId"] for row in settled["results"]],
+        "failures": [
+            _failure_view(row) for row in settled["failures"] if row["recovery"] is None
+        ],
+        "notDispatched": not_dispatched,
+        "phase": draft["phase"],
+    }
+
+
+def _failure_view(row: Mapping[str, Any]) -> dict[str, Any]:
+    return {
+        "recordId": row["recordId"],
+        "worker": row["author"],
+        "stage": row["stage"],
+        "attempts": row["attempts"],
+        "reason": row["reason"],
+        "unverifiedScope": (
+            f"question {row['questionId']}" if row.get("questionId")
+            else f"the research of {row['author']} in {row['cycleId']}"
+        ),
+        "choices": list(_QUESTION_CHOICES if row.get("questionId") else CHOICES),
+    }
+
+
+def choose_recovery(
+    store: DiscussionStore, run: DiscussionRun, failure_id: str, choice: str,
+) -> dict[str, Any]:
+    with transaction(store) as txn:
+        failure = next((row for row in txn.rows if row["recordId"] == failure_id), None)
+        if failure is None or failure["kind"] != "failure":
+            raise DiscussionWorkflowError(f"no failure {failure_id} in this discussion")
+        allowed = _QUESTION_CHOICES if failure.get("questionId") else CHOICES
+        if choice not in allowed:
+            raise DiscussionWorkflowError(
+                f"{failure_id} accepts {', '.join(allowed)}; a direct question goes to a "
+                "participant of a replacement run with `okstra discussion address`"
+            )
+        if choice == "retry" and failure["sourceRun"] != run.source.manifest:
+            raise DiscussionWorkflowError(
+                f"{failure_id} failed in {failure['sourceRun']}; a retry stays in that run's attempt record"
+            )
+        record, created = txn.append(
+            "recovery",
+            {"failureId": failure_id, "choice": choice, "worker": failure["author"],
+             "cycleId": failure["cycleId"], "questionId": failure.get("questionId", "")},
+            author=USER,
+            source_run=run.source,
+        )
+        draft = txn.draft()
+    return {"record": record, "created": created, "next": _recovery_next(store, draft, failure, choice),
+            "phase": draft["phase"]}
+
+
+def _recovery_next(
+    store: DiscussionStore, draft: Mapping[str, Any], failure: Mapping[str, Any], choice: str,
+) -> str:
+    worker = failure["author"]
+    if failure.get("questionId"):
+        if choice == "retry":
+            return (
+                f"run `okstra discussion question-prompt --question {failure['questionId']}` again: it "
+                "names a new invocation for the retry; dispatch it and run `collect-answer`"
+            )
+        return f"{failure['questionId']} stays unanswered by {worker}; continue without it"
+    if choice == "retry":
+        cycle = next(c for c in draft["cycles"] if c["recordId"] == failure["cycleId"])
+        return (
+            f"materialize a new invocation id for {worker} with --assignment-ref initial/{worker}, "
+            f"--dispatch-kind {RESEARCH_DISPATCH_KIND} and --instruction {cycle['instructionPath']}, "
+            "dispatch it, then run `okstra discussion settle`"
+        )
+    if choice == "replace":
+        return (
+            "prepare a continuation run with `--discussion-start "
+            f"{store.task_key}` and the replacement roster; the completed results stay recorded "
+            "with their authors and reach the new run's research input"
+        )
+    return (
+        f"continue {failure['cycleId']} with the remaining participants; the research of {worker} "
+        "stays unverified and the reduced roster is recorded"
+    )
+
+
+def _final_state(store: DiscussionStore, run: DiscussionRun) -> tuple[Path, Mapping[str, Any]]:
+    state_path = run.project_path(str(run.manifest["convergenceStatePath"]))
+    try:
+        state = load_owned_object(state_path, artifact="convergence final state")
+    except JsonBoundaryError as exc:
+        raise DiscussionWorkflowError(
+            f"{exc}; finish the verification cycle with `okstra convergence finalize` first"
+        ) from exc
+    errors = validate_final_state(state)
+    if errors:
+        raise DiscussionWorkflowError("the convergence final state is invalid: " + "; ".join(errors))
+    if not same_task(str(state.get("taskKey", "")), store.task_key):
+        raise DiscussionWorkflowError(
+            f"{run.relative(state_path)} belongs to {state.get('taskKey')!r}, not {store.task_key}"
+        )
+    return state_path, state
+
+
+def close_cycle(store: DiscussionStore, run: DiscussionRun) -> dict[str, Any]:
+    with transaction(store) as txn:
+        cycle = _cycle_of_run(txn.draft(), run)
+        if cycle is None or cycle["status"] == "superseded":
+            raise DiscussionWorkflowError(
+                "this run has no research cycle to close; a replaced cycle continues in a new run"
+            )
+        open_failures = [f["recordId"] for f in cycle["failures"] if f["recovery"] is None]
+        if open_failures:
+            raise DiscussionWorkflowError(
+                f"{', '.join(open_failures)} wait for the user's choice "
+                "(`okstra discussion recover`); the cycle closes after it"
+            )
+        state_path, state = _final_state(store, run)
+        claims = []
+        for finding in state["findings"]:
+            record, _ = txn.append("claim", _claim_fields(cycle["recordId"], finding),
+                                   author=str(finding["originWorker"]), source_run=run.source)
+            claims.append(record["recordId"])
+        close, created = txn.append(
+            "close",
+            {
+                "cycleId": cycle["recordId"],
+                "convergenceState": run.relative(state_path),
+                "stateDigest": _digest(state_path.read_bytes()),
+                "finalState": state["finalState"],
+                "stopReason": state["round2SkippedReason"],
+            },
+            author=LEADER,
+            source_run=run.source,
+        )
+        draft = txn.draft()
+    return {
+        "cycle": cycle["recordId"],
+        "close": close,
+        "created": created,
+        "claims": claims,
+        "remainingDisagreements": _claims(draft, draft["remainingDisagreements"]),
+        "phase": draft["phase"],
+    }
+
+
+def _claim_fields(cycle_id: str, finding: Mapping[str, Any]) -> dict[str, Any]:
+    return {
+        "cycleId": cycle_id,
+        "findingId": finding["findingId"],
+        "summary": finding["summary"],
+        "category": finding["category"],
+        "discoveredBy": sorted(finding["discoveredBy"]),
+        "evidence": finding["originEvidence"],
+        "classification": finding["classification"],
+        "verdicts": [
+            {"round": row["round"], "worker": worker, "verdict": vote["verdict"],
+             "disagreeBasis": vote.get("disagreeBasis"), "explanation": vote["explanation"]}
+            for row in finding["rounds"]
+            for worker, vote in row["votes"].items()
+        ],
+    }
+
+
+def _question(draft: Mapping[str, Any], question_id: str) -> dict[str, Any]:
+    question = next((q for q in draft["questions"] if q["recordId"] == question_id), None)
+    if question is None:
+        raise DiscussionWorkflowError(f"no question {question_id} in this discussion")
+    if question["to"] == USER:
+        raise DiscussionWorkflowError(
+            f"{question_id} is for the user; put it to the user and record the answer with `answer`"
+        )
+    return question
+
+
+def _question_names(run: DiscussionRun, draft: Mapping[str, Any], question: Mapping[str, Any]) -> dict[str, Any]:
+    retries = sum(1 for row in draft["failures"] if row.get("questionId") == question["recordId"])
+    slug = question["recordId"].lower() + (f"-r{retries}" if retries else "")
+    worker = question["to"]
+    prompts = run.run_dir / "prompts"
+    return {
+        "invocationId": f"discussion-question-{slug}-{worker}-{run.seq}",
+        "invocationPrefix": f"discussion-question-{question['recordId'].lower()}-",
+        "instruction": prompts / f"discussion-question-{slug}-discussion-{run.seq}.md",
+        "prompt": prompts / f"{worker}-worker-prompt-discussion-question-{slug}-discussion-{run.seq}.md",
+        "result": run.run_dir / "worker-results" / f"{worker}-worker-discussion-question-{slug}-discussion-{run.seq}.md",
+        "batch": run.run_dir / "state" / f"discussion-question-{slug}-batch-discussion-{run.seq}.json",
+    }
+
+
+def _question_instruction(question: Mapping[str, Any], draft: Mapping[str, Any]) -> str:
+    return (
+        f"# Discussion question {question['recordId']} — to {question['to']}\n\n"
+        f"{question['author']} asked you this question directly:\n\n{question['text']}\n\n"
+        "Answer it in your result file. Base the answer on the discussion record below and on "
+        "the evidence you inspect; give each factual claim its evidence location and say what you "
+        "could not establish. Your whole result file is recorded as your answer and every "
+        "participant reads it in their next input.\n\n"
+        + render_draft_text(draft)
+    )
+
+
+def question_dispatch(store: DiscussionStore, run: DiscussionRun, question_id: str) -> dict[str, Any]:
+    draft = read_draft(store)
+    question = _question(draft, question_id)
+    if question["answers"] or question["dropped"]:
+        raise DiscussionWorkflowError(f"{question_id} is already settled; ask a follow-up question instead")
+    waiting = [
+        row["recordId"] for row in draft["failures"]
+        if row.get("questionId") == question_id and row["recovery"] is None
+    ]
+    if waiting:
+        raise DiscussionWorkflowError(
+            f"{', '.join(waiting)} waits for the user's choice (`okstra discussion recover`) "
+            "before the question is dispatched again"
+        )
+    worker = question["to"]
+    if worker not in {row["worker"] for row in run.analysers}:
+        raise DiscussionWorkflowError(
+            f"{worker} is not an analyser of {run.source.manifest}; address a participant of this run"
+        )
+    names = _question_names(run, draft, question)
+    if not names["instruction"].is_file():
+        names["instruction"].parent.mkdir(parents=True, exist_ok=True)
+        names["instruction"].write_text(_question_instruction(question, draft), encoding="utf-8")
+    entry = {
+        "invocation-id": names["invocationId"],
+        "worker-id": worker,
+        "audience": _DUTY,
+        "dispatch-kind": DISCUSSION_QUESTION_DISPATCH_KIND,
+        "assignment-ref": f"initial/{worker}",
+        "instruction": run.relative(names["instruction"]),
+        "prompt": run.relative(names["prompt"]),
+        "result": run.relative(names["result"]),
+    }
+    write_owned_object_atomic(names["batch"], {"invocations": [entry]}, artifact="agent prompt batch")
+    return {
+        "question": question_id,
+        "worker": worker,
+        "invocationId": names["invocationId"],
+        "dispatchKind": DISCUSSION_QUESTION_DISPATCH_KIND,
+        "instructionPath": entry["instruction"],
+        "resultPath": entry["result"],
+        "batchPath": run.relative(names["batch"]),
+    }
+
+
+def collect_answer(store: DiscussionStore, run: DiscussionRun, question_id: str) -> dict[str, Any]:
+    draft = read_draft(store)
+    question = _question(draft, question_id)
+    names = _question_names(run, draft, question)
+    outcomes = [
+        outcome for outcome in _outcomes(run, _team_state(run), question["to"], DISCUSSION_QUESTION_DISPATCH_KIND)
+        if outcome["invocationId"].startswith(names["invocationPrefix"])
+    ]
+    if not outcomes:
+        raise DiscussionWorkflowError(
+            f"no dispatch of {question_id} in {run.source.manifest}; dispatch the batch "
+            "`okstra discussion question-prompt` wrote first"
+        )
+    kind, fields = _settled_fields(outcomes[-1])
+    if kind == "result":
+        result_path = run.project_path(fields["resultPath"])
+        fields = {"questionId": question_id, "text": result_path.read_text(encoding="utf-8"),
+                  "resultPath": fields["resultPath"]}
+        kind = "answer"
+    else:
+        fields = {"cycleId": "", "questionId": question_id, **fields}
+    with transaction(store) as txn:
+        record, created = txn.append(kind, fields, author=question["to"], source_run=run.source)
+        after = txn.draft()
+    return {"record": record, "created": created, "phase": after["phase"],
+            "pendingForParticipants": after["pendingForParticipants"]}
+
+
+def status(draft: Mapping[str, Any]) -> dict[str, Any]:
+    by_id = {q["recordId"]: q for q in draft["questions"]}
+    next_question = by_id.get(draft["nextForUser"]) if draft["nextForUser"] else None
+    return {
+        "phase": draft["phase"],
+        "draftVersion": draft["recordsDigest"],
+        "completedRevision": draft["completedRevision"],
+        "revisions": [{key: row[key] for key in ("revisionId", "contentDigest")} for row in draft["revisions"]],
+        "basedOn": (
+            {"revisionId": draft["basedOn"]["revisionId"], "reason": draft["basedOn"]["reason"]}
+            if draft["basedOn"] else None
+        ),
+        "nextForUser": (
+            {key: next_question[key] for key in ("recordId", "author", "text")} if next_question else None
+        ),
+        "pendingForUser": draft["pendingForUser"],
+        "pendingForParticipants": draft["pendingForParticipants"],
+        "unrecoveredFailures": [
+            _failure_view(row) for row in draft["failures"] if row["recordId"] in draft["unrecoveredFailures"]
+        ],
+        "remainingDisagreements": _claims(draft, draft["remainingDisagreements"]),
+        "cycles": [
+            {"recordId": c["recordId"], "status": c["status"], "run": c["sourceRun"],
+             "participants": c["roster"]}
+            for c in draft["cycles"]
+        ],
+    }