okstra 0.206.1 → 0.207.0

package/runtime/python/okstra_ctl/report_finalize.py

@@ -62,7 +62,10 @@ from .final_report_paths import (
     final_report_markdown_path,
     sidecar_source_rel,
 )
-from .paths import task_dir, task_manifest_file
+from .run_artifact_prune import prune_run_artifacts
+from .handoff import record_verified
+from .handoff_error import HandoffError
+from .paths import RunRef, task_dir, task_manifest_file
 from .report_view_artifacts import html_view_path
 from .release_gate import release_handoff_allowed
 from .report_translation_dispatch import TranslateOutcome, translate_report
@@ -73,6 +76,7 @@ from .stage_targets import (
     integrate_and_teardown_whole_task,
 )
 from .session import observe_lead_session
+from .lead_progress import record_checkpoint
 from .error_log_write import record_runtime_failure
 
 # 포인터 값 타입만 쓴다. `okstra_project.phase_pointer` 는 okstra 안의
@@ -91,10 +95,12 @@ STEP_TRANSLATE = "translate"
 STEP_TOKEN_USAGE = "token-usage"
 STEP_RENDER_VIEWS = "render-views"
 STEP_SPAWN_FOLLOWUPS = "spawn-followups"
+STEP_RECORD_VERIFIED = "record-verified"
 STEP_VALIDATE_RUN = "validate-run"
 STEP_RECORD_GROUP_MEMORY = "record-group-memory"
 STEP_TEARDOWN_STAGES = "teardown-stages"
 STEP_PREFLIGHT = "preflight"
+STEP_PRUNE_RUN_ARTIFACTS = "prune-run-artifacts"
 
 STEP_ORDER = (
     STEP_PROJECT_ACTIVITY,
@@ -102,13 +108,15 @@ STEP_ORDER = (
     STEP_TOKEN_USAGE,
     STEP_RENDER_VIEWS,
     STEP_SPAWN_FOLLOWUPS,
+    STEP_RECORD_VERIFIED,
     STEP_VALIDATE_RUN,
     # After validation: the group's sibling tasks read this run's conclusion
     # from `group-context.md`, and only a validated record is worth handing on.
     STEP_RECORD_GROUP_MEMORY,
-    # Last, and only after the run validated: it removes the stage worktrees a
+    # Only after the run validated: it removes the stage worktrees a
     # blocked verdict would send the user straight back to.
     STEP_TEARDOWN_STAGES,
+    STEP_PRUNE_RUN_ARTIFACTS,
 )
 
 V3_STEP_ORDER = (
@@ -119,9 +127,12 @@ V3_STEP_ORDER = (
     STEP_TRANSLATE,
     STEP_RENDER_VIEWS,
     STEP_SPAWN_FOLLOWUPS,
+    # Needs the assembled record; `validate-run` requires the row it writes.
+    STEP_RECORD_VERIFIED,
     STEP_VALIDATE_RUN,
     STEP_RECORD_GROUP_MEMORY,
     STEP_TEARDOWN_STAGES,
+    STEP_PRUNE_RUN_ARTIFACTS,
 )
 
 # 앞 단계가 실패하면 건너뛰는 단계. 하나는 worktree 를 거두고, 하나는 검증 안 된
@@ -391,6 +402,10 @@ def build_commands(ctx: FinalizeContext) -> list[tuple[str, list[str]]]:
                 ctx.task_key,
             ],
         ),
+        (
+            STEP_RECORD_VERIFIED,
+            ["<in-process>", "record-verified", str(ctx.data_path)],
+        ),
         (STEP_VALIDATE_RUN, _validate_run_command(ctx, ctx.data_path)),
         (
             STEP_RECORD_GROUP_MEMORY,
@@ -400,6 +415,10 @@ def build_commands(ctx: FinalizeContext) -> list[tuple[str, list[str]]]:
             STEP_TEARDOWN_STAGES,
             ["<in-process>", "teardown-stages", str(ctx.data_path)],
         ),
+        (
+            STEP_PRUNE_RUN_ARTIFACTS,
+            ["<in-process>", "prune-run-artifacts", str(ctx.data_path)],
+        ),
     ]
     if ctx.report_contract_version != "3.0":
         return commands
@@ -502,6 +521,51 @@ def _next_in_group(steps: Sequence[Mapping[str, Any]]) -> dict[str, str] | None:
     return None
 
 
+def _record_verified_stages(
+    ctx: FinalizeContext,
+    command: list[str],
+) -> subprocess.CompletedProcess:
+    """Write a `verified` row for every stage a release-ready verdict clears.
+
+    `handoff record-verified` needs the assembled `data.json` and `validate-run`
+    requires its rows, and both happen inside this one call, so the lead had no
+    point at which to run it (observed 2026-09-26, dev-11054). Re-recording the
+    same report is a no-op, so a resumed finalize may run this again.
+    """
+    def _done(payload: Mapping[str, Any]) -> subprocess.CompletedProcess:
+        return subprocess.CompletedProcess(command, 0, json.dumps(payload), "")
+
+    if ctx.task_type != "final-verification":
+        return _done({"skipped": "not a final-verification run"})
+    try:
+        data = load_owned_object(Path(ctx.data_path), artifact="final report record")
+    except JsonBoundaryError as exc:
+        return subprocess.CompletedProcess(
+            command, 1, "", f"cannot read final-report data.json: {exc}")
+    if data.get("verificationScope") not in ("single-stage", "whole-task"):
+        return _done({"skipped": "report names no verification scope"})
+    if not release_handoff_allowed(data):
+        return _done({"skipped": "verdict does not clear the work for release"})
+    stages = sorted({
+        row["stage"]
+        for row in (data.get("finalVerification") or {}).get("stageReports") or ()
+        if isinstance(row, Mapping) and isinstance(row.get("stage"), int)
+    })
+    try:
+        plan_run_root = (
+            RunRef.from_report_path(Path(ctx.data_path).resolve())
+            .sibling("implementation-planning").run_dir
+        )
+        for stage in stages:
+            record_verified(
+                plan_run_root=plan_run_root, stage=stage,
+                report_path=str(ctx.data_path), data_json=str(ctx.data_path),
+            )
+    except (HandoffError, ValueError, OSError) as exc:
+        return subprocess.CompletedProcess(command, 1, "", str(exc))
+    return _done({"recorded": stages})
+
+
 def _teardown_stage_worktrees(
     ctx: FinalizeContext,
     command: list[str],
@@ -538,6 +602,27 @@ def _teardown_stage_worktrees(
     return _done(result)
 
 
+def _prune_run_artifacts(
+    ctx: FinalizeContext,
+    command: list[str],
+) -> subprocess.CompletedProcess:
+    """이 run 디렉터리에서 run 종료 뒤 읽는 곳이 없는 산출물을 지운다.
+
+    실패한 run 에서도 돈다. 빌드 디렉터리는 남은 lockfile 로 다시 만들고, dispatch
+    스냅샷은 검증을 통과한 run 의 것만 지운다(`run_artifact_prune`).
+    """
+    reports_dir = Path(ctx.data_path).resolve().parent
+    if reports_dir.name != "reports":
+        return subprocess.CompletedProcess(
+            command, 1, "", f"report record is not under a run's reports/: {ctx.data_path}")
+    run_dir = reports_dir.parent
+    try:
+        result = prune_run_artifacts(ctx.project_root, run_dir, apply=True)
+    except OSError as exc:
+        return subprocess.CompletedProcess(command, 1, "", str(exc))
+    return subprocess.CompletedProcess(command, 0, json.dumps(result), "")
+
+
 def _validate_run_command(ctx: FinalizeContext, report_record_path: Path) -> list[str]:
     command = [
         sys.executable,
@@ -875,8 +960,12 @@ def _run_finalize_step(
         return _run_translate(ctx, command)
     if name == STEP_TEARDOWN_STAGES:
         return _teardown_stage_worktrees(ctx, command)
+    if name == STEP_PRUNE_RUN_ARTIFACTS:
+        return _prune_run_artifacts(ctx, command)
     if name == STEP_RECORD_GROUP_MEMORY:
         return _record_group_memory(ctx, command)
+    if name == STEP_RECORD_VERIFIED:
+        return _record_verified_stages(ctx, command)
     if name == STEP_VALIDATE_RUN:
         try:
             _link_lead_result_for_validation(ctx)
@@ -1066,6 +1155,9 @@ Runs the Phase 7 steps in their contractual order against one final-report:
   5. spawn-followups   turn section 4 rows into task stubs
   6. validate-run      validate the finished run artifacts
   7. record-group-memory / 8. teardown-stages  after a clean validation
+  9. prune-run-artifacts  remove node_modules and .next under this run
+                       directory, and the dispatch snapshots and publication
+                       locks of a validated run; runs after a failure too
 
 Every step is idempotent, so re-running after a fixed failure is safe. The
 sequence stops at the first non-zero exit and reports which step failed, except
@@ -1075,6 +1167,10 @@ exits non-zero the command prints the --only flags that resume the sequence
 from the earliest failing step — follow those rather than rerunning the failing
 step alone, which would leave the html rendered before the tokens landed.
 
+A full run (no --only) first records the lead's `phase-7-persist` checkpoint
+and returns it as `progressLines`; the lead emits that line instead of calling
+`okstra lead-progress append` for it.
+
 This is the same code path the Codex lead adapter runs automatically after its
 report-writer completes, so a Claude-led and a Codex-led run finalize
 identically.
@@ -1264,7 +1360,15 @@ def main(argv: Sequence[str] | None = None) -> int:
     # 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)
+    # 재개(`--only`)는 Phase 7 을 새로 시작하지 않고 다시 들어가는 것이다. 이 행은
+    # 그것을 요구하는 `validate-run` 보다 먼저 있어야 한다.
+    progress_line = None if args.only else record_checkpoint(
+        ctx.project_root, ctx.manifest_path, "phase-7-persist",
+        source="okstra report-finalize",
+    )
     result = run_finalize(ctx, only=args.only or None)
+    if progress_line:
+        result["progressLines"] = [progress_line]
     order = V3_STEP_ORDER if ctx.report_contract_version == "3.0" else STEP_ORDER
     print(json.dumps(result, indent=2, ensure_ascii=False))
     print("finalize steps:", file=sys.stderr)

package/runtime/python/okstra_ctl/run.py

@@ -2498,7 +2498,7 @@ def recommended_role_models(
     codex 이고 다른 provider 요청은 거부된다(`resolve_lead_provider`). 그래서
     `lead_provider` 를 받아 그 provider 의 기본값으로 해소한다. 받지 않으면
     role 별 레거시 기본값(claude 계열)으로 떨어지는데, 그 값을 codex 호스트
-    화면에 그대로 쓰면 안내는 `opus` 인데 prepare 는 `gpt-6-sol` 을 배정한다.
+    화면에 그대로 쓰면 안내는 `opus` 인데 prepare 는 `gpt-6.1-sol` 을 배정한다.
     """
     lead_provider_id = lead_provider or "claude"
     report_writer_provider_id = report_writer_provider or "claude"

package/runtime/python/okstra_ctl/run_artifact_prune.py

@@ -0,0 +1,200 @@
+"""run 이 끝난 뒤 읽는 곳이 없는 산출물을 찾고 지운다.
+
+- 의존성·빌드 디렉터리(`node_modules`, `.next`): technical-verification 워커는
+  `experiments/<seq>/<worker-id>/` 에 사이트 복사본을 만들고 그 안에서 설치·빌드한다.
+  증거는 계획·로그·lockfile·diff 이고, 설치·빌드 결과는 lockfile 로 다시 만든다. 태스크
+  하나에 `node_modules` 46개와 `.next` 16개(약 22GB)가 남은 사례가 있다(2026-09-27).
+- dispatch 스냅샷(`*.mutation-audit.json`)과 프롬프트 발행 잠금(`*.publish.lock`): 워커
+  시도의 종결 판정과 같은 run 의 증거 복구만 읽는다. 결과는 시도 기록의 변경 요약에
+  남고, `validate-run` 은 경로 문자열만 본다. 검증을 통과한 run 과, 같은 run 디렉터리에서
+  더 뒤의 run 이 검증을 통과한 run 의 dispatch 기록이 가리키는 것만 지운다 — 가장 최근의
+  실패한 run 은 같은 run 안에서 워커를 다시 보낼 수 있다.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import shutil
+from pathlib import Path
+from typing import Any
+
+from okstra_project import resolve_project_root
+
+from .fixed_text import line
+from .json_boundary import JsonBoundaryError, load_owned_object
+from .paths import task_dir
+
+PRUNED_DIR_NAMES = frozenset({"node_modules", ".next"})
+_DISPATCH_ARRAYS = ("agentDispatches", "workerDispatches")
+_MANIFEST_SEQ = re.compile(r"^run-manifest-.+-(\d{3,})\.json$")
+
+
+def _tree_bytes(root: Path) -> int:
+    total = 0
+    for current, _dirs, files in os.walk(root):
+        for name in files:
+            try:
+                total += os.lstat(os.path.join(current, name)).st_size
+            except OSError:
+                continue
+    return total
+
+
+def find_build_dirs(root: Path) -> list[dict[str, Any]]:
+    """`root` 아래 의존성·빌드 디렉터리. 심볼릭 링크는 따라가지도 지우지도 않는다."""
+    found: list[dict[str, Any]] = []
+    # `.okstra` 아래는 `Path.glob("**")` 이 숨김 디렉터리를 건너뛰므로 os.walk 로 훑는다.
+    for current, dirs, _files in os.walk(root):
+        kept = []
+        for name in dirs:
+            path = Path(current) / name
+            if name in PRUNED_DIR_NAMES and not path.is_symlink():
+                found.append({"path": str(path), "bytes": _tree_bytes(path)})
+            else:
+                kept.append(name)
+        dirs[:] = kept
+    return sorted(found, key=lambda row: row["path"])
+
+
+def _resolve(project_root: Path, value: str) -> Path:
+    path = Path(value)
+    return path if path.is_absolute() else project_root / path
+
+
+def _settled_manifests(manifests_dir: Path, names: list[str]) -> list[dict[str, Any]]:
+    """검증을 통과했거나, 같은 디렉터리의 더 뒤 run 이 통과한 run 매니페스트.
+
+    한 `manifests/` 의 seq 는 한 카운터에서 나오므로 숫자 순서가 실행 순서다.
+    """
+    loaded: list[tuple[int, dict[str, Any]]] = []
+    for name in names:
+        match = _MANIFEST_SEQ.match(name)
+        if match is None:
+            continue
+        try:
+            manifest = load_owned_object(manifests_dir / name, artifact="run manifest")
+        except (OSError, JsonBoundaryError):
+            continue
+        loaded.append((int(match[1]), manifest))
+    passed = [
+        seq for seq, manifest in loaded
+        if (manifest.get("validation") or {}).get("status") == "passed"
+    ]
+    if not passed:
+        return []
+    return [manifest for seq, manifest in loaded if seq <= max(passed)]
+
+
+def find_dispatch_leftovers(project_root: Path, root: Path) -> list[dict[str, Any]]:
+    """`root` 아래 끝난 run(`_settled_manifests`)의 dispatch 스냅샷과 발행 잠금."""
+    found: dict[str, int] = {}
+    for current, dirs, files in os.walk(root):
+        dirs[:] = [name for name in dirs if name not in PRUNED_DIR_NAMES]
+        if Path(current).name != "manifests":
+            continue
+        for manifest in _settled_manifests(Path(current), files):
+            try:
+                team_state = load_owned_object(
+                    _resolve(project_root, str(manifest.get("teamStatePath") or "")),
+                    artifact="team state",
+                )
+            except (OSError, JsonBoundaryError):
+                continue
+            for key in _DISPATCH_ARRAYS:
+                for row in team_state.get(key) or ():
+                    if not isinstance(row, dict):
+                        continue
+                    candidates = [row.get("mutationAuditSnapshotPath")]
+                    if row.get("promptPath"):
+                        candidates.append(f"{row['promptPath']}.publish.lock")
+                    for value in candidates:
+                        if not isinstance(value, str) or not value:
+                            continue
+                        path = _resolve(project_root, value)
+                        if path.is_file() and not path.is_symlink():
+                            found[str(path)] = path.stat().st_size
+    return [{"path": path, "bytes": size} for path, size in sorted(found.items())]
+
+
+def prune_run_artifacts(project_root: Path, root: Path, *, apply: bool) -> dict[str, Any]:
+    dirs = find_build_dirs(root) if root.is_dir() else []
+    files = find_dispatch_leftovers(project_root, root) if root.is_dir() else []
+    if apply:
+        for row in dirs:
+            shutil.rmtree(row["path"])
+        for row in files:
+            Path(row["path"]).unlink(missing_ok=True)
+    return {
+        "root": str(root),
+        "applied": apply,
+        "dirs": dirs,
+        "files": files,
+        "totalBytes": sum(row["bytes"] for row in (*dirs, *files)),
+    }
+
+
+def render_result_text(result: dict[str, Any]) -> str:
+    parts = [
+        "# Okstra Run Artifact Prune\n\n",
+        line("Root", result.get("root")),
+        line("Applied", result.get("applied")),
+        line("Directory count", len(result.get("dirs") or [])),
+        line("File count", len(result.get("files") or [])),
+        line("Total bytes", result.get("totalBytes")),
+    ]
+    for row in result.get("dirs") or []:
+        parts.extend(("\n## Directory\n\n", line("Path", row["path"]), line("Bytes", row["bytes"])))
+    return "".join(parts)
+
+
+_CLI_EPILOG = r"""Usage:
+  okstra prune-run-artifacts [--project-root <dir>] [--cwd <dir>]
+                             [--task-group <group> --task-id <id>] [--apply] [--text]
+
+Lists what no reader needs once a run has ended, under
+<project-root>/.okstra/tasks (or one task root), with sizes and a total:
+  - every node_modules and .next directory (symbolic links are neither
+    followed nor removed);
+  - the dispatch snapshots (*.mutation-audit.json) and prompt publication
+    locks (*.publish.lock) recorded by a run whose validation passed, or by
+    an earlier run in the same run directory as a run that passed.
+Nothing is removed without --apply. Source copies, logs, lockfiles, diffs,
+prompts and results stay. --text lists directories only; files are counted.
+"""
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        epilog=_CLI_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        prog="okstra prune-run-artifacts",
+        description="List, and with --apply remove, run artifacts no reader needs after the run.")
+    parser.add_argument("--project-root", default="")
+    parser.add_argument("--cwd", default=".")
+    parser.add_argument("--task-group", default="")
+    parser.add_argument("--task-id", default="")
+    parser.add_argument("--apply", action="store_true", help="remove the listed paths")
+    parser.add_argument("--text", action="store_true", help="emit fixed text fields")
+    args = parser.parse_args(argv)
+    if bool(args.task_group) != bool(args.task_id):
+        parser.error("--task-group and --task-id go together")
+
+    project_root = resolve_project_root(explicit_root=args.project_root, cwd=args.cwd)
+    root = (
+        task_dir(project_root, args.task_group, args.task_id)
+        if args.task_group else project_root / ".okstra" / "tasks"
+    )
+    result = {
+        "ok": True,
+        "projectRoot": str(project_root),
+        **prune_run_artifacts(project_root, root, apply=args.apply),
+    }
+    output = render_result_text(result) if args.text else json.dumps(result, ensure_ascii=False, indent=2)
+    print(output, end="" if args.text else "\n")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/runtime/python/okstra_ctl/team.py

@@ -36,6 +36,12 @@ from .dispatch_core import (
     await_dispatches,
     dispatch_plan,
 )
+from .dispatch_checkpoints import (
+    record_collect_checkpoints,
+    record_dispatch_checkpoints,
+    settled_initial_dispatches,
+)
+from .lead_progress import record_checkpoint, render_progress_line
 from .ports.worker_dispatch import WorkerDispatchPort, WorkerDispatchRequest
 from .registry.host_registry import default_host_registry
 from .registry.provider_registry import default_provider_registry
@@ -44,6 +50,7 @@ from .json_boundary import load_owned_object
 
 
 _SUPPORTED_WRAPPERS = provider_worker_wrappers(default_provider_registry())
+_SOURCE = "okstra team"
 
 
 def main(argv: Sequence[str] | None = None) -> int:
@@ -73,7 +80,7 @@ _CLI_EPILOG = r"""Usage:
     [--poll-interval-seconds <n>] [--timeout-seconds <n>] \
     [--heartbeat-seconds <n>] [--json]
   okstra team reclaim --project-root <dir> --run-manifest <path> \
-    [--dry-run] [--json]
+    [--dry-run] [--gate] [--json]
   okstra team teardown --project-root <dir> --run-manifest <path> \
     [--dry-run] [--json]
 
@@ -84,11 +91,23 @@ descriptor owns the team lifecycle (launch_mode=team) — a worker there is a CL
 wrapper subprocess holding no pane, so there is nothing to close.
 
   reclaim   round boundary: closes the panes of dispatches that have finished and
-            leaves the in-progress ones open. Run it with --dry-run first to
-            count, then again to close.
+            leaves the in-progress ones open, then on a cmux-pane run records
+            `PROGRESS: phase-batch-cleanup panes=<n>`. With --gate it is the
+            cleanup before a user gate and prints
+            `PROGRESS: phase-gate-cleanup panes=<n>` without recording it.
+
   teardown  end of run: closes every recorded pane and writes off any dispatch
             that never reached a terminal status.
 
+  On a cmux-pane run, dispatch records `phase-3-team-create` when it writes the
+  implicit-team marker, `phase-4-dispatch` for each `initial` job and
+  `phase-6-synthesis` on the first report-writer dispatch; await records
+  `phase-5-poll` on entry and again when the counts changed, and
+  `phase-5-collect` for each `initial` dispatch it settled. The lead does not
+  call `okstra lead-progress append` for those checkpoints; each command prints
+  the `PROGRESS:` lines to emit (`progressLines` in JSON output). On any other
+  backend the team commands record nothing.
+
   --workspace-root and --okstra-bin are owned by this command.
 """
 _CLI_DESCRIPTION = "Dispatch, await, and close okstra-owned worker panes."
@@ -148,6 +167,10 @@ def _add_reclaim_parser(sub) -> None:
     )
     _add_run_args(parser)
     parser.add_argument("--dry-run", action="store_true")
+    parser.add_argument(
+        "--gate", action="store_true",
+        help="cleanup before a user gate: print phase-gate-cleanup, record nothing",
+    )
     parser.add_argument("--json", action="store_true")
 
 
@@ -179,11 +202,31 @@ def _dispatch(args) -> int:
     if args.dry_run:
         _print_json(backend_plan.to_payload(dry_run=True))
         return 0
-    result = dispatch_plan(backend_plan, wait=False)
-    _print_json(backend_plan.to_payload(dry_run=False))
+    lines: list[str] = []
+    result = dispatch_plan(
+        backend_plan, wait=False,
+        before_start=lambda prepared: lines.extend(
+            _record_dispatch(args, manifest, prepared)
+        ),
+    )
+    payload = backend_plan.to_payload(dry_run=False)
+    payload["progressLines"] = lines
+    _print_json(payload)
     return result
 
 
+def _record_dispatch(args, manifest: Mapping[str, Any], prepared) -> list[str]:
+    # cmux-pane run 만 체크포인트를 team 명령에 맡긴다. external 리드는 CLI 워커도
+    # `team await` 로 기다리지만 체크포인트는 직접 append 하므로, 여기서 쓰면 행이 둘이 된다.
+    if not _is_cmux_run(manifest):
+        return []
+    return record_dispatch_checkpoints(
+        prepared.project_root, args.run_manifest,
+        _load_json(prepared.team_state_path, "team-state"), prepared.jobs,
+        source=_SOURCE,
+    )
+
+
 def team_dispatch_port(manifest: Mapping[str, Any]) -> WorkerDispatchPort:
     """이 run 의 워커를 띄울 포트. cmux run 이면 pane, 아니면 리드 호스트의 포트.
 
@@ -209,19 +252,59 @@ def _await(args) -> int:
     _validate_team_manifest(manifest)
     _observe_lead_session_from_manifest(Path(args.project_root).resolve(), manifest)
     plan = _plan_for_existing(Path(args.project_root), Path(args.workspace_root), Path(args.run_manifest), manifest)
+    should_record = _is_cmux_run(manifest)
+    entry_state = _load_json(plan.team_state_path, "team-state")
+    entry = _dispatch_counts(entry_state)
+    lines = [_record_poll(args, entry)] if should_record else []
     code = await_dispatches(
         plan,
         poll_interval_seconds=args.poll_interval_seconds,
         timeout_seconds=args.timeout_seconds,
         heartbeat_seconds=0 if args.json else args.heartbeat_seconds,
     )
+    if should_record:
+        exit_state = _load_json(plan.team_state_path, "team-state")
+        lines.extend(record_collect_checkpoints(
+            plan.project_root, args.run_manifest,
+            settled_initial_dispatches(entry_state),
+            settled_initial_dispatches(exit_state),
+            source=_SOURCE,
+        ))
+        exit_counts = _dispatch_counts(exit_state)
+        if exit_counts != entry:
+            lines.append(_record_poll(args, exit_counts))
+    lines = [line for line in lines if line]
     if args.json:
-        _print_json(_await_payload(plan, code == 0))
+        payload = _await_payload(plan, code == 0)
+        payload["progressLines"] = lines
+        _print_json(payload)
     else:
+        for line in lines:
+            print(line)
         print("ALL_WORKERS_DONE" if code == 0 else "POLL_TIMEOUT")
     return code
 
 
+def _dispatch_counts(team_state: Mapping[str, Any]) -> tuple[int, int]:
+    """이 run 의 dispatch 행 기준 (pending, done) — `phase-5-poll` 의 두 값."""
+    statuses = [
+        record.get("status")
+        for record in team_state.get("workerDispatches", [])
+        if isinstance(record, dict)
+    ]
+    done = sum(1 for status in statuses if status in TERMINAL_WORKER_STATUSES)
+    return len(statuses) - done, done
+
+
+def _record_poll(args, counts: tuple[int, int]) -> str | None:
+    pending, done = counts
+    return record_checkpoint(
+        Path(args.project_root), args.run_manifest, "phase-5-poll",
+        source=_SOURCE,
+        fields=(("pending", str(pending)), ("done", str(done))),
+    )
+
+
 def _teardown(args) -> int:
     manifest = _load_manifest(args.project_root, args.run_manifest)
     _validate_team_manifest(manifest)
@@ -259,7 +342,16 @@ def _reclaim(args) -> int:
         _emit_panes(args.json, panes)
         return 0
     _close_panes(manifest, panes)
-    _emit_panes(args.json, panes)
+    count = (("panes", str(len(panes))),)
+    line: str | None = None
+    if args.gate:
+        line = render_progress_line("phase-gate-cleanup", count)
+    elif _is_cmux_run(manifest):
+        line = record_checkpoint(
+            Path(args.project_root), args.run_manifest, "phase-batch-cleanup",
+            source=_SOURCE, fields=count,
+        )
+    _emit_panes(args.json, panes, line)
     return 0
 
 
@@ -434,12 +526,19 @@ def _mark_teardown_errors(team_state_path: Path) -> None:
     mutate_team_state(team_state_path, mark)
 
 
-def _emit_panes(as_json: bool, panes: list[dict[str, str]]) -> None:
+def _emit_panes(
+    as_json: bool, panes: list[dict[str, str]], progress_line: str | None = None
+) -> None:
     if as_json:
-        _print_json({"panes": panes})
+        payload: dict[str, Any] = {"panes": panes}
+        if progress_line:
+            payload["progressLines"] = [progress_line]
+        _print_json(payload)
         return
     for pane in panes:
         print(f"{pane['paneId']}\t{pane['kind']}")
+    if progress_line:
+        print(progress_line)
 
 
 def _manifest_backend(manifest: Mapping[str, Any]) -> str:

package/runtime/python/okstra_ctl/wizard/steps_options.py

@@ -206,12 +206,20 @@ def _suggest_sibling_task_ids(state: WizardState) -> str:
     return ",".join(siblings)
 
 
+def _sibling_count_note(state: WizardState, suggestion: str) -> str:
+    """라벨은 CSV 앞부분만 보여 주므로, 선택하면 몇 개가 들어가는지 따로 적는다."""
+    count = len([tid for tid in suggestion.split(",") if tid])
+    note = _p(state.workspace_root, "related_tasks_pick")["labels"]["siblings_count"]
+    return note.format(count=count)
+
+
 _RELATED_TASKS_PICK_SPEC = _OptionalCachedPickSpec(
     step=S_RELATED_TASKS_PICK, prompt_key="related_tasks_pick",
     recommend_token=_SIBLINGS_TOKEN, label_key="siblings", echo_suffix_key="siblings",
     suggest=_suggest_sibling_task_ids, snippet_style="prefix",
     cache_attr="last_siblings_cached", target_attr="related_tasks_raw",
     pending_attr="related_tasks_pending_text",
+    recommend_note=_sibling_count_note,
 )