okstra 0.186.7 → 0.187.0

package/runtime/python/okstra_ctl/container_registry.py

@@ -1,72 +0,0 @@
-"""Per-task container registry — flock 보조 인덱스.
-
-docker 라벨은 컨테이너 존재 여부의 기준값(SSOT)이지만 tmux session/pane id 나
-findings 파일 경로 같은 운영 메타데이터는 추적하지 못한다. 이 모듈은 task root
-하위 ``container/registry.json`` 에 그런 보조 정보를 가벼운 dict 로 보관한다.
-
-flock + tmp+``os.replace`` 원자 쓰기 idiom 은 ``json_registry`` 의 공용
-Interface 를 사용하고, lock/registry 경로만 ``paths.container_paths()`` 로
-해소해 전역 ``~/.okstra/worktrees/registry.json`` 과 분리한다. dict 구조는
-``{"services": {<svc>: {session_name, pane_id, findings_path}}}`` 한 가지뿐 —
-worktree_registry 의 dataclass 는 복제하지 않는다.
-"""
-from __future__ import annotations
-
-from pathlib import Path
-
-from .json_registry import load_registry_json, registry_lock, save_registry_json
-from . import paths
-
-
-def _registry_lock(lock_path: Path):
-    """``container/registry.json.lock`` 에 대한 배타 flock."""
-    return registry_lock(lock_path)
-
-
-def _load(registry_path: Path) -> dict:
-    data = load_registry_json(registry_path, lambda: {"services": {}})
-    data.setdefault("services", {})
-    return data
-
-
-def _save(registry_path: Path, data: dict) -> None:
-    save_registry_json(registry_path, data)
-
-
-def reserve(
-    project_root: Path, group: str, task_id: str, service: str,
-    *, session_name: str, pane_id: str, findings_path: str,
-) -> None:
-    """``service`` 의 tmux session/pane/findings 메타데이터를 등록한다."""
-    cp = paths.container_paths(project_root, group, task_id)
-    with _registry_lock(cp["registry_lock"]):
-        data = _load(cp["registry"])
-        data["services"][service] = {
-            "session_name": session_name,
-            "pane_id": pane_id,
-            "findings_path": findings_path,
-        }
-        _save(cp["registry"], data)
-
-
-def lookup(project_root: Path, group: str, task_id: str) -> dict:
-    """현재 registry dict 를 돌려준다. 파일 부재 시 ``{"services": {}}``."""
-    cp = paths.container_paths(project_root, group, task_id)
-    with _registry_lock(cp["registry_lock"]):
-        return _load(cp["registry"])
-
-
-def release(project_root: Path, group: str, task_id: str, service: str) -> None:
-    """``service`` 항목 하나만 제거한다(없으면 no-op)."""
-    cp = paths.container_paths(project_root, group, task_id)
-    with _registry_lock(cp["registry_lock"]):
-        data = _load(cp["registry"])
-        data["services"].pop(service, None)
-        _save(cp["registry"], data)
-
-
-def clear(project_root: Path, group: str, task_id: str) -> None:
-    """모든 service 항목을 비운다."""
-    cp = paths.container_paths(project_root, group, task_id)
-    with _registry_lock(cp["registry_lock"]):
-        _save(cp["registry"], {"services": {}})

package/runtime/python/okstra_ctl/improvement_assignment.py

@@ -1,61 +0,0 @@
-"""Assign improvement-discovery primary passes from the resolved roster."""
-from __future__ import annotations
-
-from collections.abc import Mapping
-
-
-def assign_primary_lenses(
-    worker_ids: list[str],
-    priority_lenses: list[str],
-) -> dict[str, str]:
-    """Round-robin resolved worker instances over resolved priority lenses."""
-    if not worker_ids:
-        raise ValueError("worker IDs must not be empty")
-    if not priority_lenses:
-        raise ValueError("priority lenses must not be empty")
-    if len(set(worker_ids)) != len(worker_ids):
-        raise ValueError("worker IDs must be unique")
-    return {
-        worker_id: priority_lenses[index % len(priority_lenses)]
-        for index, worker_id in enumerate(worker_ids)
-    }
-
-
-def validate_primary_lens_assignments(
-    assignments: Mapping[str, str],
-    worker_ids: list[str],
-    priority_lenses: list[str],
-) -> list[str]:
-    """Require every selected analyser once at its roster-order lens."""
-    errors: list[str] = []
-    if not worker_ids:
-        return ["resolved analyser worker IDs must not be empty"]
-    if not priority_lenses:
-        return ["resolved priority lenses must not be empty"]
-    try:
-        expected = assign_primary_lenses(worker_ids, priority_lenses)
-    except ValueError as exc:
-        return [str(exc)]
-    if list(assignments) != worker_ids:
-        errors.append(
-            "assignment order must match resolved analyser worker order: "
-            + ", ".join(worker_ids)
-        )
-    for worker_id in worker_ids:
-        if worker_id not in assignments:
-            errors.append(f"missing worker assignment: {worker_id}")
-    for worker_id, lens in assignments.items():
-        if worker_id not in expected:
-            errors.append(f"extra worker assignment: {worker_id}")
-            continue
-        if lens not in priority_lenses:
-            errors.append(
-                f"{worker_id}: primary lens {lens!r} is outside resolved priority lenses"
-            )
-            continue
-        if lens != expected[worker_id]:
-            errors.append(
-                f"{worker_id}: expected primary lens {expected[worker_id]!r}, "
-                f"got {lens!r}"
-            )
-    return errors

package/runtime/python/okstra_ctl/resolver.py

@@ -1,54 +0,0 @@
-"""run id 해석."""
-from __future__ import annotations
-
-from pathlib import Path
-from typing import List
-
-from .listing import list_runs
-
-
-class ResolveError(Exception):
-    """runId 해석 실패. candidates 에 후보 목록 포함."""
-
-    def __init__(self, message: str, candidates: List[str]) -> None:
-        super().__init__(message)
-        self.candidates = candidates
-
-
-def _all_run_ids(home: Path) -> List[str]:
-    rows = list_runs(home, include_archive=True)
-    return [r["runId"] for r in rows]
-
-
-def resolve_run_id(home: Path, query: str) -> str:
-    """prefix substring 매칭 규칙으로 runId 해석.
-    1. 정확 일치 → 즉시 반환.
-    2. endswith 일치 1건 → 반환.
-    3. substring 일치 1건 → 반환.
-    그 외(0건/다수) → ResolveError.
-    """
-    ids = _all_run_ids(home)
-    if query in ids:
-        return query
-    ends = [i for i in ids if i.endswith(query)]
-    if len(ends) == 1:
-        return ends[0]
-    if len(ends) > 1:
-        raise ResolveError(f"ambiguous (endswith): {query!r}", ends)
-    subs = [i for i in ids if query in i]
-    if len(subs) == 1:
-        return subs[0]
-    if len(subs) > 1:
-        raise ResolveError(f"ambiguous (substring): {query!r}", subs)
-    raise ResolveError(f"no run matches {query!r}", [])
-
-
-def resolve_last(home: Path, *, project: str, task_group: str) -> str:
-    """가장 최근 runId 를 반환. 매칭 없으면 ResolveError."""
-    rows = list_runs(home, project=project, task_group=task_group,
-                     include_archive=True, limit=1)
-    if not rows:
-        raise ResolveError(
-            f"no run found for project={project} task_group={task_group}", []
-        )
-    return rows[0]["runId"]

package/runtime/python/okstra_ctl/team_reconcile.py

@@ -1,275 +0,0 @@
-"""Stale team-member reconciliation for run-end teardown.
-
-A Claude Code team member clears its own ``isActive`` flag in
-``~/.claude/teams/<team>/config.json`` when its ``Agent()`` dispatch returns, so
-by Phase 7 every worker is normally already inactive. The one failure mode is a
-member whose tmux pane died WITHOUT clearing the flag (killed mid-turn): it stays
-``isActive: true`` forever and keeps showing as a live member that re-sending
-``shutdown_request`` cannot clear — the addressee is already gone.
-
-This module reconciles exactly that case: a member with ``isActive`` truthy
-whose recorded tmux pane is no longer live is flipped to inactive. It NEVER
-touches a member whose pane is still live, the lead, or a member with no
-recorded pane — those are left for graceful shutdown.
-
-CC v2.1.178 removed ``TeamDelete``: the implicit team ends with the session and
-run-end teardown only dismisses teammates via ``shutdown_request``. Reconcile
-keeps the roster honest so a dismissed-but-dead member does not linger as a
-live pill — see okstra-lead-contract.md "Run-scoped worker-resource lifecycle"
-for neutral cleanup ownership and the selected Claude adapter's
-"Run-scoped resource lifecycle" for this provider-specific reconciliation.
-
-Roster resolution (``--project-root``) exists because ``team-state.lead.sessionId``
-is a phase-3 snapshot: Claude Code re-issues the session id across resume /
-compaction mid-run, so the live on-disk roster often sits under a DIFFERENT
-``session-*`` dir than the snapshot names. Resolving by the CURRENT live session
-(the newest jsonl under the encoded-cwd projects dir) is what makes split-pane
-teardown find the teammates it must dismiss.
-"""
-from __future__ import annotations
-
-import json
-import os
-import subprocess
-import sys
-import tempfile
-from pathlib import Path
-
-from okstra_ctl.session import resolve_inproc_lead_session_id
-from okstra_ctl.json_boundary import (
-    JsonBoundaryError,
-    external_claude_team_json_source,
-    load_external_json,
-)
-
-
-def live_pane_ids() -> tuple[bool, set[str]]:
-    """Return ``(tmux_available, live_pane_ids)``.
-
-    ``tmux_available`` is False when no tmux server is reachable; the caller must
-    then skip reconciliation rather than treat every pane as dead.
-    """
-    try:
-        out = subprocess.run(
-            ["tmux", "list-panes", "-a", "-F", "#{pane_id}"],
-            capture_output=True, text=True,
-        )
-    except FileNotFoundError:
-        return False, set()
-    if out.returncode != 0:
-        return False, set()
-    return True, {ln.strip() for ln in out.stdout.splitlines() if ln.strip()}
-
-
-def reconcile_members(config: dict, live_panes: set[str]) -> list[str]:
-    """Flip dead-pane stale-active members to inactive in-place.
-
-    Returns the names of members that were flipped. A member qualifies only when
-    it is not the lead, ``isActive`` is truthy, it has a recorded ``tmuxPaneId``,
-    and that pane is not among ``live_panes``.
-    """
-    lead = config.get("leadAgentId")
-    flipped: list[str] = []
-    for member in config.get("members", []):
-        if member.get("agentId") == lead:
-            continue
-        pane = (member.get("tmuxPaneId") or "").strip()
-        if not member.get("isActive") or not pane:
-            continue
-        if pane not in live_panes:
-            member["isActive"] = False
-            flipped.append(member.get("name", member.get("agentId", "?")))
-    return flipped
-
-
-def dismissible_members(config: dict) -> list[str]:
-    """Names of every non-lead member — the set the lead may ``shutdown_request``.
-
-    The lead further filters by confirmed-complete (result path present) before
-    dismissing; this just tells it which teammates the resolved roster holds.
-    """
-    lead = config.get("leadAgentId")
-    names: list[str] = []
-    for member in config.get("members", []):
-        if member.get("agentId") == lead:
-            continue
-        names.append(member.get("name", member.get("agentId", "?")))
-    return names
-
-
-def _team_config_for_session(session_id: str) -> Path:
-    """``~/.claude/teams/session-<prefix>/config.json`` for a session id.
-
-    The harness names the team dir with the session id's first segment (the
-    8-hex stem before the first dash), never the ``teamName`` label.
-    """
-    prefix = session_id.split("-", 1)[0]
-    return Path.home() / ".claude" / "teams" / f"session-{prefix}" / "config.json"
-
-
-def _live_team_config(project_root: Path) -> Path | None:
-    """Resolve the CURRENT live session's team config, or None when absent.
-
-    Robust to the mid-run session-id drift that strands the phase-3
-    ``lead.sessionId`` snapshot: keys off the live session, not the snapshot.
-    """
-    sid = resolve_inproc_lead_session_id(project_root)
-    if not sid:
-        return None
-    cand = _team_config_for_session(sid)
-    return cand if cand.is_file() else None
-
-
-def _config_path(team_arg: str) -> Path:
-    """Resolve a team name, a team dir, or a config.json path to the config file."""
-    p = Path(team_arg)
-    if p.name == "config.json":
-        return p
-    if p.is_dir():
-        return p / "config.json"
-    return Path.home() / ".claude" / "teams" / team_arg / "config.json"
-
-
-def _atomic_write(path: Path, text: str) -> None:
-    """Replace ``path`` atomically — config.json is the harness's roster source
-    of truth, so a partial write on crash must never be observable."""
-    fd, tmp = tempfile.mkstemp(dir=str(path.parent), prefix=".reconcile-")
-    try:
-        with os.fdopen(fd, "w") as handle:
-            handle.write(text)
-        os.replace(tmp, path)
-    except BaseException:
-        try:
-            os.unlink(tmp)
-        except OSError:
-            pass
-        raise
-
-
-def _reconcile_config(cfg_path: Path, dry_run: bool, print_members: bool) -> int:
-    """Read, reconcile, and (unless dry-run) write back one config.json.
-
-    When ``print_members`` is set, also emit one ``dismissible-member: <name>``
-    line per non-lead member so the lead knows whom to ``shutdown_request``.
-    """
-    try:
-        # 외부 입력: Claude Code가 소유하는 team roster 설정이다.
-        config = load_external_json(
-            external_claude_team_json_source(cfg_path),
-            artifact="Claude team configuration",
-        )
-    except JsonBoundaryError as exc:
-        print(f"team-reconcile: cannot read team config at {cfg_path}: {exc}",
-              file=sys.stderr)
-        return 1
-
-    available, live = live_pane_ids()
-    if not available:
-        print("team-reconcile: tmux unavailable — skipped (no flip)")
-    else:
-        flipped = reconcile_members(config, live)
-        if flipped and dry_run:
-            print("team-reconcile (dry-run): would deactivate " + ", ".join(flipped))
-        elif flipped:
-            _atomic_write(cfg_path, json.dumps(config, indent=2, ensure_ascii=False) + "\n")
-            print(f"team-reconcile: deactivated {len(flipped)} stale member(s): "
-                  + ", ".join(flipped))
-        else:
-            print("team-reconcile: no stale-active members")
-
-    if print_members:
-        for name in dismissible_members(config):
-            print(f"dismissible-member: {name}")
-    return 0
-
-
-def _session_id_from_stdin() -> str:
-    """Extract ``session_id`` from a SessionEnd hook's JSON payload on stdin.
-
-    Returns "" when stdin is a terminal (manual invocation), empty, or not the
-    expected JSON — the caller then no-ops. The hook must never block or fail a
-    session teardown.
-    """
-    if sys.stdin.isatty():
-        return ""
-    try:
-        raw = sys.stdin.read()
-    except OSError:
-        return ""
-    if not raw.strip():
-        return ""
-    try:
-        data = json.loads(raw)
-    except json.JSONDecodeError:
-        return ""
-    sid = data.get("session_id") or data.get("sessionId") or ""
-    return sid if isinstance(sid, str) else ""
-
-
-def _run_resolve_and_reconcile(project_root: str, fallback_team: str, dry_run: bool) -> int:
-    """``--project-root`` mode: resolve the live roster, reconcile, list members."""
-    cfg = _live_team_config(Path(project_root))
-    if cfg is None and fallback_team:
-        fb = _config_path(fallback_team)
-        cfg = fb if fb.is_file() else None
-    if cfg is None:
-        print("team-reconcile: no live roster for this session — nothing to dismiss")
-        return 0
-    print(f"team-reconcile: roster resolved at {cfg}")
-    return _reconcile_config(cfg, dry_run, print_members=True)
-
-
-def _run_session_end(dry_run: bool) -> int:
-    """``--session-end`` mode: reconcile the ending session's roster from the
-    SessionEnd hook payload. Safety net so a lead that skipped run-end teardown
-    still leaves no dead-pane member lingering as a live pill."""
-    sid = _session_id_from_stdin()
-    if not sid:
-        return 0
-    cfg = _team_config_for_session(sid)
-    if not cfg.is_file():
-        return 0
-    return _reconcile_config(cfg, dry_run, print_members=False)
-
-
-def _parse_argv(argv: list[str]) -> tuple[bool, str, str, bool, list[str]]:
-    dry_run = False
-    project_root = ""
-    fallback_team = ""
-    session_end = False
-    rest: list[str] = []
-    it = iter(argv)
-    for arg in it:
-        if arg in ("--list", "--dry-run"):
-            dry_run = True
-        elif arg == "--project-root":
-            project_root = next(it, "")
-        elif arg == "--fallback-team":
-            fallback_team = next(it, "")
-        elif arg == "--session-end":
-            session_end = True
-        else:
-            rest.append(arg)
-    return dry_run, project_root, fallback_team, session_end, rest
-
-
-def main(argv: list[str]) -> int:
-    dry_run, project_root, fallback_team, session_end, rest = _parse_argv(argv)
-
-    if session_end:
-        return _run_session_end(dry_run)
-    if project_root:
-        return _run_resolve_and_reconcile(project_root, fallback_team, dry_run)
-
-    if len(rest) != 1:
-        print("usage: okstra-team-reconcile.sh [--list] "
-              "(<team-name|team-dir|config.json> | --project-root <dir> "
-              "[--fallback-team <label>] | --session-end)",
-              file=sys.stderr)
-        return 2
-
-    cfg_path = _config_path(rest[0])
-    if not cfg_path.is_file():
-        print(f"team-reconcile: no team config at {cfg_path}", file=sys.stderr)
-        return 1
-    return _reconcile_config(cfg_path, dry_run, print_members=False)

package/runtime/python/okstra_ctl/tmux.py

@@ -1,134 +0,0 @@
-"""tmux command helpers for okstra-owned container and rerun sessions.
-
-Worker dispatch does not come through here. Workers land in a cmux surface or,
-outside cmux, in a cli-wrapper subprocess — neither owns a tmux pane. What is
-left is the two places that use tmux purely as a way to hold a long-lived
-background process: the container watcher/tail panes and `cmd-rerun.sh`'s
-detached spawn.
-"""
-from __future__ import annotations
-
-import shlex
-import shutil
-import subprocess
-from typing import Optional, Sequence
-
-
-# container watcher/tail pane 전용 태그. 이 태그가 붙은 pane 은 세션 종료 후에도
-# 생존한다 — watcher/tail 의 "세션 후 생존" 불변식이다. 예전에는 SessionEnd 의
-# 태그 스캔이 다른 태그만 본다는 사실이 그 생존을 지탱했지만, 지금은 그 스캔과
-# 훅과 스크립트 자체가 없어 pane 을 세션 경계에서 회수하는 주체가 아예 없다. 회수는 `down` / `stop-watcher` 의 스코프 reap 뿐이다.
-CONTAINER_TAG_OPTION = "@okstra_container_run"
-
-
-def _shell_quote(s: str) -> str:
-    """POSIX shell 안전 인용. shlex.quote 가 모든 메타문자를 처리한다."""
-    return shlex.quote(s)
-
-
-def build_tmux_command(*, session_name: str, cwd: str, run_seq: int,
-                       argv: list, okstra_script: str,
-                       extra_env: Optional[dict] = None) -> list:
-    """tmux new-session 명령을 list 형태로 반환."""
-    env_prefix = f"OKSTRA_RUN_SEQ_OVERRIDE={run_seq}"
-    if extra_env:
-        for k, v in extra_env.items():
-            env_prefix += f" {k}={_shell_quote(str(v))}"
-    inner = (f"{env_prefix} {_shell_quote(okstra_script)} "
-             + " ".join(_shell_quote(a) for a in argv))
-    return ["tmux", "new-session", "-d", "-s", session_name, "-c", cwd, inner]
-
-
-def tmux_available() -> bool:
-    if shutil.which("tmux") is None:
-        return False
-    try:
-        result = run_tmux(["display-message", "-p", "#{version}"], timeout=3)
-    except (OSError, subprocess.SubprocessError):
-        return False
-    return result.returncode == 0
-
-
-def run_tmux(
-    args: Sequence[str], *, timeout: int = 10
-) -> subprocess.CompletedProcess[str]:
-    return subprocess.run(
-        ["tmux", *args],
-        capture_output=True,
-        text=True,
-        timeout=timeout,
-        check=False,
-    )
-
-
-def new_detached_session(
-    session_name: str, cwd: str, first_cmd: str | None = None
-) -> str:
-    """detached tmux 세션을 띄우고 첫 pane id 를 반환한다.
-
-    cmd-rerun.sh 의 detached spawn 패턴을 python 으로 옮긴 것
-    (`tmux new-session -d -s <name> -c <cwd> [cmd]`). `-P -F #{pane_id}` 로
-    생성된 pane id 를 받아 이후 split_container_pane 의 `-t` 대상으로 쓴다.
-    first_cmd 미지정 시 기본 셸이 첫 pane 을 점유한다 — `true` 처럼 즉시 끝나는
-    명령을 주면 단일-윈도우 세션이 split 전에 무너질 수 있으므로(remain-on-exit
-    off), holder pane 은 오래 사는 명령이어야 한다.
-    """
-    args = ["new-session", "-d", "-s", session_name, "-c", cwd,
-            "-P", "-F", "#{pane_id}"]
-    if first_cmd:
-        args.append(first_cmd)
-    result = run_tmux(args)
-    if result.returncode != 0:
-        raise RuntimeError(result.stderr.strip() or "tmux new-session failed")
-    return result.stdout.strip()
-
-
-def split_container_pane(
-    *,
-    session_pane: Optional[str],
-    cwd: str,
-    command: str,
-    title: str,
-    scope_value: str,
-    kind: str,
-) -> Optional[str]:
-    """container watcher/tail pane 을 split 하고 container 전용 태그만 부착한다.
-
-    reap 가 스캔하는 trace 태그는 절대 부착하지 않는다 — CONTAINER_TAG_OPTION 으로
-    직접 set-option 한다. session_pane 가 빈값/None(tmux 미사용 경로)이면 raise
-    없이 None 반환(degrade).
-    """
-    if not session_pane:
-        return None
-    result = run_tmux(
-        ["split-window", "-h", "-P", "-F", "#{pane_id}",
-         "-c", cwd, "-t", session_pane, command]
-    )
-    if result.returncode != 0:
-        raise RuntimeError(result.stderr.strip() or "tmux split-window failed")
-    pane_id = result.stdout.strip()
-    set_pane_title(pane_id, title)
-    tag_container_pane(pane_id, scope_value)
-    return pane_id
-
-
-def tag_container_pane(pane_id: str, scope_value: str) -> None:
-    """container 전용 태그(CONTAINER_TAG_OPTION)만 부착한다.
-
-    reap 가 스캔하는 trace 태그는 절대 거치지 않는다 — 이 태그가 붙은 pane 은
-    세션 종료 후에도 생존하고 `down`/`stop-watcher` 의 스코프 reap 로만
-    회수된다. holder pane 도 이 태그로 묶어 회수 대상에 포함한다."""
-    run_tmux(["set-option", "-p", "-t", pane_id, CONTAINER_TAG_OPTION, scope_value])
-
-
-def set_pane_title(pane_id: str, title: str) -> None:
-    result = run_tmux(["select-pane", "-t", pane_id, "-T", title])
-    if result.returncode != 0:
-        raise RuntimeError(result.stderr.strip() or "tmux select-pane failed")
-
-
-def kill_pane(pane_id: str) -> None:
-    try:
-        run_tmux(["kill-pane", "-t", pane_id])
-    except (OSError, subprocess.SubprocessError):
-        return