okstra 0.163.1 → 0.163.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.163.1",
+  "version": "0.163.2",
   "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.163.1",
-  "builtAt": "2026-08-09T08:20:00.790Z",
+  "package": "0.163.2",
+  "builtAt": "2026-08-09T12:57:56.931Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/python/okstra_ctl/cmux.py

@@ -14,7 +14,7 @@ import socket
 import subprocess
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Any, Sequence
+from typing import Any, Collection, Sequence
 
 PING_OK = "PONG"
 
@@ -165,15 +165,31 @@ class Placement:
 
 
 def plan_worker_placement(
-    panes: Sequence[PaneGeometry], *, lead_pane_id: str, min_columns: int
+    panes: Sequence[PaneGeometry],
+    *,
+    lead_pane_id: str,
+    owned_surface_ids: Collection[str],
+    min_columns: int,
 ) -> Placement:
     """Pick the next worker slot from the workspace's current geometry.
 
     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.
+
+    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.
     """
-    workers = [pane for pane in panes if pane.pane_id != lead_pane_id]
+    workers = [
+        pane
+        for pane in panes
+        if pane.pane_id != lead_pane_id
+        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)
 
@@ -196,6 +212,17 @@ def lead_shrink_points(lead: PaneGeometry, *, target_columns: int) -> int:
     return surplus * lead.cell_width_points
 
 
+def _holds_an_okstra_surface(
+    pane: PaneGeometry, owned_surface_ids: Collection[str]
+) -> 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.
+    """
+    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:
@@ -270,18 +297,30 @@ def list_panes(workspace: str) -> list[PaneGeometry]:
 
 
 def spawn_worker_surface(
-    *, workspace: str, cwd: Path, command: Sequence[str], title: str
+    *,
+    workspace: str,
+    cwd: Path,
+    command: Sequence[str],
+    title: str,
+    owned_surface_ids: Collection[str],
 ) -> str:
     """Start one worker beside the lead and return its surface UUID.
 
     The UUID is what okstra records and later closes by. Positional refs cannot
     serve that purpose: cmux renumbers them as surfaces open and close, so a
     close by ref can land on a pane okstra never created.
+
+    `owned_surface_ids` are the UUIDs earlier dispatches returned. They are what
+    keeps this placement inside okstra's own panes; the workspace belongs to the
+    user and may hold anything.
     """
     panes = list_panes(workspace)
     lead = _lead_pane(panes)
     placement = plan_worker_placement(
-        panes, lead_pane_id=lead.pane_id, min_columns=WORKER_MIN_COLUMNS
+        panes,
+        lead_pane_id=lead.pane_id,
+        owned_surface_ids=owned_surface_ids,
+        min_columns=WORKER_MIN_COLUMNS,
     )
     target = _pane_by_id(panes, placement.pane_id)
     surface_uuid = _open_worker_surface(workspace, placement, target)

package/runtime/python/okstra_ctl/dispatch_core.py

@@ -452,6 +452,7 @@ def _start_cmux_or_degrade(plan: DispatchPlan, job: WorkerJob) -> WorkerHandle:
             cwd=plan.project_root,
             command=job.command,
             title=f"{job.worker_id}-worker",
+            owned_surface_ids=_opened_cmux_surfaces(plan.team_state_path),
         )
     except (RuntimeError, OSError, subprocess.SubprocessError):
         return _run_cli_wrapper(plan, job, BACKEND_CMUX_PANE)
@@ -460,6 +461,28 @@ def _start_cmux_or_degrade(plan: DispatchPlan, job: WorkerJob) -> WorkerHandle:
     )
 
 
+def _opened_cmux_surfaces(team_state_path: Path) -> tuple[str, ...]:
+    """The surfaces this run has already opened in the user's cmux workspace.
+
+    Placement needs them to tell okstra's own panes from the rest of the
+    workspace, which belongs to the user and may hold another agent session or
+    a shell okstra must not split or stack into. A degraded dispatch opened no
+    surface and records an empty id, which would name no pane at all.
+    """
+    payload = _load_json_object(team_state_path, "team-state")
+    dispatches = payload.get("workerDispatches")
+    if not isinstance(dispatches, list):
+        return ()
+    opened = []
+    for record in dispatches:
+        if not isinstance(record, dict):
+            continue
+        surface_id = str(record.get("paneId", ""))
+        if surface_id:
+            opened.append(surface_id)
+    return tuple(opened)
+
+
 def _start_tmux_or_degrade(plan: DispatchPlan, job: WorkerJob) -> WorkerHandle:
     lead_pane = tmux.resolve_caller_pane()
     if not lead_pane: