okstra 0.180.0 → 0.183.2

package/runtime/python/okstra_ctl/cmux.py

@@ -32,9 +32,9 @@ SHIM_DIR_MARKER = "cmux-cli-shims"
 
 # The workspace is split in fifths: two for the lead, three for the workers.
 # Every worker lands in that one column and the column divides downward, so all
-# workers hold the same width and only one border — the lead's — is ever
-# computed. Splitting sideways instead would make each worker's width a
-# function of how many rounds preceded it.
+# workers hold the same width. Splitting sideways instead would make each
+# worker's width a function of how many rounds preceded it. The split itself
+# halves the pane it lands on; worker heights are evened out afterwards.
 LEAD_SHARE_WITH_WORKERS = 2 / 5
 
 # Three fifths is what a worker needs to be worth watching: measured against a
@@ -46,10 +46,9 @@ LEAD_SHARE_WITH_WORKERS = 2 / 5
 # whole workspace back rather than sitting at its working width.
 LEAD_SHARE_ALONE = 1.0
 
-# A floor for the dimension the worker column actually divides. A pane
-# this short still shows a command and its first lines of output; below it the
-# pane stops being a window onto the worker and the next one stacks as a tab.
-WORKER_MIN_ROWS = 20
+# Two passes per pane above the bottom. A roster of four analysers is four
+# workers in the column; eight moves is that bound with one extra pass.
+MAX_WORKER_HEIGHT_MOVES = 8
 
 # Sidebar entries are keyed by source so tools do not overwrite each other's.
 SIDEBAR_SOURCE = "okstra"
@@ -163,15 +162,29 @@ class PaneGeometry:
     width_points: float = 0.0
     ref: str = ""
     selected_surface_id: str = ""
+    height_points: float = 0.0
 
 
 @dataclass(frozen=True)
 class Placement:
-    """Where the next worker goes: split `pane_id`, or stack a tab into it."""
+    """Where the next worker goes: split `pane_id` in `direction`."""
 
     pane_id: str
     direction: str
-    stack_as_tab: bool
+
+
+@dataclass(frozen=True)
+class WorkerHeightResize:
+    """One vertical border move that equalizes the worker column.
+
+    `down` on a pane grows it into the neighbour below. `up` on a pane pulls
+    the shared border up, shrinking the neighbour above — the top pane has no
+    upper border, so shrinking it is the pane below's request.
+    """
+
+    pane_id: str
+    direction: str
+    amount: int
 
 
 def plan_worker_placement(
@@ -179,15 +192,14 @@ def plan_worker_placement(
     *,
     lead_pane_id: str,
     owned_surface_ids: Collection[str],
-    min_rows: int,
 ) -> Placement:
     """Pick the next worker slot from the workspace's current geometry.
 
     One column for every worker: the first split takes it off the lead, and each
-    one after that divides the column downward. Width is therefore decided once,
-    by where the lead's border sits, and every worker inherits it — nothing here
-    computes a width, and no worker's width depends on how many rounds ran
-    before it.
+    one after that divides the worker next to the lead downward. Width is
+    therefore decided once, by where the lead's border sits, and every worker
+    inherits it — nothing here computes a width, and no worker's width depends
+    on how many rounds ran before it.
 
     Stateless by design: okstra records surface UUIDs, never a layout, so a
     resumed or crashed run cannot carry a layout model that no longer matches
@@ -207,8 +219,8 @@ def plan_worker_placement(
         and _holds_an_okstra_surface(pane, owned_surface_ids)
     ]
     if not workers:
-        return Placement(pane_id=lead_pane_id, direction="right", stack_as_tab=False)
-    return _extend_the_worker_column(workers, min_rows=min_rows)
+        return Placement(pane_id=lead_pane_id, direction="right")
+    return _extend_the_worker_column(workers)
 
 
 def lead_target_width(
@@ -273,28 +285,52 @@ def _holds_an_okstra_surface(
 ) -> bool:
     """Whether okstra opened anything in this pane.
 
-    Any one recorded surface is enough: workers that stacked as tabs share a
-    pane, and only the tab that opened it carries the UUID okstra split on.
+    Any one recorded surface is enough: a pane may hold more than one surface,
+    and only one of those UUIDs has to be in the ledger.
     """
     return any(surface_id in owned_surface_ids for surface_id in pane.surface_ids)
 
 
-def _extend_the_worker_column(
-    workers: Sequence[PaneGeometry], *, min_rows: int
-) -> Placement:
-    """Divide the bottom worker, or stack when the halves would be unreadable.
+def _extend_the_worker_column(workers: Sequence[PaneGeometry]) -> Placement:
+    """Divide the worker next to the lead downward. A tab would hide the new worker.
+
+    The first worker is split off the lead, so it stays at the lead's y. Later
+    workers stack below it. Splitting the bottom one parks each new pane at the
+    far end of the column; splitting the neighbour keeps the new pane next to
+    the lead.
+    """
+    neighbour = min(workers, key=lambda pane: pane.y)
+    return Placement(pane_id=neighbour.pane_id, direction="down")
+
+
+def plan_worker_height_resize(
+    workers: Sequence[PaneGeometry],
+) -> WorkerHeightResize | None:
+    """The next vertical move that gives every worker an equal share of the column.
+
+    Only the first off-share pane above the bottom is reported. Growing or
+    shrinking it changes every pane below, so the caller re-reads and asks
+    again. The bottom pane is never the one named: it absorbs the remainder.
 
-    A split halves the pane it lands on, so the bottom pane's own height decides
-    whether the column can take another worker at all. Once it cannot, further
-    workers stack as tabs into the pane holding the fewest — a background tab is
-    worse than a visible pane, but better than two panes too short to show a
-    command and its first lines of output.
+    `new-split` halves the pane it lands on and does not take a ratio, so a
+    third worker split off the top would otherwise stay at a quarter while
+    the bottom one keeps a half.
     """
-    bottom = max(workers, key=lambda pane: pane.y)
-    if bottom.rows // 2 >= min_rows:
-        return Placement(pane_id=bottom.pane_id, direction="down", stack_as_tab=False)
-    roomiest = min(workers, key=lambda pane: (len(pane.surface_ids), pane.y))
-    return Placement(pane_id=roomiest.pane_id, direction="", stack_as_tab=True)
+    if len(workers) < 2:
+        return None
+    ordered = sorted(workers, key=lambda pane: pane.y)
+    total = sum(pane.height_points for pane in ordered)
+    if total <= 0:
+        return None
+    share = total / len(ordered)
+    for index, pane in enumerate(ordered[:-1]):
+        delta = round(pane.height_points - share)
+        if delta == 0:
+            continue
+        if delta < 0:
+            return WorkerHeightResize(pane.pane_id, "down", -delta)
+        return WorkerHeightResize(ordered[index + 1].pane_id, "up", delta)
+    return None
 
 
 def shim_free_login_path() -> str:
@@ -331,6 +367,17 @@ def worker_command_line(
     The `cd` is part of the command because neither `new-split` nor
     `respawn-pane` accepts a working directory the way `tmux split-window -c`
     does.
+
+    `exec` is here for termination, not for the pane's life, and removing it
+    does not keep a finished worker's pane on screen. Measured 2026-08-21: a
+    surface's life is bound to the command `respawn-pane` starts — cmux runs it
+    through `login … bash --noprofile --norc` and closes the surface when it
+    exits — and cmux's settings schema carries no option that keeps a surface
+    open past its process. Dropping `exec` was tried against a live dispatch and
+    the pane still went with the worker; what it changed was that
+    `close_surface` would kill an intermediate shell rather than the worker
+    itself. So the adapter contract's "finished workers leave their panes
+    behind" does not hold under cmux, and no edit to this line makes it hold.
     """
     return (
         f"cd {shlex.quote(str(cwd))} && "
@@ -366,13 +413,14 @@ def spawn_worker_surface(
         panes,
         lead_pane_id=lead.pane_id,
         owned_surface_ids=owned_surface_ids,
-        min_rows=WORKER_MIN_ROWS,
     )
     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])
     _exec_worker(surface_uuid, cwd=cwd, command=command)
-    _size_lead_pane(workspace, (*owned_surface_ids, surface_uuid))
+    owned = (*owned_surface_ids, surface_uuid)
+    _size_lead_pane(workspace, owned)
+    _equalize_worker_heights(workspace, owned)
     return surface_uuid
 
 
@@ -575,21 +623,16 @@ def open_surface_ids(workspace: str) -> set[str]:
 def _create_surface(
     workspace: str, placement: Placement, target: PaneGeometry
 ) -> None:
-    if placement.stack_as_tab:
-        created = run_cmux(
-            ["new-surface", "--workspace", workspace, "--pane", target.pane_id]
-        )
-    else:
-        created = run_cmux(
-            [
-                "new-split",
-                placement.direction,
-                "--workspace",
-                workspace,
-                "--surface",
-                target.selected_surface_id or target.surface_ids[0],
-            ]
-        )
+    created = run_cmux(
+        [
+            "new-split",
+            placement.direction,
+            "--workspace",
+            workspace,
+            "--surface",
+            target.selected_surface_id or target.surface_ids[0],
+        ]
+    )
     if created.returncode != 0:
         raise RuntimeError(created.stderr.strip() or "cmux could not open a pane")
 
@@ -606,9 +649,10 @@ def _exec_worker(surface_uuid: str, *, cwd: Path, command: Sequence[str]) -> Non
 def _size_lead_pane(workspace: str, owned_surface_ids: Collection[str]) -> None:
     """Move the lead's border to its share of the workspace.
 
-    This is the only border okstra places. Workers divide their column downward
-    and therefore all inherit whatever is left of it, so placing this one border
-    sizes every pane on screen.
+    This is the horizontal border okstra places. Workers divide their column
+    downward and inherit the remaining width, so this one move sizes the lead
+    and every worker's width. Worker heights are equalized separately after
+    the split that just halved one of them.
 
     Which pane carries the request follows from what `pane.resize` does: it
     moves the named pane's own border in the direction given. The lead can push
@@ -659,6 +703,39 @@ def _size_lead_pane(workspace: str, owned_surface_ids: Collection[str]) -> None:
     )
 
 
+def _equalize_worker_heights(
+    workspace: str, owned_surface_ids: Collection[str]
+) -> None:
+    """Give every owned worker the same height in the column.
+
+    `new-split` halves whichever pane it lands on, so the third worker of a
+    round would otherwise sit at a quarter with the bottom one still at a half.
+    Each call moves one border and re-reads: growing the top pane steals from
+    the one below, and that is what the next plan has to see.
+    """
+    for _ in range(MAX_WORKER_HEIGHT_MOVES):
+        panes = list_panes(workspace)
+        lead = _lead_pane(panes)
+        workers = [
+            pane
+            for pane in panes
+            if pane.pane_id != lead.pane_id
+            and _holds_an_okstra_surface(pane, owned_surface_ids)
+        ]
+        move = plan_worker_height_resize(workers)
+        if move is None:
+            return
+        rpc(
+            "pane.resize",
+            {
+                "workspace_id": workspace,
+                "pane_id": move.pane_id,
+                "direction": move.direction,
+                "amount": move.amount,
+            },
+        )
+
+
 def _lead_pane(panes: Sequence[PaneGeometry]) -> PaneGeometry:
     caller_pane_ref = identify_caller().get("pane_ref", "")
     for pane in panes:
@@ -706,6 +783,7 @@ def _pane_geometry(entry: dict[str, Any]) -> PaneGeometry:
         width_points=float(frame.get("width") or 0),
         ref=str(entry.get("ref", "")),
         selected_surface_id=str(entry.get("selected_surface_id", "")),
+        height_points=float(frame.get("height") or 0),
     )
 
 

package/runtime/python/okstra_ctl/code_review_target.py

@@ -24,6 +24,7 @@ from okstra_project import (
 )
 
 from .code_review_paths import branch_review_dir, next_branch_review
+from .fixed_text import line
 
 DEFAULT_BRANCH_CANDIDATES = ("main", "master")
 
@@ -105,7 +106,9 @@ def _build_parser() -> argparse.ArgumentParser:
     parser.add_argument("--date", default="", help="YYYY-MM-DD for branch result naming")
     parser.add_argument("--project-root", default="", help="explicit project root")
     parser.add_argument("--cwd", default=".", help="cwd for project root resolution")
-    parser.add_argument("--json", action="store_true", help="emit JSON (always on)")
+    output = parser.add_mutually_exclusive_group()
+    output.add_argument("--json", action="store_true", help="emit JSON (default)")
+    output.add_argument("--text", action="store_true", help="emit fixed text fields")
     return parser
 
 
@@ -121,6 +124,25 @@ def _resolve(args: argparse.Namespace, project_root: Path) -> dict:
     raise StateError("pass either --task-key --stage or --branch", stage="args")
 
 
+def render_code_review_target_text(payload: dict) -> str:
+    """모델이 소비할 리뷰 범위와 결과 경로만 고정 줄로 투영한다."""
+    rows = ["Okstra code review target\n"]
+    rows.append(line("Status", "ready" if payload.get("ok") else "error"))
+    fields = (
+        ("Project root", "projectRoot"), ("Mode", "mode"),
+        ("Worktree path", "worktreePath"), ("Branch", "branch"),
+        ("Base commit", "baseCommit"), ("Head commit", "headCommit"),
+        ("Review path", "reviewPath"), ("Round", "round"),
+        ("Task key", "taskKey"), ("Task root", "taskRoot"), ("Stage", "stage"),
+        ("Failure stage", "stage"), ("Failure reason", "reason"),
+    )
+    for label, key in fields:
+        failure_field = label.startswith("Failure")
+        if key in payload and failure_field != bool(payload.get("ok")):
+            rows.append(line(label, payload.get(key)))
+    return "".join(rows)
+
+
 def main(argv: list[str] | None = None) -> int:
     args = _build_parser().parse_args(argv)
     try:
@@ -128,23 +150,27 @@ def main(argv: list[str] | None = None) -> int:
             explicit_root=args.project_root, cwd=args.cwd
         )
     except ResolverError as exc:
-        print(json.dumps({"ok": False, "stage": "resolve", "reason": str(exc)}))
+        payload = {"ok": False, "stage": "resolve", "reason": str(exc)}
+        print(render_code_review_target_text(payload) if args.text else json.dumps(payload))
         return 2
 
     try:
         snapshot = _resolve(args, Path(project_root))
     except StateError as exc:
-        print(json.dumps({
+        payload = {
             "ok": False,
             "stage": exc.stage or "target",
             "reason": str(exc),
-        }))
+        }
+        print(render_code_review_target_text(payload) if args.text else json.dumps(payload))
         return 1
 
-    print(json.dumps(
-        {"ok": True, "projectRoot": str(project_root), **snapshot},
-        ensure_ascii=False, indent=2,
-    ))
+    payload = {"ok": True, "projectRoot": str(project_root), **snapshot}
+    print(
+        render_code_review_target_text(payload)
+        if args.text
+        else json.dumps(payload, ensure_ascii=False, indent=2)
+    )
     return 0
 
 

package/runtime/python/okstra_ctl/consumers.py

@@ -16,6 +16,8 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import Any, Dict, List, Optional
 
+from .json_boundary import JsonBoundaryError, load_owned_object
+from .jsonl import append_jsonl
 from .run_context import consumers_mutex
 
 CONSUMERS_FILENAME = "consumers.jsonl"
@@ -265,8 +267,7 @@ def _release_stage_occupancy_keeping_branch(
 
 
 def _append_row(plan_run_root: Path, record: Dict[str, Any]) -> None:
-    with _path(plan_run_root).open("a", encoding="utf-8") as f:
-        f.write(json.dumps(record, ensure_ascii=False) + "\n")
+    append_jsonl(_path(plan_run_root), record, ensure_ascii=False, compact=False)
 
 
 def append_verified(plan_run_root: Path, *, impl_task_key: str, stage: int,
@@ -414,8 +415,8 @@ def backfill_done_from_carry(plan_run_root: Path) -> int:
     recovered = 0
     for cf in sorted(carry_dir.glob("stage-*.json")):
         try:
-            carry = json.loads(cf.read_text(encoding="utf-8"))
-        except (json.JSONDecodeError, OSError):
+            carry = load_owned_object(cf, artifact="implementation stage carry")
+        except (JsonBoundaryError, OSError):
             continue
         if not isinstance(carry, dict):
             continue

package/runtime/python/okstra_ctl/container.py

@@ -28,6 +28,8 @@ from typing import Callable, Iterable
 
 from .stage_targets import PrepareError  # 단일 PrepareError 타입 재노출(run.py 와 공유)
 from .stage_map import StageMapError, parse_stage_map_file, stage_map_records
+from .json_boundary import JsonBoundaryError, load_owned_object, write_owned_object_atomic
+from .fixed_text import line
 
 OKSTRA_LABEL_KEYS = ("okstra.task-key", "okstra.project-name", "okstra.run-trace")
 
@@ -426,13 +428,19 @@ def query_containers_by_label(project_name: str) -> list[dict]:
     out = _docker_run([
         "docker", "ps", "-a", "--filter",
         f"label=okstra.project-name={project_name}",
-        "--format", "{{.ID}}\t{{.Names}}\t{{.State}}",
+        "--format", (
+            "{{.ID}}\t{{.Names}}\t{{.State}}\t"
+            '{{.Label "com.docker.compose.service"}}\t{{.Ports}}'
+        ),
     ])
     rows: list[dict] = []
     for line in out.splitlines():
         parts = line.split("\t")
-        if len(parts) >= 3:
-            rows.append({"id": parts[0], "name": parts[1], "state": parts[2]})
+        if len(parts) >= 5:
+            rows.append({
+                "id": parts[0], "name": parts[1], "state": parts[2],
+                "service": parts[3], "ports": parts[4],
+            })
     return rows
 
 
@@ -774,8 +782,7 @@ def _spawn_service_panes(
 
 def _write_deploy_state(cp: dict, **state) -> None:
     cp["container_dir"].mkdir(parents=True, exist_ok=True)
-    cp["deploy_state"].write_text(
-        json.dumps(state, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+    write_owned_object_atomic(cp["deploy_state"], state, artifact="container deploy state")
 
 
 # --------------------------------------------------------------------------- #
@@ -879,8 +886,10 @@ def _read_project_id(project_json: Path) -> str:
     if not project_json.is_file():
         return ""
     try:
-        return json.loads(project_json.read_text(encoding="utf-8")).get("projectId", "")
-    except (OSError, json.JSONDecodeError):
+        return load_owned_object(project_json, artifact="project configuration").get(
+            "projectId", ""
+        )
+    except JsonBoundaryError:
         return ""
 
 
@@ -928,6 +937,7 @@ def main(argv: list[str] | None = None) -> int:
         sp = sub.add_parser(name)
         sp.add_argument("--project-root", required=True)
         sp.add_argument("--task-key", default="")
+        sp.add_argument("--text", action="store_true")
         if name == "down":
             sp.add_argument("--all", action="store_true")
         if name == "logs":
@@ -944,10 +954,95 @@ def main(argv: list[str] | None = None) -> int:
             findings_path=args.findings, scan_interval_seconds=args.scan_interval)
         return 0
     result = _dispatch(args)
-    print(json.dumps(result, ensure_ascii=False, indent=2))
+    print(
+        render_container_text(args.command, result)
+        if args.text
+        else json.dumps(result, ensure_ascii=False, indent=2)
+    )
     return 0
 
 
+def render_container_text(command: str, payload: dict) -> str:
+    """container 명령별 승인된 상태만 고정 순서로 투영한다."""
+    if command not in {"up", "status", "logs", "stop-watcher", "down"}:
+        raise ValueError("unknown container text purpose")
+    rows = [f"Okstra container {command}\n", line("Status", "ready")]
+    for label, key in (("Project name", "projectName"), ("Watchers dir", "watchersDir"),
+                       ("Note", "note")):
+        if key in payload:
+            rows.append(line(label, payload.get(key)))
+    if command == "up":
+        rows.extend(_render_container_up(payload))
+    elif command in {"status", "logs"}:
+        rows.extend(_render_container_watchers(payload))
+        if command == "status":
+            rows.extend(_render_container_status(payload))
+    elif command == "stop-watcher":
+        rows.extend(_render_reaped_panes("Reaped pane", payload.get("reapedPanes")))
+    else:
+        rows.extend(_render_container_down(payload))
+    return "".join(rows)
+
+
+def _render_container_up(payload: dict) -> list[str]:
+    rows: list[str] = []
+    for index, service in enumerate(payload.get("services") or [], 1):
+        rows.append(line(f"Service {index} name", service))
+    for index, warning in enumerate(payload.get("warnings") or [], 1):
+        rows.append(line(f"Warning {index} text", warning))
+    watch = payload.get("watch") if isinstance(payload.get("watch"), dict) else {}
+    for label, key in (("Watcher enabled", "enabled"), ("Watcher session", "session"),
+                       ("Watcher note", "note")):
+        if key in watch:
+            rows.append(line(label, watch.get(key)))
+    for index, service in enumerate(watch.get("services") or [], 1):
+        rows.append(line(f"Watcher service {index} name", service))
+    return rows
+
+
+def _render_container_watchers(payload: dict) -> list[str]:
+    watchers = payload.get("watchers") if isinstance(payload.get("watchers"), dict) else {}
+    rows: list[str] = []
+    for index, (service, metadata) in enumerate(sorted(watchers.items()), 1):
+        rows.append(line(f"Watcher {index} service", service))
+        values = metadata if isinstance(metadata, dict) else {}
+        for label, key in (("pane ID", "paneId"), ("session", "sessionName"),
+                           ("findings path", "findingsPath")):
+            if key in values:
+                rows.append(line(f"Watcher {index} {label}", values.get(key)))
+    return rows
+
+
+def _render_container_status(payload: dict) -> list[str]:
+    containers = payload.get("containers") if isinstance(payload.get("containers"), list) else []
+    rows: list[str] = []
+    for index, item in enumerate(containers, 1):
+        values = item if isinstance(item, dict) else {}
+        for label, key in (("name", "name"), ("service", "service"), ("state", "state"),
+                           ("status", "status"), ("ports", "ports")):
+            if key in values:
+                rows.append(line(f"Container {index} {label}", values.get(key)))
+    return rows
+
+
+def _render_reaped_panes(prefix: str, raw_panes: object) -> list[str]:
+    panes = raw_panes if isinstance(raw_panes, list) else []
+    return [line(f"{prefix} {index}", pane) for index, pane in enumerate(panes, 1)]
+
+
+def _render_container_down(payload: dict) -> list[str]:
+    downed = payload.get("downed") if isinstance(payload.get("downed"), list) else []
+    rows: list[str] = []
+    for index, item in enumerate(downed, 1):
+        values = item if isinstance(item, dict) else {}
+        rows.append(line(f"Downed {index} project name", values.get("projectName")))
+        rows.extend(_render_reaped_panes(
+            f"Downed {index} reaped pane", values.get("reapedPanes")
+        ))
+    rows.extend(_render_reaped_panes("Orphan pane", payload.get("orphanPanesReaped")))
+    return rows
+
+
 def _dispatch(args) -> dict:
     pr = args.project_root
     if args.command == "up":

package/runtime/python/okstra_ctl/context_cost.py

@@ -15,6 +15,7 @@ from typing import Iterable
 
 from okstra_ctl.paths import RunRef, runs_dir_of, task_manifest_file
 from okstra_ctl.task_target import resolve_task_root, project_rel
+from okstra_ctl.json_boundary import load_owned_object
 
 
 INPUT_FILES = (
@@ -83,7 +84,7 @@ def _load_json(path: Path) -> dict:
     if not path.is_file():
         return {}
     try:
-        data = json.loads(path.read_text(encoding="utf-8"))
+        data = load_owned_object(path, artifact="context cost input")
     except Exception:
         return {}
     return data if isinstance(data, dict) else {}