okstra 0.186.7 → 0.188.0

package/runtime/python/okstra_ctl/worker_runner.py

@@ -10,6 +10,7 @@ SIGTERM a healthy worker in the middle of a long reasoning stretch.
 """
 from __future__ import annotations
 
+import dataclasses
 import json
 import os
 import selectors
@@ -21,6 +22,7 @@ from typing import Any, Callable, Mapping
 
 from .domain.provider import ServedModelAttestation, ServedModelNormalizer
 from .domain.worker_exec import (
+    NO_RESULT_EXIT_CODE,
     SERVED_MODEL_MISMATCH_EXIT_CODE,
     ExecCommand,
     ExecutionStrategy,
@@ -71,7 +73,7 @@ def run_worker(
 
     try:
         with guard:
-            exit_code, timed_out, idle_seconds, raw_model = _launch(
+            exit_code, timed_out, idle_seconds, raw_model, usage = _launch(
                 command,
                 log_path,
                 presentation=presentation,
@@ -92,6 +94,11 @@ def run_worker(
         raise
 
     status = _closed(status, started_monotonic)
+    if usage is not None:
+        # 스트림이 마지막으로 보고한 토큰 스냅샷, 공급자 어휘 그대로. 토큰
+        # 수집기(`okstra_token_usage`)가 홈 트랜스크립트가 없는 공급자의
+        # 사용량을 여기서 읽는다.
+        status["usage"] = dict(usage)
     if served_model_normalizer is not None:
         attestation = served_model_normalizer(raw_model)
         status["servedModelAttestation"] = _attestation_payload(attestation)
@@ -170,11 +177,14 @@ def _launch(
     presentation: str,
     idle_timeout_seconds: int,
     on_spawn: Callable[[subprocess.Popen[bytes]], None],
-) -> tuple[int, bool, int, str | None]:
+) -> tuple[int, bool, int, str | None, Mapping[str, Any] | None]:
     live = presentation == LIVE
     transcript = SessionTranscript(log_path, live=live)
     observation = _ServedModelObservation()
-    strategy = _with_served_model_observation(command.presentation, observation)
+    usage_observation = _UsageObservation()
+    strategy = _with_stream_observations(
+        command.presentation, observation, usage_observation
+    )
     try:
         # The strategy decided where this provider runs — some CLIs work in the
         # stage tree, others in the project root and reach the tree by flag.
@@ -203,34 +213,43 @@ def _launch(
             idle_timeout_seconds=idle_timeout_seconds,
             stdin_text=command.stdin_text,
         )
-        return exit_code, timed_out, idle_seconds, observation.raw_model
+        return (
+            exit_code,
+            timed_out,
+            idle_seconds,
+            observation.raw_model,
+            usage_observation.usage,
+        )
     finally:
         transcript.close()
 
 
-def _with_served_model_observation(
+def _with_stream_observations(
     presentation: Presentation,
     observation: _ServedModelObservation,
+    usage_observation: _UsageObservation,
 ) -> Presentation:
-    """JSON 경로의 서빙 모델 관측을 러너가 모아 둔다.
+    """JSON 경로의 서빙 모델·토큰 사용량 관측을 러너가 모아 둔다.
 
-    해석 전략은 이벤트를 보고 모델 문자열만 돌려준다. 그 값을 사이드카에
-    적는 일은 러너의 것이라, 여기서 한 번 감싼다.
+    해석 전략은 이벤트를 보고 모델 문자열과 사용량 스냅샷만 돌려준다. 그 값을
+    사이드카에 적는 일은 러너의 것이라, 여기서 한 번 감싼다. 사용량은 어댑터가
+    읽는 법을 넘긴 어휘에서만 관측된다.
     """
     if not isinstance(presentation, JsonEvents):
         return presentation
     original = presentation.observe
+    original_usage = presentation.observe_usage
 
     def observe(event: Mapping[str, Any]) -> str | None:
         observed = original(event)
         observation.record(observed)
+        if original_usage is not None:
+            usage_observation.record(original_usage(event))
         return observed
 
-    return JsonEvents(
-        normalise=presentation.normalise,
-        observe=observe,
-        join_adjacent_text=presentation.join_adjacent_text,
-    )
+    # 필드를 손으로 옮기지 않는다 — 그렇게 하던 동안 어댑터가 선언한
+    # `is_conclusion` 이 여기서 떨어져 나가, grok 의 종결 판정이 무효였다.
+    return dataclasses.replace(presentation, observe=observe)
 
 
 class _ServedModelObservation:
@@ -242,6 +261,21 @@ class _ServedModelObservation:
             self.raw_model = raw_model
 
 
+class _UsageObservation:
+    """스트림이 보고한 마지막 사용량 스냅샷.
+
+    첫 값이 아니라 마지막 값이다 — 단계별 스냅샷을 내는 CLI 도 종결 이벤트에
+    합계를 싣고, 그 이벤트가 스트림의 끝에 온다.
+    """
+
+    def __init__(self) -> None:
+        self.usage: Mapping[str, Any] | None = None
+
+    def record(self, usage: Mapping[str, Any] | None) -> None:
+        if isinstance(usage, Mapping) and usage:
+            self.usage = usage
+
+
 class _AbnormalExit:
     """Close the status sidecar for the exits that raise nothing at all.
 
@@ -393,11 +427,16 @@ def _pump(
     strategy.flush(transcript)
 
     exit_code = process.wait()
-    if closing_text is None and isinstance(strategy, JsonEvents):
-        # JSON 스트림은 결과 이벤트로 끝나야 한다. 텍스트를 흘리는 CLI 에는
-        # 놓칠 결과 이벤트가 없다.
+    if isinstance(strategy, JsonEvents) and not strategy.concluded():
+        # JSON 스트림은 그 어휘의 종결 이벤트로 끝나야 한다. 텍스트를 흘리는
+        # CLI 에는 놓칠 종결 이벤트가 없다. 무엇이 종결인지는 전략이 안다.
         transcript.note("no result event in the CLI's output")
-    elif closing_text is not None:
+        if exit_code == 0 and not timed_out:
+            # 실측(dev-10341, 한 CLI 4회): 종결 이벤트도 산출물도 없이 exit 0.
+            # 그대로 돌려주면 사이드카와 셸 소비자에게는 성공으로 읽힌다.
+            # CLI 자신의 비영 코드는 보존한다 — 그쪽이 더 구체적인 사실이다.
+            exit_code = NO_RESULT_EXIT_CODE
+    if closing_text is not None:
         # Result 는 format_* 가 줄을 만들지 않는다. 아카이브 결론은 러너가 적는다.
         # 상한 밖에 둔다 — 잘린 결론은 사후 분석 전체를 잃게 한다.
         if isinstance(strategy, JsonEvents):
@@ -559,6 +598,8 @@ def _terminate(process: subprocess.Popen[bytes]) -> None:
         try:
             os.killpg(process.pid, signal.SIGKILL)
         except ProcessLookupError:
+            # expected-miss: SIGTERM 유예 사이에 그룹이 스스로 끝난 경우다.
+            # 죽이려던 대상이 이미 없는 것은 성공이지 실패가 아니다.
             pass
         process.wait()
 

package/runtime/python/okstra_ctl/worker_state.py

@@ -18,8 +18,23 @@ def _validated_team_state_path(value: str) -> Path:
     return path
 
 
+_CLI_EPILOG = r"""Usage:
+  okstra worker-state transition --team-state <path> --worker <worker-id> \
+    --status <in-progress|completed|timeout|error|not-run> \
+    [--reason <text>] [--model <execution-value>]
+
+in-progress records startedAt and clears endedAt. completed, timeout, and error
+record endedAt. timeout, error, and not-run require --reason.
+"""
+_CLI_DESCRIPTION = "Atomically transition persisted worker status."
+
+
 def _parser() -> argparse.ArgumentParser:
-    parser = argparse.ArgumentParser(prog="okstra worker-state")
+    parser = argparse.ArgumentParser(
+        description=_CLI_DESCRIPTION,
+        epilog=_CLI_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        prog="okstra worker-state")
     commands = parser.add_subparsers(dest="command", required=True)
     transition = commands.add_parser(
         "transition", help="atomically transition one worker status"

package/runtime/python/okstra_ctl/workflow.py

@@ -54,7 +54,7 @@ PHASE_RULES: dict[str, dict[str, str]] = {
             "  - top-N ranking (default 8, brief `candidate-cap` overrides within 1..12)\n"
             "  - per-candidate columns Lens / Scope / Severity / Effort / Consensus / Source workers / Recommended next-phase / Expected behavior after / Evidence (path:line)\n"
             "  - Phase 1.5 reflect-back grilling log at `runs/improvement-discovery/<seq>/state/phase-1.5-grilling.md`\n"
-            "  - Phase 5.5 consensus classification (full / partial / contested / worker-unique)"
+            "  - Phase 5.5 consensus classification (full / partial / contested / worker-unique / unverified)"
         ),
     },
     "project-analysis": {
@@ -173,6 +173,22 @@ def load_phase_forbidden(workspace_root: Path) -> dict[str, str]:
     return {phase: render_forbidden(items) for phase, items in data.items()}
 
 
+def phase_position(task_type: str) -> str:
+    """이 phase 가 생애주기 몇 번째인지 — `"5 of 7"`.
+
+    리드는 자기가 어느 칸을 도는지만 알고 지도를 못 본다. 다음 phase 이름은
+    이 run 의 리포트가 정하므로 계속 감추지만(`WORKFLOW_NEXT_RECOMMENDED_PHASE`
+    가 빈 문자열인 이유), 위치를 감출 이유는 없다 — 위치를 모르면 중간 단계를
+    도는 run 이 자기가 마지막인 것처럼 결론을 낸다.
+
+    `PHASE_SEQUENCE` 밖의 사이드트랙 task-type(improvement-discovery 등)은
+    생애주기 칸이 없으므로 빈 문자열이다.
+    """
+    if task_type not in PHASE_SEQUENCE:
+        return ""
+    return f"{PHASE_SEQUENCE.index(task_type) + 1} of {len(PHASE_SEQUENCE)}"
+
+
 def compute_workflow_state(
     *,
     task_type: str,
@@ -219,6 +235,7 @@ def compute_workflow_state(
         "WORKFLOW_WORK_CATEGORY": resolved_work_category,
         "WORKFLOW_CURRENT_PHASE": task_type,
         "WORKFLOW_CURRENT_PHASE_STATE": phase_state,
+        "WORKFLOW_PHASE_POSITION": phase_position(task_type),
         # 값이 아니라 자리표시자다. 실제 포인터는 리포트 라우팅에서 투영돼
         # 매니페스트의 `workflow.nextRecommendedPhase` 구조체로 저장된다.
         # 이 ctx 값은 그 구조체로 대체되지 않는다 — 남은 소비자는

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

@@ -0,0 +1,92 @@
+"""Per-task git worktree provisioning.
+
+Every okstra task — regardless of task-type/phase — runs inside an
+isolated git worktree rooted at
+`~/.okstra/worktrees/<project_id>/<task_group>/<task_id>/`. The same
+worktree is reused across all phases of one task-key (requirements-
+discovery → error-analysis → implementation-option-selection →
+implementation-planning → implementation), so phase N picks up exactly
+the working-tree state phase N-1 left behind.
+
+A global registry (`worktree_registry.py`) maps task-keys to the
+on-disk path + branch and serialises reservations, so two concurrent
+okstra runs cannot collide on the same path or branch name.
+
+Pre-conditions handled here:
+  - Skip when `project_root` is not a git repo (degrade gracefully).
+  - Skip when `project_root` itself is already a non-main worktree
+    (caller's tree is already an isolated workspace; reuse it).
+  - Re-entry of the same task-key returns the existing worktree.
+  - Branch / path collisions across task-keys raise PrepareError-like
+    RuntimeError.
+
+Side effects:
+  - `git worktree add -b <branch> <path> <base_ref>` invoked in the
+    main worktree of `project_root` (NOT `project_root` itself when it
+    is also a worktree — base must be the main checkout).
+  - Per-task sync dirs (.project-docs, .scratch, graphify-out by
+    default) symlinked from the **main worktree** into the new
+    worktree so every task sees the same shared state, irrespective of
+    which worktree the caller invoked okstra from.
+  - The function does NOT chdir.
+
+구현은 여섯 층으로 나뉜다. 바닥의 세 층 — `naming`(문자열 계산),
+`sync_config`(무엇을 옮길지), `git_ops`(git 사실) — 은 서로를 모른다. 그 위에
+`cleanliness`(무엇이 더러운가) · `linking`(실제로 링크 걸기) ·
+`decisions`(무엇이 일어날지 미리 답하기)가 있고, 부수 효과를 내는 것은
+`provision` 하나뿐이다. 이 파일은 밖으로 나가는 이름만 모아 둔다.
+"""
+from __future__ import annotations
+
+from .cleanliness import (
+    dirty_entries_excluding_okstra,
+    is_dirty_excluding_okstra,
+    nested_worktree_excludes,
+    okstra_clean_gate_excludes,
+)
+from .decisions import (
+    StageWorktreeDecision,
+    WorktreeDecision,
+    preview_worktree_decision,
+    resolve_stage_worktree_decision,
+)
+from .git_ops import (
+    MergeError,
+    _git,
+    _resolve_commit_sha,
+    is_ancestor,
+    is_git_work_tree,
+    main_worktree_path,
+    merge_branch,
+    remove_worktree_force,
+)
+from .naming import compute_branch_name, compute_worktree_path
+from .provision import (
+    WorktreeProvision,
+    provision_stage_worktree,
+    provision_task_worktree,
+)
+
+__all__ = [
+    "MergeError",
+    "StageWorktreeDecision",
+    "WorktreeDecision",
+    "WorktreeProvision",
+    "_git",
+    "_resolve_commit_sha",
+    "compute_branch_name",
+    "compute_worktree_path",
+    "dirty_entries_excluding_okstra",
+    "is_ancestor",
+    "is_dirty_excluding_okstra",
+    "is_git_work_tree",
+    "main_worktree_path",
+    "merge_branch",
+    "nested_worktree_excludes",
+    "okstra_clean_gate_excludes",
+    "preview_worktree_decision",
+    "provision_stage_worktree",
+    "provision_task_worktree",
+    "remove_worktree_force",
+    "resolve_stage_worktree_decision",
+]

package/runtime/python/okstra_ctl/worktree/cleanliness.py

@@ -0,0 +1,89 @@
+"""okstra 기준으로 worktree 가 깨끗한지 판정한다.
+
+`git status` 가 보는 더러움과 okstra 가 신경 쓰는 더러움은 다르다. okstra 는
+자기 산출물(`.okstra/`), 자기가 걸어 둔 sync 심링크, 자기가 만든 중첩 worktree
+를 제외하고 남는 변경만 사용자의 것으로 본다. 그 제외 목록을 만드는 곳이
+여기이고, 그래서 `sync_config`(무엇을 걸었나)와 `git_ops`(지금 무엇이 바뀌었나)
+양쪽을 쓴다.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+from .git_ops import _git
+from .sync_config import (
+    _resolve_snapshot_files,
+    _resolve_sync_dirs,
+    _resolve_sync_files,
+)
+
+
+def okstra_clean_gate_excludes(project_root: Optional[Path] = None) -> tuple[str, ...]:
+    """Project-relative paths okstra owns and source clean gates should ignore."""
+    out: list[str] = []
+    seen: set[str] = set()
+    for rel in (
+        ".okstra",
+        *_resolve_sync_dirs(project_root),
+        *_resolve_sync_files(project_root),
+        *_resolve_snapshot_files(project_root),
+    ):
+        cleaned = rel.strip().removeprefix("./").rstrip("/")
+        if not cleaned or cleaned == "." or cleaned in seen:
+            continue
+        seen.add(cleaned)
+        out.append(cleaned)
+    return tuple(out)
+
+
+def nested_worktree_excludes(worktree_path) -> tuple[str, ...]:
+    """Relative paths of git worktrees nested under `worktree_path`.
+
+    implementation stage worktrees live inside the task worktree
+    (`<task-id>/stage-<N>/`), so the parent's `git status --short` reports
+    each as an untracked `?? stage-N/`. They are git-registered worktrees,
+    not user source changes, so clean gates must ignore them. Derived from
+    `git worktree list` rather than a hardcoded pattern so it tracks exactly
+    what git registered.
+    """
+    root = Path(worktree_path).resolve()
+    r = _git(root, "worktree", "list", "--porcelain")
+    if r.returncode != 0:
+        return ()
+    out: list[str] = []
+    for line in r.stdout.splitlines():
+        if not line.startswith("worktree "):
+            continue
+        wt = Path(line[len("worktree "):].strip()).resolve()
+        if wt == root:
+            continue
+        try:
+            rel = wt.relative_to(root)
+        except ValueError:
+            continue
+        out.append(str(rel))
+    return tuple(out)
+
+
+def dirty_entries_excluding_okstra(cwd) -> list[str]:
+    """`git status --short` rows for changes outside okstra-owned paths.
+
+    okstra-owned = `okstra_clean_gate_excludes` (e.g. `.okstra`, synced dirs)
+    plus `nested_worktree_excludes` (stage worktrees nested under `cwd`).
+
+    This is the clean-worktree question every okstra gate asks, and the one a
+    plan step must ask through `okstra worktree-status` rather than through a
+    bare `git status --porcelain`: okstra provisions `.okstra` plus the synced
+    entries into every task worktree, so a bare status is never empty there and
+    an assertion built on it fails on okstra's own scaffolding.
+    """
+    owned = (*okstra_clean_gate_excludes(Path(cwd)), *nested_worktree_excludes(cwd))
+    excludes = [f":(exclude){p}" for p in owned]
+    out = _git(Path(cwd), "status", "--short", "--", ".", *excludes).stdout
+    return [line for line in out.splitlines() if line.strip()]
+
+
+def is_dirty_excluding_okstra(cwd) -> bool:
+    """True iff the worktree has changes outside okstra-owned paths."""
+    return bool(dirty_entries_excluding_okstra(cwd))

package/runtime/python/okstra_ctl/worktree/decisions.py

@@ -0,0 +1,127 @@
+"""provision 하기 전에 무엇이 일어날지 답한다.
+
+위저드는 사용자에게 경로와 브랜치를 보여 준 뒤 확인을 받는다. 그 시점에 이미
+worktree 를 만들어 버리면 안 되므로, 판단(재사용인가 신규인가, 어느 경로인가)만
+떼어 여기에 둔다. 레지스트리를 읽기는 하지만 예약하지는 않는다 — 예약은
+`provision` 의 몫이다.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from .. import worktree_registry
+from .git_ops import _is_inside_non_main_worktree, is_git_work_tree
+from .naming import _safe_segment, compute_branch_name, compute_worktree_path
+
+
+@dataclass
+class WorktreeDecision:
+    """Side-effect-free preview of what `provision_task_worktree` would do.
+
+    status:
+      - "new": no active registry entry; a fresh worktree would be created
+      - "reused": registry already has this task-key; existing path/branch returned
+      - "skipped-in-worktree": project_root is itself a non-main worktree
+      - "skipped-not-git": project_root has no .git
+    """
+    status: str
+    path: str              # worktree path (new: prospective; reuse: existing; skip: project_root)
+    branch: str = ""       # new: prospective branch; reused: existing branch
+    base_ref: str = ""     # new: requested base_ref; reused: existing base
+
+
+def preview_worktree_decision(
+    *,
+    project_root,
+    project_id: str,
+    task_group_segment: str,
+    task_id_segment: str,
+    work_category: str,
+    base_ref: str = "",
+) -> "WorktreeDecision":
+    """Side-effect-free: what provision_task_worktree WOULD do, without touching disk.
+
+    Mirrors provision's decision branches exactly; reuses the same read-only
+    helpers so preview never diverges from the actual provisioning result.
+    """
+    project_root = Path(project_root)
+    if not is_git_work_tree(project_root):
+        return WorktreeDecision(status="skipped-not-git", path=str(project_root))
+    if _is_inside_non_main_worktree(project_root):
+        return WorktreeDecision(status="skipped-in-worktree", path=str(project_root))
+    safe_project = _safe_segment(project_id)
+    safe_group = _safe_segment(task_group_segment)
+    safe_task = _safe_segment(task_id_segment)
+    existing = worktree_registry.lookup(safe_project, safe_group, safe_task)
+    if existing is not None and existing.status == "active":
+        return WorktreeDecision(
+            status="reused", path=existing.worktree_path,
+            branch=existing.branch, base_ref=existing.base_ref,
+        )
+    return WorktreeDecision(
+        status="new",
+        path=str(compute_worktree_path(
+            project_id=safe_project, task_group_segment=safe_group,
+            task_id_segment=safe_task)),
+        branch=compute_branch_name(work_category=work_category, task_id_segment=safe_task),
+        base_ref=base_ref,
+    )
+
+
+@dataclass
+class StageWorktreeDecision:
+    """Side-effect-free decision for one concrete implementation stage."""
+
+    status: str
+    path: str
+    branch: str = ""
+    base_ref: str = ""
+
+
+def resolve_stage_worktree_decision(
+    *,
+    project_id: str,
+    task_group_segment: str,
+    task_id_segment: str,
+    work_category: str,
+    stage_number: int,
+) -> StageWorktreeDecision:
+    """Resolve whether one concrete stage worktree is new or reusable."""
+    safe_project = _safe_segment(project_id)
+    safe_group = _safe_segment(task_group_segment)
+    safe_task = _safe_segment(task_id_segment)
+    existing = worktree_registry.lookup(
+        safe_project, safe_group, safe_task, stage_number=stage_number)
+    if existing is not None and _stage_entry_is_reusable(existing):
+        return StageWorktreeDecision(
+            status="reused",
+            path=existing.worktree_path,
+            branch=existing.branch,
+            base_ref=existing.base_ref,
+        )
+    return StageWorktreeDecision(
+        status="new",
+        path=str(compute_worktree_path(
+            project_id=safe_project, task_group_segment=safe_group,
+            task_id_segment=safe_task, stage_number=stage_number)),
+        branch=compute_branch_name(
+            work_category=work_category, task_id_segment=safe_task,
+            stage_number=stage_number),
+    )
+
+
+def _stage_entry_is_reusable(entry: worktree_registry.WorktreeEntry) -> bool:
+    """Whether a registered stage worktree can be entered by this run.
+
+    `active` is the live-run case. `released` with the directory still on disk is
+    the fix-run case: a stage whose verifier returned FAIL records a `failed`
+    consumers row, which frees the occupancy but deliberately keeps the worktree
+    and its branch as the reviewable stack. Re-entry MUST reuse that tree —
+    provisioning anew refuses on the existing path and branch. After whole-task
+    final-verification removes the directory the entry stops being reusable, so
+    the stage provisions from scratch.
+    """
+    if entry.status == "active":
+        return True
+    return entry.status == "released" and Path(entry.worktree_path).is_dir()