okstra 0.173.0 → 0.174.0

package/runtime/python/okstra_ctl/final_report_schema.py

@@ -1,7 +1,7 @@
 """Mini JSON Schema validator for the final-report data.json.
 
 This is a deliberately narrow JSON Schema implementation that supports
-exactly the keywords used by ``schemas/final-report-v1.0.schema.json``:
+exactly the keywords used by ``schemas/final-report-v2.0.schema.json``:
 
   type, required, properties, additionalProperties, enum, const, pattern,
   minLength, minItems, maxItems, uniqueItems, items, minimum, maximum, $ref ($defs),
@@ -23,6 +23,8 @@ import re
 from pathlib import Path
 from typing import Any
 
+from okstra_ctl.report_contract import CURRENT_REPORT_SCHEMA_VERSION
+
 
 class SchemaError(ValueError):
     """Raised when a schema itself is malformed (e.g. a $ref points
@@ -260,7 +262,6 @@ def validate(data: Any, schema: dict) -> list[str]:
 
 
 SCHEMA_FILENAMES = {
-    "1.0": "final-report-v1.0.schema.json",
     "2.0": "final-report-v2.0.schema.json",
 }
 
@@ -295,9 +296,9 @@ def load_schema_for_data(data: dict, start: Path | None = None) -> dict:
 
 def load_schema(schema_path: Path | None = None) -> dict:
     """Load the final-report schema. If ``schema_path`` is None, locate
-    ``schemas/final-report-v1.0.schema.json`` relative to this file's
+    ``schemas/final-report-v2.0.schema.json`` relative to this file's
     repo root.
     """
     if schema_path is not None:
         return json.loads(Path(schema_path).read_text(encoding="utf-8"))
-    return load_schema_version("1.0")
+    return load_schema_version(CURRENT_REPORT_SCHEMA_VERSION)

package/runtime/python/okstra_ctl/pane_reclaim.py

@@ -1,5 +1,13 @@
-"""완료(terminal) worker 판정 — pane 회수용. 판정 SSOT 는
-wrapper_status.read_wrapper_status 이며 여기서 재사용한다."""
+"""활성 run 스코프 조회 — pane 정리 의무를 어느 run 에 걸지 고르는 데 쓴다.
+
+호출자는 `SessionStart(compact)` 훅(`okstra-compact-reminder.sh`) 하나다. 압축
+직후 리드에게 "이 run 의 완료 teammate pane 을 라운드 경계마다 회수하라"는 의무를
+재주입할 때, 그 대상이 되는 이 프로젝트의 진행 중 run 을 여기서 찾는다.
+
+완료 판정(`is_completed_status`)과 프로젝트 무관 전체 조회(`active_run_dirs`)도
+여기 있었으나, 그것을 쓰던 `okstra-trace-cleanup.sh --reclaim-completed` 와
+`okstra-subagent-reclaim.sh` 가 제거되면서 함께 사라졌다.
+"""
 from __future__ import annotations
 
 import json
@@ -8,12 +16,6 @@ from pathlib import Path
 
 from .paths import resolve_under_root
 from .reconcile import NON_TERMINAL_RECENT_STATUSES
-from .wrapper_status import read_wrapper_status
-
-
-def is_completed_status(status_path: str) -> bool:
-    status = read_wrapper_status(Path(status_path))
-    return status is not None and status.is_terminal
 
 
 def _iter_active_run_dirs(home: Path):
@@ -30,9 +32,9 @@ def _iter_active_run_dirs(home: Path):
             row = json.loads(line)
         except json.JSONDecodeError:
             continue
-        # 회수 대상(진행 중) 집합은 reconcile 의 NON_TERMINAL_RECENT_STATUSES 가
-        # SSOT. reserving 은 아직 run-dir 산출물이 없어(= 회수할 pane 이 없어) 이
-        # 집합에 들어있지 않으므로 자연히 제외된다(allowlist).
+        # 대상(진행 중) 집합은 reconcile 의 NON_TERMINAL_RECENT_STATUSES 가
+        # SSOT. reserving 은 아직 run-dir 산출물이 없어 이 집합에 들어있지
+        # 않으므로 자연히 제외된다(allowlist).
         if row.get("status") not in NON_TERMINAL_RECENT_STATUSES:
             continue
         run_dir = resolve_under_root(row.get("projectRoot"), row.get("runDirRel"))
@@ -40,11 +42,6 @@ def _iter_active_run_dirs(home: Path):
             yield row.get("projectRoot"), run_dir
 
 
-def active_run_dirs(home: Path) -> list[Path]:
-    """active.jsonl 의 진행 중 run 들의 절대 run-dir 목록."""
-    return [run_dir for _project_root, run_dir in _iter_active_run_dirs(home)]
-
-
 def active_run_dirs_for_project(home: Path, cwd: Path) -> list[Path]:
     """진행 중 run 중 projectRoot 이 cwd(또는 그 상위)인 것의 절대 run-dir 목록.
     SessionStart(compact) 훅이 이 프로젝트의 run 에만 리마인더를 걸도록 스코프한다."""
@@ -63,16 +60,10 @@ def active_run_dirs_for_project(home: Path, cwd: Path) -> list[Path]:
 
 
 def main(argv: list[str]) -> int:
-    if len(argv) == 2 and argv[0] == "--active-dirs":
-        for run_dir in active_run_dirs(Path(argv[1])):
-            print(run_dir)
-        return 0
     if len(argv) == 3 and argv[0] == "--active-dirs-for":
         for run_dir in active_run_dirs_for_project(Path(argv[1]), Path(argv[2])):
             print(run_dir)
         return 0
-    if len(argv) == 1:
-        return 0 if is_completed_status(argv[0]) else 1
     return 1
 
 

package/runtime/python/okstra_ctl/render_final_report.py

@@ -12,10 +12,10 @@ columns in the Execution Status table, omitted §4 phase-continuation
 rows, ad-hoc ``## Index`` sections. Routing everything through one
 template + schema cuts those failure modes to zero.
 
-For schema-v1 compatibility, the top-of-report ``## Index`` remains a
-deterministic post-render section built by ``_inject_index_and_anchors``.
-Schema v2 keeps its compact fixed AI-handoff order and does not inject the
-legacy reader index; the task-specific HTML provides the human navigation.
+Rendering never injects a reader index: the AI-handoff markdown keeps its
+compact fixed order and the task-specific HTML provides human navigation.
+``_inject_index_and_anchors`` survives as a standalone pass over an already
+written markdown file, driven by ``scripts/okstra-inject-report-index.py``.
 
 Phase 7 mutation flow: ``okstra-token-usage.py --substitute-data`` fills
 the ``tokenUsage`` and ``executionStatus[].totalTokens`` etc. cells in
@@ -53,7 +53,11 @@ from okstra_ctl.i18n import I18nError, SUPPORTED_LANGS, load_dictionary, make_ji
 from okstra_ctl.md_table import UNESCAPED_PIPE_RE, to_cell_text
 from okstra_ctl.models import UnknownModelError, resolve_model_metadata
 from okstra_ctl.paths import find_asset_root
-from okstra_ctl.report_contract import TASK_TYPE_DATA_PROPERTY, markdown_template_for
+from okstra_ctl.report_contract import (
+    CURRENT_REPORT_SCHEMA_VERSION,
+    TASK_TYPE_DATA_PROPERTY,
+    markdown_template_for,
+)
 from okstra_ctl.report_markdown import ReportSections
 from okstra_ctl.schema_excerpt import excerpt_cut_from_version
 from okstra_ctl.seeding import installed_version
@@ -61,10 +65,9 @@ from okstra_ctl.usage_cells import format_duration_ms, format_int, format_usd
 
 
 TEMPLATE_BY_SCHEMA_VERSION = {
-    "1.0": ("templates", "reports", "final-report.template.md"),
     "2.0": ("templates", "reports", "final-report-v2.template.md"),
 }
-DEFAULT_TEMPLATE_REL = TEMPLATE_BY_SCHEMA_VERSION["1.0"]
+DEFAULT_TEMPLATE_REL = TEMPLATE_BY_SCHEMA_VERSION[CURRENT_REPORT_SCHEMA_VERSION]
 
 TASK_DELIVERABLE_TITLES = {
     "requirements-discovery": "Requirements Discovery",
@@ -666,14 +669,7 @@ def render(
 
     try:
         template = env.get_template(template_path.name)
-        context = (
-            _ai_markdown_context(data, schema)
-            if data.get("schemaVersion") == "2.0"
-            else _with_optional_defaults(data)
-        )
-        rendered = template.render(**context)
-        if data.get("schemaVersion") == "1.0":
-            rendered = _inject_index_and_anchors(rendered, dictionary)
+        rendered = template.render(**_ai_markdown_context(data, schema))
         return _ventilate_prose(rendered)
     except I18nError as exc:
         raise FinalReportRenderError(
@@ -689,10 +685,10 @@ def find_default_template(start: Path | None = None) -> Path:
     """Locate the bundled final-report template.
 
     Resolution order:
-      1. ``$OKSTRA_HOME/templates/reports/final-report.template.md`` (installed runtime).
-      2. ``<repo>/templates/reports/final-report.template.md`` (in-repo dev runs).
+      1. ``$OKSTRA_HOME/templates/reports/final-report-v2.template.md`` (installed runtime).
+      2. ``<repo>/templates/reports/final-report-v2.template.md`` (in-repo dev runs).
          Repo root is detected by walking up from this file until a
-         ``templates/reports/final-report.template.md`` exists.
+         ``templates/reports/final-report-v2.template.md`` exists.
 
     Raises ``FinalReportRenderError`` if neither path is present.
     """
@@ -701,7 +697,7 @@ def find_default_template(start: Path | None = None) -> Path:
         return root.joinpath(*DEFAULT_TEMPLATE_REL)
 
     raise FinalReportRenderError(
-        "could not locate final-report.template.md. Set OKSTRA_HOME or "
+        "could not locate final-report-v2.template.md. Set OKSTRA_HOME or "
         "run from a checkout that contains templates/reports/."
     )
 

package/runtime/python/okstra_ctl/report_contract.py

@@ -3,7 +3,6 @@ from __future__ import annotations
 
 
 CURRENT_REPORT_SCHEMA_VERSION = "2.0"
-LEGACY_REPORT_SCHEMA_VERSION = "1.0"
 
 PUBLIC_REPORT_TASK_TYPES = (
     "requirements-discovery",

package/runtime/python/okstra_ctl/report_finalize.py

@@ -6,6 +6,18 @@ substitution, html view rendering, follow-up task spawning, and run validation.
 The order is load-bearing — rendering before substitution ships `--` token
 cells, and validating before rendering trips the report-views contract.
 
+`token-usage` is the one step whose failure does not stop the sequence, which
+deliberately accepts that first state: its input is the lead session log, so a
+refusal there would otherwise delete every artifact the later steps produce.
+The run does not pass in that state. `validators/validate-run.py` re-collects
+when the recorded usage is all zeros against an `unavailable` session source
+(`_needs_token_autofix`) and refuses the run rather than ship zeroed counts
+(`accuracy-failed`); a legacy v1 report is caught earlier still, by its
+unsubstituted `{{...}}` placeholders, which a v2 report never carries because
+its numeric cells are `null` until this step fills them. Substituting the
+tokens on a later retry then leaves the already-rendered html stale for
+`validators/validate-report-views.py`.
+
 The translation sidecar is NOT one of these steps. `render-views` overlays it,
 so a non-English run dispatches the translator before this sequence starts —
 after verifying the data.json is English, which is why `check-source` is also
@@ -29,6 +41,7 @@ from .agent_activity import ActivityProjectionError, project_agent_activity
 from .dispatch_state import DispatchError, link_agent_dispatch_result
 from .final_report_paths import final_report_data_path, final_report_markdown_path
 from .paths import task_dir, task_manifest_file
+from .session import observe_lead_session
 
 
 STEP_PROJECT_ACTIVITY = "project-activity"
@@ -354,7 +367,14 @@ def run_finalize(
     before_step: Callable[[str], None] | None = None,
     only: Sequence[str] | None = None,
 ) -> dict[str, Any]:
-    """Run the Phase 7 steps in order, stopping at the first non-zero exit.
+    """Run the Phase 7 steps in contractual order.
+
+    A non-zero exit stops the sequence, with one exception: ``token-usage``
+    defers. Its input is the lead session log — state outside this run — so a
+    refusal there is not evidence that the artifacts after it are unwritable.
+    The deferred failure becomes the result's ``reason`` when nothing later
+    fails, and yields to any later failure, which is the step that actually
+    blocked the run.
 
     ``before_step`` fires immediately before each step is spawned, letting an
     adapter settle state the step will read (the Codex adapter marks the report
@@ -366,6 +386,7 @@ def run_finalize(
     step at full token and wall-clock cost.
     """
     steps: list[dict[str, Any]] = []
+    deferred = ""
     try:
         commands = build_commands(ctx)
     except FinalizeError as exc:
@@ -426,11 +447,21 @@ def run_finalize(
             )
         steps.append(step_payload(name, command, result))
         if result.returncode != 0:
-            return {
-                "ok": False,
-                "reason": f"{name} failed with exit code {result.returncode}",
-                "steps": steps,
-            }
+            failure = f"{name} failed with exit code {result.returncode}"
+            # Token collection reads the lead session log, which lives outside
+            # this run. One refusal there (`grandTotalTokens=0`) took the whole
+            # run's output with it: html never rendered, follow-ups never
+            # spawned, and `validate-run` then blocked on `report-views:
+            # missing html artifact`. So this step alone defers instead of
+            # stopping the sequence. It hides nothing — the non-zero exit stays
+            # in `steps`, `ok` stays False, and the closing `validate-run`
+            # still refuses the run.
+            if name == STEP_TOKEN_USAGE:
+                deferred = failure
+                continue
+            return {"ok": False, "reason": failure, "steps": steps}
+    if deferred:
+        return {"ok": False, "reason": deferred, "steps": steps}
     return {"ok": True, "reason": "", "steps": steps}
 
 
@@ -546,6 +577,29 @@ def _step_summary_lines(result: Mapping[str, Any]) -> list[str]:
     return lines
 
 
+def _recovery_step_names(result: Mapping[str, Any]) -> list[str]:
+    """The steps a retry has to re-run: every step from the earliest failure on.
+
+    Naming only the failed steps would prescribe half a recovery. `token-usage`
+    defers, so `render-views` already wrote an html view from unsubstituted
+    data; substituting the tokens on a retry leaves that view stale
+    (`validators/validate-report-views.py` checks `source-sha256` against the
+    md body). And a sequence that stopped early never reached `validate-run`,
+    which is the step that decides whether the run is shippable. Resuming from
+    the earliest failure redoes both while still skipping the prefix that
+    succeeded — the saving `--only` exists for.
+    """
+    failed = {
+        string_value(step.get("name"))
+        for step in (result.get("steps") or [])
+        if step.get("exitCode") != 0
+    }
+    for index, name in enumerate(STEP_ORDER):
+        if name in failed:
+            return list(STEP_ORDER[index:])
+    return []
+
+
 def main(argv: Sequence[str] | None = None) -> int:
     args = _parser().parse_args(argv)
     try:
@@ -553,6 +607,10 @@ def main(argv: Sequence[str] | None = None) -> int:
     except FinalizeError as exc:
         print(f"error: {exc}", file=sys.stderr)
         return 2
+    # Phase 7 is the last boundary the lead crosses, and the last chance to add
+    # the generations resume and compaction split it into. It runs ahead of the
+    # sequence because the token-usage step below reads `leadSessionIds`.
+    observe_lead_session(ctx.project_root, ctx.team_state_path)
     result = run_finalize(ctx, only=args.only or None)
     print(json.dumps(result, indent=2, ensure_ascii=False))
     print("finalize steps:", file=sys.stderr)
@@ -560,10 +618,11 @@ def main(argv: Sequence[str] | None = None) -> int:
         print(line, file=sys.stderr)
     if not result["ok"]:
         print(f"error: {result['reason']}", file=sys.stderr)
-        if result.get("steps"):
+        recovery = _recovery_step_names(result)
+        if recovery:
+            flags = " ".join(f"--only {name}" for name in recovery)
             print(
-                "retry just the failing step with "
-                f"`--only {result['steps'][-1].get('name')}`",
+                f"resume the sequence from the earliest failure with `{flags}`",
                 file=sys.stderr,
             )
         return 1

package/runtime/python/okstra_ctl/run.py

@@ -125,7 +125,11 @@ from .render import (
 )
 from okstra_project.dirs import okstra_home
 
-from .dispatch_state import BACKEND_CMUX_PANE, detect_terminal_backend
+from .dispatch_state import (
+    BACKEND_CMUX_PANE,
+    detect_terminal_backend,
+    generate_claude_session_id,
+)
 from .run_context import (
     compute_and_write_run_context,
     refresh_run_context_snapshot,
@@ -139,7 +143,6 @@ from .seeding import (
     verify_installation,
 )
 from .session import (
-    generate_claude_session_id,
     resolve_inproc_lead_session_id,
     write_claude_resume_command_file,
 )
@@ -296,6 +299,43 @@ def _validate_data_json_approval_consistency(
         )
 
 
+def _validate_approved_plan_conformance(path: Path) -> None:
+    """승인 계획의 stage conformance 선언 형식을 승인 경계에서 판정한다.
+
+    같은 판정이 지금까지는 구현 런의 마지막 `validate-run` 에서만 나왔다. 그때는
+    워커 배치와 수렴이 이미 끝난 뒤라 런 하나를 통째로 버려야 했다 — 실측된
+    실패에서 승인 계획의 stage 2~7 이 기계 형식이 아니라 산문이었다.
+
+    선언이 없는 stage 는 건드리지 않는다(`conformance.malformed_conformance_stages`
+    참조): XOR 부재는 계획 단계의 check S11 이 이미 막고, 구현 진입 게이트도
+    validate-run 이 계속 요구한다. 여기서 다시 하면 같은 규칙이 두 곳이 된다.
+    """
+    from .conformance import malformed_conformance_stages
+
+    loaded = _load_final_report_data_if_present(path)
+    if loaded is None:
+        return
+    data_path, data = loaded
+    bad = malformed_conformance_stages(data)
+    if not bad:
+        return
+    # 한 stage 씩 고치고 다시 막히는 왕복을 피하려면 전부 나열해야 한다 —
+    # 실패한 런에서 검증기는 stage 2 만 지목했지만 실제로는 2~7 전부였다.
+    stages = ", ".join(str(number) for number in bad)
+    raise PrepareError(
+        f"approved plan data.json has malformed conformanceTests for stage(s) "
+        f"{stages}: {data_path}\n"
+        "  each declaring stage must read "
+        "`<task_root>/qa/scripts/stage-<N>.<ext> "
+        "(requires=[db|io|http|external,...])` after the "
+        "`Conformance tests: stage-<N> — ` prefix "
+        "(prompts/profiles/implementation-planning.md), or carry "
+        "`Conformance exemption: <reason>` instead.\n"
+        "  re-run implementation-planning so the declaration is regenerated in "
+        "that form, then approve it."
+    )
+
+
 def _set_data_json_approved_true_if_present(path: Path) -> bool:
     loaded = _load_final_report_data_if_present(path)
     if loaded is None:
@@ -474,6 +514,7 @@ def _validate_approved_plan(path: str) -> None:
         )
     _reject_blocking_plan_body_gate(p, body, action="approved plan validation")
     _validate_data_json_approval_consistency(p, markdown_approved=True)
+    _validate_approved_plan_conformance(p)
     # frontmatter approved == true 상태. §1 Clarification Items 의
     # Blocks=approval 행이 아직 open/answered 면 승인을 무효화한다.
     scan = scan_approval_gate(p)

package/runtime/python/okstra_ctl/schema_excerpt.py

@@ -1,6 +1,6 @@
 """Build a task-type-scoped excerpt of the final-report schema.
 
-The full schema (``schemas/final-report-v1.0.schema.json``) carries the
+The full schema (``schemas/final-report-v2.0.schema.json``) carries the
 deliverable property blocks for ALL task-types (``errorAnalysis``, the three
 read-only analysis blocks, ``implementationPlanning``, ``releaseHandoff``,
 ``implementation``, and ``finalVerification``) plus a

package/runtime/python/okstra_ctl/scope_provenance.py

@@ -21,7 +21,7 @@ CONTRACT_RULES = frozenset(
 )
 
 # Mirrors the report schema's requirement id pattern
-# (schemas/final-report-v1.0.schema.json: `^R-\d{3,}$`).
+# (schemas/final-report-v2.0.schema.json: `^R-\d{3,}$`).
 _REQ_ID_RE = re.compile(r"^R-\d{3,}$")
 _BRIEF_RE = re.compile(r"^brief:\s*(?P<heading>.+?)\s*$")
 _DERIVED_RE = re.compile(r"^derived:\s*(?P<parent>\S+)\s*[—-]\s*(?P<reason>.+?)\s*$")

package/runtime/python/okstra_ctl/session.py

@@ -1,21 +1,22 @@
 """Claude session helpers.
 
-bash session.sh 의 python 구현. claude session id 생성, resume command
-파일 작성.
+bash session.sh 의 python 구현. lead claude 세션 관측, resume command
+파일 작성. 세션 id 발급기는 워커 dispatch 도 쓰므로
+`dispatch_state.generate_claude_session_id` 에 있다.
 """
 from __future__ import annotations
 
 import json
 import os
-import uuid
 from pathlib import Path
+from typing import Collection
 
-from .dispatch_state import DispatchError, mutate_team_state
-
-
-def generate_claude_session_id() -> str:
-    """UUIDv4 문자열."""
-    return str(uuid.uuid4())
+from .dispatch_state import (
+    DispatchError,
+    load_json_object,
+    mutate_team_state,
+    worker_session_ids,
+)
 
 
 def _claude_projects_dir_for(cwd: Path) -> Path:
@@ -76,7 +77,11 @@ def _session_mentions(jsonl_path: Path, needle: str) -> bool:
         return False
 
 
-def resolve_lead_session_id_for_run(project_root: Path, run_dir: Path) -> str:
+def resolve_lead_session_id_for_run(
+    project_root: Path,
+    run_dir: Path,
+    exclude_session_ids: Collection[str] = (),
+) -> str:
     """`run_dir` 를 다룬 lead 세션 중 가장 최근 수정된 것의 id, 없으면 ''.
 
     프로젝트 디렉토리의 최신 jsonl 을 그대로 집으면(``resolve_inproc_lead_session_id``)
@@ -84,6 +89,12 @@ def resolve_lead_session_id_for_run(project_root: Path, run_dir: Path) -> str:
     (dev-10172): 남의 세션이 `leadSessionIds` 에 들어가 run 비용이 $80 → $207 로
     부풀고, 그 세션의 PROGRESS 라인이 conformance 스캔에 섞여 오탐을 냈다.
     자기 run 의 산출물 경로를 언급한 세션만 후보로 인정해 그 오염을 막는다.
+
+    `exclude_session_ids` 는 같은 run **안**의 오염을 막는다. cmux 워커는
+    `agentName` 을 안 남겨 아래 필터를 통과하고, 워커 세션도 자기 run 의 산출물
+    경로를 언급하므로 needle 에도 걸린다. 워커가 리드보다 늦게 끝나면 mtime
+    정렬에서 먼저 잡혀 워커 세션이 리드로 기록된다 — dispatch 가 발급한 id 를
+    호출자가 넘겨 그 세션들을 후보에서 뺀다.
     """
     proj_dir = _claude_projects_dir_for(project_root)
     try:
@@ -91,7 +102,10 @@ def resolve_lead_session_id_for_run(project_root: Path, run_dir: Path) -> str:
     except OSError:
         return ""
     needle = str(run_dir)
+    excluded = set(exclude_session_ids)
     for path in sorted(candidates, key=lambda p: p.stat().st_mtime, reverse=True):
+        if path.stem in excluded:
+            continue
         if _session_has_agent_name(path):
             continue
         if _session_mentions(path, needle):
@@ -103,17 +117,36 @@ def record_observed_lead_session(project_root: Path, team_state_path: Path) -> s
     """이 run 의 live lead 세션을 관측해 team-state 에 append(멱등). 이 run 을
     다룬 lead 세션을 못 찾거나 중복이면 '' 반환. 재발급으로 갈린 세대를 축1 이
     여기에 모은다.
+
+    후보에서 뺄 워커 세션 id 는 append 대상인 team-state 자체가 들고 있다 —
+    dispatch 가 `workerDispatches[].sessionId` 에 적어 둔 값이라, 관측 시점에
+    이 run 이 연 워커 세션의 목록은 그 파일 하나로 완결된다.
     """
-    sid = resolve_lead_session_id_for_run(project_root, team_state_path.parent.parent)
+    try:
+        team_state = load_json_object(team_state_path, "team-state")
+    except (DispatchError, OSError):
+        team_state = {}
+    sid = resolve_lead_session_id_for_run(
+        project_root,
+        team_state_path.parent.parent,
+        exclude_session_ids=worker_session_ids(team_state),
+    )
     if not sid:
         return ""
     def add_observed_session(state: dict) -> bool:
         lead_ids = state.setdefault("leadSessionIds", [])
+        observed = state.setdefault("observedTeamNames", [])
+        # 두 키가 list 가 아니면 `sid in None` 이 TypeError 를, `str.append` 가
+        # AttributeError 를 낸다. 그 예외는 아래 `(DispatchError, OSError)` 도
+        # `observe_lead_session` 의 `OSError` 도 통과해 dispatch 를 죽인다 —
+        # 관측이 호출자를 깨뜨리지 않는다는 계약을 docstring 이 아니라 여기서
+        # 지킨다. 관측을 건너뛰면 이 run 은 관측 이전과 같은 상태로 남는다.
+        if not isinstance(lead_ids, list) or not isinstance(observed, list):
+            return False
         if sid in lead_ids:
             return False
         lead_ids.append(sid)
         team = f"session-{sid[:8]}"
-        observed = state.setdefault("observedTeamNames", [])
         if team not in observed:
             observed.append(team)
         return True
@@ -125,6 +158,30 @@ def record_observed_lead_session(project_root: Path, team_state_path: Path) -> s
     return sid if changed else ""
 
 
+def observe_lead_session(project_root: Path, team_state_path: Path) -> None:
+    """단계 경계에서 부르는 부수효과 — 관측 실패를 호출자에게 내지 않는다.
+
+    리드 세션은 resume·compaction 으로 세대가 갈리므로 prepare 때 적힌 단 하나의
+    id 는 런 구간에 레코드가 없는 죽은 세션을 가리킬 수 있다. 리드가 반드시
+    지나가는 지점마다 관측해 `leadSessionIds` 에 세대를 모은다 — 리드의 협조를
+    요구하지 않는 것이 요점이다.
+
+    잡는 범위가 OSError 뿐인 이유: 이 아래 호출들이 각자 자기 실패를 흡수하고,
+    그러고도 밖으로 나오는 것이 후보 정렬의 `p.stat()` 이다 — 스캔 도중 세션
+    jsonl 이 사라지면 여기서 OSError 가 난다. team-state 읽기·쓰기
+    (`load_json_object` / `mutate_team_state`)와 세션 본문 스캔이 그 흡수
+    지점이고, 비정상 team-state 가 낼 TypeError/AttributeError 는 잡는 대신 아예
+    내지 않는 쪽으로 막는다 — append 대상 키(`leadSessionIds` /
+    `observedTeamNames`)는 `add_observed_session` 이, 제외 집합의 출처
+    (`workerDispatches`)는 `worker_session_ids` 가 각각 비-list 를 걸러낸다.
+    더 넓게 잡으면 team-state 를 깨뜨리는 진짜 버그까지 조용히 삼킨다.
+    """
+    try:
+        record_observed_lead_session(project_root, team_state_path)
+    except OSError:
+        return
+
+
 def write_claude_resume_command_file(
     *,
     resume_command_path: Path,