okstra 0.189.4 → 0.191.0

package/runtime/python/okstra_token_usage/collect.py

@@ -19,6 +19,7 @@ from .codex import (
     codex_session_ids,
     codex_session_is_worker,
     codex_session_total,
+    codex_session_window_total,
     find_codex_sessions,
 )
 from .antigravity import (
@@ -32,9 +33,9 @@ from .grok import (
     grok_session_is_non_interactive,
     grok_session_total,
 )
-from .paths import claude_project_dir, utc_now
+from .paths import claude_project_dir, find_session_jsonl, utc_now
 from .pricing import antigravity_cost_usd, provider_cost_usd
-from okstra_ctl.dispatch_state import worker_session_ids
+from okstra_ctl.dispatch_state import worker_dispatch_records, worker_session_ids
 from okstra_ctl.models import provider_wrappers
 from okstra_ctl.wrapper_status import (
     log_path_for_prompt,
@@ -637,10 +638,18 @@ def _cli_sessions_for_windows(
     return sessions
 
 
-def _cli_session_totals(provider: str, session_paths: list[Path]) -> list[dict]:
+def _cli_session_totals(
+    provider: str,
+    session_paths: list[Path],
+    *,
+    window: tuple[str, str] | None = None,
+) -> list[dict]:
+    """세션별 합계. `window` 는 codex 리드 전용 — run 보다 먼저 열린 세션을 창으로 자른다."""
     totals = []
     for session_path in session_paths:
-        if provider == "codex":
+        if provider == "codex" and window is not None:
+            total = codex_session_window_total(session_path, *window)
+        elif provider == "codex":
             total = codex_session_total(session_path)
         elif provider == "antigravity":
             total = (
@@ -778,19 +787,50 @@ def collect_cli_usage(
     return block
 
 
-def _worker_cli_windows(
-    project_root: Path,
-    worker: dict,
-    fallback_windows: list[tuple[str, str]],
-) -> tuple[list[tuple[str, str]], Path | None, bool]:
-    prompt_path = _resolve_project_path(project_root, str(worker.get("promptPath") or ""))
+def _prompt_cli_window(
+    project_root: Path, prompt_path_raw: str,
+) -> tuple[tuple[str, str] | None, Path | None]:
+    """한 dispatch 의 래퍼 창 — 프롬프트 옆 status 사이드카의 started/ended."""
+    prompt_path = _resolve_project_path(project_root, prompt_path_raw)
     status_path = status_path_for_prompt(prompt_path) if prompt_path is not None else None
     execution = wrapper_execution(status_path)
     started_at = execution.get("startedAt")
-    ended_at = execution.get("endedAt")
-    if started_at:
-        return [(started_at, ended_at or utc_now())], status_path, False
-    return fallback_windows, status_path, True
+    if not started_at:
+        return None, status_path
+    return (started_at, execution.get("endedAt") or utc_now()), status_path
+
+
+def _worker_prompt_paths(worker: dict, records: list[dict]) -> list[str]:
+    """이 워커가 띄운 dispatch 의 프롬프트 경로 전부 — 원장 행이 없으면(v1) 명부 행의 하나."""
+    paths: list[str] = []
+    for record in records:
+        raw = str(record.get("promptPath") or "").strip()
+        if raw and raw not in paths:
+            paths.append(raw)
+    if not paths:
+        raw = str(worker.get("promptPath") or "").strip()
+        if raw:
+            paths.append(raw)
+    return paths
+
+
+def _worker_session_cwds(project_root: Path, records: list[dict]) -> list[Path]:
+    """세션 디렉터리가 인코딩된 cwd 후보 — grok·kimi 는 워크트리 안에서 돈다.
+
+    `providers/grok/adapter.py` 는 `request.worktree_path or request.project_root`
+    를 cwd 로 넘기고 세션 디렉터리는 그 경로를 퍼센트 인코딩한 이름이다. 프로젝트
+    루트로만 찾으면 워크트리 안에서 돈 세션은 0건이다(실측 2026-09-08 jobs
+    implementation-planning r01: grok critic 세션이 워크트리 이름 아래 있었다).
+    codex·claude 는 루트에서 돌므로 워크트리 후보는 빈 결과로 끝난다.
+    """
+    cwds: list[Path] = []
+    for record in records:
+        raw = str(record.get("worktreePath") or "").strip()
+        if raw and Path(raw) not in cwds:
+            cwds.append(Path(raw))
+    if project_root not in cwds:
+        cwds.append(project_root)
+    return cwds
 
 
 def _antigravity_usage_sources(
@@ -828,25 +868,114 @@ def _worker_cli_usage_block(
     provider: str,
     project_root: Path,
     worker: dict,
+    records: list[dict],
     fallback_windows: list[tuple[str, str]],
 ) -> dict:
-    """공급자 프로세스 트랜스크립트와 실행 증거로 워커 사용량 블록을 만든다."""
-    windows, status_path, used_fallback = _worker_cli_windows(
-        project_root,
-        worker,
-        fallback_windows,
-    )
-    session_paths = _cli_sessions_for_windows(provider, project_root, windows)
+    """공급자 프로세스 트랜스크립트와 실행 증거로 워커 사용량 블록을 만든다.
+
+    dispatch 원장 행마다 래퍼 창을 하나씩 잡아 그 창의 세션을 전부 합산한다 —
+    재검증·critic-gap·plan-verify 로 다시 띄운 실행이 각각 새 세션이므로
+    첫 프롬프트 하나만 보면 나머지는 통째로 빠진다. 실행 상태는 마지막
+    dispatch 의 것, 소요 시간은 래퍼 창의 합이다.
+    """
+    windows: list[tuple[str, str]] = []
+    prompt_paths = _worker_prompt_paths(worker, records)
+    status_paths: list[Path | None] = []
+    for raw in prompt_paths:
+        window, status_path = _prompt_cli_window(project_root, raw)
+        status_paths.append(status_path)
+        if window is not None:
+            windows.append(window)
+    used_fallback = not windows
+    if used_fallback:
+        windows = fallback_windows
+    session_paths: list[Path] = []
+    for cwd in _worker_session_cwds(project_root, records):
+        for path in _cli_sessions_for_windows(provider, cwd, windows):
+            if path not in session_paths:
+                session_paths.append(path)
+    status_path = status_paths[-1] if status_paths else None
     if provider == "antigravity":
-        for source in _antigravity_usage_sources(project_root, worker, status_path):
-            if source not in session_paths:
-                session_paths.append(source)
-    return collect_cli_usage(
+        for raw, source_status in zip(prompt_paths, status_paths):
+            for source in _antigravity_usage_sources(
+                project_root, {"promptPath": raw}, source_status,
+            ):
+                if source not in session_paths:
+                    session_paths.append(source)
+    block = collect_cli_usage(
         provider=provider,
         status_path=status_path,
         sessions=session_paths,
         fallback_window_used=used_fallback,
     )
+    durations = [
+        wrapper_execution(path).get("durationMs")
+        for path in status_paths
+        if path is not None
+    ]
+    measured = [value for value in durations if isinstance(value, int)]
+    if len(measured) > 1:
+        block["durationMs"] = sum(measured)
+    return block
+
+
+def _wrapper_claude_worker(worker: dict) -> bool:
+    """호스트가 claude 가 아닐 때 래퍼로 띄운 claude 워커."""
+    provider = str(worker.get("provider") or worker.get("agent") or "").strip()
+    runner = str(worker.get("runner") or "").strip()
+    return provider in _SESSION_JSONL_PROVIDERS and runner in {"", "cli-wrapper"}
+
+
+def _claude_wrapper_usage_block(
+    *,
+    project_root: Path,
+    worker_id: str,
+    state: dict,
+    window: tuple[str | None, str | None],
+    incremental: bool,
+) -> dict:
+    """래퍼로 띄운 claude 워커의 세션 jsonl — dispatch 가 발급한 세션 id 로 찾는다.
+
+    `okstra-claude-exec.sh` 는 `claude -p --session-id <id>` 로 돌고 그 id 는
+    `workerDispatches[].sessionId` 에 적힌다(`_dispatch_record`). 트랜스크립트는
+    `~/.claude/projects/<루트 인코딩>/<id>.jsonl` 에 있는데, claude 가 아닌
+    호스트의 수집기는 이 워커를 "세션 jsonl 공급자" 라며 건너뛰어 항상
+    `unavailable` 이었다(실측 2026-09-08 jobs implementation-planning r01:
+    claude planner 5회·report-writer 2회 세션이 전부 디스크에 있었다). claude
+    호스트의 `collect_claude_runtime_usage` 가 같은 id 로 하는 일을 여기서 한다.
+    """
+    since, until = window
+    session_ids = worker_session_ids(state, worker_id)
+    if not session_ids:
+        return na_block(
+            "claude wrapper worker has no dispatch session id recorded in workerDispatches"
+        )
+    totals: list[dict] = []
+    paths: list[Path] = []
+    attributed: list[str] = []
+    for session_id in session_ids:
+        path = find_session_jsonl(session_id, project_root)
+        if path is None:
+            continue
+        session_totals = claude_session_totals(
+            path, since=since, until=until, incremental=incremental,
+        )
+        # 창 밖 세션은 0 토큰 totals 가 되어 허위 0 으로 보고된다 — claude 호스트
+        # 경로와 같은 `startedAt` 검사로 거른다.
+        if not session_totals.get("startedAt"):
+            continue
+        totals.append(session_totals)
+        paths.append(path)
+        attributed.append(session_id)
+    if not totals:
+        return na_block(
+            "claude session jsonl not found under "
+            f"{claude_project_dir(project_root)} for dispatch session ids {session_ids}"
+        )
+    block = usage_block(_aggregate_totals(totals), source="claude-jsonl")
+    block["sessionIds"] = attributed
+    block["sessionPaths"] = [str(path) for path in paths]
+    return block
 
 
 def _attach_cli_usage(
@@ -886,27 +1015,46 @@ def _attach_cli_usage(
 
 
 def _collect_cli_runtime_usage(
-    state: dict, project_root: Path, team_state_path: Path | None = None,
+    state: dict,
+    project_root: Path,
+    team_state_path: Path | None = None,
+    *,
+    incremental: bool = True,
 ) -> dict:
     windows_by_worker = _codex_worker_windows(project_root, state)
+    run_window: tuple[str | None, str | None] = (None, None)
+    if team_state_path is not None:
+        run_window = resolve_run_window(team_state_path, state)
     for worker in state.get("workers", []):
         if not isinstance(worker, dict):
             continue
+        worker_id = str(worker.get("workerId") or "").strip()
+        records = [
+            dict(record) for record in worker_dispatch_records(state, worker_id)
+        ] if worker_id else []
         provider = _cli_assignment_provider(worker)
-        if not provider:
+        if provider:
+            worker["usage"] = _worker_cli_usage_block(
+                provider=provider,
+                project_root=project_root,
+                worker=worker,
+                records=records,
+                fallback_windows=windows_by_worker.get(worker_id, []),
+            )
+        elif worker_id and _wrapper_claude_worker(worker):
+            worker["usage"] = _claude_wrapper_usage_block(
+                project_root=project_root,
+                worker_id=worker_id,
+                state=state,
+                window=run_window,
+                incremental=incremental,
+            )
+        else:
             worker["usage"] = na_block(
                 "worker usage is not read from a provider CLI transcript "
-                "(host-native, session-jsonl provider, or no registered CLI provider): "
+                "(host-native or no registered CLI provider): "
                 f"{worker.get('provider') or worker.get('agent') or worker.get('workerId')}"
             )
-            continue
-        worker_id = str(worker.get("workerId") or "").strip()
-        worker["usage"] = _worker_cli_usage_block(
-            provider=provider,
-            project_root=project_root,
-            worker=worker,
-            fallback_windows=windows_by_worker.get(worker_id, []),
-        )
     state["leadUsage"] = _cli_lead_usage(state, project_root, team_state_path)
     _populate_usage_summary(state, team_name=resolve_team_name(state),
                             sessions_found=0, needle_source="none")
@@ -952,22 +1100,29 @@ def _cli_lead_usage(
         if isinstance(worker, dict)
         for path in ((worker.get("usage") or {}).get("cliSessionPaths") or [])
     }
+    # in-session codex 리드는 run 보다 먼저 열린 세션이다 — 창 안에서 시작한
+    # 세션만 보면 없다고 나오고, 세션 전체를 더하면 다른 task 의 턴이 섞인다.
+    # 창 안에서 활동한 세션을 후보에 넣고 토큰은 창으로 잘라 센다.
+    window = (run_since, run_until) if provider == "codex" else None
+    if provider == "codex":
+        candidates = find_codex_sessions(
+            project_root, run_since, run_until, active_before_start=True,
+        )
+    else:
+        candidates = _cli_sessions_for_windows(
+            provider, project_root, [(run_since, run_until)],
+        )
     sessions = _select_cli_lead_sessions(
         provider,
-        [
-            path
-            for path in _cli_sessions_for_windows(
-                provider, project_root, [(run_since, run_until)],
-            )
-            if path not in worker_paths
-        ],
+        [path for path in candidates if path not in worker_paths],
         state,
+        window=window,
     )
-    totals = _cli_session_totals(provider, sessions)
+    totals = _cli_session_totals(provider, sessions, window=window)
     if not totals:
         return na_block(
             f"{provider} lead usage accounting is unavailable because no host session "
-            "started in the run window."
+            "was active in the run window."
         )
     return _cli_usage_block(provider, _aggregate_totals(totals), sessions)
 
@@ -981,7 +1136,11 @@ def _cli_worker_session(provider: str, path: Path) -> bool:
 
 
 def _select_cli_lead_sessions(
-    provider: str, sessions: list[Path], state: dict,
+    provider: str,
+    sessions: list[Path],
+    state: dict,
+    *,
+    window: tuple[str, str] | None = None,
 ) -> list[Path]:
     """워커 래퍼 세션을 빼고, 아이디가 있으면 그 세션, 없으면 벽시계가 가장 긴 대화."""
     candidates = [
@@ -997,7 +1156,7 @@ def _select_cli_lead_sessions(
     best = candidates[0]
     best_ms = -1
     for path in candidates:
-        totals = _cli_session_totals(provider, [path])
+        totals = _cli_session_totals(provider, [path], window=window)
         total = totals[0] if totals else {}
         wall = _wall_ms(total.get("startedAt"), total.get("endedAt")) if total else None
         if wall is None:
@@ -1056,14 +1215,22 @@ def _populate_usage_summary(
         worker_cost += unattributed_usage.get("estimatedCostUsd", 0) or 0
 
     unmatched_models: list[str] = []
-    if lead.get("model") and lead.get("estimatedCostUsd") is None and (lead.get("totalTokens") or 0) > 0:
+    if (
+        lead.get("model")
+        and lead.get("estimatedCostUsd") is None
+        and lead.get("cliEstimatedCostUsd") is None
+        and (lead.get("totalTokens") or 0) > 0
+    ):
         unmatched_models.append(lead["model"])
     for w in workers:
         u = w.get("usage") or {}
+        # CLI 블록의 가격은 `cliEstimatedCostUsd` 에 붙는다 — 그 키를 안 보면
+        # 가격이 붙은 grok 도 미매칭으로 찍힌다.
         if (
             u.get("source") not in {"codex-cli", "agy-cli"}
             and u.get("model")
             and u.get("estimatedCostUsd") is None
+            and u.get("cliEstimatedCostUsd") is None
             and (u.get("totalTokens") or 0) > 0
         ):
             unmatched_models.append(u["model"])
@@ -1269,6 +1436,12 @@ def collect_claude_runtime_usage(
                     provider=provider,
                     project_root=cwd,
                     worker=worker,
+                    records=[
+                        dict(record)
+                        for record in worker_dispatch_records(
+                            state, str(worker_id or "").strip()
+                        )
+                    ] if worker_id else [],
                     fallback_windows=cli_windows_by_worker.get(
                         str(worker_id or "").strip(), []
                     ),
@@ -1363,7 +1536,9 @@ def collect_cli_runtime_usage(
 ) -> dict:
     state = json.loads(team_state_path.read_text())
     cwd = project_root or _infer_project_root(team_state_path, state)
-    return _collect_cli_runtime_usage(state, cwd, team_state_path)
+    return _collect_cli_runtime_usage(
+        state, cwd, team_state_path, incremental=incremental,
+    )
 
 
 def collect(

package/runtime/python/okstra_token_usage/pricing.py

@@ -59,8 +59,12 @@ CLAUDE_PRICING = {
     # Claude Opus 5.
     "opus-5":     (5.0, 6.25, 0.50, 25.0),     # Opus 5 (cache prices derived from ratios)
 
-    # Claude Sonnet 5.
-    "sonnet-5":   (3.0, 3.75, 0.30, 15.0),     # Sonnet 5 (cache prices derived from ratios)
+    # Claude Sonnet 5 — $2/$10 launched as introductory pricing and became the
+    # standard price (the announced 2026-09-01 rise to $3/$15 was withdrawn;
+    # platform.claude.com/docs/en/about-claude/pricing, read 2026-09-08). The
+    # old (3.0, 3.75, 0.30, 15.0) row was the Sonnet 4.6 rate and overbilled
+    # every Sonnet 5 worker by 1.5x.
+    "sonnet-5":   (2.0, 2.50, 0.20, 10.0),     # Sonnet 5 (cache prices derived from ratios)
 
     # Claude 4 point releases (explicit so future divergence is easy to see).
     "opus-4-8":   (5.0, 6.25, 0.50, 25.0),     # Opus 4.8 (cache prices derived from ratios)
@@ -90,8 +94,8 @@ _LEGACY_CODEX_PRICING = {
 
     # GPT-5 series.
     # gpt-5.6 was dropped from the provider catalog; its rate stays so past runs
-    # keep pricing. Substring matching means sol / terra / luna resolve here too
-    # -- the 5.6 family rate, not a per-variant price we have a source for.
+    # keep pricing. sol / terra / luna no longer land here: their catalog rows
+    # carry per-variant prices, and `_match_pricing` prefers the longer key.
     "gpt-5.6":      (5.00,  0.50,  30.0),
     "gpt-5.2-pro":  (21.0,  2.10,  168.0),
     "gpt-5.1":      (1.25,  0.125, 10.0),

package/runtime/skills/okstra-brief-gen/SKILL.md

@@ -222,6 +222,11 @@ Order of operations:
    questions into one. When you relay this preflight, tell the user in one
    line *why* task group comes first (it scopes where this ticket's brief —
    and any sub-ticket briefs — are written).
+
+   **Enforced:** `validators/validate-brief.py` requires the brief's
+   directory segment to equal the slugified frontmatter `task-group`, so a
+   brief written before the group is known — or under an invented placeholder
+   group — fails validation rather than landing in the wrong tree.
 1. `AskUserQuestion` (free text):
    `"Ticket key or URL (e.g. LIN-1234, PROJ-42, https://linear.app/..., https://your.atlassian.net/browse/...)"` →
    `ticket_ref`. Issue this only **after** Step 2a's task-group answer is in
@@ -451,6 +456,8 @@ to Source Material body, not to the filename):
 Validate the full `<ticket-id>-<file-title>` slug: must have at least one
 alphanumeric character after slugification. Apply Step 2c on collision.
 
+**Enforced:** `validators/validate-brief.py` checks the brief's filename and its task-group directory segment against the slugified frontmatter `task-group`, and rejects a Source Material section whose entry does not match the source it names.
+
 ### 2c. Collision handling
 
 If a brief file already exists, `AskUserQuestion` with (`Skip` /
@@ -546,6 +553,8 @@ empty or trivially thin **after** reading Source Material verbatim, ask **at
 most one** `AskUserQuestion` to fill it. Never ask about sections already
 covered by the source material.
 
+**Enforced:** `validators/validate-brief.py` fails a brief whose required section is missing, is left as a template placeholder (`is_placeholder`), or carries only the template's own example lines (`is_template_example`) — so a section skipped here does not pass as filled.
+
 ### Sharpening pass (bounded grill)
 
 The following rules absorb the useful parts of `grill-me` /
@@ -656,6 +665,8 @@ labels. Unlabelled augmentation is rejected as half-formed translation.
 **Inline form** — `> augmented: intent-inference — <one line>`.
 **Section form** — `- intent-inference: <one line>` under `Augmentation`.
 
+**Enforced:** `validators/validate-brief.py` reads both forms (`inline_augmented_blockquotes`, `augmentation_entries`) and fails a brief whose entry carries a label outside this table (`parse_augmentation_label`).
+
 ### Auto-mirroring rule
 
 Every `intent-inference` entry must have a paired entry in `Open Questions`
@@ -1014,13 +1025,21 @@ per-page ratio instead of origin load). If the file is absent, ask once via
 
 Never fill the skeleton yourself from the tickets: a ticket summary decides
 nothing, and the sections ask for what the tickets do not say. If the file
-exists, leave it untouched and mention its path in the hand-off block.
+exists, leave it untouched and mention its path in the hand-off block. The
+file's trailing `## Task Memory` region (between `<!-- okstra:task-memory:begin -->`
+and `end`) is okstra's: `report-finalize` rewrites it after every run with the
+group's start order and each task's latest conclusion, and a group whose
+runs finished before anyone created the file already has one holding that
+region alone — `init` then inserts the human sections above it.
 
 Then stop. Do not invoke `okstra-run` directly — the user chooses when to
 proceed, and they may want to edit the brief externally first. In the
 multi-brief case the user also decides the order in which tasks are
-started. When a skeleton was created in 7a, add one line to the hand-off
-block:
+started; the brief ordinal in each brief id (`<TICKET>-<n>-<slug>`) is what
+okstra reads as the group's start order (`Related Task Graph` edges are
+quoted beside it as `waits for`, never reordering), so number the briefs in
+the order the user wants them started. When a
+skeleton was created in 7a, add one line to the hand-off block:
 
 ```
 group context skeleton: <abs>/<task-group>/group-context.md   (fill before /okstra-run)

package/runtime/skills/okstra-chat/SKILL.md

@@ -48,10 +48,12 @@ If the host has a native picker, use it. Otherwise print a numbered list.
 1. Run `okstra chat rooms`.
 2. If the output is `no rooms`, say so and offer create.
 3. Otherwise pick a room from that list (picker, or numbered list if the picker limit is exceeded).
-4. Ask for the display name as free input.
-5. Run `okstra chat join --room <room> --name <display>`.
+4. Run `okstra chat members --room <room>`.
+5. Ask for the display name as free input.
+6. If that name is not in the members output, run `okstra chat join --room <room> --name <display>`.
+7. If that name is already in the members output, ask one question: is this session already in the room under that name (for example, it joined before the conversation was summarized)? If yes, do not run join; continue with `--as <display>`. If no, ask for a different display name and go back to 6.
 
-`--name` is required. An empty name, `all`, or a name already in the room fails.
+`--name` is required. An empty name, `all`, or a name already in the room fails. `display name already taken` after a context loss means step 7, not a new name.
 
 ## Step 2: Unread
 
@@ -59,7 +61,7 @@ If the host has a native picker, use it. Otherwise print a numbered list.
 okstra chat unread --room <room> --as <display>
 ```
 
-Show the rows. Each row is `id @from YYYY-MM-DD HH:MM body`. Sender is always `@name`. The id is the first token (before the first space). A reply inserts `↑<parentId>` after the time. Recipient is not on the line.
+Show the rows. Each row is `id @from YYYY-MM-DD HH:MM body`. Sender is always `@name`. The id is the first token (before the first space). A reply inserts `↑<parentId>` after the time. Recipient is not on the line. A body with several lines continues on the following rows; those rows start with two spaces and carry no id.
 
 If the output is `no unread`, do not ack.
 
@@ -69,7 +71,7 @@ If there are unread rows, always run:
 okstra chat ack --room <room> --as <display> --through <id>
 ```
 
-Use the last unread row's id. CLI unread does not move the cursor; this ack does.
+Use the id of the last row that starts with an id. CLI unread does not move the cursor; this ack does. Ack never moves the cursor backwards.
 
 ## Step 3: Next action
 
@@ -81,7 +83,7 @@ There is no ack menu item. Choosing unread again shows the rows then acks, same
 
 1. Run `okstra chat members --room <room>`.
 2. Pick the recipient from `all` plus those names except the current display name (`--as`). Filter after `okstra chat members`. Do not pass `--as` to `members`. Recipient is required.
-3. Ask for the body as free input.
+3. Ask for the body as free input. The body may span several lines; pass it as one `--body` argument.
 4. Run `okstra chat send --room <room> --as <display> --to <all|name> --body <text>`.
 
 ### Reply

package/runtime/skills/okstra-inspect/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: okstra-inspect
 description: >-
-  Use this for everything that happens AFTER a single okstra task has already run — inspecting it or light bookkeeping on it, never launching new work. The tell is usually a named task id (PROD-1623, dev-9184), often dropped without the word "okstra." Reach for it when the user wants one task's: status, current/next phase, blockers, or approval gate; its final report — where it is or whether it passed (verdict / pass); its elapsed time or context/read cost; its run history, re-run, or resume; to mark it done / in-progress / blocked / todo; or a failed run's error logs gathered into a report (error report). Also turns cross-project okstra errors into an anonymized zip (error feedback), and audits run health across tasks (run audit). NOT for starting a run (okstra-run), rollups/schedules (okstra-rollup / okstra-schedule-gen), a brief (okstra-brief-gen), setup (okstra-setup), or cross-project management (okstra-manager).
+  Use this for everything that happens AFTER an okstra task has already run — inspecting it or light bookkeeping, never launching new work. The tell is usually a named task id (PROD-1623, dev-9184) without the word "okstra." Reach for it when the user wants one task's: status, current/next phase, blockers, or approval gate; its final report — where it is or whether it passed; its elapsed time or context/read cost; its run history, re-run, or resume; to mark it done / in-progress / blocked / todo; or a failed run's error logs gathered into a report. The recap facet also takes a task-group: which briefs are done / in progress / not started, what is next, each task's latest conclusion. Also builds an anonymized cross-project error zip and audits run health. NOT for starting a run (okstra-run), a group's run/time/error totals (okstra-rollup), schedules (okstra-schedule-gen), a brief (okstra-brief-gen), setup (okstra-setup), or cross-project management (okstra-manager).
 ---
 
 # OKSTRA Inspect
@@ -19,7 +19,7 @@ Single read-side entry point for okstra runtime inspection plus the one status m
 | `errors` | `facets/errors.md` | Aggregate okstra-run error logs for a task into a timestamped markdown report; print a summary. |
 | `error-zip` | `facets/error-zip.md` | Collect cross-project okstra error logs into an anonymized zip (report + raw) and summarize clusters. |
 | `run-audit` | `facets/run-audit.md` | Check every run's artifacts against progress invariants; report what went wrong without an error ever being logged. |
-| `recap` | `facets/recap.md` | Summarize a task's run-to-run phase transitions, then answer free-form questions over its `.okstra` artifacts. Appends each summary/Q&A to `recap/recap-log.jsonl`, and writes agent-authored notes to `notes/` for feeding into later runs. |
+| `recap` | `facets/recap.md` | Summarize a task's run-to-run phase transitions — or a task-group's start order, per-brief status, and each task's latest conclusion — then answer free-form questions over the `.okstra` artifacts. Appends each summary/Q&A to `recap-log.jsonl` (task `recap/`, group `.recap/`), and writes agent-authored notes to `notes/` for feeding into later runs. |
 
 ## Step 0: Preflight (shared)
 

package/runtime/skills/okstra-inspect/facets/recap.md

@@ -6,13 +6,16 @@ Loaded lazily by the dispatch table in `SKILL.md` (core). Shared rules — Step
 
 Trigger phrases: "okstra recap", "recap", "work summary", "summarize this task", "before/after summary", "explain this work", "task question".
 
-On top of the `.okstra` artifacts accumulated for a single task-id, (a) produce a before/after summary and (b) answer free-form questions about that work. By default it reads only the `.okstra/` subtree (artifact mode). It expands to code mode only when the user explicitly asks to look at the code changes too. This sub-command performs only the `recap/recap-log.jsonl` append and the `notes/` note authoring (recap.5); it never mutates `task-manifest.json` / catalog / timeline.
+On top of the `.okstra` artifacts accumulated for a single task-id — or for every task of one task-group — (a) produce a before/after summary and (b) answer free-form questions about that work. By default it reads only the `.okstra/` subtree (artifact mode). It expands to code mode only when the user explicitly asks to look at the code changes too. This sub-command performs only the `recap-log.jsonl` append and the `notes/` note authoring (recap.5); it never mutates `task-manifest.json` / catalog / timeline / `group-context.md`.
 
 ### recap.1 — Resolve target
 
-The same three forms as `cost` / `errors`: ① full task-key, ② bare token — the standard task-key resolution rule in `SKILL.md` (core), ③ task-root path.
+Two scopes. Decide the scope before resolving anything:
 
-If the user asks for a recap without naming a task (e.g. "summarize this work"), apply the core no-task fallback as-is — do not list only a placeholder form like `<task-group>` and ask back.
+- **Task scope** — the same three forms as `cost` / `errors`: ① full task-key, ② bare token — the standard task-key resolution rule in `SKILL.md` (core), ③ task-root path.
+- **Group scope** — the user names a task-group ("recap the cache group", "how far is the `cache` group", "group progress") or the bare token resolves with every match `Matched via: taskGroup`. Do **not** drop to the N-match picker in that case; carry the group name as `<task-group>` and follow recap.2g / recap.4g below. A group-scope request still takes the one-task path when the user picks a single task from it.
+
+If the user asks for a recap without naming a task or a group (e.g. "summarize this work"), apply the core no-task fallback as-is — do not list only a placeholder form like `<task-group>` and ask back.
 
 ### recap.2 — Assemble the before/after summary
 
@@ -28,11 +31,27 @@ Read the fixed-text `Run count` and repeated `Transition` blocks. Narrate each b
 
 For a transition that has a `Report`, run `okstra render-final-report <Report>` and read the rendered Markdown only when the user wants a deeper summary. Do not open the report data JSON directly and do not render every report automatically.
 
+### recap.2g — Assemble the group status (group scope)
+
+```bash
+okstra model-io recap-input --project-root <projectRoot> --task-group <task-group>
+```
+
+The projection joins three sources and is the only place to read them from — do not re-derive the queue from the brief directory, the catalog, or `group-context.md` by hand:
+
+- the group's briefs give the start order (brief ordinal) and the `waits for` edges;
+- the catalog / each `task-manifest.json` gives the real `Status` (`done` / `in progress` / `not started`), `Progress` (`<phase> (<state>)`), run count, next phase, and report path;
+- the group document's Task Memory gives each recorded task's `Headline`, `Decision N`, `Watch out N`, `Follow-up N`. A task with `Memory run: -` finished before group memory existed — its conclusion lives only in its `Report`.
+
+Read the head lines (`Brief count`, `Task count`, `Next in group`), then the repeated `Queue entry` blocks in order, then the repeated `Task` blocks. Narrate the group as: how many briefs, how many started, which are done, which is next (`Next in group` — `-` means every brief has started), and any `Waits for` that names a ticket not yet done. `Human sections: absent` means the group has no authored `group-context.md` context yet (only okstra's memory region) — say so once when the user asks why the group exists; do not offer to write it here (that is `okstra group-context init` via okstra-brief-gen).
+
+Numbers beyond run count (CPU, wall clock, error totals) are okstra-rollup's; if the user asks for them, point to `/okstra-rollup --task-group <task-group>` instead of summing anything here.
+
 ### recap.3 — Free-form Q&A loop
 
 After the summary output, take the user's free-form questions.
 
-- **artifact mode (default)**: answer only from `.okstra/` artifacts (timeline, task-manifest, that run's final-report). Every factual claim is accompanied by a `path:line` citation to the `.okstra` file.
+- **artifact mode (default)**: answer only from `.okstra/` artifacts (timeline, task-manifest, that run's final-report; in group scope also `.okstra/briefs/<task-group>/group-context.md` and each member task's artifacts). Every factual claim is accompanied by a `path:line` citation to the `.okstra` file.
 - **code mode (opt-in)**: only when the user **explicitly asks** — "look at the code changes / the diff too" — additionally read `git diff` · `git log` from that task's worktree/branch and answer at the code level. Entering recap never by itself switches to code mode.
 
 ### recap.4 — Persist each turn
@@ -48,6 +67,19 @@ okstra recap record <resolved-target> --project-root <projectRoot> \
 
 Put a one-or-two-line summary in `--answer`, not the full answer transcript. If there are multiple citations, repeat `--citation`. Do not silently swallow a recording failure (abnormal exit) — tell the user.
 
+### recap.4g — Persist each turn (group scope)
+
+Same flags, but the group replaces the target and the log lands at `.okstra/tasks/<task-group>/.recap/recap-log.jsonl`:
+
+```bash
+okstra recap record --task-group <task-group> --project-root <projectRoot> \
+  --kind <summary|qa> --mode <artifact|code> \
+  --question "<question or omit>" --answer "<one or two line summary>" \
+  --citation "<path:line>"
+```
+
+`recap note` has no group form — a note belongs to the task whose next run will carry it, so write it against that task-key.
+
 ### recap — Output template
 
 ```markdown
@@ -62,6 +94,22 @@ Before/after summary (runs: <N>):
 <Free-form questions follow. To include code changes, ask "also show me the diff".>
 ```
 
+Group scope:
+
+```markdown
+## okstra Recap — task-group <task-group> (briefs: <Brief count>, started: <Task count>)
+
+| # | task | status | progress | waits for | latest conclusion |
+|---|---|---|---|---|---|
+| 1 | dev-10626-1-… | done | release-handoff (completed) | — | <Headline, or "report only" when Memory run is -> |
+| 2 | dev-10627-2-… | in progress | implementation-option-selection (prepared) | DEV-10642 | <Headline> |
+| 3 | dev-10628-3-… | not started | — | — | — |
+
+Next in group: <Next in group or "every brief has started">
+
+<Free-form questions follow.>
+```
+
 ### recap.5 — Agent-authored notes (`notes/`)
 
 Leave something in `notes/` only when, during recap, you produced an artifact **for the okstra task** — verification evidence, a design/decision draft, an analysis note — that may serve as grounding for future runs, and whose content is **neither a rendered report nor a user decision**.

package/runtime/skills/okstra-rollup/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: okstra-rollup
 description: |
-  Use when the user wants run results from MULTIPLE okstra tasks collected and summarized at once — a task-group digest or a whole-project roll-up, not a single task. Aggregates per-task run count, elapsed time, error count, and latest report path, plus group-level totals and status/category/phase tallies, then synthesizes a cross-task prose summary from the report files. Make sure to use this skill whenever the user mentions "okstra rollup", "rollup", "task-group summary", "group-level report", "collect multiple task results", "whole-project task status summary", "cross-task summary", "consolidated group report", "organize all tasks", "run results all at once", even if they don't say "rollup". For a SINGLE task's report/time/errors/recap use okstra-inspect instead; for a forward-looking work plan over non-done tasks use okstra-schedule-gen.
+  Use when the user wants run results from MULTIPLE okstra tasks collected and summarized at once — a task-group digest or a whole-project roll-up, not a single task. Aggregates per-task run count, elapsed time, error count, and latest report path, plus group-level totals and status/category/phase tallies, then synthesizes a cross-task prose summary from the report files. Make sure to use this skill whenever the user mentions "okstra rollup", "rollup", "task-group summary", "group-level report", "collect multiple task results", "whole-project task status summary", "cross-task summary", "consolidated group report", "organize all tasks", "run results all at once", even if they don't say "rollup". For a SINGLE task's report/time/errors/recap, or "where does the group stand" (per-brief status, what is next), use okstra-inspect; this skill is for the numbers and the cross-task digest. For a forward-looking work plan over non-done tasks use okstra-schedule-gen.
 ---
 
 # OKSTRA Rollup