okstra 0.98.2 → 0.99.1

package/runtime/python/okstra_ctl/team_reconcile.py

@@ -2,22 +2,20 @@
 
 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 and ``TeamDelete()``
-succeeds immediately. The one failure mode is a member whose tmux pane died
-WITHOUT clearing the flag (killed mid-turn): it stays ``isActive: true`` forever,
-and ``TeamDelete`` then refuses the whole team with an "active members" error
-that re-sending ``shutdown_request`` cannot clear — the addressee is already
-gone.
+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.
 
-Note: the active-member flag is the harness's source of truth, but whether
-``TeamDelete`` re-reads ``config.json`` at delete time (vs. caching the roster in
-the owning session) is a harness behaviour that can only be confirmed inside a
-real run — see _common-contract.md "Run-end team teardown".
+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 _common-contract.md "Run-end teammate teardown".
 """
 from __future__ import annotations
 
@@ -79,8 +77,8 @@ def _config_path(team_arg: str) -> Path:
 
 
 def _atomic_write(path: Path, text: str) -> None:
-    """Replace ``path`` atomically — config.json is load-bearing for the next
-    TeamDelete, so a partial write on crash must never be observable."""
+    """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:

package/runtime/python/okstra_ctl/worktree.py

@@ -41,7 +41,7 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import Optional
 
-from okstra_project.dirs import project_json_path
+from okstra_project.dirs import okstra_home, project_json_path
 
 from .ids import _safe_fs_segment
 from . import worktree_registry
@@ -642,8 +642,7 @@ def compute_worktree_path(
     `~/.okstra`."""
     if stage_number is not None and group_id is not None:
         raise ValueError("stage_number and group_id are mutually exclusive")
-    okstra_home = os.environ.get("OKSTRA_HOME", "").strip()
-    base = Path(okstra_home) if okstra_home else (Path.home() / ".okstra")
+    base = okstra_home()
     path = (
         base / "worktrees"
         / _safe_segment(project_id)

package/runtime/python/okstra_ctl/worktree_registry.py

@@ -32,15 +32,15 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import Optional
 
+from okstra_project.dirs import okstra_home
+
 
 REGISTRY_FILENAME = "registry.json"
 LOCK_FILENAME = "registry.lock"
 
 
 def _okstra_worktrees_dir() -> Path:
-    home_env = os.environ.get("OKSTRA_HOME", "").strip()
-    base = Path(home_env) if home_env else (Path.home() / ".okstra")
-    return base / "worktrees"
+    return okstra_home() / "worktrees"
 
 
 def task_key(

package/runtime/python/okstra_project/dirs.py

@@ -15,6 +15,8 @@ DRY 위반의 비용: 이전에는 동일 path 문자열이 50+ Python·Shell·m
 from __future__ import annotations
 
 import os
+import sys
+import tempfile
 from pathlib import Path
 
 OKSTRA_DIR_NAME = ".okstra"
@@ -40,12 +42,37 @@ TASK_CATALOG_RELATIVE = DISCOVERY_RELATIVE / "task-catalog.json"
 LATEST_TASK_RELATIVE = DISCOVERY_RELATIVE / "latest-task.json"
 
 
+def _is_stale_tmp_home(path: str) -> bool:
+    """삭제된 pytest 격리 OKSTRA_HOME 누수 판별. tests/conftest.py 가 격리 홈을
+    ``<tmp_path>/.okstra-isolated``(시스템 임시 하위)로 만드는데, 그 디렉터리가
+    사라진 채 env 만 남은 경우만 폴백 대상이다. 실제/커스텀 홈이나 곧 생성될
+    임시 홈(``.okstra`` 등)은 이름이 달라 걸리지 않는다(테스트 오폴백 방지)."""
+    if Path(path).name != ".okstra-isolated":
+        return False
+    roots = [
+        tempfile.gettempdir(),
+        "/tmp", "/private/tmp", "/var/folders", "/private/var/folders",
+    ]
+    return any(path == r or path.startswith(r.rstrip("/") + "/")
+               for r in roots if r)
+
+
 def okstra_home() -> Path:
-    """`~/.okstra` 절대 path. 테스트/설치 환경에서 `OKSTRA_HOME` env 로 override."""
+    """`~/.okstra` 절대 path. 테스트/설치 환경에서 `OKSTRA_HOME` env 로 override.
+
+    OKSTRA_HOME 이 존재하지 않는 시스템 임시 경로(삭제된 pytest 격리 홈 등
+    누수된 값)를 가리키면 stderr 경고 후 기본 `~/.okstra` 로 폴백한다."""
     override = os.environ.get("OKSTRA_HOME", "").strip()
-    if override:
-        return Path(override)
-    return Path.home() / ".okstra"
+    if not override:
+        return Path.home() / ".okstra"
+    home = Path(override).expanduser()
+    if not home.exists() and _is_stale_tmp_home(str(home)):
+        sys.stderr.write(
+            f"⚠ OKSTRA_HOME={override} 가 존재하지 않는 임시 경로입니다 "
+            "(누수된 테스트 격리 값으로 보임) → ~/.okstra 로 폴백합니다.\n"
+        )
+        return Path.home() / ".okstra"
+    return home
 
 
 def okstra_root(project_root: Path) -> Path:

package/runtime/python/okstra_token_usage/collect.py

@@ -517,12 +517,14 @@ def collect(team_state_path: Path, project_root: Path | None = None, *,
             unattributed_sessions.append(sid)
             unattributed_totals.append(totals)
 
-    # no-team run (teamCreate skipped/concurrent-run, or error fallback) —
-    # worker 세션에 team 태그가 없어 위 needle 탐색이 비므로, agentName 기반
-    # 발견으로 보강한다. run 윈도우 밖 세션(in-window 이벤트 없음 = startedAt
-    # 부재)은 같은 agentName 의 타 run 세션이므로 버린다.
+    # implicit-team run (CC v2.1.178+: no TeamCreate, status "implicit") or
+    # legacy no-team run (skipped/concurrent-run, error fallback) — the implicit
+    # team tags worker jsonls with the harness team name (`session-<leadSid>`),
+    # NOT okstra's `teamName` label, so the needle scan above only finds the lead.
+    # agentName 기반 발견으로 worker 세션을 보강한다. run 윈도우 밖 세션(in-window
+    # 이벤트 없음 = startedAt 부재)은 같은 agentName 의 타 run 세션이므로 버린다.
     team_create_status = str((state.get("teamCreate") or {}).get("status", "")).strip()
-    if team_create_status in ("skipped", "error"):
+    if team_create_status in ("implicit", "skipped", "error"):
         worker_prefix_pool = [
             prefix
             for w in state.get("workers", [])

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

@@ -209,14 +209,14 @@ When the user picks a waiver, append `--qa-waiver "<stageKey>:<reason>"` to the
 
 `render-bundle` stdout 에 `okstra concurrent-run stages: <stages>` 라벨 라인이
 있으면(같은 task-key 의 다른 implementation run 이 `<stages>` 를 점유 중), launch
-프롬프트는 이미 "Concurrent-run: no-team background" 게이트로 렌더돼 있다. 이 라인이
+프롬프트는 이미 "Concurrent-run marker" 게이트로 렌더돼 있다. 이 라인이
 없으면 동시-run 이 아니므로 이 분기를 건너뛴다. 라인이 있으면 dispatch 전에
 사용자에게 3-옵션 recommendation picker 를 제시한다 (run-prompt recommendation 규칙:
 1–2 추천 + 직접 입력; 이 picker 는 스킬이 author 하는 것이라 wizard `options[]`
 제약과 무관):
 
-1. (추천) 이대로 no-team background 로 진행 — 이미 렌더된 bundle 을 그대로 사용한다.
-   team 을 만들지 않아 `~/.claude/teams/` race 를 회피한다(Teams split-pane 관찰성만 포기).
+1. (추천) 이대로 진행 — 이미 렌더된 bundle 을 그대로 사용한다. 각 세션은 자기
+   implicit team 을 쓰므로 동시 run 끼리 team 충돌이 없고, split-pane 도 정상 동작한다.
 2. 대기 — 지금 dispatch 를 보류한다. stage worktree·run-context 는 보존되므로,
    점유 중인 다른 run 종료 후 같은 stage 를 resume 으로 재개하면 그때는 정상 team
    경로다. resume 명령(`okstra-inspect` history → resume)을 사용자에게 출력한다.

package/runtime/validators/lib/fixtures.sh

@@ -288,13 +288,13 @@ if isinstance(lead, dict):
         lead["sessionId"] = "fixture-lead-session-0001"
 team_state["workflowState"] = "worker-results-collected"
 
-# validate-run.py requires team-state.teamCreate.attempted=true with a
-# status of ok|error once any worker has been dispatched (see
-# validators/validate-run.py:334-337). Mirror that here so the fixture
-# represents a valid post-Phase-3 state.
+# validate-run.py requires team-state.teamCreate.status == "implicit" once any
+# worker has been dispatched (CC v2.1.178 removed TeamCreate; every session has
+# an implicit team). Mirror that here so the fixture is a valid post-Phase-3 state.
 team_state["teamCreate"] = {
-    "attempted": True,
-    "status": "ok",
+    "attempted": False,
+    "status": "implicit",
+    "splitPane": False,
 }
 
 # Phase 7 token-usage collection is normally produced by okstra-token-usage.py.
@@ -461,7 +461,7 @@ if lead_sid:
         "PROGRESS: phase-1-intake reading task bundle",
         "PROGRESS: phase-1-intake complete",
         f"PROGRESS: phase-2-prompts preparing {len(team_state.get('workers') or [])} worker prompts",
-        "PROGRESS: phase-3-team-create attempting TeamCreate",
+        "PROGRESS: phase-3-team-create using implicit team (split-pane=off)",
     ]
     for worker in team_state.get("workers", []):
         if not isinstance(worker, dict):
@@ -478,6 +478,7 @@ if lead_sid:
             progress_lines.append(
                 f"PROGRESS: phase-5-collect worker={worker_id}-worker status=completed"
             )
+    progress_lines.append("PROGRESS: phase-batch-cleanup panes=1 teammates=1")
     progress_lines.append("PROGRESS: phase-6-synthesis dispatching report-writer-worker")
     progress_lines.append("PROGRESS: phase-7-persist updating manifests")
     records = [

package/runtime/validators/validate-run.py

@@ -357,9 +357,9 @@ def _is_legal_concurrent_run_skip(
     team_create: object, concurrent_run_authorized: bool
 ) -> bool:
     """prepare 가 run-manifest 에 동시-run 을 기록한 run 에서만, 렌더 게이트
-    ("Concurrent-run: no-team background")가 지시한 teamCreate skipped 형태를
-    legal 터미널 상태로 인정한다. lead 의 team-state 자기 선언만으로는(앵커
-    없이) 열리지 않는다 — 선언이 아닌 prepare-측 사실이 강제 근거다."""
+    ("Concurrent-run marker")가 지시한 teamCreate skipped 형태를 legal 터미널
+    상태로 인정한다. lead 의 team-state 자기 선언만으로는(앵커 없이) 열리지
+    않는다 — 선언이 아닌 prepare-측 사실이 강제 근거다."""
     if not concurrent_run_authorized or not isinstance(team_create, dict):
         return False
     return (
@@ -431,23 +431,26 @@ def validate_team_state(
             team_create = team_state.get("teamCreate")
             if _is_legal_concurrent_run_skip(team_create, concurrent_run_authorized):
                 pass
-            elif not isinstance(team_create, dict) or not team_create.get("attempted"):
+            elif not isinstance(team_create, dict) or not str(team_create.get("status", "")).strip():
                 failures.append(
-                    "team-state.teamCreate.attempted must be true once any worker has "
-                    "been dispatched (status in completed/timeout/error/in-progress). "
-                    "Phase 3 (TeamCreate) was skipped — workers ran in-process without "
-                    "the Teams split-pane surface. See prompts/lead/okstra-lead-contract.md Phase 3. "
-                    "(The no-team concurrent-run path is legal ONLY when the "
-                    "run-manifest carries prepare-recorded `concurrentRun.detected: "
-                    'true` AND team-state records `teamCreate: { attempted: false, '
-                    'status: "skipped", reason: "concurrent-run" }`.)'
+                    "team-state.teamCreate must be recorded with a status once any worker "
+                    "has been dispatched (status in completed/timeout/error/in-progress). "
+                    "CC v2.1.178 removed TeamCreate; every session has an implicit team, so "
+                    'Phase 3 records `teamCreate: { attempted: false, status: "implicit" }` — '
+                    "the audit marker that drives Phase 7 token attribution. See "
+                    "prompts/lead/okstra-lead-contract.md Phase 3. (The concurrent-run path "
+                    "is legal ONLY when the run-manifest carries prepare-recorded "
+                    '`concurrentRun.detected: true` AND team-state records '
+                    '`teamCreate: { attempted: false, status: "skipped", reason: "concurrent-run" }`.)'
                 )
             else:
                 tc_status = str(team_create.get("status", "")).strip()
-                if tc_status not in {"ok", "error"}:
+                if tc_status != "implicit":
                     failures.append(
-                        "team-state.teamCreate.status must be `ok` or `error` once "
-                        f"workers have been dispatched (found: `{tc_status}`)."
+                        "team-state.teamCreate.status must be `implicit` once workers have "
+                        "been dispatched (the only other legal value is `skipped` with "
+                        "reason `concurrent-run` in a prepare-authorized concurrent run). "
+                        f"Found: `{tc_status}`."
                     )
 
     by_role: dict[str, dict] = {}

package/runtime/validators/validate_session_conformance.py

@@ -348,6 +348,38 @@ def _check_worker_checkpoint_lines(
             )
 
 
+def _check_batch_cleanup_checkpoints(
+    by_phase: dict[str, list[tuple[str, str]]],
+    convergence_ran: bool,
+    report_writer_dispatched: bool,
+    errors: list[str],
+) -> None:
+    """phase-batch-cleanup: 각 배치 경계 직전에 이전 배치 pane/teammate 정리가
+    실제로 일어났는지 (prompts/profiles/_common-contract.md 'Phase-start cleanup').
+    R1=convergence round 1 직전, R2=report-writer dispatch 직전(수렴이 있었으면
+    마지막 라운드 이후 별도 1회). ISO-8601 ts 는 lexicographic 비교가 곧 시간순."""
+    detail = "prompts/profiles/_common-contract.md 'Phase-start cleanup'"
+    cleanup_ts = sorted(ts for ts, _line in by_phase.get("phase-batch-cleanup", []))
+    conv_ts = sorted(ts for ts, _line in by_phase.get("phase-5.5-convergence", []))
+    synth_ts = sorted(ts for ts, _line in by_phase.get("phase-6-synthesis", []))
+
+    if convergence_ran and conv_ts and not any(ts <= conv_ts[0] for ts in cleanup_ts):
+        errors.append(
+            "PROGRESS checkpoint missing: no `phase-batch-cleanup` line before the "
+            f"first `phase-5.5-convergence` round ({conv_ts[0]}) — the prior analysis "
+            f"batch's panes/teammates must be cleared first ({detail})."
+        )
+
+    if report_writer_dispatched and synth_ts:
+        lower = conv_ts[-1] if (convergence_ran and conv_ts) else ""
+        if not any(lower <= ts <= synth_ts[0] for ts in cleanup_ts):
+            errors.append(
+                "PROGRESS checkpoint missing: no `phase-batch-cleanup` line before "
+                f"`phase-6-synthesis` ({synth_ts[0]}) — the prior batch must be cleared "
+                f"before dispatching report-writer ({detail})."
+            )
+
+
 def _check_progress_checkpoints(
     evidence: _LeadEvidence,
     team_state: dict,
@@ -387,24 +419,31 @@ def _check_progress_checkpoints(
     require(
         "phase-3-team-create",
         any_dispatched,
-        "immediately before the TeamCreate call — or, in the authorized no-team "
-        "concurrent-run path, the `phase-3-team-create skipped (concurrent-run)` "
-        "variant emitted right after recording teamCreate skipped in team-state",
+        "in Phase 3 after recording teamCreate in team-state — the "
+        "`using implicit team (split-pane=<on|off>)` line, or the "
+        "`skipped (concurrent-run)` variant in the concurrent-run path",
     )
     _check_worker_checkpoint_lines(by_phase, analysis_workers, errors)
+    convergence_ran = _convergence_rounds_ran(run_dir, suffix)
     require(
         "phase-5.5-convergence",
-        _convergence_rounds_ran(run_dir, suffix),
+        convergence_ran,
         "at the start of each convergence round (state artifact records totalRounds >= 1)",
     )
     report_writer = next((w for w in workers if _is_report_writer(w)), None)
+    report_writer_dispatched = (
+        report_writer is not None
+        and str(report_writer.get("status", "")).strip() in _DISPATCHED_STATUSES
+    )
     require(
         "phase-6-synthesis",
-        report_writer is not None
-        and str(report_writer.get("status", "")).strip() in _DISPATCHED_STATUSES,
+        report_writer_dispatched,
         "at the start of Phase 6 (report-writer dispatch)",
     )
     require("phase-7-persist", True, "at the start of Phase 7")
+    _check_batch_cleanup_checkpoints(
+        by_phase, convergence_ran, report_writer_dispatched, errors
+    )
 
 
 def _parse_iso(ts: str) -> datetime | None:
@@ -469,13 +508,26 @@ def _check_heartbeat_sidecar(path: Path, errors: list[str]) -> None:
         prev = ts
 
 
-def _check_heartbeat_sidecars(run_dir: Path, task_type: str, errors: list[str]) -> None:
+def _check_heartbeat_sidecars(
+    run_dir: Path, task_type: str, suffix: str | None, errors: list[str]
+) -> None:
     """검사 2 — 사이드카 **존재** 는 validate-run.py validate_worker_results_audit 가
-    이미 강제하므로, 여기서는 존재하는 사이드카의 heartbeat 내용만 본다."""
+    이미 강제하므로, 여기서는 존재하는 사이드카의 heartbeat 내용만 본다.
+
+    비-stage 격리 task-type(requirements-discovery / error-analysis /
+    implementation-planning)은 `runs/<task-type>/worker-results/` 를 run 끼리
+    공유한다 — seq 는 파일명에만 있다. seq 를 무시하고 glob 하면 이미 폐기된
+    직전 run 의 audit(heartbeat 위반)까지 검사해 현재 run 을 오탐 실패시킨다.
+    다른 검사(progress / sidecar-read)와 동일하게 현재 run seq(suffix)로 스코핑한다."""
     worker_results_dir = run_dir / "worker-results"
     if not worker_results_dir.is_dir():
         return
-    for path in sorted(worker_results_dir.glob(f"claude-worker-audit-{task_type}-*.md")):
+    pattern = (
+        f"claude-worker-audit-{suffix}.md"
+        if suffix
+        else f"claude-worker-audit-{task_type}-*.md"
+    )
+    for path in sorted(worker_results_dir.glob(pattern)):
         _check_heartbeat_sidecar(path, errors)
 
 
@@ -534,8 +586,8 @@ def validate_session_conformance(
         return result
 
     run_dir = report_path.parent.parent
-    _check_heartbeat_sidecars(run_dir, task_type, result.errors)
     suffix = run_artifact_suffix(team_state_path)
+    _check_heartbeat_sidecars(run_dir, task_type, suffix, result.errors)
 
     lead_runtime = team_state.get("leadRuntime", "") or "claude-code"
     dispatch_mode = str(team_state.get("dispatchMode", "")).strip()

package/src/commands/lifecycle/config.mjs

@@ -1,7 +1,6 @@
 import { promises as fs } from "node:fs";
-import { homedir } from "node:os";
 import { dirname, join, resolve, isAbsolute } from "node:path";
-import { buildPythonpath, resolvePaths } from "../../lib/paths.mjs";
+import { buildPythonpath, resolvePaths, resolveOkstraHome } from "../../lib/paths.mjs";
 import { OKSTRA_DIR, projectJsonPath } from "../../lib/okstra-dirs.mjs";
 import { fileExists, runProcess } from "../../lib/proc.mjs";
 
@@ -124,8 +123,7 @@ function parseArgs(args) {
 }
 
 function okstraHome() {
-  const override = (process.env.OKSTRA_HOME || "").trim();
-  return override !== "" ? override : join(homedir(), ".okstra");
+  return resolveOkstraHome();
 }
 
 function globalConfigPath() {

package/src/commands/memory/memory.mjs

@@ -2,8 +2,8 @@ import { createInterface } from "node:readline/promises";
 import { stdin as input, stdout as output } from "node:process";
 import { randomBytes } from "node:crypto";
 import { promises as fs } from "node:fs";
-import { homedir } from "node:os";
 import { basename, dirname, join, relative, resolve } from "node:path";
+import { resolveOkstraHome } from "../../lib/paths.mjs";
 
 const MEMORY_TYPES = new Set([
   "context",
@@ -68,8 +68,7 @@ Add options:
 `;
 
 function okstraHome() {
-  const override = (process.env.OKSTRA_HOME || "").trim();
-  return override !== "" ? override : join(homedir(), ".okstra");
+  return resolveOkstraHome();
 }
 
 function memoryRoot() {

package/src/lib/paths.mjs

@@ -1,10 +1,36 @@
-import { homedir } from "node:os";
+import { homedir, tmpdir } from "node:os";
 import { join } from "node:path";
 import { existsSync } from "node:fs";
 import { getPackageRoot, getPackageVersion } from "./version.mjs";
 
+function isStaleTmpHome(p) {
+  // tests/conftest.py creates the isolated home as `<tmp_path>/.okstra-isolated`
+  // under the system temp dir. Only a deleted one (env leaked, dir gone) heals;
+  // a soon-to-be-created `.okstra` temp home or a custom home is left untouched.
+  if (!p.endsWith("/.okstra-isolated")) return false;
+  const roots = [tmpdir(), "/tmp", "/private/tmp", "/var/folders", "/private/var/folders"];
+  return roots.some(
+    (r) => r && (p === r || p.startsWith(r.replace(/\/+$/, "") + "/")),
+  );
+}
+
+// Resolve OKSTRA_HOME, healing a leaked value: when it points at a missing
+// system-temp path (e.g. a deleted pytest-isolated home), warn and fall back
+// to ~/.okstra instead of operating on the dead directory.
+export function resolveOkstraHome() {
+  const raw = process.env.OKSTRA_HOME?.trim();
+  if (!raw) return join(homedir(), ".okstra");
+  if (!existsSync(raw) && isStaleTmpHome(raw)) {
+    process.stderr.write(
+      `⚠ OKSTRA_HOME=${raw} points to a missing temp dir (leaked test value); falling back to ~/.okstra\n`,
+    );
+    return join(homedir(), ".okstra");
+  }
+  return raw;
+}
+
 export async function resolvePaths() {
-  const home = process.env.OKSTRA_HOME?.trim() || join(homedir(), ".okstra");
+  const home = resolveOkstraHome();
   const pkgRoot = getPackageRoot();
   const devLink = await readSimpleFile(join(home, "dev-link"));
   const runtimeRoot = devLink || join(pkgRoot, "runtime");