okstra 0.107.2 → 0.109.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.107.2",
+  "version": "0.109.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.2",
-  "builtAt": "2026-07-01T09:21:00.281Z",
+  "package": "0.109.0",
+  "builtAt": "2026-07-02T07:00:18.587Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

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:
 

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

@@ -16,7 +16,7 @@ profile document.
   - **Phase 4 / 5 (independent analysis)**: analyser workers (`claude`, `codex`, `antigravity` when opted in) produce findings independently and have no access to one another's outputs. `report-writer` does not analyse.
   - **Phase 5.5 (convergence — peer review by workers)**: the lead replays each analyser's findings to the *other* analysers and collects `AGREE` / `DISAGREE` / `SUPPLEMENT` verdicts across up to `effectiveMaxRounds` rounds. Workers act as peer reviewers of each other's findings in this phase; the lead mediates but does not vote. See `prompts/lead/convergence.md` for the round protocol, queue invariants, and final classification (`full-consensus` / `partial-consensus` / `contested` / `worker-unique`). For `requirements-discovery`, `error-analysis`, and `implementation-planning` this phase runs in **adversarial mode** (`convergence.adversarial=true`): verifiers try to refute each finding against its cited evidence and the burden of proof sits on the claim — see that skill's §"Adversarial Verification Mode".
   - Do NOT conclude "no peer review happens" from the roster alone — every profile that lists ≥2 analyser workers runs convergence by default (`convergence.enabled=true` in `task-manifest.json`).
-  - **Pane-budget fallback (tolerance).** If a worker dispatch is rejected with `no room for another tmux split` (or an equivalent teammate-pane creation failure), the lead retries that worker in-process without `run_in_background`; if it was an external CLI worker, the lead instead **substitutes** an in-process `claude` analysis. Either way the lead records the substitution as provider unavailable in the run log and the convergence notes. Completed external-CLI worker trace panes are reclaimed automatically by the `SubagentStop` hook, but okstra cannot directly reclaim the teammate panes the harness creates, so this fallback is the last line of defence against pane-budget exhaustion. (This is a prompt instruction, not a code-enforced gate.)
+  - **provider-unavailable fallback (tolerance).** A worker dispatch can fail to produce a result for two distinct reasons, and both take the same recovery path. (1) **Pane budget:** the dispatch is rejected with `no room for another tmux split` (or an equivalent teammate-pane creation failure). (2) **Sandbox CLI-start failure (non-tmux path):** an external CLI worker wrapper exits non-zero within seconds with empty stdout and its live-log shows `operation not permitted` (e.g. `agy`'s `listen tcp 127.0.0.1:0: bind` under a seatbelt sandbox around a non-tmux subagent's Bash tool). In either case the lead retries that worker in-process without `run_in_background`; if it was an external CLI worker, the lead instead **substitutes** an in-process `claude` analysis. Either way the lead records the substitution as provider unavailable in the run log and the convergence notes. Completed external-CLI worker trace panes are reclaimed automatically by the `SubagentStop` hook, but okstra cannot directly reclaim the teammate panes the harness creates, so this fallback is the last line of defence against pane-budget exhaustion and sandbox-blocked CLI workers. (This is a prompt instruction, not a code-enforced gate.)
 - Tooling — read-only MCP availability (shared):
   - MCP is not implicit okstra context. Query an MCP server only when the task brief explicitly lists it as source material for this run. Any MCP-derived finding MUST cite server, table, and the SELECT used. MCP MUST NEVER be used as a write path — schema/data mutations go through repository migration files reviewed by humans.
 - Resource boundary (shared — artifact-home rule):
@@ -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).

package/runtime/python/okstra_ctl/graphify_cmd.py

@@ -0,0 +1,225 @@
+"""okstra-graphify 스코프 래퍼 — resolve_scope + assemble + main 디스패치.
+
+입력은 항상 ``<project_root>/.okstra`` 로, 출력은 ``<project_root>/.okstra/graph``
+로 고정한다. resolve_scope 가 corpus·output 경로의 유일 정의점이며,
+assemble 이 추출 청크를 그래프·리포트로 병합하고, main 이 query/path/explain/
+mcp/wiki 서브커맨드를 디스패치한다.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+import okstra_vendor  # noqa: F401  (registers vendored graphify/networkx)
+
+OUT_DIRNAME = "graph"
+
+
+@dataclass(frozen=True)
+class ScopePaths:
+    corpus: Path
+    out_dir: Path
+
+
+def resolve_scope(project_root: Path) -> ScopePaths:
+    root = Path(project_root).resolve()
+    okstra = root / ".okstra"
+    return ScopePaths(corpus=okstra, out_dir=okstra / OUT_DIRNAME)
+
+
+def assemble(project_root: Path) -> Path:
+    sp = resolve_scope(project_root)
+    chunk_dir = sp.out_dir / ".chunks"
+    chunks = sorted(chunk_dir.glob("*.json")) if chunk_dir.is_dir() else []
+    if not chunks:
+        raise FileNotFoundError(f"no extraction chunks under {chunk_dir}")
+
+    merged = {"nodes": [], "edges": []}
+    for c in chunks:
+        data = json.loads(c.read_text(encoding="utf-8"))
+        merged["nodes"].extend(data.get("nodes", []))
+        merged["edges"].extend(data.get("edges", []))
+
+    from graphify.build import build_from_json
+    from graphify.cluster import cluster, score_all
+    from graphify.analyze import god_nodes, surprising_connections, suggest_questions
+    from graphify.report import generate
+    from graphify.export import to_json, to_html
+
+    sp.out_dir.mkdir(parents=True, exist_ok=True)
+    G = build_from_json(merged)
+    communities = cluster(G)
+    cohesion = score_all(G, communities)
+    gods = god_nodes(G)
+    surprises = surprising_connections(G, communities)
+    labels = {cid: f"Community {cid}" for cid in communities}
+    questions = suggest_questions(G, communities, labels)
+    tokens = {"input": 0, "output": 0}
+    report = generate(
+        G, communities, cohesion, labels, gods, surprises,
+        {"warning": "okstra-graphify: .okstra scope"},
+        tokens, str(sp.corpus), suggested_questions=questions,
+    )
+    (sp.out_dir / "GRAPH_REPORT.md").write_text(report, encoding="utf-8")
+    to_json(G, communities, str(sp.out_dir / "graph.json"))
+    to_html(G, communities, str(sp.out_dir / "graph.html"), community_labels=labels or None)
+    return sp.out_dir
+
+
+def _graph_path(project_root: Path) -> Path:
+    return resolve_scope(project_root).out_dir / "graph.json"
+
+
+def _require_graph(project_root: Path) -> Path:
+    gp = _graph_path(project_root)
+    if not gp.exists():
+        raise SystemExit(
+            f"okstra-graphify: no graph at {gp}. Run `okstra graphify build` first."
+        )
+    return gp
+
+
+def _load_graph(graph_path: Path):
+    from networkx.readwrite import json_graph
+    raw = json.loads(Path(graph_path).read_text(encoding="utf-8"))
+    try:
+        return json_graph.node_link_graph(raw, edges="links")
+    except TypeError:
+        return json_graph.node_link_graph(raw)
+
+
+def _run_query(graph_path: Path, question: str, *, budget: int = 2000, use_dfs: bool = False) -> None:
+    # 벤더 __main__.py query 핸들러(1092–1149) 미러: 그래프 경로만 스코프로 교체.
+    from graphify.serve import _score_nodes, _bfs, _dfs, _subgraph_to_text
+    G = _load_graph(graph_path)
+    terms = [t.lower() for t in question.split() if len(t) > 2]
+    scored = _score_nodes(G, terms)
+    if not scored:
+        print("No matching nodes found.")
+        return
+    start = [nid for _, nid in scored[:5]]
+    nodes, edges = (_dfs if use_dfs else _bfs)(G, start, depth=2)
+    print(_subgraph_to_text(G, nodes, edges, token_budget=budget))
+
+
+def _run_path(graph_path: Path, source_label: str, target_label: str) -> None:
+    # 벤더 __main__.py path 핸들러(1169–1217) 미러.
+    from graphify.serve import _score_nodes
+    import networkx as nx
+    G = _load_graph(graph_path)
+    src_scored = _score_nodes(G, [t.lower() for t in source_label.split()])
+    tgt_scored = _score_nodes(G, [t.lower() for t in target_label.split()])
+    if not src_scored:
+        print(f"No node matching '{source_label}' found.")
+        return
+    if not tgt_scored:
+        print(f"No node matching '{target_label}' found.")
+        return
+    src_nid, tgt_nid = src_scored[0][1], tgt_scored[0][1]
+    try:
+        path_nodes = nx.shortest_path(G, src_nid, tgt_nid)
+    except (nx.NetworkXNoPath, nx.NodeNotFound):
+        print(f"No path found between '{source_label}' and '{target_label}'.")
+        return
+    hops = len(path_nodes) - 1
+    segments = []
+    for i in range(len(path_nodes) - 1):
+        u, v = path_nodes[i], path_nodes[i + 1]
+        edata = G.edges[u, v]
+        rel = edata.get("relation", "")
+        conf = edata.get("confidence", "")
+        conf_str = f" [{conf}]" if conf else ""
+        if i == 0:
+            segments.append(G.nodes[u].get("label", u))
+        segments.append(f"--{rel}{conf_str}--> {G.nodes[v].get('label', v)}")
+    print(f"Shortest path ({hops} hops):\n  " + " ".join(segments))
+
+
+def _run_explain(graph_path: Path, label: str) -> None:
+    # 벤더 __main__.py explain 핸들러(1219–1261) 미러.
+    from graphify.serve import _find_node
+    G = _load_graph(graph_path)
+    matches = _find_node(G, label)
+    if not matches:
+        print(f"No node matching '{label}' found.")
+        return
+    nid = matches[0]
+    d = G.nodes[nid]
+    print(f"Node: {d.get('label', nid)}")
+    print(f"  ID:        {nid}")
+    print(f"  Source:    {d.get('source_file', '')} {d.get('source_location', '')}".rstrip())
+    print(f"  Type:      {d.get('file_type', '')}")
+    print(f"  Community: {d.get('community', '')}")
+    print(f"  Degree:    {G.degree(nid)}")
+    neighbors = list(G.neighbors(nid))
+    if neighbors:
+        print(f"\nConnections ({len(neighbors)}):")
+        for nb in sorted(neighbors, key=lambda n: G.degree(n), reverse=True)[:20]:
+            edata = G.edges[nid, nb]
+            rel = edata.get("relation", "")
+            conf = edata.get("confidence", "")
+            print(f"  --> {G.nodes[nb].get('label', nb)} [{rel}] [{conf}]")
+        if len(neighbors) > 20:
+            print(f"  ... and {len(neighbors) - 20} more")
+
+
+def _run_wiki(project_root: Path) -> int:
+    # 벤더 wiki.to_wiki(wiki.py:168) 미러 — 그래프에서 커뮤니티/라벨/god-node 를
+    # 재구성해 <out_dir>/wiki/ 로 기록한다. assemble 과 동일한 재클러스터 경로.
+    from graphify.build import build_from_json
+    from graphify.cluster import cluster, score_all
+    from graphify.analyze import god_nodes
+    from graphify.wiki import to_wiki
+    sp = resolve_scope(project_root)
+    raw = json.loads((sp.out_dir / "graph.json").read_text(encoding="utf-8"))
+    G = build_from_json(raw)
+    communities = cluster(G)
+    cohesion = score_all(G, communities)
+    gods = god_nodes(G)
+    labels = {cid: f"Community {cid}" for cid in communities}
+    return to_wiki(
+        G, communities, str(sp.out_dir / "wiki"),
+        community_labels=labels or None, cohesion=cohesion, god_nodes_data=gods,
+    )
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(prog="okstra graphify")
+    parser.add_argument(
+        "subcmd",
+        choices=["build", "query", "path", "explain", "mcp", "wiki"],
+    )
+    parser.add_argument("rest", nargs="*")
+    parser.add_argument("--project-root", required=True, type=Path)
+    ns = parser.parse_args(argv)
+    root = ns.project_root
+
+    if ns.subcmd == "build":
+        assemble(root)
+        return 0
+    if ns.subcmd == "mcp":
+        from graphify.serve import serve
+        serve(str(_require_graph(root)))
+        return 0
+    if ns.subcmd == "wiki":
+        _require_graph(root)
+        _run_wiki(root)
+        return 0
+
+    gp = _require_graph(root)
+    if ns.subcmd == "query":
+        _run_query(gp, " ".join(ns.rest))
+    elif ns.subcmd == "path":
+        if len(ns.rest) < 2:
+            raise SystemExit("usage: okstra graphify path <ConceptA> <ConceptB> --project-root <dir>")
+        _run_path(gp, ns.rest[0], ns.rest[1])
+    elif ns.subcmd == "explain":
+        _run_explain(gp, " ".join(ns.rest))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

package/runtime/python/okstra_ctl/resolve_task_key.py

@@ -1,8 +1,9 @@
-"""bare task-id → task-catalog.json 후보 entry 목록(skill 공용 해석기).
+"""bare token(task-id 또는 task-group) → task-catalog.json 후보 entry 목록.
 
-skill markdown 이 복제하던 "catalog 를 읽어 taskId 를 case-insensitive 매칭 →
-0/1/N 분기" 를 단일 CLI 진입점으로 수렴시킨다. okstra_project.resolve_task_id
-가 SSOT 이고, 이 모듈은 project-root 해석 + JSON 정형화만 한다.
+skill markdown 이 복제하던 "catalog 를 읽어 case-insensitive 매칭 → 0/1/N 분기" 를
+단일 CLI 진입점으로 수렴시킨다. okstra_project.resolve_task_reference 가 SSOT 이고,
+이 모듈은 project-root 해석 + JSON 정형화만 한다. token 은 task-id 와 task-group
+두 축으로 매칭돼 합집합이 나온다(각 entry 의 _matchedVia 로 구분).
 """
 from __future__ import annotations
 
@@ -14,16 +15,21 @@ from okstra_project import (
     ResolverError,
     StateError,
     resolve_project_root,
-    resolve_task_id,
+    resolve_task_reference,
 )
 
 
 def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(
-        description="Resolve a bare task-id to candidate task-keys from the catalog."
+        description="Resolve a bare token (task-id or task-group) to candidate "
+        "task-keys from the catalog."
+    )
+    parser.add_argument(
+        "task_id", help="bare token: task-id or task-group (case-insensitive)"
+    )
+    parser.add_argument(
+        "--task-group", default="", help="scope the task-id match to this task-group"
     )
-    parser.add_argument("task_id", help="bare task-id (case-insensitive)")
-    parser.add_argument("--task-group", default="", help="scope match to this task-group")
     parser.add_argument("--project-root", default="", help="project root for catalog lookup")
     parser.add_argument("--cwd", default=".", help="cwd for project root resolution")
     parser.add_argument("--json", action="store_true", help="emit JSON (always on)")
@@ -36,7 +42,7 @@ def main(argv: list[str] | None = None) -> int:
         return 2
 
     try:
-        matches = resolve_task_id(
+        matches = resolve_task_reference(
             project_root, args.task_id, task_group=args.task_group or None
         )
     except StateError as exc:

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_project/__init__.py

@@ -36,6 +36,7 @@ from .state import (
     read_task_manifest,
     resolve_task_id,
     resolve_task_identity,
+    resolve_task_reference,
     slugify,
 )
 
@@ -61,6 +62,7 @@ __all__ = [
     "resolve_project_root",
     "resolve_task_id",
     "resolve_task_identity",
+    "resolve_task_reference",
     "slugify",
     "tasks_root",
     "upsert_project_json",

package/runtime/python/okstra_project/state.py

@@ -187,6 +187,42 @@ def resolve_task_id(
     return matches
 
 
+def resolve_task_reference(
+    project_root: Path,
+    token: str,
+    *,
+    task_group: Optional[str] = None,
+) -> list[dict]:
+    """bare token 을 task-id 또는 task-group 으로 매칭한 후보 목록을 돌려준다.
+
+    resolve_task_id 는 token 을 task-id 로만 봤다. 여기서는 같은 token 을 (a) task-id
+    (선택 task_group 스코프 유지) 와 (b) task-group 두 축으로 매칭해 합집합을 낸다.
+    task-group 매칭은 그 group 의 모든 멤버 task 로 펼쳐진다. 두 축 모두에 걸리면
+    양쪽 후보를 모두 담는다(taskKey 로 dedup). 각 entry 에 어느 축으로 걸렸는지
+    `_matchedVia`("taskId" | "taskGroup") 를 덧붙여 호출자가 picker 에서 구분한다.
+    """
+    wanted = (token or "").strip().lower()
+    if not wanted:
+        return []
+    out: list[dict] = []
+    seen: set[str] = set()
+
+    def _add(entry: dict, matched_via: str) -> None:
+        key = entry.get("taskKey")
+        if not isinstance(key, str) or not key or key in seen:
+            return
+        seen.add(key)
+        out.append({**entry, "_matchedVia": matched_via})
+
+    for entry in resolve_task_id(project_root, token, task_group=task_group):
+        _add(entry, "taskId")
+    for entry in read_task_catalog(Path(project_root)):
+        entry_group = entry.get("taskGroup")
+        if isinstance(entry_group, str) and entry_group.lower() == wanted:
+            _add(entry, "taskGroup")
+    return out
+
+
 def list_project_tasks(
     project_root: Path,
     *,

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)