okstra 0.186.7 → 0.187.0

package/runtime/python/okstra_ctl/listing.py

@@ -7,60 +7,10 @@ from pathlib import Path
 from typing import List, Optional
 
 from .paths import resolve_under_root
-from .json_boundary import JsonBoundaryError, load_owned_object
 from .reconcile import _parse_iso
 from .run_index_row import read_run_index
 
 
-def list_projects(home: Path, *, only_active: bool = False,
-                  sort_by: str = "recent") -> List[dict]:
-    """projects/<id>/meta.json 을 모두 읽어 정렬된 목록을 반환."""
-    base = home / "projects"
-    if not base.is_dir():
-        return []
-    items: List[dict] = []
-    for child in base.iterdir():
-        meta_file = child / "meta.json"
-        if not meta_file.is_file():
-            continue
-        try:
-            meta = load_owned_object(meta_file, artifact="project metadata")
-        except JsonBoundaryError:
-            # 동시 쓰기/이전 크래시로 깨진 meta.json 하나가 전체 listing 을
-            # 죽이지 않도록 해당 프로젝트만 건너뛴다(다른 JSON 리더와 동일 정책).
-            continue
-        # projectRoot 가 누락/빈 문자열이면 Path("").is_dir() 이 cwd 를 가리켜
-        # True 가 되므로(missing 으로 잡히지 않음), 빈 값은 명시적으로 missing
-        # 처리한다.
-        proj_root = meta.get("projectRoot") or ""
-        meta["missing"] = (not proj_root) or (not Path(proj_root).is_dir())
-        if only_active and int(meta.get("activeCount", 0)) <= 0:
-            continue
-        items.append(meta)
-    if sort_by == "name":
-        items.sort(key=lambda m: m.get("projectId", ""))
-    elif sort_by == "count":
-        items.sort(key=lambda m: int(m.get("runCount", 0)), reverse=True)
-    else:
-        items.sort(key=lambda m: m.get("lastRunAt", ""), reverse=True)
-    return items
-
-
-def format_projects_table(items: List[dict]) -> str:
-    """projects 테이블 텍스트 포맷팅."""
-    rows = [("PROJECT-ID", "RUNS", "ACTIVE", "LAST-RUN", "ROOT")]
-    for it in items:
-        root = it.get("projectRoot", "") + (" (MISSING)" if it.get("missing") else "")
-        rows.append((it.get("projectId", ""), str(it.get("runCount", 0)),
-                     str(it.get("activeCount", 0)), it.get("lastRunAt", ""),
-                     root))
-    widths = [max(len(r[i]) for r in rows) for i in range(5)]
-    lines = []
-    for r in rows:
-        lines.append("  ".join(c.ljust(widths[i]) for i, c in enumerate(r)))
-    return "\n".join(lines) + "\n"
-
-
 def _parse_since(value: str) -> Optional[datetime]:
     """--since 파싱. 빈 문자열은 None(필터 없음). 형식 위반은 ValueError 로
     fail-fast 한다. 이전엔 잘못된 값(`7days`)이 silently None 으로 강등되어
@@ -133,47 +83,6 @@ def list_runs(home: Path, *, project: str = "all", task_group: str = "all",
     return out
 
 
-def format_runs_table(rows: List[dict]) -> str:
-    header = ("RUN-ID", "STATUS", "STARTED", "TASK-TYPE")
-    body = [(r.get("runId", ""), r.get("status", ""),
-             r.get("startedAt", ""), r.get("taskType", "")) for r in rows]
-    table = [header] + body
-    widths = [max(len(t[i]) for t in table) for i in range(4)]
-    lines = []
-    for t in table:
-        lines.append("  ".join(c.ljust(widths[i]) for i, c in enumerate(t)))
-    return "\n".join(lines) + "\n"
-
-
-def find_row_by_run_id(home: Path, run_id: str) -> Optional[dict]:
-    """active+recent+archive 를 모두 뒤져 runId 가 일치하는 최신 row 반환."""
-    rows = list_runs(home, include_archive=True)
-    for r in rows:
-        if r.get("runId") == run_id:
-            return r
-    return None
-
-
-def format_show(row: dict) -> str:
-    inv = row.get("invocationFile", "")
-    return (
-        f"runId           : {row.get('runId')}\n"
-        f"projectId       : {row.get('projectId')}\n"
-        f"projectRoot     : {row.get('projectRoot')}\n"
-        f"taskKey         : {row.get('taskGroup')}/{row.get('taskId')}\n"
-        f"taskType        : {row.get('taskType')}\n"
-        f"status          : {row.get('status')}\n"
-        f"startedAt       : {row.get('startedAt')}\n"
-        f"finishedAt      : {row.get('finishedAt')}\n"
-        f"workers         : {','.join(row.get('workers', []))}\n"
-        f"leadModel       : {row.get('leadModel')}\n"
-        f"validation      : {row.get('validation')}\n"
-        f"runDirRel       : {row.get('runDirRel')}\n"
-        f"finalReportRecordRel  : {row.get('finalReportRecordRel') or row.get('finalReportRel')}\n"
-        f"invocationFile  : {inv}\n"
-    )
-
-
 def absolute_final_report_path(row: dict) -> Optional[Path]:
     from .final_report_paths import index_report_record_rel
 

package/runtime/python/okstra_ctl/locks.py

@@ -1,4 +1,4 @@
-"""중앙 락과 task-lock 파일명. 다른 okstra_ctl 모듈에 의존하지 않는다."""
+"""중앙 락과 task-key 단위 mutex. 다른 okstra_ctl 모듈에 의존하지 않는다."""
 from __future__ import annotations
 
 import contextlib
@@ -9,9 +9,10 @@ from .ids import _escape_segment_for_join, _safe_fs_segment
 
 @contextlib.contextmanager
 def central_lock(home):
-    """~/.okstra/.lock 위에 fcntl LOCK_EX. okstra-central.sh 의
-    okstra_central_with_lock 과 같은 파일을 사용하므로 record_start 와
-    상호 직렬화된다.
+    """~/.okstra/.lock 위에 fcntl LOCK_EX.
+
+    중앙 인덱스(active.jsonl·recent.jsonl)를 쓰는 모든 경로가 이 한 파일을
+    거치므로 record_start·reconcile·reserve 가 서로 직렬화된다.
     """
     from pathlib import Path as _Path
     home_p = _Path(home)
@@ -57,18 +58,3 @@ def worktree_provision_mutex(home, project_id: str, task_group: str,
             yield
         finally:
             fcntl.flock(f.fileno(), fcntl.LOCK_UN)
-
-
-def task_lock_filename(project_id: str, task_group: str, task_id: str,
-                       task_type: str) -> str:
-    """task-key + task-type 단위 mutex 파일명. ~/.okstra/.locks/ 아래에 위치한다.
-    okstra 의 RUN_DIR 가 task-type 별로 분리되므로 mutex 도 같은 입자에 둔다.
-    각 세그먼트는 먼저 fs-safe 슬러그로 정규화해 `/` 나 `..` 가 .locks 디렉터리
-    밖으로 mutex 를 escape 시키는 것을 막고, 이어서 `-` 를 `--` 로 escape 한
-    뒤 `-` 로 조인해 슬래시 경계를 보존한다(('p','feature-8','email','x') 와
-    ('p','feature','8-email','x') 가 같은 파일명으로 매핑되어 mutex 가 공유
-    되는 문제 방지).
-    """
-    parts = [_escape_segment_for_join(_safe_fs_segment(s))
-             for s in (project_id, task_group, task_id, task_type)]
-    return "-".join(parts) + ".lock"

package/runtime/python/okstra_ctl/log_report.py

@@ -140,8 +140,22 @@ def render_result_text(result: dict) -> str:
     return "".join(parts)
 
 
+_CLI_EPILOG = r"""Usage:
+  okstra log-report [--project-root <dir>] [--cwd <dir>] [--top <N>] [--json]
+
+Output: JSON { ok, projectRoot, logsRoot, topLargest[], perTask[], totals }.
+Scans <project-root>/.okstra/tasks/**/runs/*/prompts/*.log. Each entry reports
+the wrapper transcript as transcriptBytes and its sibling prompt Markdown as
+promptBytes; sizeBytes remains the transcript-size compatibility field. Sizes
+are raw bytes and mtimes are epoch seconds — the caller formats KB/MB and ages.
+Read-only: it never deletes logs (cleanup commands stay in the skill).
+"""
+
+
 def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(
+        epilog=_CLI_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
         prog="okstra log-report",
         description="Inventory wrapper sidecar logs by size and task (read-only).")
     parser.add_argument("--project-root", default="")

package/runtime/python/okstra_ctl/manager_cli.py

@@ -3,7 +3,6 @@ from __future__ import annotations
 
 import argparse
 import json
-import os
 import sys
 from pathlib import Path
 
@@ -146,8 +145,29 @@ def _parse_child_specs(values: list[str], task_group: str, default_task_id: str)
     return specs
 
 
+_CLI_EPILOG = r"""Usage:
+  okstra manager init --manager-id <id>
+  okstra manager discover-projects
+  okstra manager new project --manager-id <id> --project-id <id> --project-root <path> [--role <role>] [--tag <tag>]
+  okstra manager new task-group --manager-id <id> --task-group <task-group>
+  okstra manager new task --manager-id <id> --task-group <task-group> --task-id <task-id> [--task <project-id:task-group:task-id>]
+  okstra manager task status --manager-id <id> --task-group <task-group> --task-id <task-id>
+  okstra manager task sync --manager-id <id> --task-group <task-group> --task-id <task-id>
+  okstra manager task assign --manager-id <id> --task-group <task-group> --task-id <task-id> --project-id <project-id>
+  okstra manager task note --manager-id <id> --task-group <task-group> --task-id <task-id> --scope <shared|project> --body <text>
+  okstra manager task run --manager-id <id> --project-id <project-id> --task-group <task-group> --task-id <task-id>
+
+  --workspace-root is owned by this command.
+"""
+_CLI_DESCRIPTION = "Manage cross-project okstra tasks."
+
+
 def _parser() -> argparse.ArgumentParser:
-    parser = argparse.ArgumentParser(prog="okstra manager")
+    parser = argparse.ArgumentParser(
+        description=_CLI_DESCRIPTION,
+        epilog=_CLI_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        prog="okstra manager")
     parser.add_argument("--json", action="store_true")
     parser.add_argument("--workspace-root", default="")
     sub = parser.add_subparsers(dest="command", required=True)
@@ -299,7 +319,6 @@ def main(argv: list[str] | None = None) -> int:
                     args.task_id,
                     args.project_id,
                     child_task_id=args.child_task_id,
-                    env=os.environ,
                 ),
                 args.json,
             )

package/runtime/python/okstra_ctl/manager_launch.py

@@ -2,7 +2,6 @@
 from __future__ import annotations
 
 from pathlib import Path
-from typing import Mapping
 
 from okstra_ctl.jsonl import append_jsonl, read_jsonl
 
@@ -19,13 +18,12 @@ from .manager_store import ManagerError, _now_iso, _read_json, _read_json_defaul
 
 
 WORKER_DISPATCH_BACKEND = "subagent"
+# child lead 는 언제나 subagent 로 뜬다. 예전에는 `$TMUX` 가 잡히면
+# `tmux-child-lead` 를 골랐지만 tmux 백엔드가 사라져 분기가 남지 않았다.
+CHILD_LEAD_BACKEND = "subagent-child-lead"
 LAUNCH_STATUS_PREPARED = "prepared"
 
 
-def select_child_lead_backend(env: Mapping[str, str]) -> str:
-    return "tmux-child-lead" if str(env.get("TMUX") or "").strip() else "subagent-child-lead"
-
-
 def _find_project(projects: dict, project_id: str) -> dict:
     for project in projects.get("projects", []):
         if isinstance(project, dict) and project.get("projectId") == project_id:
@@ -189,7 +187,6 @@ def build_launch_packet(
     project_id: str,
     *,
     child_task_id: str | None = None,
-    env: Mapping[str, str] | None = None,
     now: str | None = None,
 ) -> dict:
     manifest = _read_json(task_manifest_path(home, manager_id, task_group, task_id))
@@ -204,7 +201,6 @@ def build_launch_packet(
     target_task_key = _target_task_key(project_id, task_group, child_task_id_value)
     _validate_child_task_key(child, target_task_key)
     project_root = _validated_project_root(project)
-    backend = select_child_lead_backend(env or {})
     created_at = now or _now_iso()
     context_path = child_context_path(home, manager_id, task_group, task_id, project_id, child_task_id_value)
     context_path.parent.mkdir(parents=True, exist_ok=True)
@@ -224,7 +220,7 @@ def build_launch_packet(
         "taskId": task_id,
         "projectId": project_id,
         "taskKey": target_task_key,
-        "backend": backend,
+        "backend": CHILD_LEAD_BACKEND,
         "workerDispatchBackend": WORKER_DISPATCH_BACKEND,
         "projectRoot": project_root,
         "contextPath": str(context_path),

package/runtime/python/okstra_ctl/material.py

@@ -11,7 +11,7 @@ import json
 from pathlib import Path
 from typing import Optional
 
-from .json_boundary import load_owned_object
+from .json_boundary import JsonBoundaryError, load_owned_object
 
 
 def build_analysis_material(brief_path: Path, directive: str = "") -> str:
@@ -43,7 +43,7 @@ def resolve_related_tasks(
             existing = manifest.get("relatedTasks") or []
             if not isinstance(existing, list):
                 existing = []
-        except Exception:
+        except JsonBoundaryError:
             existing = []
     provided = [v.strip() for v in (raw_related or "").split(",") if v.strip()]
     seen: set[str] = set()

package/runtime/python/okstra_ctl/migrate.py

@@ -389,6 +389,24 @@ def _replace_in_project_rows(
     return updated, changed
 
 
+_CLI_EPILOG = r"""Dry-run by default:
+prints the migration plan as JSON and exits without touching anything.
+
+Usage:
+  okstra migrate [--apply] [--cwd <dir>] [--quiet]
+
+Options:
+  --apply   Execute the migration (git mv + .gitignore + okstra-home
+            registry row updates). Without it, preview only.
+  --cwd     Project root to migrate. Default: current directory.
+  --quiet   Single-line JSON output.
+
+Exits 1 when the migration is refused (.okstra/ already exists, or no
+legacy .project-docs/okstra/ found).
+"""
+_CLI_DESCRIPTION = "Move legacy .project-docs/okstra/ to .okstra/ (one-shot)."
+
+
 def main(argv: Optional[list[str]] = None) -> int:
     """`python3 -m okstra_ctl.migrate [--apply] [--cwd <dir>] [--quiet]`.
 
@@ -399,7 +417,11 @@ def main(argv: Optional[list[str]] = None) -> int:
     import argparse
     import sys
 
-    p = argparse.ArgumentParser(prog="okstra migrate")
+    p = argparse.ArgumentParser(
+        description=_CLI_DESCRIPTION,
+        epilog=_CLI_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        prog="okstra migrate")
     p.add_argument("--apply", action="store_true",
                    help="실제 실행 (기본: dry-run 미리보기)")
     p.add_argument("--cwd", default=".",

package/runtime/python/okstra_ctl/model_cli.py

@@ -142,7 +142,6 @@ def _catalog_row(model, adapter, role: str | None) -> dict[str, Any]:
     }
     if not model.selectable:
         row["reason"] = "not selectable"
-        return row
     if role != "leader":
         return row
     if model.provider_id != adapter.descriptor.native_provider_id:
@@ -165,9 +164,10 @@ def _catalog_row(model, adapter, role: str | None) -> dict[str, Any]:
         # resolution actually does — it accepts the model and falls back to
         # `cli-wrapper` — leaving no way to find out why a lead was not native.
         row["leaderRunner"] = "cli-wrapper"
-        row["reason"] = (
-            f"native-session unavailable ({exc}); the lead runs via cli-wrapper"
-        )
+        row["reason"] = "; ".join(filter(None, (
+            row["reason"],
+            f"native-session unavailable ({exc}); the lead runs via cli-wrapper",
+        )))
     else:
         row["leaderRunner"] = "native-session"
     return row
@@ -234,8 +234,22 @@ def _write_json_atomic(path: Path, payload: dict[str, Any]) -> None:
     write_owned_object_atomic(path, payload, artifact="model configuration")
 
 
+_CLI_EPILOG = r"""Usage:
+  okstra model list [--role <role>] [--host <host>] [--json]
+  okstra model default set <role> <modelRef[,modelRef...]> --scope project|global [--cwd <dir>]
+  okstra model default unset <role> --scope project|global [--cwd <dir>]
+
+Listing and default writes never send an inference call.
+"""
+_CLI_DESCRIPTION = "List catalog models and manage role defaults."
+
+
 def main(argv: list[str] | None = None) -> int:
-    parser = argparse.ArgumentParser(prog="okstra model")
+    parser = argparse.ArgumentParser(
+        description=_CLI_DESCRIPTION,
+        epilog=_CLI_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        prog="okstra model")
     sub = parser.add_subparsers(dest="command", required=True)
     listed = sub.add_parser("list")
     listed.add_argument("--role")

package/runtime/python/okstra_ctl/model_discovery.py

@@ -12,6 +12,12 @@ import subprocess
 from functools import lru_cache
 from pathlib import Path
 
+from .json_boundary import (
+    JsonBoundaryError,
+    external_codex_catalog_json_source,
+    load_external_json,
+)
+
 # Per-role reasoning-effort policy for CLIs that bake effort into the model
 # name (agy). Deterministic — no per-run improvisation.
 # `critic` is intentionally absent: an opt-in critic reuses its worker's
@@ -30,37 +36,16 @@ def role_effort(role: str) -> str:
     return ROLE_EFFORT.get(role, _DEFAULT_EFFORT)
 
 
-# agy lists a tier per model, but the listed slug is not always the model it
-# serves: on agy 1.1.10 a `gemini-3.1-pro-high` session identifies itself as
-# "Gemini 3.6 Flash", while `gemini-3.1-pro-low` correctly identifies as
-# "Gemini 3.1 Pro". The substitution is not visible anywhere in the dispatch —
-# `agy models` lists the slug and the run exits 0 — so it surfaces only as a
-# verifier that never refutes anything: measured over one 63-item plan-body
-# prompt, the high slug returned all-AGREE in 64s while the low slug spent 328s
-# and raised three DISAGREEs, one of them the defect claude and codex both
-# caught that round. Only the `high` tier is affected, so a role asking for any
-# other effort still resolves normally (and a tier agy does not offer still
-# hard-fails below).
-_UNTRUSTED_HIGH_TIER_EXECUTIONS = frozenset({"gemini-3.1-pro"})
-
-
-def _dispatch_effort(execution: str, role: str) -> str:
-    effort = role_effort(role).lower()
-    if effort == "high" and execution in _UNTRUSTED_HIGH_TIER_EXECUTIONS:
-        return "low"
-    return effort
-
-
-def dispatch_tier_suffixes() -> frozenset[str]:
-    """Every tier suffix dispatch can append to an agy execution value.
+def agy_tier_suffixes() -> frozenset[str]:
+    """agy 가 모델 식별자에 담는 티어 어휘.
 
-    The provider serves back the suffixed identity it was given, so reading
-    that identity means undoing exactly this set — not guessing at whatever
-    trails the last hyphen. `low` is here because `_dispatch_effort` demotes
-    the untrusted high tier to it.
+    서빙 식별자에서 티어를 벗겨 카탈로그 id 로 되돌릴 때 이 집합만 벗긴다 —
+    마지막 하이픈 뒤를 무엇이든 벗기면 카탈로그에 없는 id 를 만들어 낸다.
+    이 집합은 okstra 의 역할별 effort 정책(`ROLE_EFFORT`)이 아니라 agy 의
+    어휘다. 둘은 다르다: 정책이 지금 붙이는 것은 `high` 뿐이지만, 관측값에는
+    다른 티어가 실려 올 수 있다.
     """
-    efforts = {value.lower() for value in (*ROLE_EFFORT.values(), _DEFAULT_EFFORT)}
-    return frozenset(efforts | {"low"})
+    return frozenset({"high", "medium", "low"})
 
 
 @lru_cache(maxsize=1)
@@ -84,28 +69,42 @@ def agy_models(agy_bin: str = "agy") -> tuple[str, ...]:
     return tuple(model_id for model_id in ids if model_id)
 
 
-def _codex_config_path() -> Path:
-    return Path.home() / ".codex" / "config.toml"
+def _codex_home() -> Path:
+    return Path.home() / ".codex"
 
 
-def codex_availability(config_path: Path | None = None) -> tuple[str, ...]:
-    """Keys under [tui.model_availability_nux] in codex config, or ()."""
-    path = config_path or _codex_config_path()
+def codex_availability(codex_home: Path | None = None) -> tuple[str, ...]:
+    """Model slugs the codex CLI last fetched from the provider, or ().
+
+    The earlier source, `[tui.model_availability_nux]` in `config.toml`, is a
+    per-model onboarding-notice ledger, not an account's model list: measured
+    2026-08-26 that section held `gpt-5.5` and `gpt-5.6-sol` while this machine's
+    session history recorded 2072 turns on `gpt-5.6-terra` and 130 on
+    `gpt-5.6-luna`. Gating dispatch on it rejected models the CLI runs.
+
+    `visibility` is not filtered. It governs the CLI's own model picker, not
+    whether `--model <slug>` is accepted -- `codex-auto-review` is `hide` and is
+    dispatched by okstra today.
+    """
+    home = codex_home or _codex_home()
     try:
-        lines = path.read_text(encoding="utf-8").splitlines()
-    except OSError:
+        payload = load_external_json(
+            external_codex_catalog_json_source(home / "models_cache.json", home),
+            artifact="codex model catalog",
+        )
+    except JsonBoundaryError:
+        # No cache yet, or one this process may not read. Returning () turns the
+        # gate off rather than blocking dispatch, which is what every other
+        # discovery failure in this module does.
+        return ()
+    models = payload.get("models") if isinstance(payload, dict) else None
+    if not isinstance(models, list):
         return ()
     out: list[str] = []
-    in_section = False
-    for raw in lines:
-        line = raw.strip()
-        if line.startswith("[") and line.endswith("]"):
-            in_section = line == "[tui.model_availability_nux]"
-            continue
-        if in_section and "=" in line:
-            key = line.split("=", 1)[0].strip().strip('"')
-            if key:
-                out.append(key)
+    for entry in models:
+        slug = entry.get("slug") if isinstance(entry, dict) else None
+        if isinstance(slug, str) and slug.strip():
+            out.append(slug.strip())
     return tuple(out)
 
 
@@ -150,7 +149,7 @@ def normalize_antigravity_execution(
     # (`gemini-3.1-pro-high`) and rejects the bare slug with "requires --effort"
     # — a flag the wrapper never sends. So the suffixed form is the only
     # dispatchable spelling, including on the un-verified fallback below.
-    tiered = f"{execution}-{_dispatch_effort(execution, role)}"
+    tiered = f"{execution}-{role_effort(role).lower()}"
     if not available:
         return tiered  # discovery unavailable → dispatch anyway, wrapper still guards
     if execution in available:

package/runtime/python/okstra_ctl/model_io/__init__.py

@@ -0,0 +1 @@
+"""`okstra model-io` 의 구현. 진입점은 `..model_io_cli` 다."""

package/runtime/python/okstra_ctl/model_io/lines.py

@@ -0,0 +1,163 @@
+"""읽은 값을 고정 Markdown 줄로 바꾼다.
+
+이 층은 파일을 열지 않는다 — 이미 읽힌 매핑을 받아 문자열만 만든다. 그래서
+참조 해석과 독립이고, 서식을 고칠 때 경로 규칙을 다시 읽을 필요가 없다.
+`_provider_models` 만 예외적으로 거절하지만, 그것도 디스크가 아니라 받은
+매핑 안의 모순을 보는 것이다.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Mapping
+
+from ..fixed_text import line as _line, scalar as _value
+from ..json_boundary import JsonBoundaryError
+
+
+def _mapping(payload: Mapping[str, Any], key: str) -> Mapping[str, Any]:
+    value = payload.get(key)
+    return value if isinstance(value, Mapping) else {}
+
+
+def _project_policy_lines(project: Mapping[str, Any]) -> str:
+    packs = project.get("reviewRulePacks")
+    pack_lines = (
+        [
+            _line("Review rule pack", path)
+            for path in packs
+            if isinstance(path, str)
+        ]
+        if isinstance(packs, list)
+        else []
+    )
+    qa_lines: list[str] = []
+    qa_commands = project.get("qaCommands")
+    if isinstance(qa_commands, Mapping):
+        for category, entries in sorted(qa_commands.items()):
+            if not isinstance(entries, list):
+                continue
+            for entry in entries:
+                if not isinstance(entry, Mapping):
+                    continue
+                qa_lines.append(
+                    f"- QA `{_value(category)}` / `{_value(entry.get('label'))}`: "
+                    f"`{_value(entry.get('cmd'))}`\n"
+                )
+    return (
+        "\n## Project Review Rule Packs\n\n"
+        + ("".join(pack_lines) or "- None\n")
+        + "\n## Project QA Commands\n\n"
+        + ("".join(qa_lines) or "- None\n")
+    )
+
+
+def _assignment_line(prefix: str, assignment: Mapping[str, Any], identifier: object = None) -> str:
+    label = prefix if identifier is None else f"{prefix} `{_value(identifier)}`"
+    return (
+        f"- {label}: role `{_value(assignment.get('role'))}`; "
+        f"provider `{_value(assignment.get('provider'))}`; "
+        f"model `{_value(assignment.get('model'))}`\n"
+    )
+
+
+def _worker_assignment_lines(run: Mapping[str, Any]) -> str:
+    assignments = run.get("workerAssignments")
+    if not isinstance(assignments, list):
+        return "- None\n"
+    lines = [
+        _assignment_line("Worker", assignment, assignment.get("workerId"))
+        for assignment in assignments
+        if isinstance(assignment, Mapping)
+    ]
+    return "".join(lines) or "- None\n"
+
+
+def _worker_prompt_lines(run: Mapping[str, Any]) -> str:
+    paths = run.get("workerPromptPathByWorkerId")
+    if not isinstance(paths, Mapping):
+        return "- None\n"
+    lines = [
+        f"- Worker prompt `{_value(worker_id)}`: `{_value(path)}`\n"
+        for worker_id, path in sorted(paths.items(), key=lambda item: _value(item[0]))
+    ]
+    return "".join(lines) or "- None\n"
+
+
+def _next_phase_lines(workflow: Mapping[str, Any]) -> str:
+    pointer = _mapping(workflow, "nextRecommendedPhase")
+    return (
+        _line("Next phase", pointer.get("phase"))
+        + _line("Next phase status", pointer.get("status"))
+        + _line("Next phase rationale", pointer.get("rationale"))
+    )
+
+
+def _status_overview_text(rows: list[dict[str, object]]) -> str:
+    blocks = [_line("Task count", len(rows))]
+    for row in rows:
+        blocks.extend((
+            "\n## Task\n\n",
+            _line("Task key", row.get("taskKey")),
+            _line("Task group", row.get("taskGroup")),
+            _line("Task type", row.get("taskType")),
+            _line("Latest run status", row.get("latestRunStatus")),
+            _line("Updated at", row.get("updatedAt")),
+            _line("Latest run manifest", row.get("latestRunManifestPath")),
+            _line("Work category", row.get("workCategory")),
+            _line("Current status", row.get("currentStatus")),
+            _line("Current phase", row.get("currentPhase")),
+            _line("Current phase state", row.get("currentPhaseState")),
+            _line("Next phase", row.get("nextPhase")),
+            _line("Next phase status", row.get("nextPhaseStatus")),
+            _line("Next phase rationale", row.get("nextPhaseRationale")),
+            _line("Awaiting approval", row.get("awaitingApproval")),
+            _line("Latest report", row.get("latestReportRecordPath")),
+            _line("Latest resume command", row.get("latestResumeCommandPath")),
+            _line("Work status", row.get("workStatus")),
+        ))
+    return "# Okstra Status Input\n\n" + "".join(blocks)
+
+
+def _history_overview_text(rows: list[dict[str, object]], limit: int) -> str:
+    shown = rows[:limit]
+    blocks = [
+        _line("Task count", len(rows)),
+        _line("Shown task count", len(shown)),
+        _line("Remaining task count", max(0, len(rows) - len(shown))),
+    ]
+    for row in shown:
+        blocks.extend((
+            "\n## Task\n\n", _line("Task key", row.get("taskKey")),
+            _line("Task group", row.get("taskGroup")),
+            _line("Task type", row.get("taskType")),
+            _line("Current status", row.get("currentStatus")),
+            _line("Latest run status", row.get("latestRunStatus")),
+            _line("Last run", row.get("lastRun")),
+            _line("Latest report", row.get("latestReportRecordPath")),
+            _line("Updated at", row.get("updatedAt")),
+            _line("Latest run manifest", row.get("latestRunManifestPath")),
+        ))
+    return "# Okstra History Input\n\n" + "".join(blocks)
+
+
+def _csv(value: object) -> str:
+    return ",".join(str(item) for item in value) if isinstance(value, list) else ""
+
+
+def _provider_models(run: Mapping[str, Any]) -> dict[str, str]:
+    values: dict[str, set[str]] = {}
+    assignments = run.get("workerAssignments")
+    if isinstance(assignments, list):
+        for assignment in assignments:
+            if not isinstance(assignment, Mapping):
+                continue
+            provider = assignment.get("provider")
+            model = assignment.get("model")
+            if isinstance(provider, str) and isinstance(model, str) and model:
+                values.setdefault(provider, set()).add(model)
+    for provider, models in values.items():
+        if len(models) > 1:
+            raise JsonBoundaryError(
+                Path("workerAssignments"), "run manifest", f"conflicting models for provider {provider}"
+            )
+    return {provider: next(iter(models)) for provider, models in values.items()}