okstra 0.186.7 → 0.187.0

package/runtime/python/okstra_ctl/clarification_items/scan.py

@@ -0,0 +1,215 @@
+"""게이트를 읽는다 — 아직 열려 있는 것이 무엇인가.
+
+`scan_approval_gate` 와 `scan_open_user_input` 을 run-prep · 위저드 ·
+user-response CLI 가 공유하므로 세 곳이 서로 다른 답을 낼 수 없다.
+판정은 fail-closed 다: 확신을 갖고 읽지 못하면 `unreadable_reason` 을 남기고
+호출자는 soft-pass 대신 승인을 거절해야 한다.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+from .parsing import (
+    ClarificationItem,
+    _LOOSE_SECTION_1_RE,
+    _section_1_slice,
+    _walk_section_1_table,
+)
+from .dispositions import (
+    APPROVAL_BLOCKS,
+    PROCEEDING_DISPOSITIONS,
+    USER_INPUT_BLOCKS,
+    incorporated_clarification_ids,
+    row_blocks_progress,
+)
+from .rows import (
+    _read_report_text,
+    _structured_report_data,
+    _v2_row,
+)
+from .sidecars import (
+    sidecar_dispositions,
+)
+
+
+@dataclass(frozen=True)
+class ClarificationScan:
+    """Fail-closed read of the clarification rows blocking on one `Blocks`
+    value set.
+
+    ``unreadable_reason`` is ``None`` only when the scan is confident: the
+    rows parsed cleanly (or the report is the legitimate table-less
+    placeholder) and ``blockers`` is therefore authoritative. A non-None
+    reason means the caller must refuse to act — never soft-pass.
+    """
+    blockers: list[ClarificationItem]
+    unreadable_reason: Optional[str]
+
+
+def scan_approval_gate(report_path: Path) -> ClarificationScan:
+    """Scan for ``Blocks=approval`` rows that still block progress.
+
+    A recorded user proceeding disposition (`accept-risk` / `select` /
+    `answer`), including one that lives only in the sidecar, does not block.
+    ``request-revision`` / ``reject`` still block unless this report's
+    ``supersessionLedger`` already incorporated that id. The scan refuses to
+    guess whenever the schema drifted.
+    """
+    return scan_clarification_blockers(
+        report_path,
+        APPROVAL_BLOCKS,
+        honor_sidecar_answers=True,
+        sidecar_unblocks_proceeding_only=True,
+    )
+
+
+def scan_open_user_input(report_path: Path) -> ClarificationScan:
+    """Scan for every unresolved row that still owes the user an answer
+    (``Blocks`` in ``{approval, next-phase}``)."""
+    return scan_clarification_blockers(
+        report_path, USER_INPUT_BLOCKS, honor_sidecar_answers=True
+    )
+
+
+def scan_clarification_blockers(
+    report_path: Path,
+    blocking_values: frozenset[str],
+    *,
+    honor_sidecar_answers: bool,
+    sidecar_unblocks_proceeding_only: bool = False,
+) -> ClarificationScan:
+    """Shared fail-closed clarification walk for both gates above — schema-v2
+    reads its rows from the data sibling and schema-v1 from the §1 table.
+    ``honor_sidecar_answers`` hides rows the sidecar already answered.
+    ``sidecar_unblocks_proceeding_only`` keeps an unincorporated
+    ``request-revision`` / ``reject`` as a blocker so a return choice cannot
+    start the next phase. A ledger entry for that id means this report already
+    absorbed the return.
+    """
+    v2_scan = _scan_v2_blockers(report_path, blocking_values)
+    scan = (
+        v2_scan if v2_scan is not None
+        else scan_section_1_blockers(_read_report_text(report_path), blocking_values)
+    )
+    return (
+        _resolve_blockers_answered_by_user(
+            report_path,
+            scan,
+            proceeding_only=sidecar_unblocks_proceeding_only,
+        )
+        if honor_sidecar_answers
+        else scan
+    )
+
+
+def _resolve_blockers_answered_by_user(
+    report_path: Path,
+    scan: ClarificationScan,
+    *,
+    proceeding_only: bool = False,
+) -> ClarificationScan:
+    """사용자가 사이드카로 답한 행을 blocker 에서 뺀 스캔.
+
+    답의 정본은 사용자의 `user-responses/` 사이드카다. 리포트의 `Status` 는 그
+    run 이 스스로 적어둔 값이고, 답이 사이드카로만 들어오는 경로(HTML 뷰의
+    `Export user response`, `okstra user-response write`)에서는 갱신되지 않는다.
+    사용자 입력 목록은 사이드카 답변이 있는 항목을 다시 묻지 않는다. 승인
+    게이트는 진행 처분만 차단에서 뺀다.
+
+    fail-closed 는 그대로다: 행 자체를 못 읽은 스캔(`unreadable_reason`)은
+    어떤 id 가 blocker 인지 모르는 상태이므로 사이드카로 덮지 않는다.
+    """
+    if scan.unreadable_reason is not None or not scan.blockers:
+        return scan
+    dispositions = sidecar_dispositions(report_path)
+    if not dispositions:
+        return scan
+    answered_ids = {
+        row_id
+        for row_id, disposition in dispositions.items()
+        if (not proceeding_only) or disposition in PROCEEDING_DISPOSITIONS
+    }
+    if not answered_ids:
+        return scan
+    return ClarificationScan(
+        [b for b in scan.blockers if b.row_id not in answered_ids], None
+    )
+
+
+def scan_section_1_blockers(
+    report_text: str, blocking_values: frozenset[str]
+) -> ClarificationScan:
+    """Fail-closed §1 walk over any markdown carrying the table — a schema-v1
+    report, or the carry-in body a reconciliation just produced."""
+    section = _section_1_slice(report_text)
+    if section is None:
+        if _LOOSE_SECTION_1_RE.search(report_text):
+            reason = (
+                "`## 1. Clarification Items` heading exists but does not match "
+                "the schema heading format (anchor/format drift)"
+            )
+        else:
+            expected = "/".join(sorted(blocking_values))
+            reason = (
+                "report has no `## 1. Clarification Items` section — the gate "
+                f"cannot confirm there are no unresolved `Blocks={expected}` rows"
+            )
+        return ClarificationScan([], reason)
+    table = _walk_section_1_table(section)
+    if table.items is None:
+        if table.has_pipe_lines:
+            return ClarificationScan([], (
+                "§1 contains a table but its header row is not the schema "
+                "header (`| ... | Statement | Expected form | User input |`)"
+            ))
+        # Renderer's emptyState placeholder: heading is intact and no table
+        # was emitted — confidently "no blocking items".
+        return ClarificationScan([], None)
+    if table.unparsed_row_count:
+        return ClarificationScan([], (
+            f"§1 table has {table.unparsed_row_count} row(s) whose metadata "
+            "cell could not be parsed (Blocks/Status markers missing or "
+            "malformed)"
+        ))
+    blockers = [
+        it for it in table.items
+        if it.blocks in blocking_values and row_blocks_progress(it.status)
+    ]
+    return ClarificationScan(blockers, None)
+
+
+def _scan_v2_blockers(
+    report_path: Path, blocking_values: frozenset[str]
+) -> Optional[ClarificationScan]:
+    """schema-v2 data.json 기준 스캔, 이 리포트가 v2 가 아니면 ``None``.
+    필수 필드가 빠진 행은 §1 의 unparsed row 와 같이 fail-closed 로 다룬다."""
+    data = _structured_report_data(report_path)
+    if data is None:
+        return None
+    entries = data.get("clarificationItems")
+    if entries is None:
+        return ClarificationScan([], None)
+    if not isinstance(entries, list):
+        return ClarificationScan([], (
+            "schema-v2 data.json `clarificationItems` is not an array — the "
+            "gate cannot read the clarification rows"
+        ))
+    rows = [_v2_row(e) if isinstance(e, dict) else None for e in entries]
+    unparsed = sum(1 for row in rows if row is None)
+    if unparsed:
+        return ClarificationScan([], (
+            f"schema-v2 data.json has {unparsed} `clarificationItems` row(s) "
+            "missing id/blocks/status"
+        ))
+    incorporated = incorporated_clarification_ids(data)
+    blockers = [
+        row["item"] for row in rows
+        if row["item"].blocks in blocking_values
+        and row_blocks_progress(
+            row["item"].status,
+            str(row.get("disposition") or ""),
+            incorporated=row["item"].row_id in incorporated,
+        )
+    ]
+    return ClarificationScan(blockers, None)

package/runtime/python/okstra_ctl/clarification_items/sidecars.py

@@ -0,0 +1,211 @@
+"""사용자 응답 사이드카를 찾아 읽고 리포트에 붙일 형태로 만든다.
+
+사이드카는 사용자가 답한 내용을 담은 별도 파일이다. 어떤 것을 리포트에
+첨부할지, 어떤 답이 어떤 id 에 붙는지를 여기서 정한다.
+"""
+from __future__ import annotations
+
+from ..user_response_values import (
+    UserResponseError,
+    parse_analysis_review,
+    parse_user_response_entries,
+)
+from pathlib import Path
+import re
+
+
+ANSWER_DISPOSITIONS = frozenset({
+    "answer",
+    "select",
+    "accept-risk",
+    "request-revision",
+    "reject",
+})
+
+
+def user_response_sidecars(source: Path) -> list[Path]:
+    """``source`` 형제 ``user-responses/`` 의 ``user-response-*.md`` 목록(이름 순).
+
+    ``source`` 가 ``runs/<task-type>/reports/final-report-*.md`` 레이아웃일 때만
+    형제 ``user-responses/`` 디렉토리를 찾는다(HTML 뷰의 `Export user response`
+    가 내려준 파일을 사용자가 거기 저장). 그 외 경로·디렉토리 부재 시 빈 목록.
+    carry-in 첨부 본문(``clarification_response_with_sidecars``)과 위저드 안내
+    문구의 사이드카 카운트가 같은 한 곳을 보도록 하는 단일 참조점이다.
+    """
+    responses_dir = source.parent.parent / "user-responses"
+    if source.parent.name != "reports" or not responses_dir.is_dir():
+        return []
+    return sorted(
+        p for p in responses_dir.glob("user-response-*.md") if p.is_file()
+    )
+
+
+_ANALYSIS_REPORT_NAME_RE = re.compile(
+    r"^final-report-(?P<task_type>project-analysis|feature-analysis|"
+    r"change-impact-analysis)-(?P<seq>\d{3})\.md$"
+)
+
+
+_SIDECAR_FRONTMATTER_RE = re.compile(
+    r"\A---[ \t]*\r?\n(?P<body>.*?)(?:\r?\n)---[ \t]*(?:\r?\n|\Z)",
+    re.DOTALL,
+)
+
+
+_ANALYSIS_REVIEW_HEADING_RE = re.compile(
+    r"^## ANALYSIS REVIEW\s*$", re.MULTILINE
+)
+
+
+def _sidecar_frontmatter_value(text: str, key: str) -> str:
+    match = _SIDECAR_FRONTMATTER_RE.match(text)
+    if match is None:
+        return ""
+    value = re.search(
+        rf"^{re.escape(key)}:\s*(\S.*?)\s*$",
+        match.group("body"),
+        re.MULTILINE,
+    )
+    return value.group(1) if value else ""
+
+
+def _sidecars_for_attachment(source: Path) -> list[Path]:
+    sidecars = user_response_sidecars(source)
+    report_match = _ANALYSIS_REPORT_NAME_RE.fullmatch(source.name)
+    if report_match is None:
+        return sidecars
+    expected_source = (
+        f"runs/{report_match.group('task_type')}/reports/{source.name}"
+    )
+    ordinary: list[Path] = []
+    candidates: list[tuple[Path, str]] = []
+    for sidecar in sidecars:
+        try:
+            text = sidecar.read_text(encoding="utf-8")
+        except OSError:
+            ordinary.append(sidecar)
+            continue
+        if _ANALYSIS_REVIEW_HEADING_RE.search(text) is None:
+            ordinary.append(sidecar)
+            continue
+        source_report = _sidecar_frontmatter_value(text, "source-report")
+        seq = _sidecar_frontmatter_value(text, "seq")
+        if source_report and source_report != expected_source:
+            continue
+        if seq and seq != report_match.group("seq"):
+            continue
+        candidates.append((sidecar, text))
+
+    valid: list[Path] = []
+    malformed: list[Path] = []
+    for sidecar, text in candidates:
+        try:
+            review = parse_analysis_review(text)
+        except UserResponseError:
+            malformed.append(sidecar)
+            continue
+        if review is not None and (
+            review.source_report == expected_source
+            and review.seq == report_match.group("seq")
+        ):
+            valid.append(sidecar)
+        else:
+            malformed.append(sidecar)
+    selected = valid if valid else malformed
+    return sorted([*ordinary, *selected])
+
+
+def _sidecar_answer_records(source: Path) -> dict[str, tuple[str, str]]:
+    """사이드카 답을 `{id: (value, disposition)}` 로 모은다.
+
+    `disposition` 이 `ANSWER_DISPOSITIONS` 에 속하는 항목만 답으로 센다.
+    `reframe` 은 답이 아니므로 집합에서 빠진다. 같은 id 는 이름순 마지막이
+    이긴다 — 최신이 reframe 이거나 값이 비면 앞선 답을 지운다.
+    """
+    answers: dict[str, tuple[str, str]] = {}
+    for sidecar in user_response_sidecars(source):
+        for entry in parse_user_response_entries(
+            sidecar.read_text(encoding="utf-8")
+        ):
+            if entry.value and entry.disposition in ANSWER_DISPOSITIONS:
+                answers[entry.response_id] = (entry.value, entry.disposition)
+            else:
+                answers.pop(entry.response_id, None)
+    return answers
+
+
+def sidecar_answers(source: Path) -> dict[str, str]:
+    """`user-responses/` 사이드카들의 답변을 `{clarification-id: value}` 로 모은다.
+
+    사용자가 답한 항목이 무엇인지 아는 단일 참조점 — carry-in 병합도, 승인
+    게이트도, 스킬의 열린 항목 목록도 전부 이 한 곳을 본다.
+    """
+    return {
+        row_id: value
+        for row_id, (value, _disposition) in _sidecar_answer_records(source).items()
+    }
+
+
+def sidecar_dispositions(source: Path) -> dict[str, str]:
+    """사이드카 답의 처분을 `{clarification-id: disposition}` 로 모은다."""
+    return {
+        row_id: disposition
+        for row_id, (_value, disposition) in _sidecar_answer_records(source).items()
+    }
+
+
+_ATTACHED_SECTION_RE = re.compile(
+    r"^## (?P<name>user-response-[^\n]*?\.md)\s*$", re.MULTILINE
+)
+
+
+def attached_response_sections(text: str) -> list[tuple[str, str]]:
+    """`# Attached User Responses` 본문을 `(사이드카 이름, 사이드바 본문)` 으로 되돌린다.
+
+    `attached_user_responses_section` 의 역방향이다. 묶음 파일은 태스크 수준으로
+    누적되므로 답이 어느 run 에서 나왔는지는 각 구간의 frontmatter 만 안다 —
+    구간을 나누지 않으면 그 출처가 사라진다. 구간 이름을 못 찾으면 빈 목록:
+    묶음이 아닌 파일을 통째로 한 구간처럼 다루면 출처를 지어내게 된다.
+    """
+    matches = list(_ATTACHED_SECTION_RE.finditer(text))
+    sections: list[tuple[str, str]] = []
+    for index, match in enumerate(matches):
+        end = matches[index + 1].start() if index + 1 < len(matches) else len(text)
+        sections.append((match.group("name"), text[match.end():end].strip()))
+    return sections
+
+
+def response_source_report(section_body: str) -> str:
+    """구간이 답한 대상 리포트의 데이터 기록 파일 이름.
+
+    `source-data` 가 있으면 그것이 정본이다. 초기 사이드카는 `source-report`
+    (읽기용 Markdown) 만 실었으므로 그 짝 이름으로 되돌린다.
+    """
+    data = _sidecar_frontmatter_value(section_body, "source-data")
+    if data:
+        return data
+    report = _sidecar_frontmatter_value(section_body, "source-report")
+    if report.endswith(".md"):
+        return f"{report[:-len('.md')]}.data.json"
+    return ""
+
+
+def attached_user_responses_section(source: Path) -> str:
+    """`source` 형제 `user-responses/` 사이드카만 모은 `# Attached User Responses`
+    섹션 본문. 사이드카 부재 시 빈 문자열.
+
+    plan 본문이 이미 별도 경로(`--approved-plan`)로 참조되는 implementation
+    carry-in 에서, 원문을 중복 복사하지 않고 사용자 답변만 instruction-set 에
+    첨부할 때 쓴다. `clarification_response_with_sidecars` 와 같은 직렬화 포맷을
+    한 곳에서 만들어 두 carry-in 경로가 갈라지지 않게 한다.
+    """
+    sidecars = _sidecars_for_attachment(source)
+    if not sidecars:
+        return ""
+    parts = ["# Attached User Responses\n"]
+    for sidecar in sidecars:
+        parts.append(
+            f"\n## {sidecar.name}\n\n"
+            f"{sidecar.read_text(encoding='utf-8').strip()}\n"
+        )
+    return "".join(parts)

package/runtime/python/okstra_ctl/cmux.py

@@ -1,8 +1,7 @@
 """cmux command helpers for okstra-owned worker surfaces.
 
-The tmux sibling of this module is `tmux.py`. cmux is a GUI app, so there is no
-detached-server equivalent here — every surface okstra creates lands in the
-workspace the user is already looking at.
+cmux is a GUI app, so there is no detached-server mode here — every surface
+okstra creates lands in the workspace the user is already looking at.
 """
 from __future__ import annotations
 
@@ -109,7 +108,7 @@ def cmux_available() -> bool:
     Being able to drive cmux is not sufficient. Workers attach to the lead's
     workspace, so a run whose lead location is unresolvable would open panes on
     a screen nobody is watching; degrading to the blocking wrapper is the better
-    failure. Nested tmux is exactly that case — see `resolve_lead_workspace`.
+    failure. See `resolve_lead_workspace` for when that happens.
     """
     if not cmux_cli_path():
         return False
@@ -128,9 +127,9 @@ def resolve_lead_workspace() -> str:
 
     The UUID is read from the environment rather than from `identify`, whose
     refs are positional and shift as surfaces open and close. `identify` is
-    consulted only to prove the environment is current: a tmux server freezes
-    the CMUX_* block it was launched with, so those variables can outlive the
-    surface they name.
+    consulted only to prove the environment is current: a process that inherits
+    a CMUX_* block keeps it verbatim, so those variables can outlive the surface
+    they name.
     """
     workspace = _lead_workspace_env()
     if not workspace:
@@ -391,8 +390,7 @@ def worker_command_line(
     remainder to the shell as a command name.
 
     The `cd` is part of the command because neither `new-split` nor
-    `respawn-pane` accepts a working directory the way `tmux split-window -c`
-    does.
+    `respawn-pane` takes a working-directory flag.
 
     `exec` is here for termination, not for the pane's life, and removing it
     does not keep a finished worker's pane on screen. Measured 2026-08-21: a
@@ -485,28 +483,6 @@ def restore_lead_width() -> None:
     _size_lead_pane(workspace, ())
 
 
-def capture_surface(surface_uuid: str, *, last_lines: int = 200) -> str:
-    """What the worker's screen shows — for the lead to look at, never to parse.
-
-    cmux hands back a rendered grid: wrapped to the pane's width with a finite
-    history, so a path or a count read off it can be silently truncated.
-    """
-    try:
-        result = run_cmux(
-            [
-                "capture-pane",
-                "--surface",
-                surface_uuid,
-                "--scrollback",
-                "--lines",
-                str(last_lines),
-            ]
-        )
-    except (OSError, subprocess.SubprocessError):
-        return ""
-    return result.stdout if result.returncode == 0 else ""
-
-
 def socket_reachability() -> str:
     """Why this process can or cannot reach cmux, decided at syscall level.
 
@@ -551,6 +527,37 @@ def unreachable_reason() -> str:
     return LOST_NOTHING if resolve_lead_workspace() else LOST_GONE
 
 
+def unreachable_advice(reason: str) -> tuple[str, str]:
+    """(관측, 처방) — 사유별로 처방이 갈린다.
+
+    소켓 거부는 샌드박스가 AF_UNIX connect 를 막은 것이라 소켓 한 줄만 열면
+    풀리고 파일시스템 경계는 그대로 둬도 된다. 환경 소실은 CMUX_* 변수 자체가
+    없는 것이라 그 한 줄로는 못 고치고 리드를 다시 띄워야 한다.
+
+    두 소비자가 같은 문구를 써야 한다: 워커를 띄우다 막힌 dispatch
+    (`adapters/runtime/cmux.py`) 와, 같은 사유로 표면이 바뀌려는 것을 막는
+    prepare (`run.py`). 문구가 한쪽에만 있으면 다른 쪽이 낡은 처방을 안내한다.
+    """
+    if reason == LOST_ENVIRONMENT:
+        return (
+            "this process has no cmux environment left — a sandbox sanitized it",
+            "Relaunch the lead from a cmux surface so its CMUX_* variables "
+            "reach this process.",
+        )
+    if reason == LOST_DENIED:
+        return (
+            "cmux is running but this process may not connect to its socket",
+            "Let the lead's sandbox reach that socket. Under codex that is one "
+            "key — set `sandbox_workspace_write.network_access = true` in "
+            "~/.codex/config.toml, or pass `-c "
+            "sandbox_workspace_write.network_access=true` when the lead "
+            "launches. The filesystem boundary can stay as it is. A lead "
+            "already running keeps the sandbox it started with, so relaunch "
+            "it after the change.",
+        )
+    return ("cmux is no longer reachable from this process", "")
+
+
 def sidebar_log(workspace: str, message: str, *, level: str = "info") -> None:
     """Append one line to the workspace sidebar's log."""
     _sidebar_call(