okstra 0.195.4 → 0.196.0

package/docs/architecture.md

@@ -99,7 +99,7 @@ The host-native Okstra lead owns judgment policy and worker orchestration. okstr
 
 Canonical roles are `leader`, `analyser`, `critic`, `designer`, `planner`, `implementer`, `verifier`, `report-writer`, and `translator`. `lead` is a compatibility alias for `leader`. `executor` is a compatibility alias for `implementer`. New artifacts write only the canonical names.
 
-Selection is role-first: `--role-count <role>=<N>` creates `RoleInstance` ordinals, `--role-model <role>=<modelRef>` and `modelDefaults` feed `ModelPool`, and a pinned model is kept only when the host can bind it exactly. The resulting `RoleExecution` owns `Invocation` and `Attempt` rows plus the stored `executionLabel`. Pane titles use that label. Shared Git object stores and other-stage refs are observed-projection only; they are not an audit enforcement surface.
+Selection is role-first: `--role-count <role>=<N>` creates `RoleInstance` ordinals, `--role-model <role>=<modelRef>` and `modelDefaults` feed `ModelPool`, and a pinned model is kept only when the host can bind it exactly. The resulting `RoleExecution` owns `Invocation` and `Attempt` rows plus the stored `executionLabel`. Worker pane titles use that label. The lead's own cmux surface is titled `<task-group>/<task-id>` by `prepare_task_bundle` (`run.py` `_title_lead_pane`, cmux backend only): prepare runs in the lead's pane, so the calling surface from `cmux identify` is the lead's. A rename cmux refuses is a stderr line, not a failed prepare. Shared Git object stores and other-stage refs are observed-projection only; they are not an audit enforcement surface.
 
 ## Runtime assets vs support assets
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.195.4",
+  "version": "0.196.0",
   "description": "Host-aware multi-provider cross-verification orchestrator runtime and agent skills.",
   "license": "MIT",
   "author": "devonshin",

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.195.4",
-  "builtAt": "2026-09-09T19:01:57.276Z",
+  "package": "0.196.0",
+  "builtAt": "2026-09-09T20:48:12.483Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/python/okstra_ctl/adapters/providers/codex/adapter.py

@@ -93,7 +93,9 @@ class CodexExecution:
     """
 
     def build_command(self, request: WorkerExecRequest) -> ExecCommand:
-        argv = ["codex", "exec", "-C", str(request.project_root)]
+        # 출력은 파이프로 수집하므로 auto 는 색상을 끈다. 화면 표시와 기록의
+        # 색상 제거 여부는 공통 세션 기록기가 목적지에 맞춰 결정한다.
+        argv = ["codex", "exec", "--color", "always", "-C", str(request.project_root)]
         for directory in request.policy.write_scope:
             if directory != request.project_root:
                 argv += ["--add-dir", str(directory)]

package/runtime/python/okstra_ctl/cmux.py

@@ -421,7 +421,7 @@ def worker_command_line(
     """
     return (
         f"cd {shlex.quote(str(cwd))} && "
-        f"PATH={shlex.quote(path_value)} exec {shlex.join(argv)}"
+        f"PATH={shlex.quote(path_value)} FORCE_COLOR=1 exec {shlex.join(argv)}"
     )
 
 
@@ -456,7 +456,7 @@ def spawn_worker_surface(
     )
     target = _pane_by_id(panes, placement.pane_id)
     surface_uuid = _open_worker_surface(workspace, placement, target)
-    run_cmux(["rename-tab", "--surface", surface_uuid, "--title", title])
+    rename_surface(surface_uuid, title)
     _exec_worker(surface_uuid, cwd=cwd, command=command)
     owned = (*owned_surface_ids, surface_uuid)
     _size_lead_pane(workspace, owned)
@@ -464,6 +464,37 @@ def spawn_worker_surface(
     return surface_uuid
 
 
+def rename_surface(surface: str, title: str) -> subprocess.CompletedProcess[str]:
+    """Set the tab title cmux shows for one surface.
+
+    `surface` is a UUID for the worker surfaces okstra opened and a short ref
+    (`surface:N`) for the caller's own surface; cmux accepts both.
+    """
+    return run_cmux(["rename-tab", "--surface", surface, "--title", title])
+
+
+def rename_lead_surface(title: str) -> str:
+    """Title the surface this process runs in; "" on success, else the reason.
+
+    The lead is whatever pane invoked okstra, so the surface comes from
+    `identify` rather than from anything okstra recorded. A failure is returned
+    instead of raised: the title is a courtesy for the person watching the
+    workspace, and prepare has already written every manifest by the time it
+    is applied.
+    """
+    surface = identify_caller().get("surface_ref", "")
+    if not surface:
+        return "cmux could not identify the calling surface"
+    try:
+        result = rename_surface(surface, title)
+    except (OSError, subprocess.SubprocessError) as exc:
+        return f"cmux rename-tab failed: {exc}"
+    if result.returncode != 0:
+        detail = (result.stderr or result.stdout).strip() or f"exit {result.returncode}"
+        return f"cmux rename-tab failed: {detail}"
+    return ""
+
+
 def close_surface(surface_uuid: str) -> None:
     """Close an okstra-created surface, killing whatever still runs inside it."""
     try:

package/runtime/python/okstra_ctl/domain/worker_presentation.py

@@ -13,6 +13,7 @@ CLI 는 갈라 읽어야 한다.
 from __future__ import annotations
 
 import json
+import re
 from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any, Callable, Literal, Mapping, Protocol, runtime_checkable
@@ -34,6 +35,11 @@ ObserveServedModel = Callable[[Mapping[str, Any]], str | None]
 ObserveUsage = Callable[[Mapping[str, Any]], Mapping[str, Any] | None]
 
 WORKER = "worker"
+_TERMINAL_COLORS = re.compile(r"\x1b\[[0-9;:]*m")
+
+
+def strip_terminal_colors(text: str) -> str:
+    return _TERMINAL_COLORS.sub("", text)
 
 
 class TranscriptWriter(Protocol):
@@ -93,7 +99,7 @@ class SplitText:
     def sinks(self, writer: TranscriptWriter) -> tuple[SinkSpec, ...]:
         def result(line: str) -> str | None:
             writer.write(WORKER, line)
-            return line
+            return strip_terminal_colors(line)
 
         def progress(line: str) -> str | None:
             writer.write(WORKER, line)

package/runtime/python/okstra_ctl/run.py

@@ -4563,6 +4563,25 @@ def _resolve_terminal_backend(project_root: Path, inp: PrepareInputs) -> str:
     ) if part))
 
 
+def lead_pane_title(task_group: str, task_id: str) -> str:
+    """cmux 에서 리드 pane 에 붙는 제목. 사용자가 여러 task 의 pane 을 구분하는
+    이름이므로 slug 가 아니라 입력한 task-group / task-id 그대로 쓴다."""
+    return f"{task_group}/{task_id}"
+
+
+def _title_lead_pane(inp: PrepareInputs) -> None:
+    """리드 pane 제목을 `<task-group>/<task-id>` 로 바꾼다 (cmux 백엔드 전용).
+
+    prepare 는 리드 세션(또는 리드를 띄울 pane)에서 실행되므로 호출 surface 가
+    곧 리드 pane 이다. 제목은 화면 편의라 실패해도 run 을 막지 않지만, 무엇이
+    막았는지는 stderr 에 남긴다 — codex 샌드박스가 cmux 소켓을 EPERM 으로 막는
+    경우가 실제로 있다(`_resolve_terminal_backend` 참조).
+    """
+    reason = cmux.rename_lead_surface(lead_pane_title(inp.task_group, inp.task_id))
+    if reason:
+        print(f"okstra: lead pane title not applied — {reason}", file=sys.stderr)
+
+
 def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
     """Produce a complete okstra task bundle on disk. See module docstring."""
     workspace_root = Path(inp.workspace_root)
@@ -4872,6 +4891,9 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
 
     _record_run_in_central_index(inp, ctx, workspace_root, run_seq_override)
 
+    if terminal_backend == BACKEND_CMUX_PANE:
+        _title_lead_pane(inp)
+
     if not inp.render_only:
         _provision_settings_symlink(inp)
 

package/runtime/python/okstra_ctl/session_transcript.py

@@ -11,8 +11,9 @@ from datetime import datetime
 from pathlib import Path
 from typing import Callable
 
+from .domain.worker_presentation import strip_terminal_colors
+
 OKSTRA = "okstra"
-_SPEAKER_WIDTH = 14
 _RESET = "\x1b[0m"
 _MUTED = "\x1b[90m"
 _LIVE_COLORS = (
@@ -50,11 +51,20 @@ class SessionTranscript:
         path.parent.mkdir(parents=True, exist_ok=True)
         self._file = path.open("w", encoding="utf-8")
         self._live = live
+        # cmux 워커는 색상 사용을 명시한다. 리드에서 상속한 비대화형 출력
+        # 설정이 워커 터미널의 색상까지 끄지 않도록 명시적 요청을 우선한다.
+        force_color = os.environ.get("FORCE_COLOR", "")
         self._color = (
             live
             and sys.stdout.isatty()
-            and not os.environ.get("NO_COLOR")
-            and os.environ.get("TERM") != "dumb"
+            and (
+                force_color not in ("", "0")
+                or (
+                    force_color != "0"
+                    and not os.environ.get("NO_COLOR")
+                    and os.environ.get("TERM") != "dumb"
+                )
+            )
         )
         self._clock = clock
         self._archived = 0
@@ -89,9 +99,7 @@ class SessionTranscript:
             self._keep(self._row(speaker, line), capped=True)
 
     def _row(self, speaker: str, line: str) -> str:
-        # 패딩이 본문 앞 공백을 겸한다. 뒤에 공백을 한 칸 더 넣으면
-        # `[worker:grok]`(13칸) 줄이 두 칸이 되고 `[okstra]` 정렬이 깨진다.
-        label = f"[{speaker}]".ljust(_SPEAKER_WIDTH)
+        label = f"[{speaker}] "
         return f"{self._clock()} {label}{line}".rstrip()
 
     def _show(self, row: str, line: str) -> None:
@@ -110,7 +118,7 @@ class SessionTranscript:
                     f"{_MUTED}{row[:prefix_size]}{_RESET}"
                     f"{color}{row[prefix_size:]}{_RESET}"
                 )
-            print(row, flush=True)
+            print(row if self._color else strip_terminal_colors(row), flush=True)
 
     def _keep(self, row: str, *, capped: bool) -> None:
         if not capped:
@@ -136,7 +144,7 @@ class SessionTranscript:
         self._file.close()
 
     def _append(self, row: str) -> None:
-        self._file.write(row + "\n")
+        self._file.write(strip_terminal_colors(row) + "\n")
         self._file.flush()
 
     def _note_elision(self) -> None: