okstra 0.163.2 → 0.164.0

package/runtime/python/okstra_ctl/team.py

@@ -1,8 +1,9 @@
 """Neutral okstra team CLI for pane-backed worker dispatch.
 
-Outside cmux this is the external lead's door onto tmux panes. Under cmux it
-is every lead's door onto cmux surfaces, because okstra owns the panes there
-rather than the host. Which backend a run uses is read from its run manifest.
+Outside cmux this is the door onto tmux panes for hosts whose descriptor owns
+the team lifecycle. Under cmux it is every lead's door onto cmux surfaces,
+because okstra owns the panes there rather than the host. Which backend a run
+uses is read from its run manifest.
 """
 from __future__ import annotations
 
@@ -14,18 +15,23 @@ from typing import Any, Mapping, Sequence
 
 from . import cmux
 from . import tmux
+from .adapters.dispatch import provider_worker_wrappers
+from .adapters.dispatch.cmux import dispatch_port_for_terminal_backend
+from .application.dispatch_assignments import dispatch_assignments
 from .dispatch_core import (
     BACKEND_CMUX_PANE,
     BACKEND_TMUX_PANE,
     DispatchError,
     DispatchPlan,
     await_dispatches,
-    build_dispatch_plan,
     dispatch_plan,
 )
-from .runner_resolution import worker_wrapper_registry
+from .ports.worker_dispatch import WorkerDispatchRequest
+from .registry.host_registry import default_host_registry
+from .registry.provider_registry import default_provider_registry
 
-_SUPPORTED_WRAPPERS = worker_wrapper_registry()
+
+_SUPPORTED_WRAPPERS = provider_worker_wrappers(default_provider_registry())
 _TERMINAL_STATUSES = {"completed", "timeout", "error", "not-run"}
 
 
@@ -92,33 +98,43 @@ def _dispatch(args) -> int:
     if args.jobs_file and args.workers:
         raise DispatchError("--jobs-file and --workers cannot be combined")
     manifest = _load_manifest(args.project_root, args.run_manifest)
-    _validate_external_manifest(manifest)
-    requested = _parse_workers(args.workers)
-    plan = build_dispatch_plan(
+    terminal_backend = _manifest_backend(manifest)
+    lead_runtime = _require_string(manifest, "leadRuntime")
+    fallback_port = default_host_registry().resolve(
+        lead_runtime
+    ).worker_dispatch()
+    port = dispatch_port_for_terminal_backend(
+        terminal_backend,
+        fallback_port,
+        supported_worker_wrappers=_SUPPORTED_WRAPPERS,
+        unsupported_worker_label=f"{lead_runtime} lead",
+        required_lead_runtime=None if _is_cmux_run(manifest) else lead_runtime,
+    )
+    request = WorkerDispatchRequest(
         project_root=Path(args.project_root),
-        run_manifest_path=Path(args.run_manifest),
+        run_manifest=Path(args.run_manifest),
         workspace_root=Path(args.workspace_root),
         okstra_bin=Path(args.okstra_bin),
-        requested_workers=requested,
+        requested_workers=tuple(_parse_workers(args.workers)),
         idle_timeout_seconds=args.idle_timeout_seconds,
-        required_lead_runtime=None if _is_cmux_run(manifest) else "external",
-        default_backend=_manifest_backend(manifest),
-        supported_worker_wrappers=_SUPPORTED_WRAPPERS,
-        unsupported_worker_label="external lead",
         dispatch_kind=args.dispatch_kind,
         jobs_file=Path(args.jobs_file) if args.jobs_file else None,
     )
+    plan = dispatch_assignments(request, port)
+    backend_plan = plan.backend_plan
+    if backend_plan is None:
+        raise DispatchError("team dispatch did not produce a backend plan")
     if args.dry_run:
-        _print_json(plan.to_payload(dry_run=True))
+        _print_json(backend_plan.to_payload(dry_run=True))
         return 0
-    result = dispatch_plan(plan, wait=False)
-    _print_json(plan.to_payload(dry_run=False))
+    result = dispatch_plan(backend_plan, wait=False)
+    _print_json(backend_plan.to_payload(dry_run=False))
     return result
 
 
 def _await(args) -> int:
     manifest = _load_manifest(args.project_root, args.run_manifest)
-    _validate_external_manifest(manifest)
+    _validate_team_manifest(manifest)
     plan = _plan_for_existing(Path(args.project_root), Path(args.workspace_root), Path(args.run_manifest), manifest)
     code = await_dispatches(
         plan,
@@ -135,7 +151,7 @@ def _await(args) -> int:
 
 def _teardown(args) -> int:
     manifest = _load_manifest(args.project_root, args.run_manifest)
-    _validate_external_manifest(manifest)
+    _validate_team_manifest(manifest)
     project_root = Path(args.project_root).resolve()
     team_state_path = _resolve_project_path(project_root, _require_string(manifest, "teamStatePath"))
     team_state = _load_json(team_state_path, "team-state")
@@ -242,20 +258,16 @@ def _is_cmux_run(manifest: Mapping[str, Any]) -> bool:
     return _manifest_backend(manifest) == BACKEND_CMUX_PANE
 
 
-def _validate_external_manifest(manifest: Mapping[str, Any]) -> None:
-    runtime = manifest.get("leadRuntime")
-    if runtime == "external":
-        return
+def _validate_team_manifest(manifest: Mapping[str, Any]) -> None:
     if _is_cmux_run(manifest):
-        # Under cmux okstra owns the panes for every lead, so this command is no
-        # longer the external lead's private door and the advice below no longer
-        # applies — there is nowhere else for a codex or Claude Code lead to go.
         return
-    if runtime == "codex":
-        raise DispatchError("use okstra codex-dispatch for leadRuntime=codex")
-    if runtime == "claude-code":
-        raise DispatchError("use Claude Code TeamCreate/Agent flow for leadRuntime=claude-code")
-    raise DispatchError(f"unsupported leadRuntime for okstra team: {runtime}")
+    runtime = _require_string(manifest, "leadRuntime")
+    descriptor = default_host_registry().resolve(runtime).descriptor
+    if descriptor.launch_mode == "team":
+        return
+    raise DispatchError(
+        f"leadRuntime={descriptor.id} does not use the okstra team lifecycle"
+    )
 
 
 def _load_manifest(project_root: str, run_manifest: str) -> dict[str, Any]:

package/runtime/python/okstra_ctl/wizard.py

@@ -29,6 +29,23 @@ from datetime import datetime
 from pathlib import Path
 from typing import Any, Callable, Optional
 
+from okstra_ctl.application.advance_wizard import plan_prompt
+from okstra_ctl.application.resolve_assignment import resolve_lead_provider
+from okstra_ctl.domain.host import (
+    HostCapabilityMismatch,
+    HostNotRegistered,
+    HostSessionContext,
+    ProviderUnavailable,
+)
+from okstra_ctl.domain.wizard.interaction import (
+    InteractionPlan,
+    WizardAnswerError,
+    WizardOption,
+    WizardPrompt,
+    normalize_planned_answer,
+)
+from okstra_ctl.registry.host_registry import default_host_registry
+from okstra_ctl.registry.provider_registry import default_provider_registry
 from okstra_ctl.ids import slugify_task_segment
 from okstra_ctl.brief_frontmatter import read_brief_frontmatter
 from okstra_ctl.analysis_inputs import (
@@ -44,13 +61,12 @@ from okstra_ctl.analysis_inputs import (
 from okstra_ctl.models import (
     PROVIDER_MAPPINGS,
     UnknownModelError,
+    UnknownProviderError,
     picker_options,
     provider_ids,
     provider_supports_role,
     resolve_model_metadata,
 )
-from okstra_ctl.lead_runtime import lead_runtime_info
-from okstra_ctl.runner_resolution import native_provider_for_host
 from okstra_ctl.clarification_items import (
     scan_approval_gate,
     sidecar_answers,
@@ -176,7 +192,6 @@ _BRIEF_ENTRY_TASK_TYPES = (
 
 CANONICAL_BASE_REFS = ["main", "dev", "staging", "preprod", "prod"]
 BASE_REF_FREE_INPUT_TOKEN = "__free_input__"
-HOST_PICK_OPTION_CAP = 4
 
 CLAUDE_MODEL_OPTIONS = ["default", *picker_options("claude")]
 CODEX_MODEL_OPTIONS = ["default", *picker_options("codex")]
@@ -389,6 +404,8 @@ class WizardState:
     project_root: str = ""
     project_id: str = ""
     host_runtime: str = "claude-code"
+    host_entry_mode: str = "current-session"
+    available_functions: list[str] = field(default_factory=list)
 
     # task identity
     is_new_task: Optional[bool] = None
@@ -535,8 +552,6 @@ class Prompt:
             "echoTemplate": self.echo_template,
             "multi": self.multi,
         }
-        if self.kind == "pick" and len(self.options) > HOST_PICK_OPTION_CAP:
-            out["presentation"] = "numbered-text"
         if self.kind == "pick_group":
             out["questions"] = [
                 {"step": q.step, "label": q.label,
@@ -551,35 +566,6 @@ class WizardError(Exception):
     """validation failure surfaced to user."""
 
 
-def _normalize_numbered_pick_item(prompt: Prompt, answer: str) -> str:
-    candidate = (answer or "").strip()
-    exact_values = [option.value for option in prompt.options if option.value == candidate]
-    if exact_values:
-        return exact_values[0]
-
-    if candidate.isdecimal():
-        number = int(candidate)
-        if 1 <= number <= len(prompt.options):
-            return prompt.options[number - 1].value
-        raise WizardError(f"numbered-text answer is out of range: {candidate}")
-
-    label_values = [option.value for option in prompt.options if option.label == candidate]
-    if len(label_values) == 1:
-        return label_values[0]
-    if len(label_values) > 1:
-        raise WizardError(f"numbered-text answer label is ambiguous: {candidate}")
-    raise WizardError(f"numbered-text answer is not an option: {candidate}")
-
-
-def _normalize_numbered_pick_answer(prompt: Prompt, answer: str) -> str:
-    if prompt.multi:
-        return ",".join(
-            _normalize_numbered_pick_item(prompt, item)
-            for item in (answer or "").split(",")
-        )
-    return _normalize_numbered_pick_item(prompt, answer)
-
-
 # ---- Validation helpers --------------------------------------------------
 
 _SLUG_OK = re.compile(r"[a-z0-9]")
@@ -3369,6 +3355,28 @@ def _build_reuse_previous(state: WizardState) -> Prompt:
     )
 
 
+def _restore_reused_lead(state: WizardState, inputs: dict) -> None:
+    requested_provider = _safe_provider(inputs.get("leadProvider"), "lead")
+    try:
+        assignment = resolve_lead_provider(
+            host_id=state.host_runtime,
+            requested_provider=requested_provider,
+            host_registry=default_host_registry(),
+            provider_registry=default_provider_registry(),
+        )
+    except (
+        HostCapabilityMismatch,
+        HostNotRegistered,
+        ProviderUnavailable,
+        UnknownProviderError,
+    ) as exc:
+        raise WizardError(
+            f"previous run cannot be reused: {exc}; choose step-by-step re-entry"
+        ) from exc
+    state.lead_provider = assignment.provider
+    state.lead_model = _safe_model(assignment.provider, inputs.get("leadModel"))
+
+
 def _submit_reuse_previous(state: WizardState, value: str) -> Optional[str]:
     if value not in ("yes", "no"):
         raise WizardError(f"expected 'yes' or 'no', got: {value!r}")
@@ -3383,16 +3391,7 @@ def _submit_reuse_previous(state: WizardState, value: str) -> Optional[str]:
     state.workers_override = (
         ",".join(w for w in workers if isinstance(w, str))
         if isinstance(workers, list) else "")
-    state.lead_provider = _safe_provider(inputs.get("leadProvider"), "lead")
-    lead_provider = state.lead_provider or "claude"
-    native_provider = native_provider_for_host(state.host_runtime)
-    if native_provider and lead_provider != native_provider:
-        raise WizardError(
-            f"previous run used provider {lead_provider!r}, but "
-            f"{state.host_runtime} requires provider {native_provider!r}; "
-            "choose step-by-step re-entry"
-        )
-    state.lead_model = _safe_model(lead_provider, inputs.get("leadModel"))
+    _restore_reused_lead(state, inputs)
     state.claude_model = _safe_model("claude", inputs.get("claudeModel"))
     state.codex_model = _safe_model("codex", inputs.get("codexModel"))
     state.antigravity_model = _safe_model("antigravity", inputs.get("antigravityModel"))
@@ -3601,16 +3600,27 @@ def _model_pick(step: str, label: str, options: list[str], echo: str) -> Prompt:
 
 
 def _qualified_role_model_options(role: str) -> list[str]:
-    options = list(CLAUDE_MODEL_OPTIONS)
-    for provider in provider_ids(role):
+    registry = default_provider_registry()
+    options = ["default", *_provider_picker_options("claude", registry)]
+    for provider in registry.ids(role):
         if provider == "claude":
             continue
         options.extend(
-            f"{provider}:{model}" for model in picker_options(provider)
+            f"{provider}:{model}"
+            for model in _provider_picker_options(provider, registry)
         )
     return options
 
 
+def _provider_picker_options(provider: str, registry=None) -> list[str]:
+    provider_registry = registry or default_provider_registry()
+    return [
+        alias
+        for alias, model in provider_registry.resolve(provider).models.items()
+        if model.in_picker
+    ]
+
+
 def _submit_qualified_role_model(
     state: WizardState, value: str, role: str, model_field: str, provider_field: str,
 ) -> str:
@@ -3629,32 +3639,44 @@ def _submit_qualified_role_model(
 
 def _build_lead_model(state: WizardState) -> Prompt:
     t = _p(state.workspace_root, "lead_model")
-    provider = native_provider_for_host(state.host_runtime)
+    provider = default_host_registry().resolve(
+        state.host_runtime
+    ).descriptor.native_provider_id
     options = (
-        ["default", *picker_options(provider)]
+        ["default", *_provider_picker_options(provider)]
         if provider else _qualified_role_model_options("lead")
     )
     return _model_pick(S_LEAD_MODEL, t["label"], options, t["echo_template"])
 
 
 def _submit_lead_model(state: WizardState, value: str) -> Optional[str]:
-    native_provider = native_provider_for_host(state.host_runtime)
+    native_provider = default_host_registry().resolve(
+        state.host_runtime
+    ).descriptor.native_provider_id
     if native_provider:
         raw = (value or "").strip()
+        requested_provider = ""
         if ":" in raw:
-            selected_provider, raw = (
+            requested_provider, raw = (
                 part.strip().lower() for part in raw.split(":", 1)
             )
-            if selected_provider != native_provider:
-                host_label = lead_runtime_info(state.host_runtime).agent_label
-                raise WizardError(
-                    f"{host_label.removesuffix(' CLI')} host requires provider "
-                    f"{native_provider!r} "
-                    "for the in-session lead"
-                )
-        state.lead_provider = native_provider
-        state.lead_model = _validate_model(native_provider, raw)
-        return f"lead-model: {native_provider}:{state.lead_model or 'default'}"
+        try:
+            assignment = resolve_lead_provider(
+                host_id=state.host_runtime,
+                requested_provider=requested_provider,
+                host_registry=default_host_registry(),
+                provider_registry=default_provider_registry(),
+            )
+        except (
+            HostCapabilityMismatch,
+            HostNotRegistered,
+            ProviderUnavailable,
+            UnknownProviderError,
+        ) as exc:
+            raise WizardError(str(exc)) from exc
+        state.lead_provider = assignment.provider
+        state.lead_model = _validate_model(assignment.provider, raw)
+        return f"lead-model: {assignment.provider}:{state.lead_model or 'default'}"
     selected = _submit_qualified_role_model(
         state, value, "lead", "lead_model", "lead_provider",
     )
@@ -4529,6 +4551,8 @@ def _reset_field(state: WizardState, fname: str) -> None:
 def init_state(
     *, workspace_root: str, project_root: str, project_id: str,
     host_runtime: str = "claude-code",
+    host_entry_mode: str = "current-session",
+    available_functions: Optional[list[str]] = None,
 ) -> WizardState:
     """Bootstrap a new wizard state."""
     return WizardState(
@@ -4536,6 +4560,8 @@ def init_state(
         project_root=project_root,
         project_id=project_id,
         host_runtime=host_runtime,
+        host_entry_mode=host_entry_mode,
+        available_functions=list(available_functions or []),
     )
 
 
@@ -4668,9 +4694,73 @@ def _screen_progress(state: WizardState) -> dict[str, Any]:
     }
 
 
+def _domain_prompt(prompt: Prompt) -> WizardPrompt:
+    return WizardPrompt(
+        step=prompt.step,
+        kind=prompt.kind,
+        label=prompt.label,
+        options=tuple(
+            WizardOption(option.value, option.label, option.description)
+            for option in prompt.options
+        ),
+        help=prompt.help,
+        echo_template=prompt.echo_template,
+        multi=prompt.multi,
+        questions=tuple(_domain_prompt(question) for question in prompt.questions),
+    )
+
+
+def _interaction_plan(state: WizardState, prompt: Prompt) -> InteractionPlan:
+    context = HostSessionContext(
+        host_id=state.host_runtime,
+        entry_mode=state.host_entry_mode,
+        available_functions=frozenset(state.available_functions),
+        interaction_surface="terminal",
+    )
+    adapter = default_host_registry().resolve(state.host_runtime)
+    return plan_prompt(_domain_prompt(prompt), context, adapter.interaction()).interaction
+
+
+def _interaction_payload(plan: InteractionPlan) -> dict[str, Any]:
+    return {
+        "kind": plan.kind,
+        "answerProtocol": {
+            "kind": plan.answer_protocol.kind,
+            "multi": plan.answer_protocol.multi,
+        },
+    }
+
+
+def _normalize_interaction_answer(
+    state: WizardState,
+    prompt: Prompt,
+    plan: InteractionPlan,
+    value: str,
+) -> str:
+    try:
+        return normalize_planned_answer(
+            _domain_prompt(prompt),
+            plan.answer_protocol,
+            value,
+        )
+    except WizardAnswerError as exc:
+        is_legacy_raw_answer = (
+            not state.available_functions
+            and "not an option" in str(exc)
+            and not (value or "").strip().isdecimal()
+        )
+        if is_legacy_raw_answer:
+            return value
+        raise WizardError(str(exc)) from exc
+
+
 def prompt_payload(state: WizardState, prompt: Prompt) -> dict[str, Any]:
     """Prompt JSON 에 진행 카운터를 덧붙인다. done/aborted 는 progress 를 생략."""
     out = prompt.to_json()
+    plan = _interaction_plan(state, prompt)
+    out["interaction"] = _interaction_payload(plan)
+    if plan.kind in {"numbered-single", "numbered-multi"}:
+        out["presentation"] = "numbered-text"
     if prompt.kind not in ("done", "aborted"):
         out["progress"] = _screen_progress(state)
     return out
@@ -4711,10 +4801,10 @@ def submit(state: WizardState, value: str) -> dict[str, Any]:
     prompt = next_prompt(state)
     if prompt.kind in ("done", "aborted"):
         return {"echo": "", "next": prompt_payload(state, prompt)}
+    plan = _interaction_plan(state, prompt)
+    value = _normalize_interaction_answer(state, prompt, plan, value)
     if prompt.kind == "pick_group":
         return _submit_group(state, prompt, value)
-    if prompt.kind == "pick" and len(prompt.options) > HOST_PICK_OPTION_CAP:
-        value = _normalize_numbered_pick_answer(prompt, value)
     step = STEP_BY_ID[prompt.step]
     echo = step.submit(state, value or "")
     if prompt.step not in state.answered:
@@ -5048,8 +5138,14 @@ def _cli(argv: list[str]) -> int:
     p_init.add_argument(
         "--host-runtime",
         default="claude-code",
-        choices=("claude-code", "codex", "antigravity", "external"),
+        choices=default_host_registry().ids(),
+    )
+    p_init.add_argument(
+        "--entry-mode",
+        default="current-session",
+        choices=("spawn-process", "current-session"),
     )
+    p_init.add_argument("--available-function", action="append", default=[])
     p_init.add_argument("--critic", default="")
 
     p_step = sub.add_parser("step")
@@ -5079,6 +5175,8 @@ def _cli(argv: list[str]) -> int:
             project_root=args.project_root,
             project_id=args.project_id,
             host_runtime=args.host_runtime,
+            host_entry_mode=args.entry_mode,
+            available_functions=args.available_function,
         )
         if args.critic:
             state.critic = args.critic

package/runtime/python/okstra_ctl/worker_audit_ledger.py

@@ -29,8 +29,13 @@ READING_CONFIRMATION_HEADING_RE = re.compile(
     r"^##[ \t]+0\.[ \t]+Reading Confirmation\b", re.MULTILINE
 )
 
+# The row's prefix opens it and the end of the line closes it, so the backticks
+# the template prescribes are decoration and are accepted either way. Requiring
+# them once cost a run: a worker wrote six correct paths bare, none of the rows
+# parsed, and every citation it made read as unbacked — a file it demonstrably
+# opened counted as unread over markdown punctuation.
 _EVIDENCE_READ_RE = re.compile(
-    r"^- Evidence read: `(?P<path>[^`\n]+)`\s*$",
+    r"^- Evidence read: `?(?P<path>[^`\n]+?)`?\s*$",
     re.MULTILINE,
 )
 _FILE_LINE_CITATION_RE = re.compile(
@@ -106,17 +111,37 @@ def _evidence_read_ledger_failures(
     except OSError as exc:
         return [f"worker audit sidecar unreadable: {audit_path.name} ({exc})"]
 
-    missing_paths = sorted(
-        _cited_file_paths(result_content) - _audit_evidence_read_paths(audit_content)
-    )
+    read_paths = _audit_evidence_read_paths(audit_content)
+    missing_paths = sorted(_cited_file_paths(result_content) - read_paths)
     return [
         f"worker `{worker_role}` result `{result_name}` cites "
         f"`{missing_path}:line` without an Evidence read row for "
         f"`{missing_path}` in `{audit_path.name}`"
+        + _ledger_path_hint(missing_path, read_paths)
         for missing_path in missing_paths
     ]
 
 
+def _ledger_path_hint(cited_path: str, read_paths: set[str]) -> str:
+    """What to cite instead, when the ledger plainly holds the same file.
+
+    A worker that cites the full path once and the bare filename afterwards
+    reads to this check as never having opened the file, and the bare failure
+    text sends the reader looking for a missing read that is not missing. One
+    unambiguous ledger row makes the remedy a rewritten citation; two rows
+    ending the same way make it a guess, so those say nothing.
+    """
+    if "/" in cited_path:
+        return ""
+    same_name = [path for path in read_paths if path.rsplit("/", 1)[-1] == cited_path]
+    if len(same_name) != 1:
+        return ""
+    return (
+        f" — the ledger records it as `{same_name[0]}`; cite that "
+        f"project-relative path, not the bare filename"
+    )
+
+
 def _result_files(run_dir: Path, task_type: str, seq: str | None, worker: str | None):
     """Every worker-results file in *run_dir* this check owns, in name order."""
     for path in sorted((run_dir / "worker-results").glob("*.md")):

package/runtime/python/okstra_token_usage/collect.py

@@ -22,7 +22,6 @@ from .antigravity import (
 from .paths import claude_project_dir, utc_now
 from .pricing import antigravity_cost_usd, provider_cost_usd
 from okstra_ctl.models import provider_wrappers
-from okstra_ctl.lead_runtime import ARTIFACT_ONLY_LEAD_RUNTIMES
 from okstra_ctl.wrapper_status import read_wrapper_status, status_path_for_prompt
 
 
@@ -758,19 +757,20 @@ def _populate_usage_summary(
     }
 
 
-def collect(team_state_path: Path, project_root: Path | None = None, *,
-            incremental: bool = True) -> dict:
+def collect_claude_runtime_usage(
+    team_state_path: Path,
+    project_root: Path | None = None,
+    *,
+    incremental: bool = True,
+) -> dict:
     # incremental: 세션 jsonl 스캔에 byte cursor 캐시 사용 (P6). 캐시는 윈도우
     # 적용 전 이벤트를 저장하므로 결과는 전체 스캔과 동일 — False 는 캐시 경로를
     # 완전히 우회하는 정확성 폴백(CLI --no-cache).
     state = json.loads(team_state_path.read_text())
     cwd = project_root or _infer_project_root(team_state_path, state)
     run_since, run_until = resolve_run_window(team_state_path, state)
-    task_key = state.get("taskKey", "")
     team_name = resolve_team_name(state)
     lead_sid = (state.get("lead") or {}).get("sessionId")
-    if state.get("leadRuntime") in ARTIFACT_ONLY_LEAD_RUNTIMES:
-        return _collect_cli_runtime_usage(state, cwd)
 
     # 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
@@ -936,6 +936,34 @@ def collect(team_state_path: Path, project_root: Path | None = None, *,
     return state
 
 
+def collect_cli_runtime_usage(
+    team_state_path: Path,
+    project_root: Path | None = None,
+    *,
+    incremental: bool = True,
+) -> dict:
+    state = json.loads(team_state_path.read_text())
+    cwd = project_root or _infer_project_root(team_state_path, state)
+    return _collect_cli_runtime_usage(state, cwd)
+
+
+def collect(
+    team_state_path: Path,
+    project_root: Path | None = None,
+    *,
+    incremental: bool = True,
+) -> dict:
+    from okstra_ctl.application.collect_usage import collect_usage
+    from okstra_ctl.ports.usage_accounting import UsageRequest
+    from okstra_ctl.registry.host_registry import default_host_registry
+
+    state = json.loads(team_state_path.read_text())
+    cwd = project_root or _infer_project_root(team_state_path, state)
+    adapter = default_host_registry().resolve(str(state.get("leadRuntime") or ""))
+    request = UsageRequest(team_state_path, cwd, incremental)
+    return collect_usage(request, adapter.usage_accounting()).payload
+
+
 def _infer_project_root(team_state_path: Path, state: dict) -> Path:
     rel = state.get("runDirectoryPath") or ""
     p = team_state_path.resolve().parent