8re.t.n1d: unify ace-tmux live control for assignment and demo flows by cs3b · Pull Request #297 · cs3b/ace

cs3b · 2026-04-16T08:47:03Z

📋 Summary

This PR turns ace-tmux into the shared live tmux control layer used by assignment forks, demo recorders, and interactive panes. Before this branch, tmux automation was split across package-local runners and raw shell glue, interactive AI panes were brittle to target and capture, and fork launch behavior could only be chosen at the CLI. The branch consolidates those flows behind one public ace-tmux contract, moves ace-assign and ace-demo onto that surface, and adds step/config launch-mode defaults so forked subtrees can opt into tmux or headless execution without per-run flags.

✏️ Changes

Shared control surface ace-tmux now owns send, capture, wait, attach, and detach, with shared runtime target resolution, bounded named-key handling, stable window-id pane targeting, and shell-wrapped interactive CLI detection for codex, claude, and pi.
Runtime inspection UX ace-tmux list now inspects live panes in the current window by default, widens to --all-panes, --windows, or --sessions, and moves preset discovery to top-level ace-tmux --list-presets [TYPE].
Interactive pane reliability ace-tmux validates operator-facing pane syntax, resolves dotted window names through tmux window ids, captures visible TUI tails, delays the first submit Enter, adds wait --for agent plus wait --lines, and makes send --wait output compare against post-send output instead of stale screen text.
Assignment integration ace-assign removes the private TmuxForkRunner, launches forks through the shared control surface, keeps assignment state as the completion source of truth, and now resolves launch mode with precedence --launch-mode -> fork.mode -> execution.launch_mode -> auto.
Demo recorder directives ace-demo adds structured tmux recorder directives for asciinema-backed tapes, threads recorder env into tmux control resolution, and rejects unsupported vhs / capture combinations instead of silently accepting invalid YAML.
Shared CLI parsing ace-support-cli adds optional-value string flag parsing and suppresses misleading rich-help default text, which makes bare forms like --capture and --wait behave and document correctly.
Provider test hardening ace-llm stubs the Z.ai endpoint in query command tests so deterministic package runs stay offline and do not depend on blocked real HTTP calls.

📁 File Changes

+5570, -1402   113 files   total

+1455, -1277   24 files      ace-assign/
 +203,  -196    8 files   🧱 lib/
   +1,    -0                 ace/assign.rb
   +1,    -1                 ace/assign/cli.rb
  +12,    -2                 ace/assign/cli/commands/fork_run.rb
  +10,    -0                 ace/assign/models/step.rb
   +2,    -1                 ace/assign/molecules/fork_session_launcher.rb
 +176,    -0                 .../tmux_control_surface_runner.rb
   +0,  -191                 .../tmux_fork_runner.rb
   +1,    -1                 ace/assign/version.rb
 +355,  -122    7 files   🧪 test/
   +2,    -2                 fast/atoms/step_file_parser_test.rb
 +156,    -0                 fast/commands/fork_run_command_test.rb
  +15,    -2                 fast/models/step_test.rb
  +10,    -0                 fast/molecules/fork_session_launcher_test.rb
   +2,    -0                 .../queue_scanner_test.rb
 +170,    -0                 .../tmux_control_surface_runner_test.rb
   +0,  -118                 .../tmux_fork_runner_test.rb
   +9,    -1    1 files   📚 handbook/
   +9,    -1                 guides/fork-context.g.md
 +888,  -958    8 files      
   +1,    -0                 .ace-defaults/assign/config.yml
  +31,    -0                 CHANGELOG.md
   +1,    -0                 ace-assign.gemspec
 +814,  -937                 docs/demo/fork-provider.cast
                             .../fork-provider.gif (binary)
  +15,   -17                 .../fork-provider.recording.json
  +16,    -4                 .../fork-provider.tape.yml
  +10,    -0                 docs/usage.md

 +691,   -19   20 files      ace-demo/
 +224,   -11   10 files   🧱 lib/
   +2,    -0                 ace/demo.rb
   +2,    -0                 ace/demo/atoms/asciinema_tape_compiler.rb
  +77,    -7                 .../demo_yaml_parser.rb
  +14,    -0                 .../record_option_validator.rb
   +2,    -0                 .../vhs_tape_compiler.rb
   +1,    -0                 .../yaml_record_planner.rb
   +9,    -1                 ace/demo/molecules/asciinema_executor.rb
  +80,    -0                 .../tmux_directive_executor.rb
  +36,    -2                 ace/demo/organisms/demo_recorder.rb
   +1,    -1                 ace/demo/version.rb
 +356,    -2    5 files   🧪 test/
  +18,    -0                 fast/atoms/asciinema_tape_compiler_test.rb
  +63,    -0                 .../demo_yaml_parser_test.rb
  +33,    -0                 .../record_option_validator_test.rb
  +89,    -0                 fast/molecules/tmux_directive_executor_test.rb
 +153,    -2                 fast/organisms/demo_recorder_test.rb
 +111,    -6    5 files      
  +38,    -0                 CHANGELOG.md
   +9,    -2                 README.md
   +1,    -0                 ace-demo.gemspec
  +34,    -2                 docs/getting-started.md
  +29,    -2                 .../usage.md

  +20,    -2    3 files      ace-llm/
   +1,    -1    1 files   🧱 lib/
   +1,    -1                 ace/llm/version.rb
  +14,    -1    1 files   🧪 test/
  +14,    -1                 fast/commands/query_command_test.rb
   +5,    -0    1 files      
   +5,    -0                 CHANGELOG.md

  +22,    -2    3 files      ace-overseer/
   +1,    -1    1 files   🧱 lib/
   +1,    -1                 ace/overseer/version.rb
  +21,    -1    2 files      
  +20,    -0                 CHANGELOG.md
   +1,    -1                 ace-overseer.gemspec

  +75,    -7    8 files      ace-support-cli/
  +28,    -7    5 files   🧱 lib/
   +3,    -2                 ace/support/cli/command.rb
  +14,    -1                 ace/support/cli/help/banner.rb
   +3,    -2                 ace/support/cli/models/option.rb
   +7,    -1                 ace/support/cli/parser.rb
   +1,    -1                 .../version.rb
  +37,    -0    2 files   🧪 test/
  +12,    -0                 fast/atoms/help/banner_test.rb
  +25,    -0                 fast/molecules/parser_test.rb
  +10,    -0    1 files      
  +10,    -0                 CHANGELOG.md

+3065,   -73   44 files      ace-tmux/
+1544,   -50   17 files   🧱 lib/
  +10,    -0                 ace/tmux.rb
  +34,    -0                 ace/tmux/atoms/named_key_registry.rb
  +28,    -1                 .../tmux_command_builder.rb
  +27,    -2                 ace/tmux/cli.rb
  +26,    -0                 ace/tmux/cli/commands/attach.rb
  +41,    -0                 .../capture.rb
  +28,    -0                 .../detach.rb
 +111,   -46                 .../list.rb
  +67,    -0                 .../list_presets.rb
 +169,    -0                 .../send.rb
  +57,    -0                 .../wait.rb
  +46,    -0                 ace/tmux/models/runtime_target.rb
  +84,    -0                 ace/tmux/molecules/local_process_inspector.rb
 +267,    -0                 .../runtime_target_resolver.rb
  +25,    -0                 .../wait_condition_validator.rb
 +523,    -0                 ace/tmux/organisms/control_surface.rb
   +1,    -1                 ace/tmux/version.rb
+1276,    -6   22 files   🧪 test/
   +1,    -1                 e2e/TS-TMUX-001-tmux-management/TC-001-list-presets.runner.md
   +2,    -2                 .../TC-003-add-window.runner.md
  +29,    -0                 .../TC-004-runtime-list.runner.md
  +27,    -0                 .../TC-004-runtime-list.verify.md
   +2,    -1                 .../runner.yml.md
   +1,    -0                 .../scenario.yml
   +1,    -0                 .../verifier.yml.md
  +21,    -0                 fast/atoms/named_key_registry_test.rb
  +35,    -0                 .../tmux_command_builder_test.rb
   +9,    -0                 fast/commands/attach_test.rb
  +24,    -0                 .../capture_test.rb
  +23,    -2                 .../cli_test.rb
  +32,    -0                 .../detach_test.rb
 +124,    -0                 .../list_test.rb
 +184,    -0                 .../send_test.rb
  +62,    -0                 .../wait_test.rb
  +42,    -0                 fast/models/runtime_target_test.rb
  +41,    -0                 fast/molecules/local_process_inspector_test.rb
 +177,    -0                 .../runtime_target_resolver_test.rb
  +27,    -0                 .../wait_condition_validator_test.rb
 +410,    -0                 fast/organisms/control_surface_test.rb
   +2,    -0                 test_helper.rb
 +245,   -17    5 files      
  +55,    -0                 CHANGELOG.md
  +11,    -3                 README.md
   +5,    -1                 docs/demo/ace-tmux-getting-started.tape.yml
   +7,    -3                 docs/getting-started.md
 +167,   -10                 .../usage.md

  +24,   -22    5 files      .ace-tasks/
  +11,    -9                 8re.t.n1d-design-ace-tmux-control-integrations/0-specify-ace-tmux-runtime-control/8re.t.n1d.0-specify-ace-tmux-runtime-control-surface.s.md -> _archive/8r/x/8re.t.n1d-design-ace-tmux-control-integrations/0-specify-ace-tmux-runtime-control/8re.t.n1d.0-specify-ace-tmux-runtime-control-surface.s.md
   +6,    -6                 8re.t.n1d-design-ace-tmux-control-integrations/1-route-ace-assign-tmux-delegation/8re.t.n1d.1-route-ace-assign-tmux-delegation-through-ace.s.md -> _archive/8r/x/8re.t.n1d-design-ace-tmux-control-integrations/1-route-ace-assign-tmux-delegation/8re.t.n1d.1-route-ace-tmux-delegation-through-ace.s.md
   +6,    -6                 8re.t.n1d-design-ace-tmux-control-integrations/2-add-ace-demo-tmux-aware-recording/8re.t.n1d.2-add-ace-demo-tmux-aware-recording-directives.s.md -> _archive/8r/x/8re.t.n1d-design-ace-tmux-control-integrations/2-add-ace-demo-tmux-aware-recording/8re.t.n1d.2-add-ace-demo-tmux-aware-recording-directives.s.md
   +1,    -1                 8re.t.n1d-design-ace-tmux-control-integrations/8re.t.n1d-design-ace-tmux-control-integrations-for-assignment.s.md -> _archive/8r/x/8re.t.n1d-design-ace-tmux-control-integrations/8re.t.n1d-design-ace-tmux-control-integrations-for-assignment.s.md
   +0,    -0                 8re.t.n1d-design-ace-tmux-control-integrations/ux/usage.md -> _archive/8r/x/8re.t.n1d-design-ace-tmux-control-integrations/ux/usage.md

 +194,    -0    5 files      .ace-retros/
  +43,    -0                 8rf2m2-8re-t-n1d-0-tmux/8rf2m2-8re-t-n1d-0-tmux-runtime-control.retro.md
  +31,    -0                 8rf2uj-8re-t-n1d-1-assign/8rf2uj-8re-t-n1d-1-assign-tmux-delegation.retro.md
  +31,    -0                 8rf317-8re-t-n1d-2-demo/8rf317-8re-t-n1d-2-demo-tmux-recording.retro.md
  +39,    -0                 8rfedz-tmux-control-batch-closeout/8rfedz-tmux-control-batch-closeout.retro.md
  +50,    -0                 8rfutk-8re-t-n1d-cli-ux/8rfutk-8re-t-n1d-cli-ux-testing.retro.md

  +24,    -0    1 files      ./
  +24,    -0                 CHANGELOG.md

🧪 Test Evidence

ControlSurfaceTest / ListCommandTest / SendCommandTest / WaitCommandTest validate runtime list scopes, interactive-pane pacing/capture, send --wait, output-baseline waits, and pane/window resolution in ace-tmux.
ForkRunCommandTest / StepTest / StepFileParserTest / QueueScannerTest / ForkSessionLauncherTest validate fork.mode, execution.launch_mode, and CLI precedence in ace-assign while preserving shared-control-surface fork orchestration.
TmuxControlSurfaceRunnerTest validates that ace-assign launches tmux-backed forks through the shared control surface after removing the private runner.
TmuxDirectiveExecutorTest / DemoRecorderTest validate structured tmux: recorder directives and backend-specific rejection paths in ace-demo.
HelpBannerTest / ParserTest validate optional-value flag parsing and rich-help rendering for bare shorthand flags in ace-support-cli.
QueryCommandTest validates the Z.ai endpoint stub in ace-llm query command coverage.
Suite totals ace-support-cli 60 tests / 217 assertions, ace-tmux 265 tests / 704 assertions, ace-assign 559 tests / 1838 assertions, ace-demo 211 tests / 858 assertions, ace-overseer 144 tests / 540 assertions, and ace-llm 328 tests / 803 assertions; all passed with 0 failures / 0 errors.

📦 Releases

ace-tmux v0.14.0 -> v0.17.0 introduces the shared control surface, interactive-pane reliability work, send --wait / agent, and the runtime list / --list-presets split.
ace-assign v0.50.0 -> v0.54.0 adopts the shared tmux control surface for fork-run, refreshes the visible fork demo contract, and adds step/config launch-mode defaults via fork.mode and execution.launch_mode.
ace-demo v0.25.0 -> v0.25.6 adds tmux recorder directives, tightens backend/control validation, and follows the current ace-tmux line.
ace-support-cli v0.6.7, ace-llm v0.35.2, and ace-overseer v0.14.8 provide the supporting optional-value CLI parsing/help cleanup, offline Z.ai test stub, and follower dependency alignment needed for the tmux control rollout.

🎮 Demo

Run

ace-tmux --list-presets windows
ace-tmux list --windows
ace-tmux send --pane %8 --cmd "Reply with exactly: pong" --wait --capture 20 --timeout 30
ACE_TMUX_SESSION=fork-demo PROJECT_ROOT_PATH="$PWD" ace-assign fork-run --assignment "$ASSIGN_ID@010" --launch-mode tmux --provider codex:gpt@yolo --cli-args "--no-alt-screen" --timeout 120

Expected Output

ace-tmux --list-presets windows prints the available window preset names.
ace-tmux list --windows prints live tmux state with stable ids such as @window_id and %pane_id.
ace-tmux send --wait --capture returns the settled post-response pane tail for interactive CLI panes instead of stale scrollback; on a Codex pane it should include • pong.
ace-assign fork-run --launch-mode tmux opens or reuses the <current-window>-fs staging window and writes fork session metadata with launch_mode, tmux_window, provider, model, and session details.
If the fork root step sets fork.mode: tmux or assign config sets execution.launch_mode: tmux, the same visible fork-window behavior now works without repeating --launch-mode tmux on every run.

Artifacts

ace-tmux/docs/demo/ace-tmux-getting-started.tape.yml
ace-assign/docs/demo/fork-provider.tape.yml
ace-assign/docs/demo/fork-provider.recording.json
ace-assign/docs/demo/fork-provider.gif
ace-assign/docs/demo/fork-provider.cast

cs3b · 2026-04-16T09:32:06Z

Demo: fork-provider

Recorded at 2026-04-16 10:32:05

…ee orchestration

…ML tapes

…ands

…e rollout

…rollout

…ifacts

cs3b changed the title ~~8re.t.n1d: add shared tmux control integrations for assignment and demo flows~~ 8re.t.n1d: unify ace-tmux live control for assignment and demo flows Apr 16, 2026

cs3b force-pushed the n1d-design-ace-tmux-control-integrations-for-assignment-and-demo-flows branch from cf0f8bf to c55f08d Compare April 17, 2026 21:03

cs3b added 9 commits April 20, 2026 11:11

feat(ace-assign): integrate shared ace-tmux control surface for subtr…

6736bb0

…ee orchestration

feat(ace-demo): add structured tmux recorder-control directives to YA…

074e17d

…ML tapes

feat(ace-tmux): implement shared runtime control surface and CLI comm…

74e0e7c

…ands

feat(ace-support-cli): add optional-value string flag support

cb0748b

fix(ace-llm): stub Z.ai endpoint in query command tests

1973f20

chore(ace-overseer): update ace-tmux dependency to v0.17.0

c4dcb78

chore(root): perform batch dependency updates for tmux control surfac…

c319158

…e rollout

spec(retro-specs): synthesize retrospectives on tmux control surface …

f65cb1f

…rollout

spec(task-specs): archive completed tmux control integration task art…

354ba87

…ifacts

cs3b force-pushed the n1d-design-ace-tmux-control-integrations-for-assignment-and-demo-flows branch from c55f08d to 354ba87 Compare April 20, 2026 10:18

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

8re.t.n1d: unify ace-tmux live control for assignment and demo flows#297

8re.t.n1d: unify ace-tmux live control for assignment and demo flows#297
cs3b wants to merge 9 commits intomainfrom
n1d-design-ace-tmux-control-integrations-for-assignment-and-demo-flows

cs3b commented Apr 16, 2026 •

edited

Loading

Uh oh!

cs3b commented Apr 16, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

cs3b commented Apr 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📋 Summary

✏️ Changes

📁 File Changes

🧪 Test Evidence

📦 Releases

🎮 Demo

Run

Expected Output

Artifacts

Uh oh!

cs3b commented Apr 16, 2026

Demo: fork-provider

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

cs3b commented Apr 16, 2026 •

edited

Loading