okstra 0.72.0 → 0.74.0

package/runtime/python/okstra_token_usage/claude.py

@@ -2,12 +2,18 @@
 from __future__ import annotations
 
 import json
+import re
 from datetime import datetime
 from pathlib import Path
 
 from .cursor import MAX_NEEDLES, fresh_cache, load_cache, save_cache
 from .paths import claude_project_dir, ts_in_window
 
+# lead 의 단계 체크포인트 라인(agents/SKILL.md "Progress reporting") — phase id 가
+# `phase-<digit>` 로 시작하는 라인만 마커로 인정해 일반 대화의 오탐을 줄인다.
+_PROGRESS_RE = re.compile(r"^PROGRESS:\s+(phase-\d\S*(?:[ \t].*)?)$", re.MULTILINE)
+_PROGRESS_MARKER_MAX_CHARS = 160
+
 
 def _event_from_record(rec: dict) -> dict | None:
     """jsonl 레코드 1개 → 압축 이벤트. 집계에 기여하지 않으면 None.
@@ -48,6 +54,18 @@ def _event_from_record(rec: dict) -> dict | None:
                     if isinstance(b, dict) and b.get("type") == "tool_use")
         if tools:
             ev["u"] = tools
+        markers = [
+            m.group(1).strip()[:_PROGRESS_MARKER_MAX_CHARS]
+            for b in (msg.get("content") or [])
+            if isinstance(b, dict) and b.get("type") == "text"
+            for m in _PROGRESS_RE.finditer(b.get("text") or "")
+        ]
+        # 서로 다른 phase id 가 한 메시지에 섞이면 계약 인용/회고 요약이라 그
+        # 시각은 단계 경계가 아니다(관측: dev-9186 run 의 막판 요약 1건이 전
+        # phase 의 lastAt 을 오염). 같은 phase id 의 반복(병렬 dispatch 3줄,
+        # intake reading+complete)은 라이브 체크포인트로 인정한다.
+        if markers and len({m.split(None, 1)[0] for m in markers}) == 1:
+            ev["p"] = markers
     ts = rec.get("timestamp") or msg.get("timestamp")
     if ts:
         ev["t"] = ts
@@ -133,6 +151,7 @@ def _totals_from_events(events: list[dict], agent_name: str | None,
     input_t = output_t = cache_create_t = cache_read_t = 0
     cache_create_5m_t = cache_create_1h_t = 0
     tool_uses = 0
+    progress_markers: list[dict] = []
     first_ts: str | None = None
     last_ts: str | None = None
     for ev in events:
@@ -146,6 +165,8 @@ def _totals_from_events(events: list[dict], agent_name: str | None,
         cache_create_1h_t += ev.get("c1", 0)
         cache_read_t += ev.get("r", 0)
         tool_uses += ev.get("u", 0)
+        for marker in ev.get("p", ()):
+            progress_markers.append({"at": ts, "marker": marker})
         if ts:
             if first_ts is None or ts < first_ts:
                 first_ts = ts
@@ -179,6 +200,7 @@ def _totals_from_events(events: list[dict], agent_name: str | None,
         "model": model,
         "startedAt": first_ts,
         "endedAt": last_ts,
+        "progressMarkers": progress_markers,
     }
 
 

package/runtime/python/okstra_token_usage/collect.py

@@ -26,9 +26,11 @@ def match_prefixes(worker_id: str) -> list[str]:
     `-reverify-r1`, `-impl`, `-2`) when it dispatches the same role multiple
     times or in different sub-flows. We treat every `agentName` matching one of
     these prefixes — either exactly or as `<prefix>-<suffix>` — as belonging
-    to this worker so its tokens get aggregated. For implementation runs the
-    executor variant `<provider>-executor` is also attributed back to the
-    matching provider worker.
+    to this worker so its tokens get aggregated. For implementation /
+    final-verification runs the role variants `<provider>-executor` and
+    `<provider>-verifier` are also attributed back to the matching provider
+    worker (the bare `<provider>` prefix's `<prefix>-<suffix>` match covers
+    any role suffix Lead assigns).
     """
     if not worker_id:
         return []
@@ -141,6 +143,51 @@ def resolve_run_window(team_state_path: Path, state: dict) -> tuple[str | None,
     return since, until
 
 
+def _wall_ms(start_iso: str | None, end_iso: str | None) -> int | None:
+    if not start_iso or not end_iso:
+        return None
+    try:
+        a = datetime.fromisoformat(start_iso.replace("Z", "+00:00"))
+        b = datetime.fromisoformat(end_iso.replace("Z", "+00:00"))
+    except ValueError:
+        return None
+    return max(0, int((b - a).total_seconds() * 1000))
+
+
+def phase_timeline(markers: list[dict]) -> dict:
+    """lead 의 PROGRESS 체크포인트(agents/SKILL.md "Progress reporting")로
+    run 내부 단계 경계 wall-clock 을 복원한다 (perf plan v2 P0 계측).
+
+    phase id = marker 의 첫 토큰(`phase-5.5-convergence` 등). 같은 phase 의
+    반복 마커(poll/collect/dispatch)는 first/last 로 접는다. `wallMsToNext` 는
+    다음 phase 의 firstAt 까지 — 마지막 phase 는 None(run 종료 신호가 마커에
+    없으므로 추정하지 않는다). 마커가 하나도 없으면 phases 가 빈 채로 남아
+    "이 run 은 측정 불가"를 명시적으로 표현한다.
+    """
+    phases: list[dict] = []
+    by_id: dict[str, dict] = {}
+    for m in markers:
+        at = m.get("at")
+        phase_id = (m.get("marker") or "").split(None, 1)[0]
+        if not phase_id:
+            continue
+        entry = by_id.get(phase_id)
+        if entry is None:
+            entry = {"phase": phase_id, "firstAt": at, "lastAt": at,
+                     "markerCount": 0, "wallMsToNext": None}
+            by_id[phase_id] = entry
+            phases.append(entry)
+        entry["markerCount"] += 1
+        if at:
+            if entry["firstAt"] is None or at < entry["firstAt"]:
+                entry["firstAt"] = at
+            if entry["lastAt"] is None or at > entry["lastAt"]:
+                entry["lastAt"] = at
+    for current, nxt in zip(phases, phases[1:]):
+        current["wallMsToNext"] = _wall_ms(current["firstAt"], nxt["firstAt"])
+    return {"source": "lead-progress-markers", "phases": phases}
+
+
 def resolve_team_name(state: dict) -> str:
     """team-state 에서 이 run 의 team name 을 해소한다.
 
@@ -232,6 +279,7 @@ def collect(team_state_path: Path, project_root: Path | None = None, *,
                                        incremental=incremental)
         state["leadUsage"] = usage_block(totals, source="claude-jsonl")
         state["leadUsage"]["sessionId"] = lead_sid
+        state["phaseTimeline"] = phase_timeline(totals.get("progressMarkers") or [])
     else:
         state["leadUsage"] = na_block(
             f"lead session jsonl not found under {claude_project_dir(cwd)} (sessionId={lead_sid})"

package/runtime/python/okstra_token_usage/cursor.py

@@ -18,7 +18,9 @@ from pathlib import Path
 
 from okstra_project.dirs import okstra_home
 
-CACHE_SCHEMA_VERSION = 1
+# v2: usage 이벤트에 `p`(lead PROGRESS 마커) 키 추가 — v1 캐시는 이미 스캔한
+# 구간의 마커가 없으므로 폐기하고 전체 재스캔한다(fail-open).
+CACHE_SCHEMA_VERSION = 2
 IDENTITY_PREFIX_BYTES = 256
 MAX_NEEDLES = 16
 

package/runtime/schemas/final-report-v1.0.schema.json

@@ -1242,9 +1242,10 @@
 
     "ValidationCheckRow": {
       "type": "object",
-      "required": ["phase", "ticketId", "check", "commandOrObservation", "expectedOutcome"],
+      "required": ["id", "phase", "ticketId", "check", "commandOrObservation", "expectedOutcome"],
       "additionalProperties": false,
       "properties": {
+        "id": { "type": "string", "pattern": "^VC-\\d{3,}$" },
         "phase": { "enum": ["pre", "mid", "post"] },
         "ticketId": { "$ref": "#/$defs/TicketId" },
         "check": { "type": "string", "minLength": 1 },

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

@@ -519,14 +519,18 @@ Schema rules:
 Runs only when `convergence.critic.enabled == true` (set by `--critic <provider>` or the okstra-run `critic_pick` step; default off). Applies to the three finding-producing phases (`requirements-discovery`, `error-analysis`, `implementation-planning`); for `final-verification` the critic runs in a different mode — see §"Acceptance critic pass (final-verification)". This pass targets **coverage** (missed findings), distinct from convergence which targets **agreement quality**.
 
 ### When
-After Phase 5.5 finding convergence completes (findings classified) and BEFORE the Phase 6 report-writer dispatch.
+
+The critic input is the Round 0 consolidated finding list. Reverify rounds only classify findings — they never add or remove them (in-round queue insertions are forbidden, see §"Convergence State Artifact" `carriedForwardCount`) — so the critic dispatch MUST NOT wait for classification to finish:
+
+- **Dispatch**: immediately after Round 0 grouping, CONCURRENTLY with the first reverify round's dispatches. When the verification queue is empty after Round 0 (no reverify round runs), dispatch right after grouping. Concurrent dispatch to the same provider is safe — the critic result path (`<provider>-critic-...`) never collides with a reverify result path.
+- **Gap verification + merge**: only after BOTH the finding-convergence loop has exited AND the critic result is collected, and BEFORE the Phase 6 report-writer dispatch. If the loop exited `aborted-non-result`, do NOT dispatch a gap-verification round — surface the gaps as unverified `clarification` items per §"Gap verification" and record that fact.
 
 ### Dispatch (reused worker)
 Dispatch ONE pass to the `config.critic.provider`'s existing subagent (`claude-worker` / `codex-worker` / `gemini-worker`) with `model = config.critic.modelExecutionValue` — no new agent type. If `config.critic.modelExecutionValue` is null/empty (model could not be resolved), skip the critic pass and record `critic-skipped: model-unresolved` in the convergence state rather than dispatching with no model. Result path: `runs/<task-type>/worker-results/<provider>-critic-<task-type>-<seq>.md`. The critic prompt seeds the consolidated findings and asks ONLY for coverage gaps:
 
 ```
-You are the coverage critic for <task-key>. Below are the findings the workers
-already agreed on. Your ONLY job is to name what is MISSING:
+You are the coverage critic for <task-key>. Below are the consolidated findings
+the workers produced. Your ONLY job is to name what is MISSING:
 - files / directories / execution paths nobody inspected,
 - requirements or acceptance points with zero findings,
 - claims raised but never verified.
@@ -543,7 +547,7 @@ Each critic gap enters the verification queue as a finding with `originWorker =
 
 ## Acceptance critic pass (final-verification)
 
-The `final-verification` phase reuses the SAME reused-worker dispatch as §"Coverage critic pass" (provider + `config.critic.modelExecutionValue` from the `convergence.critic` block; default off; same model-unresolved skip rule). Only the prompt, the verification semantics, and the output sink differ — final-verification's findings are defects/blockers, so the critic acts as an **acceptance devil's advocate** (find reasons NOT to accept), and its candidate blockers are NEVER dropped (that would suppress real defects).
+The `final-verification` phase reuses the SAME reused-worker dispatch AND the same dispatch timing as §"Coverage critic pass" §"When" (provider + `config.critic.modelExecutionValue` from the `convergence.critic` block; default off; same model-unresolved skip rule) — the delivered work the critic inspects is likewise fixed before the reverify round starts. Only the prompt, the verification semantics, and the output sink differ — final-verification's findings are defects/blockers, so the critic acts as an **acceptance devil's advocate** (find reasons NOT to accept), and its candidate blockers are NEVER dropped (that would suppress real defects).
 
 ### Prompt
 

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

@@ -425,6 +425,15 @@ Display rule for `workerId` vs `agent`:
 
 Never write `claude (claude)` — the parenthesized agent is shown only when it adds information.
 
+**C. Per-run phase breakdown (when `phaseTimeline` is present):**
+
+team-state written by collector ≥ v0.73 carries a `phaseTimeline` block — the Phase 7 collector reconstructs lead operating-phase boundaries from the lead session's `PROGRESS: phase-*` checkpoint lines (`{source: "lead-progress-markers", phases: [{phase, firstAt, lastAt, markerCount, wallMsToNext}]}`).
+
+- When the user asks for a per-phase / per-run breakdown ("단계별", "phase별", "어느 단계가 오래"), render one table per requested run: `| Phase | Start | Wall to next |` using `firstAt` and `wallMsToNext`.
+- `wallMsToNext` is `null` on the last phase (the run-end signal is not a marker) — render `--`.
+- `phases: []` means the lead emitted no markers (run predates the contract, or markers were skipped) — say "phase timeline 측정 불가(마커 없음)" rather than estimating from other fields.
+- Older team-state files have no `phaseTimeline` key at all — omit the section silently.
+
 **Timestamp parsing:** for `startedAt` / `endedAt`, normalize ISO-8601: replace trailing `Z` with `+00:00`, accept explicit offsets as-is, parse via `datetime.fromisoformat(s.replace("Z", "+00:00"))`. Strings without an offset are assumed UTC. Mixed-form comparisons must be done as `datetime` objects, never raw strings.
 
 ### time.4 — Format output
@@ -458,6 +467,17 @@ Never write `claude (claude)` — the parenthesized agent is shown only when it
 | report-writer  | 2    | 00:01:00 | 00:00:30 |
 
 > Unavailable: 1 run (implementation / 2026-04-30_03-03-48) — team-state has no durationMs (Phase 7 not reached)
+
+### Phase breakdown — requirements-discovery (run 002)
+
+| Phase                  | Start (UTC)      | Wall to next |
+|------------------------|------------------|--------------|
+| phase-1-intake         | 2026-06-11 09:00 | 00:04:00     |
+| phase-2-prompts        | 2026-06-11 09:04 | 00:02:10     |
+| phase-4-dispatch       | 2026-06-11 09:06 | 00:18:30     |
+| phase-5.5-convergence  | 2026-06-11 09:25 | 00:21:00     |
+| phase-6-synthesis      | 2026-06-11 09:46 | 00:15:00     |
+| phase-7-persist        | 2026-06-11 10:01 | --           |
 ```
 
 **Rules:**

package/runtime/skills/okstra-report-writer/SKILL.md

@@ -105,8 +105,9 @@ The four steps below MUST execute in this exact order. Reordering them is the re
    ```
 
    Output (idempotent — re-running overwrites):
-   - `runs/<task-type>/reports/final-report-<task-type>-<seq>.html` — single-file self-contained human view, **generated only when the report has at least one §5 `C-*` clarification row**. Those rows with `Status` ∈ {`open`, `answered`} embed form widgets (`<select>` for enum-style decisions, `<input>` for material / data-point kinds, `<textarea>` fallback); an `Export user response` button serialises form values to a markdown sidecar (schema in [`templates/reports/user-response.template.md`](../../templates/reports/user-response.template.md)) that the user pastes to `runs/<task-type>/user-responses/user-response-<task-type>-<seq>.md`. The original final-report MD is **never** mutated by user input — the sidecar is the single write target.
-   - When the report has **no** `C-*` clarification rows, the html carries no interactive forms (it would only duplicate the MD), so the renderer prints `html: skipped (...)` and writes nothing. This is the expected state for clarification-free runs — `validators/validate-report-views.py` treats "no C-* rows + no html" as a pass, not a missing artifact.
+   - `runs/<task-type>/reports/final-report-<task-type>-<seq>.html` — single-file self-contained human view, **generated when the report has at least one §1 `C-*` clarification row OR an implementation-planning Plan Approval widget target** (a sibling `final-report-*.data.json` carrying `implementationPlanning.optionCandidates`). Clarification rows with `Status` ∈ {`open`, `answered`} embed form widgets (`<select>` for enum-style decisions, `<input>` for material / data-point kinds, `<textarea>` fallback); an `Export user response` button serialises form values to a markdown sidecar (schema in [`templates/reports/user-response.template.md`](../../templates/reports/user-response.template.md)) and downloads it as `user-response-<task-type>-<seq>.md`; the user saves it to `runs/<task-type>/user-responses/` (the renderer pre-creates that directory), and `--resume-clarification` auto-appends every sidecar found there to the next run's `clarification-response.md` (`clarification_items.clarification_response_with_sidecars`). The original final-report MD is **never** mutated by user input — the sidecar is the single write target.
+   - implementation-planning 보고서에는 본문 끝에 **Plan Approval** 섹션(구현 옵션 `<select>` + 승인 체크박스)이 렌더된다 — §1 `Blocks: approval` 행이 미해소면 disabled. 승인을 체크하고 Export 하면 sidecar 본문에 `## APPROVAL` 블록이 실리고, implementation 시작 마법사의 approve-confirm 단계가 그것을 감지해 사용자 확인 후 기존 `--approve` / `--implementation-option` 경로로 적용한다.
+   - When the report has **no** `C-*` clarification rows and is **not** a Plan Approval widget target, the html carries no interactive forms (it would only duplicate the MD), so the renderer prints `html: skipped (...)` and writes nothing. This is the expected state for such runs — `validators/validate-report-views.py` treats "no C-* rows + no approval target + no html" as a pass, not a missing artifact.
 
    Must run AFTER step 1 (so token placeholders are substituted in any rendered html) and BEFORE step 2 (so the html artifact, when generated, exists for the validator step that checks it).
 4. **Phase 7 step 2 — Follow-up task spawner** (BLOCKING when Section 4 is non-empty). Turns the report's `## 4. Follow-up Tasks (후속 작업)` rows into `tasks/<task-group>/<new-task-id>/` stubs.
@@ -276,7 +277,7 @@ Section numbering follows `templates/reports/final-report.template.md` exactly
 3. **Evidence and Detailed Analysis** — primary evidence rows (file path, line, snippet); secondary evidence / alternate interpretations. If `reference-expectations.md` lists explicit expected values, record match/gap per row.
 4. **Missing Information and Risks** — uncertain / "I don't know" items. `implementation-planning` adds §5.5 (see heading contract below); `release-handoff` adds §5.6.
 5. **Clarification Items** — single unified `C-*` table; column schema (4 columns with the short fields stacked in one record-meta cell), ID convention, and rerun behaviour are owned by `_common-contract.md §Clarification request policy` (SSOT). The deprecated `5.5.9 Open Questions` / `1.1 추가 자료 요청` / `1.2 사용자 확인 질문` sub-sections are removed; the validator fails reports that reintroduce them.
-6. **Recommended Next Steps** — prioritized actions. After Phase 7's follow-up spawner runs, append a row per newly created task-key (see "Phase 6 → Phase 7 execution sequence" above).
+6. **Recommended Next Steps** — prioritized actions. After Phase 7's follow-up spawner runs, append a row per newly created task-key (see "Phase 6 → Phase 7 execution sequence" above). **Approval-gate consistency:** when §1 carries any `Blocks: approval` row with `Status` ∈ {open, answered}, the Verdict Card `Next Step` and the first recommended step MUST point to the clarification rerun (`resume-clarification` of the SAME task-type) — never to "frontmatter `approved: true` 플립 → `implementation` 직행". Run-prep enforces this gate (`run.py _validate_approved_plan` fail-closes on those rows and on a blocking data.json `gateResult`), so a direct-implementation next-step is an instruction the reader cannot actually follow.
 7. **Follow-up Tasks** — auto-spawn-eligible table. Each row drives `okstra-spawn-followups.py`; see template §7 for the row schema.
 
 **§5.10 Fix History (data-presence gated).** When the run-manifest carries a `fixCycleId`, fill the data.json `fixCycle` block (`cycle` / `targetReport` / `symptom` / `runs`). Read the values from the task root's `history/fix-cycles.jsonl`: `cycle` MUST equal `fixCycleId`, `targetReport` / `symptom` come from that cycle's `opened` row, and `runs` lists its attached `run` rows (`taskType` / `runSeq` / `runManifest`). The validator (`validators/validate-run.py` → `_validate_fix_cycle`) fails the run when the block is missing or `fixCycle.cycle` does not match `fixCycleId`. When the run-manifest has no `fixCycleId`, OMIT the `fixCycle` block entirely — the renderer omits §5.10.

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

@@ -123,7 +123,7 @@ That is the entire interactive flow. The wizard handles:
 - task-type pick (추천 3개 — `nextRecommendedPhase` recommended / 현재 phase 재실행 / 라이프사이클 다음 단계 — + 직접 입력; 직접 입력은 후속 `text` 단계에서 전체 task-type 화이트리스트로 검증),
 - brief path — **entry task-type(requirements-discovery / error-analysis / improvement-discovery)에서만 질문** (same-group `.okstra/briefs/<task-group>/**/*.md` candidates first, direct input last; `유지 / 변경` for existing entry tasks). downstream task-type 은 manifest 의 brief 를 자동 carry-in 하고, 등록 brief 가 없으면 `brief_carry` 3-옵션(entry 전환 추천 / 직접 입력 / 중단)이 뜬다. `release-handoff` 는 brief 단계가 아예 없다 — prepare 가 검증 보고서 인용 input 문서를 생성한다,
 - base-ref pick + git rev-parse validation (skipped when reusing an active worktree),
-- `implementation`-only sub-flow: approved-plan path (frontmatter `approved: true` check) + stage pick (`auto` = 의존성 충족된 가장 빠른 미완료 stage, 또는 특정 stage 번호) + executor pick,
+- `implementation`-only sub-flow: approved-plan path (frontmatter `approved: true` check) + stage pick (`auto` = 의존성 충족된 가장 빠른 미완료 stage, 또는 특정 stage 번호) + executor pick. approved-plan 선택 시 그 run 의 sibling `user-responses/` 에서 plan 과 source-report·seq 가 일치하는 HTML `## APPROVAL` sidecar 를 감지하면 approve-confirm 단계가 3-옵션(`yes_apply` HTML 기록대로 승인+옵션 적용 추천 / `yes` 승인만 / `no` 중단)으로 확장된다 — `yes_apply` 는 옵션을 plan 의 `optionCandidates` 에 대해 검증한 뒤 기존 승인·옵션 경로로 적용한다,
 - `release-handoff`-only sub-flow: approved plan 자동 해소 후 `handoff_stage_pick` 멀티선택 — eligible stage 묶음(stage-group) 또는 전체 task(accepted whole-task 검증 보고서 존재 시) 선택; 결과는 render-args 의 `stages` 키(csv, whole-task 면 빈 값)로 나간다,
 - `Use defaults / Customize` branch with profile-aware worker/model questions,
 - `release-handoff` PR template override + persist scope,

package/runtime/skills/okstra-team-contract/SKILL.md

@@ -323,7 +323,7 @@ without proceeding — this is the contractual replacement for the previous
 empty run-level error logs in production.
 
 - `cli-failure` events are recorded by the wrapper subagent itself (Codex / Gemini), but **directly to the run-level error log** via `okstra error-log append-observed --error-type cli-failure ...` — NOT via the sidecar. The sidecar is an in-process tool-failure channel only.
-- **Wrapper invocation arity.** Both `okstra-codex-exec.sh` and `okstra-gemini-exec.sh` accept four required positional arguments plus an optional fifth `<role>`: `<project-root> <model> <prompt-path> <worktree-path> [<role>]`. The fourth (worktree) argument is **mandatory for implementation phase** and optional otherwise. For codex it becomes `--add-dir <worktree>` (sandbox write access); for gemini it is appended to `--include-directories`. Omitting it during implementation causes the codex sandbox to reject every Edit/Write targeting the worktree with EPERM. Workers extract the path from the `**Worktree:**` / `EXECUTOR_WORKTREE_PATH` / `cwd for every mutating command:` line in the lead prompt. The optional fifth `<role>` is folded into both the caller (worker) pane title `<cli>-<role>-<pid>` and the sibling trace-pane title `<cli>-<role>-<pid>-trace[from=<caller-pane-id>]` (e.g. `codex-worker-93421` ↔ `codex-worker-93421-trace[from=%5]`). `<pid>` is the wrapper's own PID and disambiguates concurrent dispatches of the same role; the embedded caller pane id keeps the trace ↔ worker correlation visible even when the worker pane's title is overwritten by the parent process (Claude Code's TUI emits OSC 2 title escape sequences on its own pane). Always pass the literal string `worker` so the dispatch is self-describing (the wrapper defaults to `worker` if omitted).
+- **Wrapper invocation arity.** Both `okstra-codex-exec.sh` and `okstra-gemini-exec.sh` accept four required positional arguments plus an optional fifth `<role>`: `<project-root> <model> <prompt-path> <worktree-path> [<role>]`. The fourth (worktree) argument is **mandatory for implementation phase** and optional otherwise. For codex it becomes `--add-dir <worktree>` (sandbox write access); for gemini it is appended to `--include-directories`. Omitting it during implementation causes the codex sandbox to reject every Edit/Write targeting the worktree with EPERM. Workers extract the path from the `**Worktree:**` / `EXECUTOR_WORKTREE_PATH` / `cwd for every mutating command:` line in the lead prompt. The optional fifth `<role>` is folded into both the caller (worker) pane title `<cli>-<role>-<pid>` and the sibling trace-pane title `<cli>-<role>-<pid>-tail` (e.g. `codex-executor-93421` ↔ `codex-executor-93421-tail`). `<pid>` is the wrapper's own PID and disambiguates concurrent dispatches of the same role. The role value comes from the dispatch prompt's `**Pane role:**` line: `executor` on an `implementation` Executor dispatch, `verifier` on an `implementation` / `final-verification` verifier dispatch, so the trace pane names the actual job rather than a generic `worker`. When no `**Pane role:**` line is present (analysis phases), pass the literal `worker` (the wrapper also defaults to `worker` if the argument is omitted).
 - **Background dispatch + polling contract (Codex / Gemini wrappers).** Both wrapper subagents MUST dispatch `okstra-codex-exec.sh` / `okstra-gemini-exec.sh` via `Bash(run_in_background: true)` and poll with `BashOutput(bash_id)` until the shell reports `status == "completed"`, capped at 30 minutes (1800s) of wall-clock elapsed time. `BashOutput` itself is the wait primitive — call it back-to-back; do NOT insert a standalone `sleep` between polls. The Claude Code harness blocks `sleep` calls of 5 seconds or longer as a circumvention vector and explicitly forbids chaining shorter sleeps inside until-loops to work around the block. Workers that hit the contract bug must NOT self-recover with `until ...; do sleep 2; done` wrappers — that path violates the harness anti-circumvention rule, even though it superficially "works". The legacy "single foreground `Bash` with 120000ms timeout" rule, and the subsequent "60-second cadence with `sleep 60` between polls" rule, are both retired. The current rule applies in **every phase** (analysis runs typically complete in 1–2 `BashOutput` calls, so there is no regression for short jobs). Recording responsibilities:
   - Successful completion: return the wrapper's accumulated stdout from the final `BashOutput`. No log entry.
   - Non-zero `exit_code` reported by `BashOutput`: record a `cli-failure` to the run-level error log with the real `exit_code` and observed `duration-ms`.