okstra 0.96.1 → 0.97.1

package/runtime/prompts/lead/report-writer.md

@@ -242,7 +242,7 @@ The final-report template `templates/reports/final-report.template.md` Section 7
 
 ### Release-handoff section contract (release-handoff runs only)
 
-When the run's `task-type` is `release-handoff`, the final report MUST include Section `## 5.6 Release Handoff Deliverables` with all eight sub-sections (`5.6.1` Source Verification Report, `5.6.2` Feature Branch & Working-Tree State, `5.6.3` User Selections, `5.6.4` Executed Commands, `5.6.5` Commit List, `5.6.6` Merge Conflict Probe, `5.6.7` Pull Request Outcome, `5.6.8` Routing Recommendation). Every entry is dictated by the lead's recorded git/gh command log and the user's verbatim answers to the H1/H2/H3 menu prompts. H1 choices are `local only`, `push + PR`, or `skip`; release-handoff records existing implementation commits and MUST NOT create new commits. If the user picked `skip` (H1) or `cancel` (H3), keep 5.6.3 populated but leave 5.6.4–5.6.6 explicitly empty per the template's empty-state lines.
+When the run's `task-type` is `release-handoff`, the final report MUST include Section `## 5.6 Release Handoff Deliverables` with all eight sub-sections (`5.6.1` Source Verification Report, `5.6.2` Feature Branch & Working-Tree State, `5.6.3` User Selections, `5.6.4` Executed Commands, `5.6.5` Commit List, `5.6.6` Merge Conflict Probe, `5.6.7` Pull Request Outcome, `5.6.8` Routing Recommendation). Every entry is dictated by the lead's recorded git/gh command log and the user's verbatim answers to the H1/H2/H3 menu prompts. H1 choices are `local checkout`, `push + PR`, or `skip`; release-handoff records existing implementation commits and MUST NOT create new commits. If the user picked `skip` (H1) or `cancel` (H3), keep 5.6.3 populated but leave 5.6.4–5.6.6 explicitly empty per the template's empty-state lines.
 
 **Single-lead authorship (release-handoff only):** release-handoff has no worker roster (no `Report writer worker`, no `Claude worker` drafter). The Claude lead authors the final-report file directly — there is no `Report writer worker` dispatch to perform in Phase 6, no resume-safe dispatch concern, and no mandatory worker-results file for a report-writer role. The rest of this contract's dispatch / resume / fallback machinery applies ONLY when `Report writer worker` is in the roster (i.e. every task-type other than `release-handoff`).
 

package/runtime/prompts/lead/team-contract.md

@@ -424,7 +424,7 @@ The script reads:
         "totalTokens": 2274011,
         "source": "claude-jsonl",
         "sessionId": "<wrapper-session-id>",
-        "cliSessionPath": "/Users/.../.codex/sessions/.../rollout-*.jsonl",
+        "cliSessionPaths": ["/Users/.../.codex/sessions/.../rollout-*.jsonl"],
         "cliTotalTokens": 5261833,
         "cliModel": "gpt-5.5"
       }

package/runtime/prompts/profiles/final-verification.md

@@ -26,6 +26,7 @@
 - Pre-verification entry gate (resolved & enforced by `okstra render-bundle` prep — the lead does NOT recompute it):
   - the verification target (scope / worktree / base / head / stages / source reports / diff stat) is injected as the `VERIFICATION_TARGET` block. The lead MUST treat it as authoritative and MUST NOT re-pick a target from the brief.
   - **whole-task scope** (`--stage auto`, default): prep has already verified every Stage Map stage is `status:done` in `consumers.jsonl`, every done stage's `head_commit` is an ancestor of the task worktree HEAD (all stage branches merged), and the worktree is clean outside `.okstra/`. If any check failed the run never started (PrepareError); a started whole-task run is therefore a fully-merged, clean target.
+    - **whole-task 은 read-only 가 아니라 mutating phase 다.** whole-task 모드는 진입 시 아직 task 브랜치에 머지되지 않은 done stage 들을 `--no-ff` 로 자동 머지해 통합 커밋을 생성하고, 이어서 정리 가능한 stage worktree·registry stage-key·stage 브랜치를 제거한다. 머지 충돌이 발생하면 충돌 파일을 보고하고 중단한다(사용자가 수동 해소 후 재시도). 미커밋 변경이 남은 stage worktree 는 보존한다. 따라서 위 entry gate 가 말하는 "fully-merged, clean target" 은 이 자동 통합 단계가 끝난 뒤의 상태이며, whole-task final-verification 은 통합 커밋을 만드는 mutating phase 로 취급해야 한다.
   - **single-stage scope** (`--stage N`): prep verified stage N is `status:done` and its isolated stage worktree exists and is clean. Other stages' state is irrelevant. A single-stage run is a partial verification: it MUST NOT recommend plain `release-handoff`, but MAY recommend `release-handoff(stage-group)` when the verdict is `accepted` — the stage becomes PR-eligible for a stage-group handoff.
   - the lead still captures `git rev-parse HEAD` / `git status --short` from the injected worktree to confirm the analysis ran against the injected head; a mismatch is a `tool-failure`, not a silent proceed.
 - Required deliverable shape (final report, in addition to the standard sections):

package/runtime/prompts/profiles/forbidden-actions.json

@@ -57,7 +57,7 @@
     "bypassing repo safeguards: `--no-verify` / `-n` on `git push`, bypassing GPG signing, disabling safeguards via equivalent flags, or any hook bypass.",
     "release-publishing commands: `gh release create`, `gh release edit`, `npm publish`, `cargo publish`, `pip publish`, `twine upload`, `docker push`, `terraform apply`, `kubectl apply` against any non-local cluster.",
     "source-code edits, refactors, or any modification to files outside the run's own artifact directories (`reports/`, `prompts/`, `state/`, `manifests/`, `worker-results/`, `status/`, `sessions/`). The diff being shipped MUST be exactly what the prior `implementation` run produced; release-handoff packages it, it does not re-author it.",
-    "executing any mutating command the user did NOT select. Examples: opening a PR when the user picked `local only`; pushing when the user picked `skip`; switching the PR base branch silently after the user already chose one.",
+    "executing any mutating command the user did NOT select. Examples: opening a PR when the user picked `local checkout`; pushing when the user picked `skip`; switching the PR base branch silently after the user already chose one.",
     "retrying a failed git / gh command with weaker safety flags. If `git push` fails with non-fast-forward, the lead MUST stop, explain the failure to the user, and ask for instructions — it MUST NOT add `--force`.",
     "`TeamCreate`, `Agent(...)` dispatch of any kind, or any other parallel sub-agent fan-out. This phase runs entirely under the Claude lead.",
     "silently treating an unrecognised user reply as one of the menu options. If the user's answer does not match a presented choice, re-ask the question verbatim."

package/runtime/prompts/profiles/release-handoff.md

@@ -20,10 +20,13 @@
   - the lead MUST confirm `git log --oneline <base>..HEAD` contains at least one implementation commit. If it is empty, the run MUST end with status `blocked` and route back to `implementation`.
 - User interaction protocol (Claude lead — performed in order, using `AskUserQuestion` or the equivalent interactive prompt):
   1. **Action selection** — present three choices and capture exactly one:
-     - `local only` — complete the handoff as a local delivery record: record the accepted, already-committed branch and end without push or PR.
+     - `local checkout` (whole-task mode only) — bring the verified task branch into the MAIN worktree for local testing (no push, no PR). See step 1c. When `HANDOFF_MODE` is `stage-group`, do NOT offer this option — tell the user "`local checkout` is whole-task mode only" and re-ask.
      - `push + PR` — push the feature branch, then open or reuse a pull request.
      - `skip` — cancel delivery actions for now: record that release-handoff was intentionally skipped and end the run without any git command.
      If the user picks `skip`, route directly to the final-report self-review pass.
+  1c. **Local checkout execution** (only when the user picked `local checkout`) — confirm with the user that okstra will remove the okstra task worktree and `git checkout <feature branch>` in the MAIN worktree, and that the base branch is never modified. On confirmation run:
+      `okstra handoff local-checkout --project-root <project root> --project-id <id> --task-group <g> --task-id <t>`
+      Exit 1 means a precondition failed (MAIN worktree dirty, registry entry missing, or checkout failed): show the error verbatim and re-ask the action selection. On success the okstra task worktree no longer exists — the lead's cwd is gone, so EVERY subsequent step (final-report authoring included) MUST use absolute paths or run from the MAIN worktree. Then route to the final-report self-review pass.
   - **stage-group mode order**: G1 base branch first (same options as Q2 — the dependency-closure check needs `origin/<base>`), then G2 stage confirmation, then assemble, then Q2b/Q3 as usual with the collector branch as the PR head.
   1g. **G2 — stage confirmation**: the stage selection already happened before the run (wizard `handoff_stage_pick`, or the CLI `--stages` flag) and is fixed in `HANDOFF_STAGES`. Display it as a one-line confirmation (`PR 대상 stage: <csv> — 진행합니다`) and proceed; do NOT re-ask the multi-select. Only if `HANDOFF_MODE` is `stage-group` but `HANDOFF_STAGES` is empty (defensive, should not happen) run `okstra handoff eligible --plan-run-root <plan-run-root> --approved-plan <approved plan path>` and ask the user to pick from the eligible stages.
   2g. **assemble**: run `okstra handoff assemble --plan-run-root <...> --approved-plan <...> --project-root <project root> --project-id <id> --task-group <g> --task-id <t> --work-category <c> --stages <csv> --base <chosen-base>`. Exit 2 means a stage-vs-stage merge conflict: show the `conflicts` paths and stop (route: reshape the group or resolve manually). Exit 1 means an eligibility/closure violation: show the error verbatim and re-ask G2. On success the returned `branch` is the PR head branch for every subsequent step.
@@ -65,21 +68,24 @@
   - **Source Verification Report**: relative path of the originating `final-verification` final-report file plus the literal quoted `Verdict Token` row whose value is `accepted`.
   - **Feature Branch & Working-Tree State**: branch name from `git rev-parse --abbrev-ref HEAD`, output of `git status --short` at run start.
   - **User Selections**: a block recording each prompt and the user's verbatim answer.
-    - Q1 action: `local only` | `push + PR` | `skip`.
+    - Q1 action: `local checkout` | `push + PR` | `skip`.
     - Q2 PR base (if applicable): the chosen branch and how it was selected (menu pick vs free-form input).
     - Q2b merge-conflict probe (if applicable): `not-run` | `clean` (no conflict, no prompt shown) | `proceed anyway` | `change base branch` | `cancel`. Record it in both the `User Selections` row `H2b` and the `Merge Conflict Probe` deliverable. When a conflict was detected, list the conflicting paths.
     - Q3 title/body: `use as-is` | `edit then proceed` (with a diff between the lead's draft and the final text) | `cancel`.
   - **Executed Commands**: every git / gh command the lead actually ran, with its exit code and a one-line stdout/stderr summary. Read-only inspection commands MAY be summarised; mutating commands MUST be listed verbatim.
   - **Commit List**: each existing implementation commit in `git log <base>..HEAD`, with short/full SHA, subject line, and touched files. Release-handoff MUST NOT create new commits.
   - **Merge Conflict Probe**: one of
-    - `- Not run (user picked local only or skip).`
+    - `- Not run (user picked local checkout or skip).`
     - `- Clean — no conflicts against <base> at <origin/base SHA>.`
     - `- Conflicts detected against <base> at <origin/base SHA>; user chose <proceed anyway | change base branch | cancel>. Conflicting paths: <list>.`
   - **Pull Request Outcome**: one of
-    - `- No PR action requested.` (user picked `local only` or `skip`)
+    - `- No PR action requested.` (user picked `local checkout` or `skip`)
     - `- PR created: <url>` with title and base branch
     - `- PR reused: <url>` when an existing PR was found via `gh pr list`
     - `- PR creation skipped: <reason>` for any user-driven cancellation
+  - **Local Checkout Outcome**: one of
+    - `- Not run (user picked push + PR or skip).`
+    - `- Checked out <branch> into <main worktree path>; okstra task worktree <path> removed. Next: 로컬 테스트 후 PR 하려면 okstra-run 으로 release-handoff 재진입 → push + PR.`
   - **Stage Group** (stage-group mode only): selected stages, each stage's single-stage verification report path + quoted `Verdict Token` row, collector branch name, merge commit SHAs from assemble, and the dependency-closure verdict (from the assemble output / error).
   - **Routing recommendation**: explicit `done` token, since release-handoff is the terminal lifecycle phase. If the run ended in `skip` or `cancel`, the recommendation MUST also state whether re-entry into release-handoff is appropriate.
 - Self-review pass before finalising the report (`Claude lead` runs this):

package/runtime/python/okstra_ctl/__init__.py

@@ -37,8 +37,7 @@ from .qa_commands import (
     validate_qa_commands,
 )
 from .index import (
-    _replace_or_append_active_row,
-    _replace_or_append_project_row,
+    _replace_or_append_row,
     record_start,
     reserve_run_in_active,
     remove_reservation,
@@ -65,6 +64,7 @@ from .listing import (
     list_runs,
 )
 from .resolver import ResolveError, _all_run_ids, resolve_last, resolve_run_id
+from .run_index_row import read_run_index
 from .sequence import predict_next_run_seq
 from .tmux import _shell_quote, build_tmux_command
 from .batch import expand_selectors, make_batch_id, write_batch_meta
@@ -113,6 +113,7 @@ __all__ = [
     "parse_run_id",
     "predict_next_run_seq",
     "read_jsonl",
+    "read_run_index",
     "read_run_context",
     "read_run_inputs",
     "reconcile_active",

package/runtime/python/okstra_ctl/backfill.py

@@ -10,10 +10,11 @@ from typing import List
 from okstra_project.dirs import tasks_root
 
 from .ids import build_run_id
-from .invocation import invocation_path, save_invocation
+from .invocation import save_invocation
 from .jsonl import append_jsonl, read_jsonl, rotate_recent_if_needed
 from .project_meta import _project_meta_path
 from .reconcile import _now_iso, normalize_central_status
+from .run_index_row import build_run_index_row
 
 _STAGE_DIR_RE = _re.compile(r"^stage-\d+$")
 
@@ -196,9 +197,6 @@ def backfill_project(home: Path, project_id: str, project_root: Path) -> int:
                         validation_status = raw_validation
                     else:
                         validation_status = "not-run"
-                    inv_rel = invocation_path(
-                        home, project_id, actual_group, actual_task,
-                        actual_type, seq).relative_to(home)
                     # okstra.sh manifest 는 createdAt/updatedAt 만 쓴다(P2 회귀).
                     # 별도 startedAt/finishedAt 가 없으면 createdAt/updatedAt 으로 보강한다.
                     started_at = (manifest.get("startedAt")
@@ -216,23 +214,16 @@ def backfill_project(home: Path, project_id: str, project_root: Path) -> int:
                     # 단계에서 recent 로 직접 보낸다.
                     is_non_terminal = normalized_status in {
                         "running", "in-progress"}
-                    row = {
-                        "runId": run_id, "projectId": project_id,
-                        "projectRoot": str(project_root),
-                        "taskGroup": actual_group, "taskId": actual_task,
-                        "taskKey": f"{actual_group}/{actual_task}",
-                        "taskType": actual_type, "runSeq": seq,
-                        "status": normalized_status,
-                        "startedAt": started_at,
-                        "finishedAt": None if is_non_terminal else finished_at,
-                        "workers": raw_workers,
-                        "leadModel": raw_lead_model,
-                        "validation": validation_status,
-                        "runDirRel": run_dir_rel,
-                        "finalReportRel": final_rel,
-                        "finalStatusRel": final_status_rel,
-                        "invocationFile": str(inv_rel),
-                    }
+                    row = build_run_index_row(
+                        project_id=project_id, project_root=str(project_root),
+                        task_group=actual_group, task_id=actual_task,
+                        task_type=actual_type, run_seq=seq,
+                        status=normalized_status, started_at=started_at,
+                        finished_at=None if is_non_terminal else finished_at,
+                        workers=raw_workers, lead_model=raw_lead_model,
+                        validation=validation_status, run_dir_rel=run_dir_rel,
+                        final_report_rel=final_rel,
+                        final_status_rel=final_status_rel)
                     if is_non_terminal:
                         append_jsonl(home / "active.jsonl", row)
                     else:

package/runtime/python/okstra_ctl/codex_dispatch.py

@@ -1498,8 +1498,13 @@ def _utc_now() -> str:
 
 
 def _write_json(path: Path, payload: Mapping[str, Any]) -> None:
-    path.write_text(json.dumps(payload, ensure_ascii=False, indent=2) + "\n",
-                    encoding="utf-8")
+    # Write via temp file + os.replace so a crash mid-write cannot leave a
+    # truncated team-state.json that every later _load_json_object rejects;
+    # os.replace is atomic on POSIX, matching run_context._atomic_write_json.
+    tmp = path.with_suffix(path.suffix + ".tmp")
+    tmp.write_text(json.dumps(payload, ensure_ascii=False, indent=2) + "\n",
+                   encoding="utf-8")
+    os.replace(tmp, path)
 
 
 def _print_json(payload: Mapping[str, Any]) -> None:

package/runtime/python/okstra_ctl/conformance.py

@@ -144,11 +144,29 @@ class ConformanceVerdict:
     message: str
 
 
+def _waiver_covers_entry(waiver: dict, entry: dict) -> bool:
+    """waiver 가 이 entry 의 conformance 를 통째로 면해 주는지 판정.
+
+    spec §7.2 의 capability allowlist 의미: `scope` 가 빈 배열이면 stage 전체
+    waiver(blanket). 비어 있지 않으면 그 capability 들만 waive 하므로, entry 가
+    요구하는 모든 capability(`requires`)가 scope 안에 들어올 때만 entry 가 완전히
+    가려진다. scope 밖 capability 를 entry 가 건드리면 waiver 가 덮지 못하므로
+    결과로 정상 게이트해야 한다(예: `db` 만 waive 한 run 에서 `http` 는 계속 게이트)."""
+    scope = waiver.get("scope")
+    if not isinstance(scope, list) or not scope:
+        return True
+    requires = entry.get("requires")
+    required = {c for c in requires if isinstance(c, str)} if isinstance(requires, list) else set()
+    return required.issubset({c for c in scope if isinstance(c, str)})
+
+
 def decide_conformance_gate(entry: dict, result: object) -> ConformanceVerdict:
     """단일 stage entry + 실행 결과(`QaResult | None`)로 게이트 판정.
 
-    우선순위: exemption → waiver → 결과 평가. 미실행/MISSING/FAIL 은 BLOCKING.
-    면제·waiver 의 형태 검증은 `validate_conformance_manifest` 가 이미 보장한다.
+    우선순위: exemption → (entry 를 덮는) waiver → 결과 평가. 미실행/MISSING/FAIL
+    은 BLOCKING. 면제·waiver 의 형태 검증은 `validate_conformance_manifest` 가
+    이미 보장한다. capability-scoped waiver 는 scope 가 entry.requires 를 전부
+    덮을 때만 적용되고, 그렇지 않으면 결과로 정상 게이트한다(`_waiver_covers_entry`).
     """
     key = entry.get("stageKey", "<unknown>")
     exemption = entry.get("exemption")
@@ -158,7 +176,7 @@ def decide_conformance_gate(entry: dict, result: object) -> ConformanceVerdict:
             f"conformance exempted: {exemption.get('reason', '')}",
         )
     waiver = entry.get("waiver")
-    if waiver:
+    if waiver and _waiver_covers_entry(waiver, entry):
         return ConformanceVerdict(
             key, "WAIVED", True, True,
             f"conformance waived by {waiver.get('acknowledgedBy', '?')}: "

package/runtime/python/okstra_ctl/consumers.py

@@ -30,7 +30,13 @@ def read_consumers(plan_run_root: Path) -> List[Dict[str, Any]]:
         line = line.strip()
         if not line:
             continue
-        out.append(json.loads(line))
+        # 일반 open('a') append 는 crash/동시쓰기로 마지막 줄이 잘릴 수 있다.
+        # 깨진 줄 하나가 stage 선택·reconcile 전체를 무너뜨리지 않도록,
+        # worktree_registry._load 와 같은 방식으로 해당 줄만 건너뛴다.
+        try:
+            out.append(json.loads(line))
+        except json.JSONDecodeError:
+            continue
     return out
 
 

package/runtime/python/okstra_ctl/dispatch_core.py

@@ -192,6 +192,12 @@ def build_dispatch_plan(
 
 def dispatch_plan(plan: DispatchPlan, *, wait: bool = True) -> int:
     if wait:
+        if any(job.backend == BACKEND_TMUX_PANE for job in plan.jobs):
+            raise DispatchError(
+                "wait=True dispatch does not support tmux-pane workers: "
+                "the per-job blocking loop would serialize panes instead of "
+                "running them concurrently; dispatch tmux panes with wait=False"
+            )
         _set_dispatch_mode(plan.team_state_path, _dispatch_mode(plan.jobs))
         for job in plan.jobs:
             result = _dispatch_job_with_retry(plan, job)
@@ -671,7 +677,7 @@ def _retry_details(job: WorkerJob, attempt: int, outcome: WorkerOutcome) -> dict
 
 def _outcome_from_status(record: Mapping[str, Any], status) -> WorkerOutcome:
     return WorkerOutcome(
-        returncode=status.exit_code or 0,
+        returncode=status.exit_code if status.exit_code is not None else 1,
         missing_completion_paths=tuple(path for path in _record_completion_paths(record) if not path.is_file()),
         pane_id=_string_value(record.get("paneId")),
         status_sidecar_path=status.path,
@@ -917,4 +923,6 @@ def _utc_now() -> str:
 
 
 def _write_json(path: Path, payload: Mapping[str, Any]) -> None:
-    path.write_text(json.dumps(payload, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+    tmp = path.with_suffix(path.suffix + ".tmp")
+    tmp.write_text(json.dumps(payload, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+    os.replace(tmp, path)

package/runtime/python/okstra_ctl/doctor.py

@@ -1,6 +1,7 @@
 """Phase-aware diagnostics for ``okstra doctor --phase``."""
 from __future__ import annotations
 
+import json
 import subprocess
 from dataclasses import asdict, dataclass
 from pathlib import Path
@@ -196,12 +197,19 @@ def _worker_agents_check(home: Path, workspace: Path, phase: str) -> DoctorCheck
 
 
 def _worktree_registry_check() -> DoctorCheck:
-    if callable(worktree_registry.lookup) and callable(worktree_registry.task_key):
-        return _ok(
-            "worktree lookup helper",
-            "lookup helper available; target-specific lookup requires a task key",
-        )
-    return _fail("worktree lookup helper", "lookup helper unavailable")
+    # final-verification resolves stage worktrees through the registry. A corrupt
+    # registry.json is silently swallowed by _load() (returns empty), masking every
+    # reservation, so the readiness signal must actually parse the on-disk file.
+    path = worktree_registry._registry_path()
+    if not path.exists():
+        return _ok("worktree registry", f"no registry yet ({path})")
+    try:
+        data = json.loads(path.read_text())
+    except (OSError, json.JSONDecodeError) as exc:
+        return _fail("worktree registry", f"{path} is unreadable: {exc}")
+    if not isinstance(data, dict) or not isinstance(data.get("tasks"), dict):
+        return _fail("worktree registry", f"{path} is missing a valid 'tasks' table")
+    return _ok("worktree registry", f"{len(data['tasks'])} task entries ({path})")
 
 
 def _gh_auth_check(project_root: Path) -> DoctorCheck:
@@ -212,12 +220,21 @@ def _gh_auth_check(project_root: Path) -> DoctorCheck:
 
 
 def _git_clean_check(project_root: Path) -> DoctorCheck:
-    result = _run(["git", "-C", str(project_root), "status", "--short"])
-    if result.returncode != 0:
-        return _fail("git clean tree", _command_detail(result))
-    if result.stdout.strip():
-        return _fail("git clean tree", result.stdout.strip().splitlines()[0])
-    return _ok("git clean tree", "working tree clean")
+    # okstra-owned outputs (.okstra, synced dirs, nested stage worktrees) are not
+    # readiness blockers, but untracked SOURCE still is. Reuse the shared dirty
+    # notion (worktree.is_dirty_excluding_okstra) instead of a blunter second
+    # definition of "clean".
+    from .worktree import is_dirty_excluding_okstra
+
+    try:
+        dirty = is_dirty_excluding_okstra(project_root)
+    except Exception as exc:  # git missing / not a repo
+        return _fail("git clean tree", str(exc))
+    if dirty:
+        return _fail(
+            "git clean tree", "changes present outside okstra-owned paths"
+        )
+    return _ok("git clean tree", "working tree clean (excluding okstra-owned paths)")
 
 
 def _git_remote_check(project_root: Path) -> DoctorCheck:

package/runtime/python/okstra_ctl/error_log_core.py

@@ -0,0 +1,72 @@
+"""errors-*.jsonl 글롭·파싱·집계 공용 코어 (read-only).
+
+error_report(단일 task)와 error_zip(cross-project)이 공유한다.
+errorType 값에 분기하지 않는 data-driven 집계.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+
+def glob_error_logs(task_root: Path) -> list[Path]:
+    runs = task_root / "runs"
+    if not runs.exists():
+        return []
+    flat = runs.glob("*/logs/errors-*.jsonl")
+    staged = runs.glob("*/stage-*/logs/errors-*.jsonl")
+    return sorted(set(flat) | set(staged))
+
+
+def parse_records(paths: list[Path]) -> tuple[list[dict], int]:
+    records: list[dict] = []
+    skipped = 0
+    for path in paths:
+        # cross-project zip 은 글로벌 run-index 를 순회하므로, 깨지거나 비-UTF8/잘린
+        # 로그 한 개가 전체 수집을 중단시키지 않도록 해당 파일만 건너뛴다.
+        try:
+            text = path.read_text(encoding="utf-8")
+        except (OSError, UnicodeDecodeError):
+            skipped += 1
+            continue
+        for line in text.splitlines():
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                rec = json.loads(line)
+            except Exception:
+                skipped += 1
+                continue
+            if isinstance(rec, dict):
+                rec["_sourceLog"] = str(path)
+                records.append(rec)
+            else:
+                skipped += 1
+    return records, skipped
+
+
+def tally(records: list[dict], key: str) -> dict:
+    out: dict[str, int] = {}
+    for rec in records:
+        name = str(rec.get(key, ""))
+        out[name] = out.get(name, 0) + 1
+    return out
+
+
+def rows(counts: dict, label: str) -> list[dict]:
+    return [
+        {label: name, "count": n}
+        for name, n in sorted(counts.items(), key=lambda kv: (-kv[1], kv[0]))
+    ]
+
+
+def aggregate(records: list[dict]) -> dict:
+    return {
+        "errorCount": len(records),
+        "runCount": len({rec.get("_sourceLog", "") for rec in records}),
+        "byErrorType": tally(records, "errorType"),
+        "bySource": tally(records, "source"),
+        "byPhase": rows(tally(records, "phase"), "phase"),
+        "byAgent": rows(tally(records, "agent"), "agent"),
+    }

package/runtime/python/okstra_ctl/error_report.py

@@ -13,61 +13,11 @@ import sys
 from pathlib import Path
 
 from okstra_ctl.task_target import resolve_task_root, project_rel
-
-
-def _glob_error_logs(task_root: Path) -> list[Path]:
-    runs = task_root / "runs"
-    if not runs.exists():
-        return []
-    flat = runs.glob("*/logs/errors-*.jsonl")
-    staged = runs.glob("*/stage-*/logs/errors-*.jsonl")
-    return sorted(set(flat) | set(staged))
-
-
-def _parse_records(paths: list[Path]) -> tuple[list[dict], int]:
-    records: list[dict] = []
-    skipped = 0
-    for path in paths:
-        for line in path.read_text(encoding="utf-8").splitlines():
-            line = line.strip()
-            if not line:
-                continue
-            try:
-                rec = json.loads(line)
-            except Exception:
-                skipped += 1
-                continue
-            if isinstance(rec, dict):
-                rec["_sourceLog"] = str(path)
-                records.append(rec)
-            else:
-                skipped += 1
-    return records, skipped
-
-
-def _tally(records: list[dict], key: str) -> dict:
-    out: dict[str, int] = {}
-    for rec in records:
-        out[str(rec.get(key, ""))] = out.get(str(rec.get(key, "")), 0) + 1
-    return out
-
-
-def _rows(counts: dict, label: str) -> list[dict]:
-    return [
-        {label: name, "count": n}
-        for name, n in sorted(counts.items(), key=lambda kv: (-kv[1], kv[0]))
-    ]
-
-
-def _aggregate(records: list[dict]) -> dict:
-    return {
-        "errorCount": len(records),
-        "runCount": len({rec.get("_sourceLog", "") for rec in records}),
-        "byErrorType": _tally(records, "errorType"),
-        "bySource": _tally(records, "source"),
-        "byPhase": _rows(_tally(records, "phase"), "phase"),
-        "byAgent": _rows(_tally(records, "agent"), "agent"),
-    }
+from okstra_ctl.error_log_core import (
+    glob_error_logs,
+    parse_records,
+    aggregate,
+)
 
 
 def _escape_cell(value: object) -> str:
@@ -137,9 +87,9 @@ def build_and_write(task_root: Path, project_root: Path, now: dt.datetime) -> di
             task_key = json.loads(manifest_path.read_text(encoding="utf-8")).get("taskKey", "")
         except Exception:
             task_key = ""
-    paths = _glob_error_logs(task_root)
-    records, skipped = _parse_records(paths)
-    agg = _aggregate(records)
+    paths = glob_error_logs(task_root)
+    records, skipped = parse_records(paths)
+    agg = aggregate(records)
     report_rel = ""
     if paths:
         md = render_markdown(