okstra 0.186.7 → 0.187.0

package/runtime/python/okstra_ctl/task_list_cli.py

@@ -0,0 +1,138 @@
+"""`okstra task-list` 의 프로젝션 — 프로젝트에 등록된 task 목록.
+
+이 코드는 원래 `src/commands/inspect/task-list.mts` 의 문자열 리터럴 안에 있었다.
+docs/coding-rules.md R1(다른 언어 소스를 문자열에 담지 않는다) 위반이었고, 그래서
+검사 도구도 테스트도 닿지 않았다. 로직은 그대로 옮겼다 — 이 모듈은 새 동작을
+만들지 않는다.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from okstra_project import (
+    ResolverError,
+    list_project_tasks,
+    read_latest_task,
+    resolve_project_root,
+)
+
+from .fixed_text import line
+
+
+def render_text(payload: dict) -> str:
+    """모델용 고정 텍스트 투영. 줄 형식은 `fixed_text.line` 이 단일 기준점이다."""
+    parts = ["# Okstra Task List\n\n", line("Task count", len(payload["tasks"]))]
+    for task in payload["tasks"]:
+        parts.extend((
+            "\n## Task\n\n",
+            line("Task key", task.get("taskKey")),
+            line("Task type", task.get("taskType")),
+            line("Task group", task.get("taskGroup")),
+            line("Title", task.get("title") or task.get("taskTitle")),
+            line("Latest run status", task.get("latestRunStatus")),
+            line("Updated at", task.get("updatedAt")),
+        ))
+    return "".join(parts)
+
+
+def render_resolve_failure(reason: str) -> str:
+    return (
+        "Okstra task list\n"
+        + line("Status", "error")
+        + line("Failure stage", "resolve")
+        + line("Failure reason", reason)
+    )
+
+
+def collect(
+    project_root: Path,
+    *,
+    task_type: str | None = None,
+    latest_run_status: str | None = None,
+    task_group: str | None = None,
+    limit: int | None = None,
+) -> dict:
+    return {
+        "ok": True,
+        "projectRoot": str(project_root),
+        "tasks": list_project_tasks(
+            project_root,
+            task_type=task_type,
+            latest_run_status=latest_run_status,
+            task_group=task_group,
+            limit=limit,
+        ),
+        "latest": read_latest_task(project_root),
+    }
+
+
+_CLI_EPILOG = r"""Usage:
+  okstra task-list                            Resolve PROJECT_ROOT from cwd, list tasks
+  okstra task-list --cwd <dir>                Start resolution from <dir> instead of cwd
+  okstra task-list --project <dir>            Use <dir> directly as PROJECT_ROOT
+  okstra task-list --task-type <type>         Filter by taskType
+  okstra task-list --latest-run-status <s>    Filter by latestRunStatus
+  okstra task-list --task-group <group>       Filter by taskGroup
+  okstra task-list --limit <N>                Keep the first N (catalog is updatedAt desc)
+  okstra task-list --text                     Emit fixed task identity fields for model use
+
+Output: default emits JSON { ok, projectRoot, tasks: [...], latest: {...}|null }.
+--text emits fixed task key/type/group/title/latest-status/updated fields.
+Filters are AND-combined and all optional.
+"""
+_CLI_DESCRIPTION = "List okstra tasks registered in this project."
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        description=_CLI_DESCRIPTION,
+        epilog=_CLI_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        prog="okstra task-list")
+    parser.add_argument("--project-root", "--project", default="",
+                        help="use this directory as PROJECT_ROOT")
+    parser.add_argument("--cwd", default=".",
+                        help="resolve PROJECT_ROOT starting from here")
+    parser.add_argument("--task-type", default="", help="filter by taskType")
+    parser.add_argument("--latest-run-status", default="",
+                        help="filter by latestRunStatus")
+    parser.add_argument("--task-group", default="", help="filter by taskGroup")
+    parser.add_argument("--limit", default="",
+                        help="keep the first N (the catalog is updatedAt desc)")
+    mode = parser.add_mutually_exclusive_group()
+    mode.add_argument("--json", dest="output_mode", action="store_const",
+                      const="json", default="json", help="emit JSON (default)")
+    mode.add_argument("--text", dest="output_mode", action="store_const",
+                      const="text", help="emit fixed task identity fields")
+    args = parser.parse_args(argv)
+
+    try:
+        resolved = resolve_project_root(
+            explicit_root=args.project_root, cwd=args.cwd
+        )
+    except ResolverError as exc:
+        if args.output_mode == "text":
+            print(render_resolve_failure(str(exc)), end="")
+        else:
+            print(json.dumps({"ok": False, "stage": "resolve", "reason": str(exc)}))
+        return 2
+
+    payload = collect(
+        Path(resolved),
+        task_type=args.task_type or None,
+        latest_run_status=args.latest_run_status or None,
+        task_group=args.task_group or None,
+        limit=int(args.limit) if args.limit else None,
+    )
+    if args.output_mode == "text":
+        print(render_text(payload), end="")
+    else:
+        print(json.dumps(payload, default=str))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/runtime/python/okstra_ctl/task_show_cli.py

@@ -0,0 +1,66 @@
+"""`okstra task-show` 의 프로젝션 — 한 task 의 매니페스트·워크플로 상태 요약.
+
+원래 `src/commands/inspect/task-show.mts` 의 문자열 리터럴 안에 있던 코드다
+(docs/coding-rules.md R1 위반). 로직은 그대로 옮겼다.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+from okstra_project import (
+    ResolverError,
+    StateError,
+    resolve_project_root,
+    task_read_side_snapshot,
+)
+
+
+_CLI_EPILOG = r"""Usage:
+  okstra task-show <task-key>                  task-key is project-id:task-group:task-id
+  okstra task-show <task-key> --cwd <dir>      Resolve PROJECT_ROOT from <dir>
+  okstra task-show <task-key> --project <dir>  Use <dir> directly as PROJECT_ROOT
+
+Output: JSON with taskKey, taskType, taskRoot, brief path, workflow phases,
+artifacts, modelAssignments, latestRunPath.
+"""
+_CLI_DESCRIPTION = "Summarize a task's manifest and workflow state."
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        description=_CLI_DESCRIPTION,
+        epilog=_CLI_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        prog="okstra task-show")
+    parser.add_argument("task_key", metavar="task-key",
+                        help="project-id:task-group:task-id")
+    parser.add_argument("--project-root", "--project", default="",
+                        help="use this directory as PROJECT_ROOT")
+    parser.add_argument("--cwd", default=".",
+                        help="resolve PROJECT_ROOT starting from here")
+    args = parser.parse_args(argv)
+
+    try:
+        resolved = resolve_project_root(explicit_root=args.project_root, cwd=args.cwd)
+    except ResolverError as exc:
+        print(json.dumps({"ok": False, "stage": "resolve", "reason": str(exc)}))
+        return 2
+
+    try:
+        snapshot = task_read_side_snapshot(Path(resolved), args.task_key)
+    except StateError as exc:
+        print(json.dumps({
+            "ok": False,
+            "stage": getattr(exc, "stage", None) or "task_snapshot",
+            "reason": str(exc),
+        }))
+        return 1
+
+    print(json.dumps({"ok": True, **snapshot}, ensure_ascii=False, default=str, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/runtime/python/okstra_ctl/task_target.py

@@ -14,6 +14,10 @@ from okstra_project import (
     resolve_project_root,
 )
 
+# 순수 경로 계산은 paths 가 소유한다. 여기 있는 동안 stage_map·stage_ledger 가
+# 그 함수 하나 때문에 이 모듈을 거쳐 okstra_project 전체를 끌어왔다.
+from .paths import infer_project_root, project_rel  # noqa: F401 — 재노출
+
 
 def resolve_task_root(target: str, project_root: str, cwd: str) -> tuple[Path, Path]:
     target_path = Path(target).expanduser()
@@ -40,19 +44,3 @@ def resolve_task_root(target: str, project_root: str, cwd: str) -> tuple[Path, P
     return task_root.resolve(), resolved_project
 
 
-def infer_project_root(task_root: Path) -> Path:
-    parts = task_root.parts
-    if ".okstra" not in parts:
-        return task_root
-    # The okstra subtree (.okstra/tasks/...) introduces the deepest ".okstra"
-    # segment; a project checked out under a path that itself contains
-    # ".okstra" must not resolve to that outer segment.
-    idx = len(parts) - 1 - parts[::-1].index(".okstra")
-    return Path(*parts[:idx]).resolve()
-
-
-def project_rel(path: Path, project_root: Path) -> str:
-    try:
-        return str(path.resolve().relative_to(project_root.resolve()))
-    except ValueError:
-        return str(path)

package/runtime/python/okstra_ctl/team.py

@@ -26,6 +26,7 @@ from .dispatch_state import (
     TEARDOWN_BEFORE_TERMINAL_REASON,
     TERMINAL_WORKER_STATUSES,
     mutate_team_state,
+    utc_now,
 )
 from .dispatch_core import (
     BACKEND_CLI_WRAPPER,
@@ -64,8 +65,41 @@ def main(argv: Sequence[str] | None = None) -> int:
     return 2
 
 
+_CLI_EPILOG = r"""Usage:
+  okstra team dispatch --project-root <dir> --run-manifest <path> \
+    [--workers <csv>] [--jobs-file <path>] [--dry-run] \
+    [--idle-timeout-seconds <n>] [--dispatch-kind <kind>]
+  okstra team await --project-root <dir> --run-manifest <path> \
+    [--poll-interval-seconds <n>] [--timeout-seconds <n>] \
+    [--heartbeat-seconds <n>] [--json]
+  okstra team reclaim --project-root <dir> --run-manifest <path> \
+    [--dry-run] [--json]
+  okstra team teardown --project-root <dir> --run-manifest <path> \
+    [--dry-run] [--json]
+
+Who may use it is read from the run manifest, never from a flag. A cmux run
+(terminalBackend=cmux-pane) admits any lead, because okstra owns the panes there
+rather than the host. Outside cmux it is refused unless the lead's host
+descriptor owns the team lifecycle (launch_mode=team) — a worker there is a CLI
+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.
+  teardown  end of run: closes every recorded pane and writes off any dispatch
+            that never reached a terminal status.
+
+  --workspace-root and --okstra-bin are owned by this command.
+"""
+_CLI_DESCRIPTION = "Dispatch, await, and close okstra-owned worker panes."
+
+
 def _parser() -> argparse.ArgumentParser:
-    parser = argparse.ArgumentParser(prog="okstra team")
+    parser = argparse.ArgumentParser(
+        description=_CLI_DESCRIPTION,
+        epilog=_CLI_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        prog="okstra team")
     parser.add_argument("--workspace-root", required=True)
     parser.add_argument("--okstra-bin", required=True)
     sub = parser.add_subparsers(dest="command", required=True)
@@ -363,12 +397,25 @@ def _append_pane(panes: list[dict[str, str]], seen: set[str], pane_id: str, kind
 
 
 def _mark_teardown_errors(team_state_path: Path) -> None:
+    """Write off everything still non-terminal — dispatches and roster rows both.
+
+    로스터 행과 디스패치 행은 같은 사실을 두 눈금으로 적은 것이다. 디스패치만
+    정리하면 마지막 시도가 종결에 못 간 워커의 로스터 행이 `in-progress` 로 남고,
+    `okstra team await` 는 디스패치만 보므로 완료라고 보고한다. 그 상태로는
+    `validate-run` 의 `invalid terminal status` 를 풀 수 있는 명령이 이 경로에
+    없다 — teardown 이 안 하면 아무도 안 한다.
+    """
     def mark(payload: dict[str, Any]) -> bool:
         changed = False
-        for record in payload.get("workerDispatches", []):
+        rows = [
+            *payload.get("workerDispatches", []),
+            *payload.get("workers", []),
+        ]
+        for record in rows:
             if isinstance(record, dict) and record.get("status") not in TERMINAL_WORKER_STATUSES:
                 record["status"] = "error"
                 record["reason"] = TEARDOWN_BEFORE_TERMINAL_REASON
+                record.setdefault("endedAt", utc_now())
                 changed = True
         return changed
 

package/runtime/python/okstra_ctl/time_report.py

@@ -78,8 +78,11 @@ def wall_clock_ms(state: dict) -> int:
                 continue
             try:
                 times.append(_parse_iso(raw))
-            except (TypeError, ValueError):
-                pass
+            except (TypeError, ValueError) as exc:
+                # 버리면 그 블록이 구간 계산에서 빠져 duration 이 실제보다 짧게
+                # 나오는데, 표에는 정상 값처럼 찍힌다.
+                print(f"time-report: skipping an unparseable {key} "
+                      f"({raw!r}) — {exc}", file=sys.stderr)
     if len(times) < 2:
         return 0
     return int((max(times) - min(times)).total_seconds() * 1000)
@@ -256,8 +259,20 @@ def render_result_text(result: dict) -> str:
     return "".join(parts)
 
 
+_CLI_EPILOG = r"""Usage:
+  okstra time-report <task-key> [--project-root <dir>] [--cwd <dir>] [--json]
+  okstra time-report <task-root-path> [--json]
+
+Output: JSON { ok, taskKey, byTaskType[], grandTotal, perWorker{}, perRunWallClock[],
+phaseTimelines[], unavailable[] }. All durations are raw milliseconds — the caller
+formats HH:MM:SS and renders tables. This is read-only; it never mutates task state.
+"""
+
+
 def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(
+        epilog=_CLI_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
         prog="okstra time-report",
         description="Aggregate elapsed work time across a task's runs (raw ms).")
     parser.add_argument("target", help="task root path or task-key")

package/runtime/python/okstra_ctl/usage_report.py

@@ -260,8 +260,19 @@ def _positive_days(value: str) -> int:
     return days
 
 
+_CLI_EPILOG = r"""Usage:
+  okstra usage-report [--days <positive-int>] [--project-root <dir>] [--cwd <dir>] [--json]
+
+Read-only. Prints JSON containing run coverage, raw and billable-equivalent
+tokens, known USD cost, CPU-sum time, and wall-clock time grouped by task type.
+The default window is the current project's last 30 days.
+"""
+
+
 def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(
+        epilog=_CLI_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
         prog="okstra usage-report",
         description="Aggregate recent project usage by task type.",
     )