feat(op): add a managed `new-pane` action #63

New issue

Closed

opened 2026-04-26 16:15:07 +00:00 by barrettruth · 0 comments

barrettruth commented

2026-04-26 16:15:07 +00:00

Problem

Mosaic has no explicit pane-creation command today. Users must rely on raw tmux split-window behavior and target syntax, which makes pane insertion layout-dependent and hard to reason about.

A conservative transient-pane policy also needs an explicit way to say:

this new pane belongs to Mosaic

Design

Add a top-level Mosaic operation:

#{E:@mosaic-exec} new-pane

This operation should create a pane, preserve the same shell/path defaults users expect from tmux, mark the new pane as owned by the current window, and then relayout using the window's current layout.

Required behavior

preserve #{pane_current_path} semantics
preserve tmux/default-shell behavior as closely as possible
return or capture the new pane id via split-window -P -F '#{pane_id}'
stamp the new pane with the current window generation so it is not treated as foreign
coordinate with after-split-window hook handling so Mosaic does not race with itself and misclassify its own new pane as foreign

Hook race handling

This issue must define a suppression mechanism for Mosaic-generated splits, for example a short-lived window-scoped token indicating:

this split originated from Mosaic
this window should not treat the next split hook as foreign-pane creation

The exact token shape is implementation-defined, but the flow must be robust enough that new-pane does not suspend the window or double-relayout.

Scope

This issue is about the core op plumbing.

It should add:

dispatcher support for new-pane
helper plumbing to create a pane and capture its pane id
ownership stamping for the new pane
hook suppression for Mosaic-originated splits

Layout-specific insertion semantics are tracked separately.

Non-goals

defining every layout's final insertion contract
adopting foreign panes already present in a suspended window
process-name heuristics

Acceptance criteria

new-pane exists as a top-level Mosaic op
it creates a pane using tmux shell/path defaults equivalent to normal splits
it captures the new pane id and stamps it as owned by the current window generation
it does not race with after-split-window and suspend the window
it relayouts exactly once after successful creation
tests prove the new pane is not seen as foreign after creation

Suggested implementation surface

scripts/ops.sh
scripts/helpers.sh
per-layout command dispatch glue
new integration tests for new-pane

## Problem Mosaic has no explicit pane-creation command today. Users must rely on raw tmux `split-window` behavior and target syntax, which makes pane insertion layout-dependent and hard to reason about. A conservative transient-pane policy also needs an explicit way to say: > this new pane belongs to Mosaic ## Design Add a top-level Mosaic operation: - `#{E:@mosaic-exec} new-pane` This operation should create a pane, preserve the same shell/path defaults users expect from tmux, mark the new pane as owned by the current window, and then relayout using the window's current layout. ### Required behavior - preserve `#{pane_current_path}` semantics - preserve tmux/default-shell behavior as closely as possible - return or capture the new pane id via `split-window -P -F '#{pane_id}'` - stamp the new pane with the current window generation so it is not treated as foreign - coordinate with `after-split-window` hook handling so Mosaic does not race with itself and misclassify its own new pane as foreign ### Hook race handling This issue must define a suppression mechanism for Mosaic-generated splits, for example a short-lived window-scoped token indicating: - this split originated from Mosaic - this window should not treat the next split hook as foreign-pane creation The exact token shape is implementation-defined, but the flow must be robust enough that `new-pane` does not suspend the window or double-relayout. ## Scope This issue is about the **core op plumbing**. It should add: - dispatcher support for `new-pane` - helper plumbing to create a pane and capture its pane id - ownership stamping for the new pane - hook suppression for Mosaic-originated splits Layout-specific insertion semantics are tracked separately. ## Non-goals - defining every layout's final insertion contract - adopting foreign panes already present in a suspended window - process-name heuristics ## Acceptance criteria - `new-pane` exists as a top-level Mosaic op - it creates a pane using tmux shell/path defaults equivalent to normal splits - it captures the new pane id and stamps it as owned by the current window generation - it does not race with `after-split-window` and suspend the window - it relayouts exactly once after successful creation - tests prove the new pane is not seen as foreign after creation ## Suggested implementation surface - `scripts/ops.sh` - `scripts/helpers.sh` - per-layout command dispatch glue - new integration tests for `new-pane`