okstra 0.107.1 → 0.108.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.107.1",
+  "version": "0.108.0",
   "description": "Multi-agent cross-verification orchestrator runtime + Claude Code skills.",
   "license": "MIT",
   "author": "devonshin",

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.107.1",
-  "builtAt": "2026-07-01T07:21:31.825Z",
+  "package": "0.108.0",
+  "builtAt": "2026-07-02T01:43:53.766Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/bin/okstra-team-reconcile.sh

@@ -12,8 +12,16 @@
 # are left for graceful shutdown). It no-ops when tmux is unavailable or nothing
 # is stale.
 #
-# Usage: okstra-team-reconcile.sh [--list] <team-name>
-#   --list   report what WOULD be deactivated; do not write (alias --dry-run).
+# Usage:
+#   okstra-team-reconcile.sh [--list] <team-name|team-dir|config.json>
+#   okstra-team-reconcile.sh [--list] --project-root <dir> [--fallback-team <label>]
+#   okstra-team-reconcile.sh [--list] --session-end   # reads SessionEnd JSON on stdin
+#
+#   --project-root  resolve the CURRENT live session's roster (robust to the
+#                   phase-3 lead.sessionId snapshot drifting across resume), then
+#                   reconcile and print `dismissible-member: <name>` lines.
+#   --session-end   SessionEnd-hook net: reconcile the ending session's roster.
+#   --list          report what WOULD be deactivated; do not write (alias --dry-run).
 #
 # Failures are non-fatal to the run — teardown must never block on this.
 set -u

package/runtime/prompts/lead/okstra-lead-contract.md

@@ -87,7 +87,7 @@ User-utterance interpretation rule:
 
 ## Progress reporting (BLOCKING)
 
-A single okstra run frequently spans 30–120 minutes of wall-clock time with multi-minute silent windows while workers run. Without explicit progress signals the user cannot distinguish "still working" from "hung", so Lead MUST emit a single short progress line at each of the checkpoints below — as plain user-facing text in a separate brief message (not buried inside a tool call). One line per checkpoint, format: `PROGRESS: <phase-id> <verb-phrase>`.
+A single okstra run frequently spans 30–120 minutes of wall-clock time with multi-minute silent windows while workers run. Without explicit progress signals the user cannot distinguish "still working" from "hung", so Lead MUST emit a single short progress line at each of the checkpoints below — as plain user-facing text in a separate brief message (not buried inside a tool call). One line per checkpoint, format: `PROGRESS: <phase-id> <verb-phrase>`. Emit the line raw — the literal `PROGRESS:` token must begin the line. Do NOT wrap it in inline-code backticks (`` `PROGRESS: ...` ``) or a ```` ``` ```` code fence; markdown wrapping is what the post-hoc conformance validator scrapes around, and raw emit keeps the signal unambiguous.
 
 Required checkpoints:
 
@@ -218,7 +218,7 @@ These phases are governed by [team-contract](./team-contract.md). It is the cano
 Claude Code **v2.1.178 removed the `TeamCreate` / `TeamDelete` tools and the `Agent(...)` `team_name` parameter**. With `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` (seeded by `okstra install` into the user's `settings.json`), every session already owns **one implicit team** from the moment it starts — there is no creation step to perform and no `team_name` to pass on dispatch. Workers spawned with `Agent(name: ...)` auto-join that implicit team. Do NOT search for, probe, or call `TeamCreate`: its absence is the expected state on every current Claude Code, NOT an "Agent Teams unavailable" signal, and is never a reason to degrade the run. There is no `select:TeamCreate` probe and no doubly-empty-select branch anymore — those keyed off a tool that no longer exists.
 
 1. Record team-state before any dispatch:
-   - `teamName` — the verbatim name from the launch prompt's gate block (`okstra-<task-key>`; implementation stage runs append `-s<N>`, single-stage final-verification appends `-fv-s<N>`). Audit/display label only — the implicit team's on-disk directory is `session-<leadSessionId-prefix>`, which run-end teardown and reconcile resolve from `lead.sessionId`, NEVER from `teamName`.
+   - `teamName` — the verbatim name from the launch prompt's gate block (`okstra-<task-key>`; implementation stage runs append `-s<N>`, single-stage final-verification appends `-fv-s<N>`). Audit/display label only — the implicit team's on-disk directory is `session-<leadSessionId-prefix>`, but run-end teardown resolves it from the CURRENT live session (see `_common-contract.md` "Run-end teammate teardown"), NOT from the phase-3 `lead.sessionId` snapshot recorded here, which drifts across resume / compaction; it is never resolved from `teamName`.
    - `teamCreate: { attempted: false, status: "implicit" }` — the audit marker that this run rides the session's implicit team (no explicit creation tool exists). A concurrent-run launch prompt instead pre-records `status: "skipped", reason: "concurrent-run"`; honor whichever the gate specifies.
 2. Verify `team-state.lead.sessionId` is populated. The `okstra.sh` exec path fills it automatically (`generate_claude_session_id` → `claude --session-id ...`). The render-only / in-session takeover path (`okstra-run` skill) auto-detects via `resolve_inproc_lead_session_id`, which is best-effort and may return empty if `~/.claude/projects/<encoded-cwd>/` is unreadable or has no jsonl yet. If `lead.sessionId` is empty at this point, write the running session's id into team-state before proceeding — Phase 7 token-usage collection depends on it and will fail with `lead jsonl not found (sessionId=)` otherwise.
 3. Decide split-pane capability, record it, then emit the phase-3 checkpoint and proceed to Phase 4. Split-pane teammates require a tmux session — this is a host capability, NOT an okstra success/failure gate, and is the only thing the removed "TeamCreate" probe should ever have been deciding:

package/runtime/prompts/lead/report-writer.md

@@ -277,7 +277,9 @@ Section numbering follows `templates/reports/final-report.template.md` exactly
 - `approach` — 그래서 어떤 작업이 필요한가 (택한 방향).
 - `justification` — 왜 이게 합리적 선택인가 (대안 대비, 근거).
 
-Every field MUST anchor its claim with at least one evidence reference — a `path:line`, a report ID (`C-001` / `F-013` / `§5.4`), or another cited source already present in this report. When the evidence is genuinely insufficient, say so explicitly (`근거 불충분 — <이유>`) instead of inventing one. `validators/validate-run.py` → `_validate_rationale_evidence` fails any field carrying neither a citation nor an insufficiency marker, so an ungrounded or fabricated rationale is rejected at validation time. Do NOT restate the Verdict Card or the §5.4 trade-off matrix verbatim — this section is the *why*, in connected prose, that those tables compress.
+Every field MUST anchor its claim with at least one evidence reference — a `path:line`, an **in-report** ID (`C-001` / `E-006` / `§5.4`), or another cited source already present in this report. When the evidence is genuinely insufficient, say so explicitly (`근거 불충분 — <이유>`) instead of inventing one. `validators/validate-run.py` → `_validate_rationale_evidence` fails any field carrying neither a citation nor an insufficiency marker, so an ungrounded or fabricated rationale is rejected at validation time.
+
+**Reader-facing prose MUST NOT cite a bare brief/worker-internal ID that this report never surfaces** — `RC-*` (reporter confirmations, defined in the brief), `RF-*` / `F-*` (findings, defined in worker-results) have no anchor in the final report, so a reader hits an opaque token with nothing to click. Either expand it inline (`the confirmed version target 1.27.47→1.27.48`) or, for an audit trail, namespace it (`claude:F-005`). **Enforced:** `_validate_no_opaque_id_references` fails a bare `RC-*` / `RF-*` / non-namespaced `F-*` appearing in `verdictCard` / `finalVerdict` / `rationale` / `clarificationItems[].statement`. (The renderer anchors + links in-report IDs of any digit width, so a surfaced `RC-4`-style id does resolve.) Do NOT restate the Verdict Card or the §5.4 trade-off matrix verbatim — this section is the *why*, in connected prose, that those tables compress.
 
 0. **Clarification Response Carried In** — render this `## 0.` heading ONLY when `{{CLARIFICATION_RESPONSE_RELATIVE_PATH}}` is non-empty. Walk every `C-*` row of the prior report's `## 1. Clarification Items` table, reconcile against new evidence, and record the outcome (`resolved` / `obsolete`) with citation before drafting the verdict. When no carry-in path was provided, OMIT the `## 0.` heading entirely — the validator fails an empty Section 0 stub.
 1. **Cross Verification Results** — 4 categories (Full / Partial / Contested / Worker-Unique) when convergence is enabled, per `convergence`. Prepend the Round History sub-table (columns: `Round | inputQueueSize | resolvedCount | carriedForwardCount | dispatches | skippedWorkers`) plus a `round2SkippedReason: <value>` note, pulled verbatim from `convergence-<task-type>-<seq>.json`. Empty contested list renders as `- 합의 미달 항목 없음.`. Convergence-disabled runs use the legacy Consensus/Differences format and omit the round table.

package/runtime/prompts/profiles/_common-contract.md

@@ -40,7 +40,8 @@ profile document.
     - **Only confirmed-complete teammates, never the lead.** NEVER send a shutdown_request to a teammate whose result file has not yet appeared. In particular the critic runs CONCURRENTLY with the first reverify round (see `convergence` "Coverage critic pass"), so it MUST NOT be shut down until its own result is collected. NEVER target the lead's own session.
     - Only individual completed teammates are dismissed here; the rest of the roster stays for the remaining batches. There is no `TeamDelete` tool (removed in CC v2.1.178) — the implicit team itself ends with the session; teardown only dismisses teammates.
     - Silent-skip in `tmux-pane` backend runs (external-lead workers are not session teammates); otherwise the on-disk existence check at run-end teardown is the authority on whether a roster exists.
-  - Both (a) and (b) run **automatically without any interactive prompt**. After running them, emit the checkpoint line `PROGRESS: phase-batch-cleanup panes=<n> teammates=<m>` (counts only — NEVER expose `%NNN`, `lead-pane.id`, or raw Agent names) and proceed; this is the BLOCKING checkpoint the Phase 7 validator requires before each convergence round and before the report-writer dispatch (`prompts/lead/okstra-lead-contract.md` "Progress reporting (BLOCKING)"). **Effect caveat:** Claude Code exposes no tool to surgically delete a roster entry mid-run, so a dismissed teammate may still show as an idle pill; the shutdown still reclaims its session and prevents the roster from growing with live members. On the FIRST batch of a run nothing has been dispatched yet — both steps no-op.
+  - **(c) record the current session into team-state (축1 — re-issued session generation capture).** batch cleanup 직후(그리고 아래 `PROGRESS: phase-batch-cleanup` 방출 전), lead 는 재발급된 세션 세대가 Phase 7 토큰·PROGRESS 수집에서 누락되지 않도록 현재 live 세션을 team-state 에 기록한다: `okstra token-usage "<TEAM_STATE_PATH>" --record-observed-session --project-root "<PROJECT_ROOT>"` 를 1회 호출한다(`<TEAM_STATE_PATH>` 와 `<PROJECT_ROOT>` 는 shell 변수·`$(...)` 없이 리터럴 절대경로로 치환 — `Bash(okstra:*)` 매칭 유지). `--project-root` 는 **필수**다: 생략하면 collector 가 team-state 의 상위 디렉터리(run/state 경로)를 project root 로 잘못 추론해 엉뚱한 `~/.claude/projects/<encoded-cwd>/` 를 뒤지고 조용히 no-op 하므로 축1 이 꺼진다. 실패는 무시 가능한 best-effort — worker 세션이거나 이미 기록된 세대이면 no-op 다. `python3 "$HOME/..."` 직접 호출은 금지(`$HOME` 확장이 리터럴-토큰 permission 매칭을 깨고 매 호출 확인 프롬프트를 유발) — 반드시 `okstra token-usage` 서브커맨드를 쓴다.
+  - Both (a), (b), and (c) run **automatically without any interactive prompt**. After running them, emit the checkpoint line `PROGRESS: phase-batch-cleanup panes=<n> teammates=<m>` (counts only — NEVER expose `%NNN`, `lead-pane.id`, or raw Agent names) and proceed; this is the BLOCKING checkpoint the Phase 7 validator requires before each convergence round and before the report-writer dispatch (`prompts/lead/okstra-lead-contract.md` "Progress reporting (BLOCKING)"). **Effect caveat:** Claude Code exposes no tool to surgically delete a roster entry mid-run, so a dismissed teammate may still show as an idle pill; the shutdown still reclaims its session and prevents the roster from growing with live members. On the FIRST batch of a run nothing has been dispatched yet — the pane/teammate steps (a)/(b) no-op; step (c) still records the current session.
 - Phase wrap-up — okstra pane disposition (shared, runs AFTER Phase 7 persistence/token collection and BEFORE teammate teardown):
   - At run end the only residual okstra panes are the LAST phase's (e.g. the `report-writer-worker` agent pane and any codex/antigravity trace pane). `okstra-trace-cleanup.sh --list --run-dir "<RUN_DIR>"` returns one tab-separated `<pane_id>\t<pane_title>` line per residual okstra pane (worker-agent + trace) for this run.
   - After the final-report file has been written and the routing recommendation has been issued, the lead MUST ALWAYS run `$HOME/.okstra/bin/okstra-trace-cleanup.sh --list --run-dir "<RUN_DIR>"` exactly once — NEVER gating this call on its own reading of `lead-pane.id`. The output lists every residual okstra pane (worker-agent + trace) for this run, never the lead's own pane; outside tmux it is a safe no-op (empty output).
@@ -55,15 +56,16 @@ profile document.
   - This step is mandatory for every phase (`requirements-discovery`, `error-analysis`, `implementation-planning`, `implementation`, `final-verification`, `release-handoff`). Whether there is anything to ask about is decided by the `--list` output, NOT by the lead's reading of `lead-pane.id`: an empty list → skip the question (above); the lead MUST NOT fabricate a synthetic pane list.
 - Run-end teammate teardown (shared — MUST run AFTER the pane disposition question and BEFORE `PROGRESS: complete`):
   - CC v2.1.178 removed `TeamCreate` / `TeamDelete`: this run rode the session's **implicit team** (Phase 3 recorded `teamCreate.status: "implicit"` plus the `teamName` audit label). There is no tool to delete a team — the implicit team ends when the session ends. What teardown CAN do is gracefully dismiss the worker teammates the lead spawned, so they stop showing as live members in the FleetView roster.
-  - **Whether to run this step is decided by on-disk fact.** The harness names the team directory `session-<leadSessionId-prefix>` (the `teamName` label never becomes a directory name). Resolve existence from disk: find the `~/.claude/teams/session-*/config.json` whose `leadSessionId` equals team-state `lead.sessionId`.
-    - **Matching on-disk config found, with members beyond the lead** → teammates exist; run the dismissal sequence below.
-    - **No matching on-disk config, or split-pane was off** → nothing to dismiss → silent-skip.
+  - **Whether to run this step is decided by on-disk fact, resolved at teardown time by the CURRENT live session — NOT from `team-state.lead.sessionId`.** The harness names the team directory `session-<leadSessionId-prefix>` (the `teamName` label never becomes a directory name), but `team-state.lead.sessionId` is only a phase-3 snapshot: Claude Code re-issues the session id across resume / compaction mid-run, so the live roster usually sits under a DIFFERENT `session-*` dir than the snapshot names. Resolving from the snapshot is what made split-pane teardown silently miss its own live teammates. The resolver in step 1 below keys off the live session (falling back to the snapshot dir only when the live one is absent) and prints the members to dismiss.
+    - **Resolver printed one or more `dismissible-member: <name>` lines** → teammates exist; run the dismissal sequence below.
+    - **Resolver printed `no live roster for this session`, or split-pane was off** → nothing to dismiss → silent-skip.
   - The pane disposition prompt above is the only user prompt for this cleanup decision. Do NOT ask a second teammate-only question.
   - On `아니오` / `n` / `keep` → dismiss nothing. Tell the user the teammates remain visible in FleetView/Teams until the session ends, and can be removed earlier from the Teams UI.
   - On `예` / `y` / `close` → emit `PROGRESS: phase-7-teardown dismissing teammates`, then run the sequence below. Token-usage collection MUST already be complete — it reads `~/.claude/projects/` jsonls, which dismissal never touches, but the read MUST precede teardown.
-    1. Run `$HOME/.okstra/bin/okstra-team-reconcile.sh "<resolved-config-path>"` — the on-disk `~/.claude/teams/session-<…>/config.json` resolved in the existence check above — exactly once. It flips dead-pane stale-active members to inactive, and no-ops when tmux is unavailable or nothing is stale. Do NOT loop it.
-    2. Send each confirmed-complete member a structured `SendMessage(to: <name>, message: { type: "shutdown_request" })` — the `message` MUST be the object literal shown, NEVER a JSON string stuffed into a text field. NEVER target the lead's own session, and never use `TaskStop` (teammates are not background tasks — `TaskStop` 404s on a member address).
+    1. Run `$HOME/.okstra/bin/okstra-team-reconcile.sh --project-root "<PROJECT_ROOT>" --fallback-team "session-<lead.sessionId-prefix>"` exactly once. It resolves the live session's `~/.claude/teams/session-<live>/config.json` (falling back to the snapshot `session-<lead.sessionId-prefix>` dir only if the live one is absent), flips dead-pane stale-active members to inactive (no-op when tmux is unavailable or nothing is stale), and prints one `dismissible-member: <name>` line per non-lead member. Do NOT loop it, and do NOT hand-resolve a config path from `team-state.lead.sessionId`.
+    2. Send each printed `dismissible-member: <name>` **whose completion is confirmed** (its Result Path exists) a structured `SendMessage(to: <name>, message: { type: "shutdown_request" })` — the `message` MUST be the object literal shown, NEVER a JSON string stuffed into a text field. NEVER target the lead's own session, and never use `TaskStop` (teammates are not background tasks — `TaskStop` 404s on a member address).
   - Claude Code exposes no tool to delete the team or surgically remove a roster entry, so a dismissed teammate may still show as an idle pill until the session ends. Do not pretend the team was deleted. If the user wants the roster gone entirely, surface the manual action: `Teams/FleetView 에서 team <teamName> 삭제`, and if tmux panes were kept earlier also show `$HOME/.okstra/bin/okstra-trace-cleanup.sh --run-dir "<RUN_DIR>"`.
+  - **Enforcement / safety net.** This teardown fires after the Phase 7 validator's window, so `validate_session_conformance.py` cannot check it (it is not a required checkpoint). The net is the `SessionEnd` hook `$HOME/.okstra/bin/okstra-team-reconcile.sh --session-end` (seeded into `settings.template.json`): when the Claude session ends it reconciles that session's roster regardless of whether this step ran, so a dead-pane member never lingers as a live pill past session end.
   - Report the outcome in one short line (e.g. `worker teammate 정리 완료`, or `stale 멤버 1명 reconcile 후 정리`) and proceed to the final `PROGRESS: complete ...` line.
 - Brief handoff contract (shared — applies whenever the run consumes a task brief produced by `okstra-brief`):
   - the brief is a **pre-discovery artifact**: it converts a domain-reporter's words (non-expert *or* developer) into expert-consumable form so this and later phases can run with zero fill-in questions to the operator. The brief is **not** authoritative on solution decisions; it is authoritative on the reporter's intent.

package/runtime/python/okstra_ctl/render_final_report.py

@@ -136,10 +136,12 @@ def _yaml_inline_list(values: list[str]) -> str:
 # reference must not silently jump to the wrong row.
 _HEADING_RE = re.compile(r"^(#{1,6})[ \t]+(.*?)[ \t]*$")
 _FENCE_RE = re.compile(r"^[ \t]*(?:```|~~~)")
-_FIRST_CELL_ID_RE = re.compile(r"^[ \t]*\*{0,2}([A-Z]{1,4}-\d{3,})\b")
+_FIRST_CELL_ID_RE = re.compile(r"^[ \t]*\*{0,2}([A-Z]{1,4}-\d{1,})\b")
 # A reference token: an ID not glued to a word char / `-` on either side and
 # not prefixed by `:` (which would make it a `<worker>:<item-id>` source ref).
-_REF_ID_RE = re.compile(r"(?<![:\w-])[A-Z]{1,4}-\d{3,}(?![\w-])")
+# `\d{1,}` (not `{3,}`): short IDs like `RC-4` are valid — the old 3-digit floor
+# silently dropped them, so they could never anchor or link.
+_REF_ID_RE = re.compile(r"(?<![:\w-])[A-Z]{1,4}-\d{1,}(?![\w-])")
 
 
 def _slugify(text: str) -> str:

package/runtime/python/okstra_ctl/session.py

@@ -5,6 +5,7 @@ bash session.sh 의 python 구현. claude session id 생성, resume command
 """
 from __future__ import annotations
 
+import json
 import os
 import uuid
 from pathlib import Path
@@ -48,6 +49,49 @@ def resolve_inproc_lead_session_id(project_root: Path) -> str:
         return ""
 
 
+def _session_has_agent_name(jsonl_path: Path) -> bool:
+    """세션 jsonl 에 agentName 이 있으면 worker 세션(lead 아님)."""
+    try:
+        with jsonl_path.open(encoding="utf-8") as fh:
+            for raw in fh:
+                try:
+                    rec = json.loads(raw)
+                except (json.JSONDecodeError, UnicodeDecodeError):
+                    continue
+                if rec.get("agentName"):
+                    return True
+    except OSError:
+        return False
+    return False
+
+
+def record_observed_lead_session(project_root: Path, team_state_path: Path) -> str:
+    """현재 live lead 세션을 관측해 team-state 에 append(멱등). 워커 세션이거나
+    관측 실패·중복이면 '' 반환. 재발급으로 갈린 세대를 축1 이 여기에 모은다.
+    """
+    sid = resolve_inproc_lead_session_id(project_root)
+    if not sid:
+        return ""
+    proj_dir = _claude_projects_dir_for(project_root)
+    jsonl = proj_dir / f"{sid}.jsonl"
+    if _session_has_agent_name(jsonl):
+        return ""
+    try:
+        state = json.loads(team_state_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return ""
+    lead_ids = state.setdefault("leadSessionIds", [])
+    if sid in lead_ids:
+        return ""
+    lead_ids.append(sid)
+    team = f"session-{sid[:8]}"
+    observed = state.setdefault("observedTeamNames", [])
+    if team not in observed:
+        observed.append(team)
+    team_state_path.write_text(json.dumps(state, indent=2), encoding="utf-8")
+    return sid
+
+
 def write_claude_resume_command_file(
     *,
     resume_command_path: Path,

package/runtime/python/okstra_ctl/team_reconcile.py

@@ -16,6 +16,13 @@ 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".
+
+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
 
@@ -26,6 +33,8 @@ import sys
 import tempfile
 from pathlib import Path
 
+from okstra_ctl.session import resolve_inproc_lead_session_id
+
 
 def live_pane_ids() -> tuple[bool, set[str]]:
     """Return ``(tmux_available, live_pane_ids)``.
@@ -66,6 +75,44 @@ def reconcile_members(config: dict, live_panes: set[str]) -> list[str]:
     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)
@@ -92,43 +139,126 @@ def _atomic_write(path: Path, text: str) -> None:
         raise
 
 
-def main(argv: list[str]) -> int:
-    dry_run = False
-    rest: list[str] = []
-    for arg in argv:
-        if arg in ("--list", "--dry-run"):
-            dry_run = True
-        else:
-            rest.append(arg)
-    if len(rest) != 1:
-        print("usage: okstra-team-reconcile.sh [--list] <team-name|team-dir|config.json>",
-              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
+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:
         config = json.loads(cfg_path.read_text())
     except (OSError, json.JSONDecodeError) 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)
+
 
-    flipped = reconcile_members(config, live)
-    if not flipped:
-        print("team-reconcile: no stale-active members")
+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
-    if dry_run:
-        print("team-reconcile (dry-run): would deactivate " + ", ".join(flipped))
+    cfg = _team_config_for_session(sid)
+    if not cfg.is_file():
         return 0
+    return _reconcile_config(cfg, dry_run, print_members=False)
 
-    _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))
-    return 0
+
+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_token_usage/claude.py

@@ -280,13 +280,18 @@ def _cached_needle_scan(jsonl_path: Path, cache: dict, needle_lower: str) -> boo
 
 def find_claude_team_sessions(
     cwd: Path,
-    team_name: str,
+    team_needles,
     lead_sid: str | None = None,
     projects_root: Path | None = None,
     *,
     incremental: bool = False,
 ) -> dict[str, Path]:
-    """Map sessionId -> jsonl path for all jsonls tagged with `team_name`.
+    """Map sessionId -> jsonl path for all jsonls tagged with any of `team_needles`.
+
+    `team_needles` is an ``Iterable[str]`` of teamName generations; a jsonl is
+    included when it matches any one of them (union). The lead re-issue
+    fragments an implicit-team session into multiple `session-<leadSid>`
+    generations, so a single string is no longer sufficient.
 
     Matching is case-insensitive on the teamName needle to tolerate runs where
     the lead recorded `team.teamName` with a different case than the harness
@@ -306,17 +311,18 @@ def find_claude_team_sessions(
     out: dict[str, Path] = {}
     if not proj_dir.is_dir():
         return out
-    needle_lower = f'"teamname":"{(team_name or "").lower()}"'
-    if team_name:
-        for p in proj_dir.glob("*.jsonl"):
+    needles_lower = [f'"teamname":"{n.lower()}"' for n in team_needles if n]
+    for p in proj_dir.glob("*.jsonl"):
+        for needle_lower in needles_lower:
             if incremental:
                 cache = load_cache(p)
-                if _cached_needle_scan(p, cache, needle_lower):
-                    out[p.stem] = p
+                hit = _cached_needle_scan(p, cache, needle_lower)
                 save_cache(p, cache)
             else:
-                if _needle_scan(p, {"offset": 0, "found": False}, needle_lower):
-                    out[p.stem] = p
+                hit = _needle_scan(p, {"offset": 0, "found": False}, needle_lower)
+            if hit:
+                out[p.stem] = p
+                break
     if lead_sid:
         direct = proj_dir / f"{lead_sid}.jsonl"
         if direct.is_file():

package/runtime/python/okstra_token_usage/cli.py

@@ -60,12 +60,35 @@ def main() -> int:
             "See schemas/final-report-v1.0.schema.json for the data shape."
         ),
     )
+    parser.add_argument(
+        "--record-observed-session",
+        action="store_true",
+        help=(
+            "Observe the current live lead session and append it to the "
+            "team-state's leadSessionIds/observedTeamNames (idempotent), "
+            "print the appended sid, then exit"
+        ),
+    )
     args = parser.parse_args()
 
     if not args.team_state.is_file():
         print(f"team-state not found: {args.team_state}", file=sys.stderr)
         return 2
 
+    if args.record_observed_session:
+        from okstra_ctl.session import record_observed_lead_session
+
+        from .collect import _infer_project_root
+
+        if args.project_root is not None:
+            project_root = args.project_root
+        else:
+            state = json.loads(args.team_state.read_text())
+            project_root = _infer_project_root(args.team_state, state)
+        sid = record_observed_lead_session(project_root, args.team_state)
+        print(sid)
+        return 0
+
     updated = collect(args.team_state, args.project_root,
                       incremental=not args.no_cache)
 

package/runtime/python/okstra_token_usage/collect.py

@@ -131,6 +131,53 @@ def _run_end_estimate(run_dir: Path, suffix: str) -> str | None:
     return datetime.fromtimestamp(mtime, tz=timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
 
 
+def _project_root_from_team_state(team_state_path: Path) -> Path | None:
+    """team-state path(`<root>/.okstra/tasks/.../state/team-state-*.json`)에서
+    프로젝트 루트(`.okstra` 를 담은 디렉토리)를 되짚는다. 못 찾으면 None."""
+    for parent in team_state_path.resolve().parents:
+        if parent.name == OKSTRA_RELATIVE.name:
+            return parent.parent
+    return None
+
+
+def _session_first_ts(jsonl_path: Path) -> str | None:
+    """세션 jsonl 의 최소 timestamp — reconstruct_needles_from_workers 와 동일한
+    top-level `timestamp` 규칙. 파일 부재/파싱 실패 레코드는 건너뛴다."""
+    first_ts: str | None = None
+    try:
+        with jsonl_path.open(encoding="utf-8") as fh:
+            for raw in fh:
+                try:
+                    rec = json.loads(raw)
+                except (json.JSONDecodeError, UnicodeDecodeError):
+                    continue
+                ts = rec.get("timestamp")
+                if ts and (first_ts is None or ts < first_ts):
+                    first_ts = ts
+    except OSError:
+        return None
+    return first_ts
+
+
+def _earliest_lead_session_ts(state: dict, team_state_path: Path) -> str | None:
+    """`state["leadSessionIds"]` 각 lead 세션 jsonl 첫 ts 중 최소값. 부재하거나
+    어느 세션에서도 ts 를 못 찾으면 None. proj_dir 은 team-state path 에서 되짚은
+    프로젝트 루트에 `claude_project_dir` 규칙을 적용해 해소한다."""
+    lead_ids = [sid for sid in (state.get("leadSessionIds") or []) if sid]
+    if not lead_ids:
+        return None
+    project_root = _project_root_from_team_state(team_state_path)
+    if project_root is None:
+        return None
+    proj_dir = claude_project_dir(project_root)
+    earliest: str | None = None
+    for sid in lead_ids:
+        ts = _session_first_ts(proj_dir / f"{sid}.jsonl")
+        if ts and (earliest is None or ts < earliest):
+            earliest = ts
+    return earliest
+
+
 def resolve_run_window(team_state_path: Path, state: dict) -> tuple[str | None, str | None]:
     """이 run 의 [시작, 종료] ISO 윈도우.
 
@@ -140,12 +187,21 @@ def resolve_run_window(team_state_path: Path, state: dict) -> tuple[str | None,
     $416 / 3h). 토큰 집계를 이 윈도우로 스코핑해 그 run 분만 센다. 시작 =
     이 run 의 run-manifest createdAt, 종료 = team-state.runEndedAt → 이 run 의
     status mtime → 현재 시각(아직 진행 중) 순으로 해소한다. 접미사를 못 뽑으면
-    (None, None) — 윈도우 없이 전체를 세는 기존 동작으로 안전 폴백."""
+    (None, None) — 윈도우 없이 전체를 세는 기존 동작으로 안전 폴백.
+
+    시작 완화: run-manifest createdAt 이 이 run 의 실제 lead/worker 세션보다
+    늦게 찍히면(관측: dev-9902 — createdAt 11:43Z 가 05:34Z 시작 세션보다 늦음)
+    since 가 앞선 세션을 잘라낸다. Task 3 이 기록한 `leadSessionIds[]` 세션의
+    첫 ts 최소값이 createdAt 보다 앞서면 그 값으로 since 를 앞당긴다.
+    `leadSessionIds` 부재(legacy)면 createdAt 그대로 — 기존 동작 불변."""
     suffix = run_artifact_suffix(team_state_path)
     if not suffix:
         return None, None
     run_dir = team_state_path.parent.parent
     since = _run_manifest_created_at(run_dir, suffix)
+    earliest = _earliest_lead_session_ts(state, team_state_path)
+    if earliest and (since is None or earliest < since):
+        since = earliest
     until = state.get("runEndedAt") or _run_end_estimate(run_dir, suffix) or utc_now()
     return since, until
 
@@ -214,6 +270,55 @@ def resolve_team_name(state: dict) -> str:
     return team_name
 
 
+def resolve_team_needles(state: dict) -> list[str]:
+    """이 run 에 속한 harness teamName(`session-<leadSid-prefix>`) 전체.
+
+    lead 재발급마다 세대가 갈리므로 team-state.teamName 단일값으로는 후속
+    세대 워커를 놓친다. 축1 이 기록한 `observedTeamNames[]` 를 정본으로 쓰고,
+    수동 정정으로 teamName 에 직접 박힌 `session-*` 값도 흡수한다.
+    audit label(`okstra-<task-key>`) 은 harness needle 이 아니므로 제외한다.
+    """
+    needles: set[str] = set()
+    for name in state.get("observedTeamNames") or []:
+        if isinstance(name, str) and name.startswith("session-"):
+            needles.add(name)
+    label = resolve_team_name(state)
+    if label.startswith("session-"):
+        needles.add(label)
+    return sorted(needles)
+
+
+def resolve_team_needles_with_source(
+    state: dict, cwd, since, until, projects_root=None,
+) -> tuple[list[str], str]:
+    """세 소비처(collect + 두 validator) 공통 needle 조립 규칙.
+
+    needle 은 `resolve_team_needles(state)` 만으로 조립한다 — 축1 의
+    `observedTeamNames[]` 세대들 + `session-*` 형태의 수동 정정 라벨. audit
+    label(`okstra-<task-key>`)은 needle 로 절대 쓰지 않는다: 하네스 jsonl 은
+    `session-*` teamName 만 실어(okstra-lead-contract.md), 라벨은 여러 run 이
+    공유하는 task-key 파생값이라 needle 로 쓰면 같은 task-key 의 다른 run 세션을
+    끌어와 cross-run mis-attribution 을 일으킨다(spec §2.1 이 배제하는 바로 그
+    실패). `resolve_team_name` 은 표시 라벨(`usageSummary.teamName`) 전용.
+
+    `resolve_team_needles` 가 비면(observedTeamNames 미기록 legacy run) 축4 의
+    `reconstruct_needles_from_workers` 로 run window 안 워커 jsonl 의 `session-*`
+    teamName 을 best-effort 복구하고 `reconstructed-from-workers` provenance 를
+    돌려준다 — window 로 스코핑되므로 타 run 을 안전하게 배제한다. 그마저 비면
+    `none`. 반환한 source 는 각 소비처가 자기 관례대로 표면화한다
+    (collect → usageSummary.needleSource).
+    """
+    needles = resolve_team_needles(state)
+    if needles:
+        return needles, "observed-team-names"
+    reconstructed = reconstruct_needles_from_workers(
+        cwd, since, until, projects_root=projects_root
+    )
+    if reconstructed:
+        return reconstructed, "reconstructed-from-workers"
+    return [], "none"
+
+
 def _resolve_project_path(project_root: Path, raw_path: str) -> Path | None:
     if not raw_path:
         return None
@@ -407,7 +512,8 @@ def _collect_codex_runtime_usage(state: dict, project_root: Path) -> dict:
             _aggregate_totals(totals),
             session_paths,
         )
-    _populate_usage_summary(state, team_name=resolve_team_name(state), sessions_found=0)
+    _populate_usage_summary(state, team_name=resolve_team_name(state),
+                            sessions_found=0, needle_source="none")
     return state
 
 
@@ -418,6 +524,7 @@ def _populate_usage_summary(
     sessions_found: int,
     unattributed_sessions: list[str] | None = None,
     unattributed_usage: dict[str, Any] | None = None,
+    needle_source: str = "observed-team-names",
 ) -> None:
     workers = state.get("workers", [])
     lead = state.get("leadUsage") or {}
@@ -462,6 +569,7 @@ def _populate_usage_summary(
         },
         "collectedAt": utc_now(),
         "teamName": team_name,
+        "needleSource": needle_source,
         "sessionsFound": sessions_found,
         "unmatchedModels": sorted(set(unmatched_models)),
         "unattributedTeamSessions": unattributed_sessions or [],
@@ -490,9 +598,24 @@ def collect(team_state_path: Path, project_root: Path | None = None, *,
 
     # 1) Claude sessions (lead + claude-side workers). Cache totals at scan
     # time so we don't re-read the jsonl when a worker matches multiple
-    # sessions.
-    claude_sessions = find_claude_team_sessions(cwd, team_name, lead_sid,
+    # sessions. needle 집합(observedTeamNames 여러 세대)으로 스캔하고, 없으면
+    # 워커 jsonl 에서 복구한다 — team_name 은 표시 라벨 전용.
+    team_needles, needle_source = resolve_team_needles_with_source(
+        state, cwd, run_since, run_until
+    )
+    claude_sessions = find_claude_team_sessions(cwd, team_needles, lead_sid,
                                                 incremental=incremental)
+    # Task 9: 축1 기록(observed-team-names)으로 발견한 세션들의 min first-ts 로
+    # run_since 를 완화한다. session-* needle 은 세션 고유라 발견 세션은 이 run
+    # 것이므로 안전. 불확실한 reconstruct/none source 는 완화하지 않는다(오귀속 방지).
+    if needle_source == "observed-team-names":
+        found_earliest = None
+        for path in claude_sessions.values():
+            ts = _session_first_ts(path)
+            if ts and (found_earliest is None or ts < found_earliest):
+                found_earliest = ts
+        if found_earliest and (run_since is None or found_earliest < run_since):
+            run_since = found_earliest
     by_agent: dict[str, list[tuple[str, Path, dict]]] = {}
     lead_path: Path | None = None
     # Team-tagged non-lead sessions that carry no agentName. These are almost
@@ -623,6 +746,7 @@ def collect(team_state_path: Path, project_root: Path | None = None, *,
         sessions_found=len(claude_sessions),
         unattributed_sessions=unattributed_sessions,
         unattributed_usage=unattributed_usage,
+        needle_source=needle_source,
     )
     return state
 
@@ -637,3 +761,38 @@ def _infer_project_root(team_state_path: Path, state: dict) -> Path:
             return p
         p = p.parent
     raise SystemExit(f"could not infer project root from {team_state_path}")
+
+
+def reconstruct_needles_from_workers(cwd, since, until, projects_root=None) -> list[str]:
+    """observedTeamNames 가 없는 과거 run 의 best-effort 복구: run window 안
+    워커 jsonl(agentName 존재)이 달고 있는 session-* teamName variant 집합.
+    """
+    from okstra_token_usage.paths import claude_project_dir, ts_in_window
+    proj_dir = claude_project_dir(cwd, projects_root)
+    found: set[str] = set()
+    if not proj_dir.is_dir():
+        return []
+    for p in proj_dir.glob("*.jsonl"):
+        agent = team = first_ts = None
+        try:
+            with p.open(encoding="utf-8") as fh:
+                for raw in fh:
+                    try:
+                        rec = json.loads(raw)
+                    except (json.JSONDecodeError, UnicodeDecodeError):
+                        continue
+                    if agent is None and rec.get("agentName"):
+                        agent = rec["agentName"]
+                    if team is None and rec.get("teamName"):
+                        team = rec["teamName"]
+                    ts = rec.get("timestamp")
+                    if ts and (first_ts is None or ts < first_ts):
+                        first_ts = ts
+        except OSError:
+            continue
+        # 의도적 divergence: 이 untrusted best-effort 경로에서는 ts 를 못 구한
+        # 워커를 제외한다 (ts_in_window 의 파싱 실패→포함 정책과 반대).
+        if agent and team and str(team).startswith("session-") \
+                and first_ts and ts_in_window(first_ts, since, until):
+            found.add(team)
+    return sorted(found)

package/runtime/templates/reports/settings.template.json

@@ -47,6 +47,10 @@
           {
             "type": "command",
             "command": "$HOME/.okstra/bin/okstra-trace-cleanup.sh --reap"
+          },
+          {
+            "type": "command",
+            "command": "$HOME/.okstra/bin/okstra-team-reconcile.sh --session-end"
           }
         ]
       }

package/runtime/validators/forbidden_actions.py

@@ -122,13 +122,19 @@ def scan_forbidden_actions(
     """Return human-readable violation strings (empty = clean)."""
     _ensure_token_usage_importable()
     from okstra_token_usage.claude import find_claude_team_sessions
-    from okstra_token_usage.collect import resolve_run_window, resolve_team_name
+    from okstra_token_usage.collect import (
+        resolve_run_window,
+        resolve_team_needles_with_source,
+    )
 
     since, until = resolve_run_window(team_state_path, team_state)
     lead_sid = (team_state.get("lead") or {}).get("sessionId") or ""
+    team_needles, _needle_source = resolve_team_needles_with_source(
+        team_state, project_root, since, until, projects_root=claude_projects_dir
+    )
     sessions = find_claude_team_sessions(
         project_root,
-        resolve_team_name(team_state),
+        team_needles,
         lead_sid,
         projects_root=claude_projects_dir,
     )

package/runtime/validators/validate-run.py

@@ -1527,6 +1527,7 @@ def validate_final_report_data(report_path: Path, failures: list[str]) -> None:
         failures.append(f"final-report data.json: {err}")
 
     _validate_rationale_evidence(data, failures)
+    _validate_no_opaque_id_references(data, failures)
 
     task_type = (data.get("header") or {}).get("taskType")
     if task_type == "final-verification":
@@ -1541,8 +1542,10 @@ def validate_final_report_data(report_path: Path, failures: list[str]) -> None:
         _validate_requirement_coverage_covered_by(data, failures)
 
 
-# path:line (foo.service.ts:268), report ID (C-001 / F-013 / G-crit-002 / RC-1),
-# or a section reference (§5.4) — any one satisfies "this claim is anchored".
+# path:line (foo.service.ts:268), an in-report ID (C-001 / E-006 / P-004), a
+# namespaced audit ref (claude:F-005), or a §section reference (§5.4) — any one
+# satisfies "this claim is anchored". A bare brief/worker ID (RC-*/RF-*/F-*) is
+# handled separately by `_validate_no_opaque_id_references`.
 _EVIDENCE_TOKEN = re.compile(
     r"[\w./-]+\.\w+:\d+|\b[A-Z]{1,3}(?:-[a-z]+)?-\d+\b|§\s*\d")
 # Explicit "I don't know" escapes — anti-fabrication's other valid answer.
@@ -1573,12 +1576,61 @@ def _validate_rationale_evidence(data: dict, failures: list[str]) -> None:
             continue
         failures.append(
             f"final-report data.json: rationale.{field} cites no evidence "
-            f"(expected a path:line, a report ID like C-001/F-013, or a §"
+            f"(expected a path:line, an in-report ID like C-001, or a §"
             f"section reference) and gives no explicit insufficiency marker "
             f"(e.g. '근거 불충분'). Anchor the claim or state what is unknown."
         )
 
 
+# Brief/worker-internal ID families that are NOT surfaced (anchored) in the
+# final report: `RC-` reporter confirmations live in the brief, `F-`/`RF-`
+# findings live in worker-results. A reader-facing sentence citing a bare one
+# of these has no in-report target to resolve — the reader is stuck. Namespaced
+# audit citations (`claude:F-005`) are exempt via the `:` negative lookbehind.
+_OPAQUE_ID_RE = re.compile(r"(?<![:\w-])(?:RC|RF|F)-\d+(?![\w-])")
+
+
+def _reader_facing_narrative(data: dict) -> list[tuple[str, str]]:
+    """(label, text) for every reader-facing narrative string in the report —
+    the fields a human reads to act, where an unresolvable ID is most harmful."""
+    out: list[tuple[str, str]] = []
+    for section in ("verdictCard", "finalVerdict"):
+        block = data.get(section)
+        if isinstance(block, dict):
+            for field in ("finalConclusion", "nextStep"):
+                value = block.get(field)
+                if isinstance(value, str):
+                    out.append((f"{section}.{field}", value))
+    rationale = data.get("rationale")
+    if isinstance(rationale, dict):
+        for field in _RATIONALE_FIELDS:
+            value = rationale.get(field)
+            if isinstance(value, str):
+                out.append((f"rationale.{field}", value))
+    for row in data.get("clarificationItems") or []:
+        if isinstance(row, dict) and isinstance(row.get("statement"), str):
+            out.append((f"clarificationItems[{row.get('id') or '?'}].statement", row["statement"]))
+    return out
+
+
+def _validate_no_opaque_id_references(data: dict, failures: list[str]) -> None:
+    """Reader-facing prose must not cite a bare brief/worker-internal ID
+    (`RC-*`, `RF-*`, non-namespaced `F-*`) that the report never surfaces — the
+    reader has nothing to click and no definition to find. Expand it inline
+    (`the confirmed version target 1.27.47→1.27.48`) or namespace an audit
+    citation (`claude:F-005`)."""
+    for label, text in _reader_facing_narrative(data):
+        offenders = sorted({m.group(0) for m in _OPAQUE_ID_RE.finditer(text)})
+        if offenders:
+            failures.append(
+                f"final-report data.json: {label} cites brief/worker-internal "
+                f"ID(s) {', '.join(offenders)} that this report never surfaces "
+                "(no anchor to resolve them to). Expand them to plain language "
+                "on the reference, or namespace an audit citation like "
+                "`claude:F-005` — a reader cannot resolve a bare RC-/RF-/F- token."
+            )
+
+
 def _validate_implementation_planning_cross_project(data: dict, failures: list[str]) -> None:
     """타 프로젝트 의존을 DM 행(`kind == 'cross-project'`)으로 선언했다면
     `crossProjectDependencies` 에 `direction == 'upstream-precondition'` 행이

package/runtime/validators/validate_session_conformance.py

@@ -33,7 +33,13 @@ _WORKER_DISPATCH_MODES = {"cli-wrapper", "mixed", "tmux-pane"}
 _ATTEMPTED_STATUSES = {"completed", "timeout", "error"}
 
 # lead 의 체크포인트 라인 — assistant text 블록 안에서 line-anchored 로만 인정.
-_PROGRESS_LINE_RE = re.compile(r"^PROGRESS:[ \t]+(?P<phase>\S+)(?P<rest>.*)$", re.MULTILINE)
+# lead 는 계약상 raw 로 emit 해야 하지만 실측(dev-9902)에서 `` `PROGRESS: ...` ``
+# 인라인 코드나 코드펜스로 감싸 emit 하는 경우가 있어, 라인 양끝의 backtick 과
+# 선행 들여쓰기를 허용한다. phase 는 backtick 을 포함하지 않는다.
+_PROGRESS_LINE_RE = re.compile(
+    r"^[ \t]*`*[ \t]*PROGRESS:[ \t]+(?P<phase>[^\s`]+)(?P<rest>[^`\n]*)`*[ \t]*$",
+    re.MULTILINE,
+)
 
 # claude-worker audit 사이드카의 heartbeat 라인 (claude-worker.md "Heartbeat").
 _HEARTBEAT_LINE_RE = re.compile(
@@ -139,7 +145,8 @@ def _scan_one_jsonl(
                     continue
                 if block.get("type") == "text":
                     for m in _PROGRESS_LINE_RE.finditer(block.get("text") or ""):
-                        progress.append((ts, m.group("phase"), m.group(0).strip()))
+                        line = f"PROGRESS: {m.group('phase')}{m.group('rest')}".rstrip()
+                        progress.append((ts, m.group("phase"), line))
                 elif block.get("type") == "tool_use" and block.get("name") == "Read":
                     base = Path(str((block.get("input") or {}).get("file_path") or "")).name
                     if base in _SIDECAR_BASENAMES:
@@ -160,14 +167,29 @@ def _collect_lead_evidence(
     agentName 없음)를 흡수한다 — worker 세션은 agentName 이 있어 자연 배제된다.
     """
     from okstra_token_usage.claude import find_claude_team_sessions
-    from okstra_token_usage.collect import resolve_run_window, resolve_team_name
+    from okstra_token_usage.collect import (
+        resolve_run_window,
+        resolve_team_needles_with_source,
+    )
     from okstra_token_usage.paths import claude_project_dir
 
     since, until = resolve_run_window(team_state_path, team_state)
     lead_sid = (team_state.get("lead") or {}).get("sessionId") or ""
+    team_needles, _needle_source = resolve_team_needles_with_source(
+        team_state, project_root, since, until, projects_root=projects_root
+    )
     sessions = find_claude_team_sessions(
-        project_root, resolve_team_name(team_state), lead_sid, projects_root=projects_root
+        project_root, team_needles, lead_sid, projects_root=projects_root
     )
+    # `claude --resume` 로 fork 되거나 leadSessionIds[] 에 기록된 lead 세대는
+    # team 태그 needle 로 안 잡힐 수 있어 명시적으로 후보에 추가한다.
+    proj_dir = claude_project_dir(project_root, projects_root)
+    for sid in (team_state.get("leadSessionIds") or []):
+        if not isinstance(sid, str) or not sid:
+            continue
+        candidate = proj_dir / f"{sid}.jsonl"
+        if candidate.is_file():
+            sessions.setdefault(sid, candidate)
     evidence = _LeadEvidence(window=(since, until))
     for sid, path in sorted(sessions.items()):
         progress, reads, agent_name = _scan_one_jsonl(path, since, until)
@@ -178,7 +200,6 @@ def _collect_lead_evidence(
         for base, ts_list in reads.items():
             evidence.sidecar_reads.setdefault(base, []).extend(ts_list)
     if not evidence.scanned_files:
-        proj_dir = claude_project_dir(project_root, projects_root)
         return None, (
             f"lead session jsonl not found under {proj_dir} "
             f"(lead.sessionId={lead_sid or '<empty>'}) — PROGRESS checkpoint / "