ace-tmux 0.14.3 → 0.17.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 42e752d75968cab4e3af63e513247dd29b626e28f1ac0c88847c7fe036726df4
-  data.tar.gz: 9b4aad5052e103fe757001d03d487cb221d4af0c989af41097c11d3db4cad1ea
+  metadata.gz: c4edb05780dda3c73b507989856230c358bc6b94be33bc27e34a71f0bd1a7d79
+  data.tar.gz: 679f06b6a332dbb3237c7383a6d61c665fd0bf65934a668ddc13fa1d46d86cfc
 SHA512:
-  metadata.gz: 2f5de2adedeccbc4acb9cb1d876ececc32be10255b967daf764888b484d4af5fe02f26662f5979fc8978f0766f62f24faf0c32bb6915aeee3b42094235a3b001
-  data.tar.gz: d1b4c69d036364e760299cde7ac47a3540d7889e51b4e053683d4b18e75afe39813bfdda22fbb30e5c4294153200006899b8f6e141fe58f3bbc2d1dc35e3a7a0
+  metadata.gz: 68d7a486f473d1095be471419db504421d53fa797ebaf7588c0273da6edb0c48bc24c050040662ab30941e253196343807f8db61997487d7ebbb555daa6474d5
+  data.tar.gz: da33e7b0921b5a0033827bee7aa1a9c40c3422d82591435f61e336bc61bb82d035029236c28b20e3bafa3ff2cf1a147d79758bcd71496c429a1f32945ca5a77f

data/CHANGELOG.md

@@ -7,6 +7,64 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.17.2] - 2026-04-24
+
+### Changed
+- Clarified usage docs to treat speculative shared read-side follow-up as closed for now, so any future tmux inspectability expansion must start as a new task rather than reopening the archived `8r6.t.xeu` task family.
+
+### Fixed
+- Clarified usage docs to treat `ace-tmux list` as the shipped read-side runtime inventory baseline and removed stale `ace-tmux state` references from capture and boundary notes.
+
+## [0.17.1] - 2026-04-24
+
+## [0.17.0] - 2026-04-16
+
+### Added
+- Added a shared tmux runtime control surface with public `ace-tmux send`, `capture`, `wait`, `attach`, and `detach` commands.
+- Added `send --wait` plus a new `agent` wait condition so interactive CLI panes, including shell-wrapped Codex/Claude/pi launches, can accept a prompt, block until the visible response settles, and then capture the final same-pane screen tail in one command.
+
+### Changed
+- Added runtime target resolution, bounded named-key validation, and the v1 tmux wait-condition set for ACE-managed live control flows.
+- Reworked `ace-tmux send` around `--cmd`, repeatable `--msg` / `--key`, and inline `--capture` output so one call can submit pane input and immediately tail feedback.
+- Split preset discovery from runtime inspection: `ace-tmux --list-presets [TYPE]` now lists preset names, while `ace-tmux list` inspects live tmux panes in the current window by default and supports `--all-panes`, `--windows`, and `--sessions`.
+- Tightened `ace-tmux send --wait output` so it matches post-send output instead of succeeding on stale visible text, and added `ace-tmux wait --lines` to control the observed pane tail.
+- Expanded README, CLI help, docs, demo tape, and retained E2E coverage to document the control-side contract and the `--list-presets` plus runtime `list` split.
+
+### Fixed
+- Qualified the default shared-control executor path so public `ace-tmux` control commands construct correctly without injected dependencies.
+- Restored detached explicit-session active-window fallback so `ACE_TMUX_SESSION` launches can still resolve the current window outside a live tmux client.
+- Validate `ace-tmux` pane targets before dispatch so invalid `session:window:pane` input now returns a corrective error that points users to `%pane_id`, `session:window.pane`, `.pane`, or `--window ... --pane ...`.
+- Bound `capture-pane` with `-E -1` so `ace-tmux capture --lines N` and `ace-tmux send --capture N` return the last `N` visible pane rows instead of an oversized scrollback slice.
+- Resolve pane shorthands through stable tmux window ids so `.pane`, bare pane indexes, and dotted window names like `ace-t.n1d` target the intended pane instead of producing invalid pane targets.
+- Pace the first submit `Enter` for interactive CLI panes such as `codex`, `claude`, and `pi`, and capture their visible bottom screen rows so sends submit reliably and `--capture` reflects the current TUI screen instead of stale scrollback.
+- `ace-tmux wait --for pane-exited` now succeeds when the pane disappears entirely instead of timing out on missing-pane targets.
+- `ace-tmux detach` now reports the resolved target session name, even when the session came from ACE env vars or live tmux context.
+
+### Technical
+- Added optional `split-window -P -F` command building so shared tmux consumers can capture the created pane id without private command arrays.
+
+## [0.14.6] - 2026-04-23
+
+### Technical
+- Removed the stale cross-TC `session-name` fallback from retained existing-session verification so the goal now relies only on in-scope session continuity evidence.
+
+## [0.14.5] - 2026-04-23
+
+
+### Fixed
+- Improved tmux session targeting so session-aware commands respect existing `TMUX` context instead of forcing socket-level targeting when already attached.
+- Added regression coverage for active-session command paths that previously depended on socket-legacy behavior.
+
+
+### Fixed
+- Fixed session targeting so commands now respect an active `TMUX` session and avoid forcing legacy `tmux -S` socket targeting when already inside tmux.
+
+## [0.14.4] - 2026-04-22
+
+### Fixed
+- Sanitized ACE-managed tmux window names so path-derived names such as `ace-t.k5a` become tmux-safe targets like `ace-t-k5a`.
+- Tracked startup windows by tmux window ID after creation so session startup selection no longer depends on raw or punctuation-bearing window names.
+
 ## [0.14.3] - 2026-04-16
 
 ### Technical

data/README.md

@@ -1,7 +1,7 @@
 <div align="center">
   <h1> ACE - TMUX </h1>
 
-  Composable tmux sessions from YAML presets, with window injection into active sessions.
+  Composable tmux sessions from YAML presets, with window injection and shared control operations for active sessions.
 
   <img src="../docs/brand/AgenticCodingEnvironment.Logo.XS.jpg" alt="ACE Logo" width="480">
   <br><br>
@@ -16,13 +16,15 @@
 
 [Getting Started](docs/getting-started.md) | [Usage Guide](docs/usage.md) | [Handbook - Skills, Agents, Templates](docs/handbook.md)
 
-`ace-tmux` helps you standardize terminal workspaces with preset-driven sessions, reusable windows, and nested pane layouts. You can spin up a full workspace from a session preset or inject a focused window into an already-running tmux session, with config cascade across project, user, and gem defaults.
+`ace-tmux` helps you standardize terminal workspaces with preset-driven sessions, reusable windows, nested pane layouts, runtime inspection, and a shared live-control surface for pane/session interaction. You can discover preset names with `--list-presets`, spin up a full workspace from a session preset, inspect the live tmux state with `list`, inject a focused window into an already-running tmux session, or use `send`/`capture`/`wait`/`attach`/`detach` as the public ACE tmux control contract.
 
 ## How It Works
 
 1. Define session and window layouts in YAML presets stored in `.ace/tmux/` (project), `~/.ace/tmux/` (user), or gem defaults.
 2. Run `ace-tmux start [PRESET]` to create a full session or `ace-tmux window [PRESET]` to inject a window into the current session. Use `ace-tmux start ... --name <session>` when you need multiple concurrent sessions from the same preset.
-3. Presets are deep-merged through the config cascade, so project-level overrides layer cleanly on top of shared defaults.
+3. Use `ace-tmux list` to inspect panes in the current window, or widen the scope with `--all-panes`, `--windows`, or `--sessions`.
+4. Use `ace-tmux send`, `capture`, `wait`, `attach`, and `detach` for shared live tmux interaction without dropping to raw `tmux`.
+5. Presets are deep-merged through the config cascade, so project-level overrides layer cleanly on top of shared defaults.
 
 ## Use Cases
 
@@ -30,10 +32,16 @@
 
 **Inject windows into running sessions** - run `ace-tmux window [PRESET]` to add a new window from presets without recreating the current session, useful for spinning up focused tool or test panes on the fly.
 
+**Inspect tmux state without raw tmux** - run `ace-tmux list` to inspect the current window’s panes, `ace-tmux list --windows` for the current session’s windows, or `ace-tmux list --sessions` for the tmux server view.
+
+**Control tmux through a shared ACE contract** - run `ace-tmux send`, `capture`, `wait`, `attach`, and `detach` when higher-level ACE tools or operators need live pane/session control without re-implementing tmux wrappers.
+
 **Compose nested pane layouts in YAML** - use `direction` and nested pane containers to model custom split trees beyond tmux built-in layouts, keeping workspace structure version-controlled alongside your project.
 
 **Reuse presets through config cascade** - load project presets from `.ace/tmux/`, personal presets from `~/.ace/tmux/`, and gem defaults via `.ace-defaults/tmux/` with deep-merge behavior so teams share a baseline while individuals customize.
 
+**Discover preset names cleanly** - run `ace-tmux --list-presets` with an optional `sessions`, `windows`, or `panes` filter when you need to inspect available presets without overloading the live-runtime `list` command.
+
 **Orchestrate task-focused workspaces** - pair with [ace-overseer](../ace-overseer) and [ace-assign](../ace-assign) for assignment-driven worktree and tmux orchestration that spins up isolated workspaces per task.
 
 ## Testing

data/docs/demo/ace-tmux-getting-started.tape.yml

@@ -1,5 +1,5 @@
 ---
-description: Showcase ace-tmux preset discovery, session start, and window management
+description: Showcase ace-tmux preset discovery, runtime listing, session start, and window management
 tags:
 - ace-tmux
 - docs
@@ -11,6 +11,10 @@ settings:
   format: gif
 scenes:
 - name: Discover available presets (sessions, windows, panes)
+  commands:
+  - type: ace-tmux --list-presets
+    sleep: 4s
+- name: Inspect panes in the current tmux window
   commands:
   - type: ace-tmux list
     sleep: 4s

data/docs/getting-started.md

@@ -3,8 +3,8 @@ doc-type: user
 title: ace-tmux Getting Started
 purpose: Tutorial for creating sessions and adding windows with ace-tmux.
 ace-docs:
-  last-updated: 2026-03-22
-  last-checked: 2026-03-22
+  last-updated: 2026-04-16
+  last-checked: 2026-04-16
 ---
 
 # Getting Started with ace-tmux
@@ -22,6 +22,8 @@ Verify command availability: `ace-tmux --help`.
 
 ## Start Your First Session
 
+See available presets first with `ace-tmux --list-presets sessions`.
+
 Run: `ace-tmux start`.
 
 `ace-tmux` resolves the default session preset from `defaults.session` in config.
@@ -78,9 +80,11 @@ Use it in a session or add it directly with `ace-tmux window cc`.
 
 | Command | Purpose |
 | --- | --- |
+| `ace-tmux --list-presets [TYPE]` | Show available preset names |
 | `ace-tmux start [PRESET]` | Start or attach to a session preset |
 | `ace-tmux window [PRESET]` | Add a window preset to a running session |
-| `ace-tmux list` | Show available session/window/pane presets |
+| `ace-tmux list` | Show live panes in the current window |
+| `ace-tmux list --windows` | Show windows in the current session |
 
 ## Next steps
 

data/docs/usage.md

@@ -3,8 +3,8 @@ doc-type: user
 title: ace-tmux Usage
 purpose: Full CLI and configuration reference for ace-tmux.
 ace-docs:
-  last-updated: 2026-03-22
-  last-checked: 2026-03-22
+  last-updated: 2026-04-24
+  last-checked: 2026-04-24
 ---
 
 # Usage
@@ -13,7 +13,13 @@ ace-docs:
 
 - `ace-tmux start [PRESET] [OPTIONS]`
 - `ace-tmux window [PRESET] [OPTIONS]`
-- `ace-tmux list [TYPE] [OPTIONS]`
+- `ace-tmux list [OPTIONS]`
+- `ace-tmux --list-presets [TYPE]`
+- `ace-tmux send [OPTIONS]`
+- `ace-tmux capture [OPTIONS]`
+- `ace-tmux wait [OPTIONS]`
+- `ace-tmux attach [OPTIONS]`
+- `ace-tmux detach [OPTIONS]`
 
 `PRESET` is optional for `start` and `window` when defaults are configured.
 
@@ -70,26 +76,173 @@ Behavior notes:
 - Inside tmux, current session is auto-detected.
 - Outside tmux, provide `--session` (or set `ACE_TMUX_SESSION`).
 - If no preset is provided, `defaults.window` is used.
+- ACE-managed window names are normalized to `A-Z`, `a-z`, `0-9`, `_`, and `-`; other punctuation is replaced with `-`.
 
 ## `ace-tmux list`
 
-List available presets.
+List live tmux sessions, windows, or panes.
 
 Examples:
 
 - `ace-tmux list`
-- `ace-tmux list sessions`
-- `ace-tmux list windows`
-- `ace-tmux list panes`
+- `ace-tmux list --all-panes`
+- `ace-tmux list --windows`
+- `ace-tmux list --sessions`
+- `ace-tmux list --session dev --window work`
+
+Options:
+
+- `--session`, `-s`: target session name
+- `--window`, `-w`: target window name, index, or tmux window id (`@2`)
+- `--all-panes`: list panes across the resolved session
+- `--windows`: list windows in the resolved session
+- `--sessions`: list all tmux sessions
+
+Behavior notes:
+
+- With no scope flags, `list` shows panes in the resolved current window.
+- `--all-panes` expands from the current window to every window in the resolved session.
+- `--windows` lists windows in the resolved session.
+- `--sessions` lists tmux sessions and does not accept `--session` or `--window`.
+- Runtime target resolution follows the same precedence as the control surface: explicit flags, then ACE tmux env vars, then live tmux context.
+
+## `ace-tmux --list-presets`
+
+List available tmux preset names.
+
+Examples:
+
+- `ace-tmux --list-presets`
+- `ace-tmux --list-presets sessions`
+- `ace-tmux --list-presets windows`
 
 Arguments:
 
-- `TYPE`: one of `sessions`, `windows`, `panes`
+- `TYPE`: optional `sessions`, `windows`, or `panes`
+
+## `ace-tmux send`
+
+Send a submitted command, literal text, or bounded named keys to a target pane.
+
+Examples:
+
+- `ace-tmux send --pane %1 --cmd "bundle exec rake test"`
+- `ace-tmux send --session dev --window work --pane 0 --cmd "ace-task status" --capture`
+- `ace-tmux send --pane %8 --cmd "ping" --wait --capture 20`
+- `ace-tmux send --pane %8 --cmd "Task context?" --wait agent --timeout 30 --capture`
+- `ace-tmux send --pane .1 --msg "echo ready" --key Enter`
+- `ace-tmux send --pane %1 --msg "echo ready" --key Enter`
+- `ace-tmux send --pane %1 --key C-c`
+
+Options:
+
+- `--session`, `-s`: target session name
+- `--window`, `-w`: target window name, index, or tmux window id (`@2`)
+- `--pane`, `-p`: target pane id (`%8`), full pane target (`dev:work.1`), or current-window pane shorthand (`.1`)
+- `--cmd`, `-c`: command text to send and submit with `Enter`
+- `--msg`, `-m`: literal text chunk to send without `Enter`
+- `--key`, `-k`: named key to send
+- `--capture [lines[:wait]]`: capture recent pane output after sending; defaults to `40:2`
+- `--wait [condition]`: wait after send; bare `--wait` defaults to `agent`
+- `--pattern`: pattern to match when waiting for `output`
+- `--timeout`, `-t`: wait timeout in seconds when `--wait` is used
+- `--interval`, `-i`: wait polling interval in seconds when `--wait` is used
+- `--quiet`, `-q`: suppress non-essential output
+
+Behavior notes:
+
+- Provide at least one of `--cmd`, `--msg`, or `--key`.
+- Use either `--cmd` or `--msg`, not both.
+- Repeated `--msg` values are sent in order, then any implicit `Enter` from `--cmd`, then repeated `--key` values in order.
+- `--cmd` always appends one final `Enter`.
+- Embedded newlines in `--cmd` or `--msg` remain literal text; they are not expanded into extra key presses.
+- Named keys are intentionally bounded; unsupported raw tmux key syntax is rejected.
+- Interactive CLI panes such as `codex`, `claude`, and `pi` get a brief automatic pause before the first submit `Enter` after text so the TUI sees a submit key instead of a paste burst.
+- `--wait agent` blocks until a supported interactive CLI pane visibly changes and then settles; bare `--wait` is shorthand for that main send-and-wait flow.
+- `send --wait output` compares against the pre-send pane tail, so existing visible matches do not satisfy the wait unless the pattern appears again after the send.
+- Interactive CLI detection also covers panes launched through shell wrappers, so detached `fish -c codex` / similar panes still use the interactive send, wait, and capture path.
+- When `--wait` and `--capture` are used together, ACE waits first and then captures from the same pane, so the printed tail reflects the settled post-response screen.
+- Target resolution uses one precedence rule across the control surface: explicit flags, then ACE tmux env vars, then live tmux context.
+- `--capture N` prints the visible bottom `N` rows for interactive CLI panes and a recent history tail for generic shell panes.
+- Supported pane forms are `%8`, `dev:work.1`, `.1`, and bare `1`. `dev:work:1` is invalid; use `dev:work.1` instead.
+- `.1` and bare `1` both resolve against the explicit or resolved current window.
+- Window names may contain dots. ACE resolves pane shorthands through tmux window ids internally, so `--window ace-t.n1d --pane .3` remains valid.
+
+## `ace-tmux capture`
+
+Capture recent output from a tmux pane.
+
+Examples:
+
+- `ace-tmux capture --pane %1`
+- `ace-tmux capture --pane %1 --lines 80`
+
+Options:
+
+- `--session`, `-s`: target session name
+- `--window`, `-w`: target window name, index, or tmux window id (`@2`)
+- `--pane`, `-p`: target pane id (`%8`), full pane target (`dev:work.1`), or current-window pane shorthand (`.1`)
+- `--lines`, `-n`: number of recent lines to capture
+
+Behavior notes:
+
+- Capture is a live control-side pane-tail operation, not a generic read-side runtime inventory surface.
+- `--lines N` captures the visible bottom `N` rows for interactive CLI panes such as `codex`, `claude`, and `pi`.
+- Generic shell panes keep using a recent history tail instead of the current visible screen.
+- Interactive CLI captures may include visible draft/composer text when it is on screen.
+- Pane targeting follows the same rules as `send`: `%8`, `dev:work.1`, `.1`, or bare `1`.
+
+## `ace-tmux wait`
+
+Wait for a bounded tmux condition.
+
+Examples:
+
+- `ace-tmux wait --pane %1 --for output --pattern "Task context:"`
+- `ace-tmux wait --pane %8 --for agent`
+- `ace-tmux wait --session dev --for window-active --window work-fs`
+- `ace-tmux wait --pane %1 --for pane-exited`
 
 Options:
 
-- `--verbose`, `-v`
-- `--quiet`, `-q`
+- `--for`, `-f`: one of `agent`, `output`, `window-exists`, `window-active`, `pane-exists`, `pane-exited`
+- `--session`, `-s`: target session name
+- `--window`, `-w`: target window name, index, or tmux window id (`@2`)
+- `--pane`, `-p`: target pane id (`%8`), full pane target (`dev:work.1`), or current-window pane shorthand (`.1`)
+- `--pattern`: output substring to match
+- `--lines`, `-n`: number of lines to observe for `output` and `agent` waits
+- `--timeout`, `-t`: timeout in seconds
+- `--interval`, `-i`: polling interval in seconds
+- `--quiet`, `-q`: suppress non-essential output
+
+Behavior notes:
+
+- `--for agent` waits for a supported interactive CLI pane such as `codex`, `claude`, or `pi` to become visibly idle/stable, including panes launched through wrapper shells.
+- `--pattern` is required for `--for output`.
+- `--for output` observes the last `--lines` lines of the target pane.
+- `--for pane-exited` succeeds when the pane reports `pane_dead=1` or disappears entirely.
+- Wait timeouts fail clearly; they do not silently fall through.
+- Pane targeting follows the same rules as `send`: `%8`, `dev:work.1`, `.1`, or bare `1`.
+
+## `ace-tmux attach`
+
+Attach to a tmux session using the same shared target-resolution rules.
+
+Examples:
+
+- `ace-tmux attach --session dev`
+
+## `ace-tmux detach`
+
+Detach clients from a tmux session.
+
+Examples:
+
+- `ace-tmux detach --session dev`
+
+Behavior notes:
+
+- `detach` removes attached clients from the target session and is intended to replace raw `tmux detach-client -s ...` usage in ACE-owned flows.
 
 ## Config Cascade
 
@@ -200,6 +353,11 @@ Chained preset references are supported (depth-limited).
 - [Getting Started](getting-started.md)
 - [Handbook Reference](handbook.md)
 
+## Boundary Notes
+
+- `ace-tmux` control commands (`send`, `capture`, `wait`, `attach`, `detach`) define the live interaction surface.
+- Read-side runtime inventory currently uses the shipped `ace-tmux list` surface. No additional shared read-side CLI follow-up is active today; any future consumer-driven expansion should start as a new task rather than reopening the archived `8r6.t.xeu` family.
+
 ## Testing Contract
 
 - `ace-test ace-tmux` validates deterministic fast coverage in `test/fast/`.

data/lib/ace/tmux/atoms/named_key_registry.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Ace
+  module Tmux
+    module Atoms
+      module NamedKeyRegistry
+        module_function
+
+        KEYS = {
+          "enter" => "Enter",
+          "tab" => "Tab",
+          "space" => "Space",
+          "escape" => "Escape",
+          "esc" => "Escape",
+          "up" => "Up",
+          "down" => "Down",
+          "left" => "Left",
+          "right" => "Right",
+          "c-c" => "C-c"
+        }.freeze
+
+        def normalize(key)
+          value = key.to_s.strip
+          raise Ace::Tmux::ValidationError, "Named key is required" if value.empty?
+
+          normalized = KEYS[value.downcase]
+          raise Ace::Tmux::ValidationError, "Unsupported named key: #{key}" unless normalized
+
+          normalized
+        end
+      end
+    end
+  end
+end

data/lib/ace/tmux/atoms/tmux_command_builder.rb

@@ -63,11 +63,12 @@ module Ace
         # @param horizontal [Boolean] Split horizontally (default: vertically)
         # @param tmux [String] tmux binary path
         # @return [Array<String>]
-        def split_window(target, root: nil, horizontal: false, tmux: "tmux")
+        def split_window(target, root: nil, horizontal: false, print_format: nil, tmux: "tmux")
           cmd = [tmux, "split-window"]
           cmd << "-h" if horizontal
           cmd.concat(["-t", target])
           cmd.concat(["-c", File.expand_path(root)]) if root
+          cmd.concat(["-P", "-F", print_format]) if print_format
           cmd
         end
 
@@ -80,6 +81,10 @@ module Ace
           [tmux, "send-keys", "-t", target, keys, "Enter"]
         end
 
+        def send_raw_keys(target, *keys, tmux: "tmux")
+          [tmux, "send-keys", "-t", target, *keys]
+        end
+
         # Set the layout for a window
         # @param target [String] Target window
         # @param layout [String] Layout name (e.g., "main-vertical", "tiled")
@@ -131,6 +136,12 @@ module Ace
           cmd
         end
 
+        def list_windows(target, format: nil, tmux: "tmux")
+          cmd = [tmux, "list-windows", "-t", target]
+          cmd.concat(["-F", format]) if format
+          cmd
+        end
+
         # Set a window option
         # @param target [String] Target window
         # @param option [String] Option name (e.g., "main-pane-width")
@@ -197,6 +208,22 @@ module Ace
           cmd.concat(["-F", format]) if format
           cmd
         end
+
+        def capture_pane(target, lines: 40, tmux: "tmux")
+          start = -Integer(lines.to_i.abs)
+          [tmux, "capture-pane", "-p", "-t", target, "-S", start.to_s, "-E", "-1"]
+        end
+
+        def capture_pane_visible(target, start_line:, end_line:, include_alternate: false, tmux: "tmux")
+          cmd = [tmux, "capture-pane", "-p"]
+          cmd << "-a" if include_alternate
+          cmd.concat(["-t", target, "-S", Integer(start_line).to_s, "-E", Integer(end_line).to_s])
+          cmd
+        end
+
+        def detach_client(session, tmux: "tmux")
+          [tmux, "detach-client", "-s", session]
+        end
       end
     end
   end

data/lib/ace/tmux/atoms/window_name_sanitizer.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Ace
+  module Tmux
+    module Atoms
+      # Normalizes ACE-managed tmux window names to avoid target parsing ambiguity.
+      module WindowNameSanitizer
+        module_function
+
+        def call(value, fallback: "window")
+          sanitized = sanitize(value)
+          sanitized.empty? ? sanitize(fallback).then { |name| name.empty? ? "window" : name } : sanitized
+        end
+
+        def sanitize(value)
+          value.to_s
+            .gsub(/[^A-Za-z0-9_-]+/, "-")
+            .gsub(/-+/, "-")
+            .gsub(/\A-|-+\z/, "")
+        end
+        private_class_method :sanitize
+      end
+    end
+  end
+end

data/lib/ace/tmux/cli/commands/attach.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "ace/support/cli"
+require "ace/core"
+
+module Ace
+  module Tmux
+    module CLI
+      module Commands
+        class Attach < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+
+          desc "Attach to a tmux session using shared target resolution"
+
+          option :session, type: :string, aliases: %w[-s], desc: "Target session name"
+
+          def call(**options)
+            Organisms::ControlSurface.new.attach_session(session: options[:session])
+          rescue Ace::Tmux::Error => e
+            raise Ace::Support::Cli::Error, e.message
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/tmux/cli/commands/capture.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "ace/support/cli"
+require "ace/core"
+
+module Ace
+  module Tmux
+    module CLI
+      module Commands
+        class Capture < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+
+          desc <<~DESC.strip
+            Capture recent output from a tmux pane
+
+            Interactive CLI panes capture the visible bottom of the current screen.
+            Generic shell panes capture a recent history tail.
+          DESC
+
+          example [
+            "--pane %1",
+            "--pane %8 --lines 20",
+            "--session dev --window work --pane .1 --lines 10"
+          ]
+
+          option :session, type: :string, aliases: %w[-s], desc: "Target session name"
+          option :window, type: :string, aliases: %w[-w], desc: "Target window name, index, or tmux window id (@2)"
+          option :pane, type: :string, aliases: %w[-p], desc: "Target pane id (%8), full pane target (dev:work.1), or current-window pane shorthand (.1)"
+          option :lines, type: :integer, aliases: %w[-n], default: 40, desc: "Number of recent lines to capture"
+
+          def call(**options)
+            output = Organisms::ControlSurface.new.capture_recent_output(**options.slice(:session, :window, :pane, :lines))
+            puts output
+          rescue Ace::Tmux::Error => e
+            raise Ace::Support::Cli::Error, e.message
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/tmux/cli/commands/detach.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "ace/support/cli"
+require "ace/core"
+
+module Ace
+  module Tmux
+    module CLI
+      module Commands
+        class Detach < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+
+          desc "Detach clients from a tmux session"
+
+          option :session, type: :string, aliases: %w[-s], desc: "Target session name"
+          option :quiet, type: :boolean, aliases: %w[-q], desc: "Suppress non-essential output"
+
+          def call(**options)
+            session = Organisms::ControlSurface.new.detach_session(session: options[:session])
+            puts "Detached session #{session}" unless options[:quiet]
+          rescue Ace::Tmux::Error => e
+            raise Ace::Support::Cli::Error, e.message
+          end
+        end
+      end
+    end
+  end
+end