okstra 0.98.1 → 0.99.0

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-brief/SKILL.md

@@ -393,9 +393,12 @@ Step 0):
 okstra task-list
 ```
 
-Parse the JSON `tasks[]` array; collect the **distinct** `taskGroup` values
-ordered by `updatedAt` descending. Take the **2 most-recent** distinct
-groups as recommendations.
+Parse the JSON `tasks[]` array. The `taskGroup` field is a **raw display
+name, not a slug** — `slugify` each value (lowercase + non-alphanumeric →
+`-`) and **dedupe by slug** so case/format variants collapse (e.g.
+`uploadFont` and `uploadfont` are one group, not two). Order the distinct
+slugs by their most-recent `updatedAt`. Take the **2 most-recent** distinct
+slugs as recommendations and show them in slug form.
 
 `AskUserQuestion` (single-select):
 
@@ -413,8 +416,14 @@ picker and ask one free-text question:
 `"Task group (e.g. backend-api, INV-1234, refactor)"` → `task_group`.
 
 Slug rule: same as `okstra-run` Step 3 — slugify, must have at least one
-alphanumeric character. Note that an existing group's value is already a
-slug; a `직접 입력` value is slugified before use.
+alphanumeric character. **Always slugify the chosen value**, whether it came
+from an existing-group selection or `직접 입력` — the `taskGroup` returned by
+`okstra task-list` is a raw display name, not a slug, so picking one verbatim
+would create a non-standard directory (e.g. `briefs/uploadFont/`). The brief's
+on-disk directory segment (`briefs/<task-group>/`) and the frontmatter
+`task-group` value are both the slugified form, and `validate-brief.py`
+(Step 6.6) rejects any brief whose directory segment differs from
+`slugify(frontmatter task-group)`.
 
 If `task_group` was already collected by Step 1b sub-step 0 (tracker
 preflight), reuse that value silently — do NOT ask again.
@@ -752,7 +761,7 @@ Use the same template per brief file. In tracker mode producing a parent
 plus N children, you write **N+1 files** (each carries only its own Source
 Material).
 
-The installed template `~/.okstra/templates/reports/brief.template.md` is the byte-for-byte SSOT for the brief shape — frontmatter keys, top-header blockquote, section ordering, and inline `<!-- author guidance -->` HTML comments. Render that file with the per-brief values substituted; leave any section's body as `_(none)_` rather than fabricating content. Preserve the template's HTML comments verbatim (they are part of the contract) but do NOT promote them to body prose.
+The installed template `~/.okstra/templates/reports/brief.template.md` is the byte-for-byte SSOT for the brief shape — frontmatter keys, top-header blockquote, and section ordering. The template's inline `<!-- author guidance -->` HTML comments are fill-in scaffolding for the author, NOT part of the artifact: render the file with per-brief values substituted and **strip every `<!-- ... -->` comment** so the final brief carries none. Leave any section's body as `_(none)_` rather than fabricating content.
 
 **Variant note:** The template file is the canonical reporter-input shape. For the codebase-scan variant (`scope: codebase` in frontmatter), OMIT the `## Source Material` and `## Problem / Symptom` headings entirely — do NOT include them with `_(none)_` bodies. Instead, KEEP the `## Scan Scope` and `## Priority Lenses` sections (already present in the template file, marked with HTML comments). For the error-feedback variant (`scope` omitted ⇒ `reporter-input`), use the reporter-input shape: KEEP `## Source Material` (the chosen cluster's anonymized error records) and `## Problem / Symptom`, and OMIT the codebase-only `## Scan Scope` / `## Priority Lenses` sections. The remaining sections (Context / Desired Outcome / Constraints / Related Artifacts / Open Questions / Reporter Confirmations / Augmentation) apply to all variants.
 
@@ -1010,15 +1019,17 @@ started.
   Augmentation / interpretation goes only into the `Augmentation` section
   or a `> augmented:` blockquote inside the required section.
 - **No template author-guidance in the artifact body.** The Step 5
-  template above carries author guidance in HTML comments
-  (`<!-- ... -->`); preserve those comments when writing the brief but do
-  NOT promote them to body prose. Section headings stay clean — never copy
-  parenthetical reviewer notes onto the heading itself (e.g. emit
+  template carries author guidance in HTML comments (`<!-- ... -->`);
+  **strip every such comment when writing the brief** — the final artifact
+  contains zero `<!-- ... -->` blocks. (The validator now ignores comment
+  regions, but a clean artifact is the contract, and it is what the
+  passing reference briefs look like.) Section headings stay clean — never
+  copy parenthetical reviewer notes onto the heading itself (e.g. emit
   `## Source Material`, not `## Source Material (verbatim — do not modify)`).
   Placeholder prose inside angle brackets (`<Background / scope / why
-  now…>`) is intentional and is meant to be replaced with the reporter's
-  actual content; do not strip the angle-bracket placeholders, replace
-  them.
+  now…>`) is NOT a comment — it is intentional scaffolding meant to be
+  replaced with the reporter's actual content; replace those placeholders,
+  do not leave them in.
 - If the tracker MCP is not connected, do not guess — ask the user to paste
   the body or skip the source.
 - If a URL fetch fails or hits an auth wall, do not guess — ask for a

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-brief.py

@@ -6,7 +6,8 @@ Checks performed per brief file:
 1. YAML frontmatter exists on line 1 with required keys.
 2. brief-id matches the filename stem.
 3. depth equals the number of `sub/` segments in the path (relative to the
-   `briefs/` root).
+   `briefs/` root), and the task-group directory segment equals the
+   slugified frontmatter `task-group` (lowercase, non-alphanumeric → `-`).
 4. Every Open Questions row starts with one of the five signal prefixes
    (general | terminology | intent-check | conversion-block | adr-candidate).
    `adr-candidate:` targets okstra-internal
@@ -56,6 +57,7 @@ from okstra_ctl.improvement_lenses import (
     MAX_PRIORITY_LENSES,
     MIN_PRIORITY_LENSES,
 )
+from okstra_ctl.ids import slugify_task_segment
 
 REQUIRED_FRONTMATTER_KEYS = {
     "type",
@@ -89,6 +91,23 @@ REPORTER_CONFIRMATION_VALUES = {"complete", "partial", "pending", "skipped"}
 
 SCOPE_VALUES = {"reporter-input", "codebase"}
 
+_HTML_COMMENT_RE = re.compile(r"<!--.*?-->", re.DOTALL)
+
+
+def strip_html_comments(text: str) -> str:
+    """Remove `<!-- ... -->` blocks before parsing.
+
+    The brief template carries author-guidance comments whose example rows
+    (`intent-check: <…>`, `conversion-block: <…>`, `terminology-mapping: <…>`)
+    are NOT real entries. Without this, every `- ` collector below
+    (`open_questions_rows`, `augmentation_entries`, `meaningful_bullets`) would
+    count them as data and raise false `reporter-confirmations` / `terminology`
+    failures. Comments are never brief content, so stripping them once here is
+    the single root fix. Frontmatter uses `#` comments only, so this is a no-op
+    for the YAML block.
+    """
+    return _HTML_COMMENT_RE.sub("", text)
+
 
 def strip_yaml_comment(line: str) -> str:
     """Drop a YAML inline comment, keeping `#` that is part of a value.
@@ -268,7 +287,7 @@ def check_reporter_confirmations(
 
 
 def validate_brief(path: Path, briefs_root: Path) -> list[str]:
-    text = path.read_text(encoding="utf-8")
+    text = strip_html_comments(path.read_text(encoding="utf-8"))
     errors: list[str] = []
 
     # 1. frontmatter
@@ -315,8 +334,10 @@ def validate_brief(path: Path, briefs_root: Path) -> list[str]:
     # 3. depth equals path's `sub/` nesting depth
     try:
         rel = path.relative_to(briefs_root)
+        under_root = True
     except ValueError:
         rel = path
+        under_root = False
     # path components after the task-group dir: any number of `sub` segments + filename
     parts = list(rel.parts)
     if len(parts) >= 2:
@@ -332,6 +353,19 @@ def validate_brief(path: Path, briefs_root: Path) -> list[str]:
                 f"frontmatter says depth={fm.get('depth')!r}"
             )
 
+    # 3b. task-group directory segment must equal the slugified frontmatter value.
+    # Catches case/format drift (e.g. dir `uploadFont` vs slug `uploadfont`) that
+    # case-insensitive filesystems hide but case-sensitive CI breaks on.
+    if under_root and len(parts) >= 2:
+        expected_segment = slugify_task_segment(fm.get("task-group", ""))
+        if expected_segment and parts[0] != expected_segment:
+            errors.append(
+                f"task-group directory segment {parts[0]!r} does not match the "
+                f"slugified frontmatter task-group {expected_segment!r} "
+                f"(frontmatter task-group={fm.get('task-group')!r}); rename the "
+                f"directory or fix the frontmatter so both use the slug"
+            )
+
     # 4. Open Questions prefixes
     oq_rows = open_questions_rows(text)
     intent_check_rows: list[str] = []

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:

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");