okstra 0.170.3 → 0.171.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.170.3",
+  "version": "0.171.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.170.3",
-  "builtAt": "2026-08-14T18:24:32.087Z",
+  "package": "0.171.0",
+  "builtAt": "2026-08-15T08:20:00.683Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/python/okstra_ctl/cmux.py

@@ -30,17 +30,26 @@ LOGIN_SHELL_TIMEOUT_SECONDS = 15
 # re-enters cmux's own agent wrapper instead of the real CLI.
 SHIM_DIR_MARKER = "cmux-cli-shims"
 
-# Workers fill two columns and then grow downward. A third column would cost
-# width, and width is the dimension a horizontal split cannot give back.
-GRID_COLUMNS = 2
-
-# Measured against a Claude Code worker: 67 columns renders losslessly, 33 drops
-# content off the right edge. Below this floor okstra stacks a tab instead of
-# splitting, because an unreadable pane costs the lead its view of that worker.
-WORKER_MIN_COLUMNS = 60
-
-# What the lead keeps for itself once workers arrive.
-LEAD_TARGET_COLUMNS = 80
+# 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.
+LEAD_SHARE_WITH_WORKERS = 2 / 5
+
+# Three fifths is what a worker needs to be worth watching: measured against a
+# Claude Code worker, 67 columns renders losslessly and 33 drops content off the
+# right edge, and three fifths clears 67 on any window wide enough to hold two
+# panes at all.
+#
+# With no workers on screen the lead has nothing to share with, so it takes the
+# 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
 
 # Sidebar entries are keyed by source so tools do not overwrite each other's.
 SIDEBAR_SOURCE = "okstra"
@@ -151,6 +160,7 @@ class PaneGeometry:
     x: int
     y: int
     cell_width_points: int
+    width_points: float = 0.0
     ref: str = ""
     selected_surface_id: str = ""
 
@@ -169,10 +179,16 @@ def plan_worker_placement(
     *,
     lead_pane_id: str,
     owned_surface_ids: Collection[str],
-    min_columns: int,
+    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.
+
     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
     the screen. Every dispatch re-reads the panes and derives the next slot.
@@ -180,9 +196,9 @@ def plan_worker_placement(
     Those same UUIDs say which panes okstra may place into. A workspace also
     holds panes okstra never opened — another agent session, a shell the user
     keeps around — and "not the lead" does not make a pane a worker slot. Taken
-    as one, a stranger's pane is split or, when it is too narrow to split,
-    stacked into: the workers land as background tabs in someone else's window,
-    so nothing appears on screen and that window grows tabs it did not ask for.
+    as one, a stranger's pane is split or stacked into: the workers land as
+    background tabs in someone else's window, so nothing appears on screen and
+    that window grows tabs it did not ask for.
     """
     workers = [
         pane
@@ -192,14 +208,48 @@ def plan_worker_placement(
     ]
     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)
 
-    columns = _panes_by_column(workers)
-    if len(columns) < GRID_COLUMNS:
-        return _widen_the_grid(workers, min_columns=min_columns)
-    return _extend_the_shortest_column(columns)
+
+def lead_target_width(
+    panes: Sequence[PaneGeometry],
+    *,
+    lead_pane_id: str,
+    owned_surface_ids: Collection[str],
+    container_width_points: float,
+) -> float:
+    """How wide the lead should be, in the points `pixel_frame` reports.
+
+    Two fifths while workers are on screen, all of it when they are gone. The
+    share is taken of what okstra may actually place into, not of the window:
+    a workspace can hold panes okstra never opened, and handing the lead the
+    whole container would shove those off their own width. Their width is
+    subtracted first and the share applies to the remainder.
+
+    Deriving the target from the container rather than from a fixed column count
+    is what keeps the split honest at any window size — a hardcoded 80 columns
+    is two fifths of one particular display and an arbitrary slice of every
+    other.
+    """
+    strangers = sum(
+        pane.width_points
+        for pane in panes
+        if pane.pane_id != lead_pane_id
+        and not _holds_an_okstra_surface(pane, owned_surface_ids)
+    )
+    usable = container_width_points - strangers
+    if usable <= 0:
+        return 0.0
+    workers_on_screen = any(
+        pane.pane_id != lead_pane_id
+        and _holds_an_okstra_surface(pane, owned_surface_ids)
+        for pane in panes
+    )
+    share = LEAD_SHARE_WITH_WORKERS if workers_on_screen else LEAD_SHARE_ALONE
+    return usable * share
 
 
-def lead_resize_points(lead: PaneGeometry, *, target_columns: int) -> int:
+def lead_resize_points(lead: PaneGeometry, *, target_width_points: float) -> int:
     """How far to move the lead's right border, in the points `pane.resize` takes.
 
     Signed: positive when the lead is too wide and the border comes in, negative
@@ -208,14 +258,14 @@ def lead_resize_points(lead: PaneGeometry, *, target_columns: int) -> int:
     Both directions are needed. A split halves whatever pane it lands on, and
     the first worker of every round lands on the lead — so a rule that only ever
     shrinks leaves that half permanent, and the round after it takes half of
-    what is left. Measured on this display: 215 columns becomes 80, then 40,
-    then 20, until neither the lead nor its workers can be read.
+    what is left. Measured on this display: 215 columns becomes 107, then 53,
+    then 26, until neither the lead nor its workers can be read.
 
-    The API's `amount` is points, not cells — measured at this pane's own
-    `cell_width_points`, so passing a column count moves the border by an eighth
-    of the intent on a typical display.
+    Measured in the same points `pixel_frame` reports, so no cell-size
+    conversion happens here at all. A column count would need one, and would
+    round the target to a whole cell before the border ever moved.
     """
-    return (lead.columns - target_columns) * lead.cell_width_points
+    return round(lead.width_points - target_width_points)
 
 
 def _holds_an_okstra_surface(
@@ -229,31 +279,22 @@ def _holds_an_okstra_surface(
     return any(surface_id in owned_surface_ids for surface_id in pane.surface_ids)
 
 
-def _widen_the_grid(
-    workers: Sequence[PaneGeometry], *, min_columns: int
-) -> Placement:
-    rightmost = max(workers, key=lambda pane: pane.x)
-    if rightmost.columns // GRID_COLUMNS >= min_columns:
-        return Placement(pane_id=rightmost.pane_id, direction="right", stack_as_tab=False)
-    roomiest = min(workers, key=lambda pane: (len(pane.surface_ids), pane.x))
-    return Placement(pane_id=roomiest.pane_id, direction="", stack_as_tab=True)
-
-
-def _extend_the_shortest_column(
-    columns: dict[int, list[PaneGeometry]]
+def _extend_the_worker_column(
+    workers: Sequence[PaneGeometry], *, min_rows: int
 ) -> Placement:
-    shortest = min(columns.values(), key=lambda group: (len(group), group[0].x))
-    bottom = max(shortest, key=lambda pane: pane.y)
-    return Placement(pane_id=bottom.pane_id, direction="down", stack_as_tab=False)
+    """Divide the bottom worker, or stack when the halves would be unreadable.
 
-
-def _panes_by_column(
-    workers: Sequence[PaneGeometry],
-) -> dict[int, list[PaneGeometry]]:
-    columns: dict[int, list[PaneGeometry]] = {}
-    for pane in workers:
-        columns.setdefault(pane.x, []).append(pane)
-    return columns
+    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.
+    """
+    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)
 
 
 def shim_free_login_path() -> str:
@@ -298,8 +339,7 @@ def worker_command_line(
 
 
 def list_panes(workspace: str) -> list[PaneGeometry]:
-    payload = rpc("pane.list", {"workspace_id": workspace})
-    return [_pane_geometry(entry) for entry in payload.get("panes", [])]
+    return _panes_from(_pane_list_payload(workspace))
 
 
 def spawn_worker_surface(
@@ -326,13 +366,13 @@ def spawn_worker_surface(
         panes,
         lead_pane_id=lead.pane_id,
         owned_surface_ids=owned_surface_ids,
-        min_columns=WORKER_MIN_COLUMNS,
+        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)
+    _size_lead_pane(workspace, (*owned_surface_ids, surface_uuid))
     return surface_uuid
 
 
@@ -358,11 +398,17 @@ def restore_lead_width() -> None:
     holds a run manifest rather than the workspace UUID that `pane.resize`
     needs. An unresolvable workspace means cmux is gone or was never there, and
     there is no pane left to size.
+
+    Owning nothing is the point of the empty ledger. Teardown has just closed
+    every surface it opened, so no pane on screen is okstra's but the lead's —
+    which is what makes the lead's share the whole workspace. A pane teardown
+    failed to close counts as a stranger's and keeps its width, which is the
+    safe way to be wrong here.
     """
     workspace = resolve_lead_workspace()
     if not workspace:
         return
-    _size_lead_pane(workspace)
+    _size_lead_pane(workspace, ())
 
 
 def capture_surface(surface_uuid: str, *, last_lines: int = 200) -> str:
@@ -557,8 +603,12 @@ def _exec_worker(surface_uuid: str, *, cwd: Path, command: Sequence[str]) -> Non
         raise RuntimeError(started.stderr.strip() or "cmux could not start the worker")
 
 
-def _size_lead_pane(workspace: str) -> None:
-    """Put the lead back on its target width, leaving the rest to the workers.
+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.
 
     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
@@ -568,11 +618,26 @@ def _size_lead_pane(workspace: str) -> None:
     and widening is the lead's.
 
     Run after every worker opens rather than once per round: the split that just
-    happened is what knocked the lead off its width, and no other event does.
+    happened is what knocked the lead off its share, and no other event does.
     """
-    panes = list_panes(workspace)
+    payload = _pane_list_payload(workspace)
+    container_width = _container_width_points(payload)
+    if container_width <= 0:
+        # Without the frame the shares are taken of, there is no target to move
+        # toward — and a guessed one would move the border to a wrong place
+        # rather than leave it where the user last saw it.
+        return
+    panes = _panes_from(payload)
     lead = _lead_pane(panes)
-    offset = lead_resize_points(lead, target_columns=LEAD_TARGET_COLUMNS)
+    offset = lead_resize_points(
+        lead,
+        target_width_points=lead_target_width(
+            panes,
+            lead_pane_id=lead.pane_id,
+            owned_surface_ids=owned_surface_ids,
+            container_width_points=container_width,
+        ),
+    )
     if offset == 0:
         return
     neighbours = [pane for pane in panes if pane.x > lead.x]
@@ -609,6 +674,25 @@ def _pane_by_id(panes: Sequence[PaneGeometry], pane_id: str) -> PaneGeometry:
     raise RuntimeError(f"cmux pane {pane_id} disappeared while placing a worker")
 
 
+def _pane_list_payload(workspace: str) -> dict[str, Any]:
+    return rpc("pane.list", {"workspace_id": workspace})
+
+
+def _panes_from(payload: dict[str, Any]) -> list[PaneGeometry]:
+    return [_pane_geometry(entry) for entry in payload.get("panes", [])]
+
+
+def _container_width_points(payload: dict[str, Any]) -> float:
+    """The workspace's own width, which every share here is taken of.
+
+    Reported once per `pane.list` reply rather than per pane, because it is the
+    frame the panes are laid out inside — summing the panes would instead give
+    whatever they currently happen to occupy.
+    """
+    frame = payload.get("container_frame") or {}
+    return float(frame.get("width") or 0)
+
+
 def _pane_geometry(entry: dict[str, Any]) -> PaneGeometry:
     frame = entry.get("pixel_frame") or {}
     return PaneGeometry(
@@ -619,6 +703,7 @@ def _pane_geometry(entry: dict[str, Any]) -> PaneGeometry:
         x=int(frame.get("x", 0)),
         y=int(frame.get("y", 0)),
         cell_width_points=int(entry.get("cell_width_points", 0)),
+        width_points=float(frame.get("width") or 0),
         ref=str(entry.get("ref", "")),
         selected_surface_id=str(entry.get("selected_surface_id", "")),
     )