ace-assign 0.62.0 → 0.63.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 17761502c8b23ff60844d6a3da34ddde53c776d18907a23854ad4168dec3c033
-  data.tar.gz: 1538f48c6aec44ac548dcc116bddc0c4928cbc876485513b616604f886f0deb0
+  metadata.gz: 7d743c208ce34b070929c7c5cc2acdd200289e7a82e3e2acd62129ec1d22daa5
+  data.tar.gz: 3b4e13b527152e703f7a489f0c7b123b0676c682f6eccb3bd6f30680cf96ace2
 SHA512:
-  metadata.gz: 7f6b66a87f7a32496f11974ced9cb200c092488f027eb233dde59703ba3dcffa2eaad309d1f57b0b023113eb3f08c58e451b69823a33533d80c5fb45b79110e2
-  data.tar.gz: 6d0c8ef8b69d5002b98b60b22018fdc4aecf809818284e80bd11c70020a9733b9ba37140237b30fea470d539de23ce98a658bec902b1a6b9bf4454329ab50ed9
+  metadata.gz: eeba37f93e80112453a79322c0496b6dc5753f5da072556575836a142827c2a3724848978eec0025598babbe1077def70f77fee49df79dd5ae6f54ea668fdd2d
+  data.tar.gz: f78cf53f13cbb76fb67d7a72756189063fa39d0dddb8eb3b55c28e7acd16377e0fc0a486b126fafe926791905871610800f719d166a55a1e2e65431fe62a3724

data/.ace-defaults/assign/config.yml

@@ -26,7 +26,7 @@ workflow_source_paths:
 execution:
   provider: "claude:opus@yolo"
   timeout: 1800
-  launch_mode: auto # auto | headless | tmux
+  launch_mode: auto # auto | headless | tmux | herdr
 
 # Attempt evidence persistence (managed attempts)
 attempt:

data/CHANGELOG.md

@@ -7,12 +7,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.63.1] - 2026-10-04
+
+### Changed
+
+- Install both Herdr and tmux runtime adapters for standalone runtime switching, through an acyclic dependency graph.
+
+### Fixed
+
+- Run terminal fork invocations as children of the prepared shell, retaining the same writable pane after a command exits.
+
+- Managed assignment status JSON tests run against test-owned repositories and evidence journals instead of the invoking checkout's journal, evidence ref, or worktree registrations (task 8ws.t.ibk). A sentinel-based invariance test asserts the ambient repository's refs, registrations, and files stay untouched, and fixture journals cover absent, seed-only, and stale-checkout states.
+
+## [0.63.0] - 2026-10-04
+
+### Added
+- Runtime-neutral fork launches: `launch_mode` gains `herdr` and `auto` detects the live terminal runtime (tmux first, then herdr; headless only outside any runtime). `TmuxControlSurfaceRunner` is replaced by the contract-backed `RuntimeControlSurfaceRunner`; fork windows/panes, sends, captures, and session metadata are runtime-neutral (`runtime`/`session`/`window`/`window_id`/`pane` replace the `tmux_*` metadata keys), and `--callback` works under herdr. Fork children now receive `ACE_RUNTIME` instead of `ACE_TMUX_SESSION` propagation, and the drive workflow callback rule prescribes `ace-runtime send`.
+- New dependency: `ace-runtime` (~> 0.1); `ace-tmux` is kept to install the tmux adapter.
+
 ## [0.62.0] - 2026-10-04
 
 ### Added
 - **Lock-scoped external attempt authority (spec 8wq.t.34i)**: `AttemptCoordinator#with_verified_attempt` verifies that a managed attempt is live (reserved/running — uncertainty never grants external authority), bound to the exact assignment/project, and owned by the requesting actor, holding the assignment `LifecycleExclusion` shared side across the caller's whole locked transition. `finish` and `reconcile` hold the exclusive side across their terminal commits, so a liveness check can never observe an attempt as active after the terminal event landed (and vice versa). This is the authority behind ace-hitl's managed HITL request binding.
 
-
 ## [0.61.1] - 2026-10-02
 
 ### Fixed

data/README.md

@@ -32,7 +32,7 @@ hidden: 66 | done: 64 active: 1 pending: 5 failed: 1
 Use `ace-assign status --mode full` when you need the whole tree, and `ace-assign step` when you need the raw instructions for the current or next step.
 
 
-The easiest way to start is through [ace-overseer](../ace-overseer) -- define a task and run `ace-overseer work-on --task <ref> --preset work-on-task` , which creates the assignment, worktree, and tmux window in one shot.
+The easiest way to start is through [ace-overseer](../ace-overseer) -- define a task and run `ace-overseer work-on --task <ref> --preset work-on-task` , which creates the assignment, worktree, and terminal window in one shot.
 
 ## Testing Contract
 

data/docs/usage.md

@@ -286,28 +286,27 @@ Options:
 - `--provider <provider:model>`
 - `--cli-args <args>`
 - `--timeout <seconds>`
-- `--launch-mode auto|headless|tmux`
+- `--launch-mode auto|headless|tmux|herdr`
 - `--callback`
 - `--quiet, -q`
 - `--debug, -d`
 
 Launch modes:
 
-- `auto` (default): use tmux when the current process is already inside tmux or `ACE_TMUX_SESSION` is set; otherwise use the headless subprocess path
-- `headless`: force the existing provider subprocess path and never create tmux panes
-- `tmux`: require tmux context, create or reuse `<origin-window>-fs`, start a real interactive agent in a pane there via `ace-llm --interactive`, and send the scoped `/as-assign-drive <assignment>@<root>` handoff automatically. The fork window name uses the shared `ace-tmux` safe-name policy, so punctuation in the base window is replaced with `-`. Fork windows and panes are created detached, so the current tmux focus stays where the user left it.
-- `tmux`: require tmux context, create or reuse `<origin-window>-fs`, start a real interactive agent in a pane there via `ace-llm --interactive`, and send the scoped `/as-assign-drive <assignment>@<root>` handoff automatically
+- `auto` (default): use the detected terminal runtime — tmux when the current process is inside tmux or `ACE_TMUX_SESSION` is set (tmux wins when both are live), herdr when `HERDR_SESSION` + `HERDR_PANE` are live; with no runtime detected, use the headless subprocess path (assign is the only consumer with a headless fallback)
+- `headless`: force the existing provider subprocess path and never create terminal panes
+- `tmux`: require a live tmux context, create or reuse `<origin-window>-fs` through the `ace-runtime` contract, start a real interactive agent in a prepared pane via `ace-llm --interactive`, and send the scoped `/as-assign-drive <assignment>@<root>` handoff automatically
+- `herdr`: the same flow through the Herdr adapter — the fork opens as a tab in the caller's live Herdr workspace and the child inherits `HERDR_*` plus `ACE_RUNTIME=herdr`
 
-  - This mode consumes the shared `ace-tmux` runtime/control surface for tmux targeting, pane dispatch, and diagnostics.
-  - The fork window name uses the shared `ace-tmux` safe-name policy, so punctuation in the base window is replaced with `-`.
-  - Fork windows and panes are created detached, so the current tmux focus stays where the user left it.
+  - All terminal targeting, pane dispatch, and capture go through the runtime-neutral `ace-runtime` contract; the fork window name uses the shared `ace-runtime` safe-name policy, so punctuation in the base window is replaced with `-`.
+  - Fork windows/panes and herdr tabs are created detached, so the current focus stays where the user left it.
   - Assignment step state remains the source of truth for subtree completion or failure; pane capture is diagnostic support only.
 
 Callback mode:
 
-- `--callback`: tmux-only fork mode that captures the pane where `fork-run` was started and passes it into the child fork session as `ACE_ASSIGN_CALLBACK_PANE`
-- In callback mode the child agent is instructed to send one final status sentence back to the origin pane with `ace-tmux send` before stopping
-- Callback mode is intended for interactive parent/child agent tmux flows where the parent stays idle until the child sends the final message back
+- `--callback`: terminal-only fork mode (requires `tmux` or `herdr` launch mode) that captures the pane where `fork-run` was started and passes it into the child fork session as `ACE_ASSIGN_CALLBACK_PANE`
+- In callback mode the child agent is instructed to send one final status sentence back to the origin pane with `ace-runtime send` before stopping
+- Callback mode is intended for interactive parent/child agent flows where the parent stays idle until the child sends the final message back
 
 Launch-mode precedence for fork execution:
 

data/handbook/workflow-instructions/assign/drive.wf.md

@@ -442,21 +442,21 @@ After launching `ace-assign fork-run`, the driver remains inside the same drive
 
 When `ACE_ASSIGN_CALLBACK_PANE` is present in the forked child environment:
 
-- before stopping for either success or failure, send one final sentence back to the origin pane with direct `ace-tmux send`
+- before stopping for either success or failure, send one final sentence back to the origin pane with direct `ace-runtime send`
 - use the exact pane target from `ACE_ASSIGN_CALLBACK_PANE`
 - use a success sentence shaped like:
 
   ```bash
-  ace-tmux send --pane "$ACE_ASSIGN_CALLBACK_PANE" --msg "Fork subtree ${FORK_ROOT} for assignment ${ASSIGNMENT_ID} completed. Resume parent assignment drive now." --key Enter
+  ace-runtime send --pane "$ACE_ASSIGN_CALLBACK_PANE" --msg "Fork subtree ${FORK_ROOT} for assignment ${ASSIGNMENT_ID} completed. Resume parent assignment drive now." --key Enter
   ```
 
 - use a failure sentence shaped like:
 
   ```bash
-  ace-tmux send --pane "$ACE_ASSIGN_CALLBACK_PANE" --msg "Fork subtree ${FORK_ROOT} for assignment ${ASSIGNMENT_ID} failed. Resume parent assignment drive and inspect scoped status." --key Enter
+  ace-runtime send --pane "$ACE_ASSIGN_CALLBACK_PANE" --msg "Fork subtree ${FORK_ROOT} for assignment ${ASSIGNMENT_ID} failed. Resume parent assignment drive and inspect scoped status." --key Enter
   ```
 
-- do not invent a new skill or wrapper for this callback; use `ace-tmux send` directly
+- do not invent a new skill or wrapper for this callback; use `ace-runtime send` directly
 
 #### Post-Fork Resume Checklist
 

data/lib/ace/assign/cli/commands/fork_run.rb

@@ -21,8 +21,8 @@ module Ace
           option :provider, desc: "LLM provider:model override (e.g., codex:gpt-5, claude:sonnet)"
           option :cli_args, desc: "Extra CLI args for provider process"
           option :timeout, type: :integer, desc: "Execution timeout in seconds"
-          option :launch_mode, desc: "Launch mode: auto, headless, or tmux"
-          option :callback, type: :boolean, default: false, desc: "Capture the origin tmux pane and let the forked agent send a final callback message there"
+          option :launch_mode, desc: "Launch mode: auto, headless, tmux, or herdr"
+          option :callback, type: :boolean, default: false, desc: "Capture the origin pane and let the forked agent send a final callback message there"
           option :quiet, aliases: ["-q"], type: :boolean, default: false, desc: "Suppress non-essential output"
           option :debug, aliases: ["-d"], type: :boolean, default: false, desc: "Show debug output"
 
@@ -225,13 +225,13 @@ module Ace
           def resolve_callback_pane(callback_enabled, launch_mode)
             return nil unless callback_enabled
 
-            unless launch_mode == "tmux"
-              raise Error, "--callback requires tmux launch mode so the origin pane can be addressed."
+            unless Molecules::ForkSessionLauncher::TERMINAL_LAUNCH_MODES.include?(launch_mode)
+              raise Error, "--callback requires a terminal launch mode (tmux or herdr) so the origin pane can be addressed."
             end
 
-            pane = launcher.respond_to?(:callback_pane) ? launcher.callback_pane : nil
+            pane = launcher.respond_to?(:callback_pane) ? launcher.callback_pane(runtime: launch_mode) : nil
             pane = pane.to_s.strip
-            raise Error, "--callback requires a resolvable origin tmux pane." if pane.empty?
+            raise Error, "--callback requires a resolvable origin pane." if pane.empty?
 
             pane
           end

data/lib/ace/assign/cli.rb

@@ -40,7 +40,7 @@ require_relative "molecules/step_writer"
 require_relative "molecules/step_renumberer"
 require_relative "molecules/skill_assign_source_resolver"
 require_relative "molecules/fork_session_launcher"
-require_relative "molecules/tmux_control_surface_runner"
+require_relative "molecules/runtime_control_surface_runner"
 require_relative "molecules/preset_inferrer"
 require_relative "molecules/evidence_calculator"
 require_relative "molecules/evidence_journal"

data/lib/ace/assign/molecules/fork_session_launcher.rb

@@ -11,8 +11,9 @@ module Ace
         DEFAULT_PROVIDER = "claude:sonnet"
         DEFAULT_TIMEOUT = 1800
         DEFAULT_LAUNCH_MODE = "auto"
-        VALID_LAUNCH_MODES = %w[auto headless tmux].freeze
-        TMUX_POLL_INTERVAL = 0.5
+        VALID_LAUNCH_MODES = %w[auto headless tmux herdr].freeze
+        TERMINAL_LAUNCH_MODES = %w[tmux herdr].freeze
+        SUBTREE_POLL_INTERVAL = 0.5
         DEFAULT_TARGET_ENV = "ACE_ASSIGN_DEFAULT_TARGET"
         CURRENT_ASSIGNMENT_ID_ENV = "ACE_ASSIGN_CURRENT_ASSIGNMENT_ID"
         CURRENT_FORK_ROOT_ENV = "ACE_ASSIGN_CURRENT_FORK_ROOT"
@@ -35,18 +36,11 @@ module Ace
             env[CURRENT_FORK_ROOT_ENV].to_s.strip == root_ref
         end
 
-        def initialize(config: nil, query_interface: Ace::LLM::QueryInterface, tmux_runner: nil, interactive_builder: nil)
-          @config = config || Ace::Assign.config
-          @query_interface = query_interface
-          @tmux_runner = tmux_runner || TmuxControlSurfaceRunner.new
-          @interactive_builder = interactive_builder || Ace::LLM::Molecules::InteractiveCommandBuilder.new
-        end
-
-        def initialize(config: nil, query_interface: Ace::LLM::QueryInterface, tmux_runner: nil, interactive_builder: nil,
+        def initialize(config: nil, query_interface: Ace::LLM::QueryInterface, runner: nil, interactive_builder: nil,
           lifecycle_exclusion: nil)
           @config = config || Ace::Assign.config
           @query_interface = query_interface
-          @tmux_runner = tmux_runner || TmuxControlSurfaceRunner.new
+          @runner = runner || RuntimeControlSurfaceRunner.new
           @interactive_builder = interactive_builder || Ace::LLM::Molecules::InteractiveCommandBuilder.new
           @lifecycle_exclusion = lifecycle_exclusion
         end
@@ -62,31 +56,32 @@ module Ace
           # marker fails the launch closed instead of writing into a deleted
           # assignment.
           lifecycle_exclusion.with_shared(lifecycle_exclusion.assignment_key(assignment_id)) do
-            if resolved_mode == "tmux"
-              launch_tmux(
+            if resolved_mode == "headless"
+              launch_provider_session(
                 assignment_id: assignment_id,
                 fork_root: fork_root,
                 provider: resolved_provider,
                 cli_args: cli_args,
                 timeout: resolved_timeout,
-                cache_dir: cache_dir,
-                callback_pane: callback_pane
+                cache_dir: cache_dir
               )
             else
-              launch_provider_session(
+              launch_in_runtime(
+                runtime: resolved_mode,
                 assignment_id: assignment_id,
                 fork_root: fork_root,
                 provider: resolved_provider,
                 cli_args: cli_args,
                 timeout: resolved_timeout,
-                cache_dir: cache_dir
+                cache_dir: cache_dir,
+                callback_pane: callback_pane
               )
             end
           end
         end
 
-        def callback_pane
-          tmux_runner.current_pane
+        def callback_pane(runtime: nil)
+          runtime_runner_for(runtime).current_pane
         end
 
         def launch_provider_session(assignment_id:, fork_root:, provider:, cli_args: nil, timeout: nil, cache_dir: nil,
@@ -124,7 +119,7 @@ module Ace
 
         private
 
-        attr_reader :config, :query_interface, :tmux_runner, :interactive_builder
+        attr_reader :config, :query_interface, :runner, :interactive_builder
 
         def lifecycle_exclusion
           @lifecycle_exclusion ||= Molecules::LifecycleExclusion.new
@@ -140,36 +135,35 @@ module Ace
 
           return mode unless mode == "auto"
 
-          tmux_runner.tmux_context? ? "tmux" : "headless"
+          # Assign is the only consumer whose auto mode selects headless,
+          # and only when no terminal runtime is detected (k86.3 spec).
+          runner.detect_runtime || "headless"
         end
 
-        def launch_tmux(assignment_id:, fork_root:, provider:, cli_args:, timeout:, cache_dir:, callback_pane: nil)
+        def launch_in_runtime(runtime:, assignment_id:, fork_root:, provider:, cli_args:, timeout:, cache_dir:, callback_pane: nil)
           ensure_not_same_scoped_refork!(assignment_id: assignment_id, fork_root: fork_root)
-          session = tmux_runner.current_session
-          raise Error, "Launch mode tmux requires an active tmux session (TMUX or ACE_TMUX_SESSION)." unless session
-          raise Error, "Tmux launch requires assignment cache_dir for subtree polling." if cache_dir.to_s.strip.empty?
+          launch_runner = runtime_runner_for(runtime)
+          context = launch_runner.context
+          unless context[:in_runtime]
+            raise Error, "Launch mode #{runtime} requires a live #{runtime} runtime (run inside it or set its session environment)."
+          end
+          raise Error, "Runtime launch requires assignment cache_dir for subtree polling." if cache_dir.to_s.strip.empty?
 
-          current_window = tmux_runner.current_window
-          raise Error, "Could not resolve current tmux window for fork launch." if current_window.to_s.strip.empty?
+          origin_window = context[:window]
+          raise Error, "Could not resolve current runtime window for fork launch." if origin_window.to_s.strip.empty?
 
           fork_window = ENV["ACE_ASSIGN_FORK_WINDOW"].to_s.strip
-          fork_window = tmux_runner.fork_window_name(current_window) if fork_window.empty?
+          fork_window = launch_runner.fork_window_name(origin_window) if fork_window.empty?
 
-          window_info = tmux_runner.ensure_window(session: session, name: fork_window, root: Dir.pwd)
-          pane_target = tmux_runner.prepare_pane(
-            session: session,
-            window: fork_window,
-            window_target: window_info[:target],
-            root: Dir.pwd,
-            keep_existing: window_info[:created]
-          )
+          window = launch_runner.ensure_window(name: fork_window, root: Dir.pwd)
+          pane_target = launch_runner.prepare_pane(window: fork_window)
 
           session_meta_file = build_session_meta_file(cache_dir, fork_root)
           prompt = "/as-assign-drive #{assignment_id}@#{fork_root}"
-          tmux_env = tmux_subprocess_env(
+          subprocess_env = runtime_subprocess_env(
+            runtime: runtime,
             assignment_id: assignment_id,
             fork_root: fork_root,
-            session: session,
             fork_window: fork_window,
             callback_pane: callback_pane
           )
@@ -178,32 +172,32 @@ module Ace
             prompt: prompt,
             cli_args: cli_args,
             working_dir: Dir.pwd,
-            subprocess_env: tmux_env
+            subprocess_env: subprocess_env
           )
 
-          tmux_runner.run_invocation_in_pane(
+          launch_runner.run_invocation_in_pane(
             pane_target: pane_target,
             command: invocation[:command],
             env: invocation[:env],
             working_dir: invocation[:working_dir],
             visible_handoff: invocation[:prompt]
           )
-          write_tmux_launch_metadata(
+          write_runtime_launch_metadata(
             session_meta_file: session_meta_file,
             provider: invocation[:provider],
             model: invocation[:model],
             prompt: invocation[:prompt]
           )
-          tmux_runner.merge_tmux_metadata(
+          launch_runner.merge_runtime_metadata(
             session_meta_file: session_meta_file,
-            session: session,
+            session: context[:session],
             window: fork_window,
             pane: pane_target,
-            window_id: window_info[:window_id],
+            window_id: window,
             callback_pane: callback_pane
           )
 
-          return {tmux: true, pane_target: pane_target, callback_mode: true, callback_pane: callback_pane} if callback_pane
+          return {runtime: runtime, pane_target: pane_target, callback_mode: true, callback_pane: callback_pane} if callback_pane
 
           wait_for_subtree_terminal(
             assignment_id: assignment_id,
@@ -212,10 +206,10 @@ module Ace
             timeout: timeout
           )
 
-          {tmux: true, pane_target: pane_target}
+          {runtime: runtime, pane_target: pane_target}
         end
 
-        def write_tmux_launch_metadata(session_meta_file:, provider:, model:, prompt:)
+        def write_runtime_launch_metadata(session_meta_file:, provider:, model:, prompt:)
           detected = detect_provider_session(provider, prompt)
           meta = {}
           meta = YAML.safe_load_file(session_meta_file) || {} if File.exist?(session_meta_file)
@@ -278,11 +272,19 @@ module Ace
             "Cannot fork-run subtree #{assignment_id}@#{fork_root}: already running inside that scoped subtree. Continue inline instead of calling fork-run again."
         end
 
-        def tmux_subprocess_env(assignment_id:, fork_root:, session:, fork_window:, callback_pane: nil)
+        def runtime_runner_for(runtime)
+          if runtime == runner.runtime_name
+            runner
+          else
+            RuntimeControlSurfaceRunner.new(runtime: runtime)
+          end
+        end
+
+        def runtime_subprocess_env(runtime:, assignment_id:, fork_root:, fork_window:, callback_pane: nil)
           env = self.class.fork_scope_env(assignment_id: assignment_id, fork_root: fork_root).merge(
             "PROJECT_ROOT_PATH" => Dir.pwd,
-            "ACE_TMUX_SESSION" => session,
-            "ACE_ASSIGN_LAUNCH_MODE" => "tmux",
+            "ACE_RUNTIME" => runtime,
+            "ACE_ASSIGN_LAUNCH_MODE" => runtime,
             "ACE_ASSIGN_FORK_WINDOW" => fork_window
           )
           env["ACE_ASSIGN_CALLBACK_PANE"] = callback_pane if callback_pane && !callback_pane.empty?
@@ -303,13 +305,13 @@ module Ace
           loop do
             state = scanner.scan(assignment.steps_dir, assignment: assignment)
             return state if state.subtree_complete?(fork_root)
-            raise Error, "Fork session execution failed in tmux subtree #{fork_root}." if state.subtree_failed?(fork_root)
+            raise Error, "Fork session execution failed in the #{fork_root} subtree." if state.subtree_failed?(fork_root)
 
             if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
-              raise Error, "Timed out waiting for tmux fork subtree #{fork_root} to reach a terminal state."
+              raise Error, "Timed out waiting for the fork subtree #{fork_root} to reach a terminal state."
             end
 
-            sleep(TMUX_POLL_INTERVAL)
+            sleep(SUBTREE_POLL_INTERVAL)
           end
         end
       end

data/lib/ace/assign/molecules/runtime_control_surface_runner.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+require "ace/runtime"
+require "fileutils"
+require "shellwords"
+require "yaml"
+
+module Ace
+  module Assign
+    module Molecules
+      # Contract-backed terminal helper for fork launches. Every terminal
+      # operation delegates to the resolved Ace::Runtime adapter; assign
+      # never calls a runtime-native API directly (k86.3 interface rule).
+      class RuntimeControlSurfaceRunner
+        def initialize(runtime: nil, env: ENV)
+          @runtime_name = runtime
+          @env = env
+        end
+
+        attr_reader :runtime_name, :env
+
+        def runtime
+          @runtime ||= Ace::Runtime.resolve(runtime_name || selected_name)
+        end
+
+        def context
+          runtime.context
+        end
+
+        # Side-effect-free runtime detection ("tmux", "herdr", or nil) for
+        # the assign auto launch mode.
+        def detect_runtime
+          detected = Ace::Runtime.detect(env: env)
+          detected&.to_s
+        end
+
+        def in_runtime?
+          context[:in_runtime] ? true : false
+        end
+
+        def current_session
+          context[:session]
+        end
+
+        def current_pane
+          explicit = env["ACE_ASSIGN_CALLBACK_PANE"].to_s.strip
+          return explicit unless explicit.empty?
+
+          context[:pane]
+        end
+
+        def fork_window_name(base_window)
+          base = base_window.to_s.strip.sub(/-fs\z/, "")
+
+          "#{Ace::Runtime.sanitize_name(base, fallback: "fork")}-fs"
+        end
+
+        def ensure_window(name:, root:)
+          runtime.ensure_window(name: name, root: root)
+        rescue Ace::Runtime::Error => e
+          raise Error, "Failed to ensure fork window #{name}: #{e.message}"
+        end
+
+        def prepare_pane(window:)
+          runtime.prepare_pane(window: window)
+        rescue Ace::Runtime::Error => e
+          raise Error, "Failed to prepare fork pane in #{window}: #{e.message}"
+        end
+
+        def run_invocation_in_pane(pane_target:, command:, env: nil, working_dir: nil, visible_handoff: nil)
+          shell_command = build_pane_shell_command(
+            command: command,
+            env: env,
+            working_dir: working_dir,
+            visible_handoff: visible_handoff
+          )
+          runtime.send_command(pane: pane_target, command: shell_command)
+        rescue Ace::Runtime::Error => e
+          raise Error, "Failed to send fork command: #{e.message}"
+        end
+
+        def run_script_in_pane(pane_target:, script_path:)
+          runtime.send_command(pane: pane_target, command: "bash #{File.expand_path(script_path).shellescape}")
+        rescue Ace::Runtime::Error => e
+          raise Error, "Failed to send fork command: #{e.message}"
+        end
+
+        def capture_recent_output(pane_target:, lines: 40)
+          runtime.capture(pane: pane_target, lines: lines)
+        rescue Ace::Runtime::Error => e
+          raise Error, "Failed to capture pane #{pane_target}: #{e.message}"
+        end
+
+        def merge_runtime_metadata(session_meta_file:, session:, window:, pane:, window_id: nil, callback_pane: nil)
+          data = if File.exist?(session_meta_file)
+            YAML.safe_load_file(session_meta_file) || {}
+          else
+            {}
+          end
+          data["launch_mode"] = runtime_name
+          data["runtime"] = runtime_name
+          data["session"] = session
+          data["window"] = window
+          data["window_id"] = window_id if window_id
+          data["pane"] = pane
+          data["callback_pane"] = callback_pane if callback_pane && !callback_pane.empty?
+          File.write(session_meta_file, data.to_yaml)
+        end
+
+        private
+
+        def selected_name
+          detected = Ace::Runtime.detect(env: env)
+          return detected.to_s if detected
+
+          raise Error, "no terminal runtime detected: run inside tmux/herdr, set ACE_RUNTIME, or pass an explicit runtime"
+        end
+
+        def build_pane_shell_command(command:, env:, working_dir:, visible_handoff:)
+          steps = []
+          resolved_working_dir = working_dir.to_s.strip
+          steps << "cd #{Shellwords.escape(File.expand_path(resolved_working_dir))}" unless resolved_working_dir.empty?
+
+          handoff = visible_handoff.to_s
+          steps << "printf '%s\\n' #{Shellwords.escape(handoff)}" unless handoff.empty?
+
+          # The prepared pane owns a retained interactive shell. Run the
+          # invocation as its child so another submission can use the same
+          # target after this command exits.
+          steps << build_exec_command(command: command, env: env)
+          steps.join(" && ")
+        end
+
+        def build_exec_command(command:, env:)
+          cmd = Array(command).map { |part| Shellwords.escape(part.to_s) }.join(" ")
+          env_hash = env.respond_to?(:to_h) ? env.to_h : {}
+          unset_parts = []
+          assign_parts = []
+
+          env_hash.each do |key, value|
+            next if key.to_s.strip.empty?
+
+            if value.nil?
+              unset_parts << "-u #{Shellwords.escape(key.to_s)}"
+            else
+              assign_parts << "#{key}=#{Shellwords.escape(value.to_s)}"
+            end
+          end
+          env_parts = unset_parts + assign_parts
+
+          return cmd if env_parts.empty?
+
+          "env #{env_parts.join(' ')} #{cmd}"
+        end
+      end
+    end
+  end
+end

data/lib/ace/assign/version.rb

@@ -2,6 +2,6 @@
 
 module Ace
   module Assign
-    VERSION = "0.62.0"
+    VERSION = "0.63.1"
   end
 end

data/lib/ace/assign.rb

@@ -5,7 +5,7 @@ require "ace/support/config"
 require "ace/support/fs"
 require "ace/support/nav"
 require "ace/support/cli"
-require "ace/tmux"
+require "ace/runtime"
 require "pathname"
 
 # CLI and commands

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ace-assign
 version: !ruby/object:Gem::Version
-  version: 0.62.0
+  version: 0.63.1
 platform: ruby
 authors:
 - Michal Czyz
@@ -135,6 +135,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.37'
+- !ruby/object:Gem::Dependency
+  name: ace-runtime
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
 - !ruby/object:Gem::Dependency
   name: ace-tmux
   requirement: !ruby/object:Gem::Requirement
@@ -149,6 +163,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.18'
+- !ruby/object:Gem::Dependency
+  name: ace-herdr
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.3.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.3.2
 - !ruby/object:Gem::Dependency
   name: ace-support-test-helpers
   requirement: !ruby/object:Gem::Requirement
@@ -344,10 +372,10 @@ files:
 - lib/ace/assign/molecules/preset_inferrer.rb
 - lib/ace/assign/molecules/queue_scanner.rb
 - lib/ace/assign/molecules/receipt_verifier.rb
+- lib/ace/assign/molecules/runtime_control_surface_runner.rb
 - lib/ace/assign/molecules/skill_assign_source_resolver.rb
 - lib/ace/assign/molecules/step_renumberer.rb
 - lib/ace/assign/molecules/step_writer.rb
-- lib/ace/assign/molecules/tmux_control_surface_runner.rb
 - lib/ace/assign/organisms/assignment_executor.rb
 - lib/ace/assign/organisms/attempt_coordinator.rb
 - lib/ace/assign/organisms/task_assignment_creator.rb

data/lib/ace/assign/molecules/tmux_control_surface_runner.rb

@@ -1,249 +0,0 @@
-# frozen_string_literal: true
-
-require "ace/tmux"
-require "fileutils"
-require "shellwords"
-require "yaml"
-
-module Ace
-  module Assign
-    module Molecules
-      # Shared ace-tmux backed runtime helper for tmux fork launches.
-      class TmuxControlSurfaceRunner
-        def initialize(executor: Ace::Tmux::Molecules::TmuxExecutor.new, resolver: nil, control_surface: nil, tmux: "tmux", env: ENV)
-          @executor = executor
-          @tmux = tmux
-          @env = env
-          @resolver = resolver || Ace::Tmux::Molecules::RuntimeTargetResolver.new(executor: executor, tmux: tmux, env: env)
-          @control_surface = control_surface || Ace::Tmux::Organisms::ControlSurface.new(
-            executor: executor,
-            resolver: @resolver,
-            tmux: tmux
-          )
-        end
-
-        def tmux_context?
-          !current_session.to_s.strip.empty?
-        end
-
-        def current_session
-          resolver.resolve_session.session
-        rescue Ace::Tmux::TargetResolutionError
-          nil
-        end
-
-        def current_window
-          explicit = env["ACE_ASSIGN_FORK_WINDOW"].to_s.strip
-          return explicit unless explicit.empty?
-
-          resolver.resolve_window(session: current_session).window
-        rescue Ace::Tmux::TargetResolutionError
-          nil
-        end
-
-        def current_pane
-          explicit = env["ACE_ASSIGN_CALLBACK_PANE"].to_s.strip
-          return explicit unless explicit.empty?
-
-          resolver.resolve_pane(session: current_session, window: current_window).pane_target
-        rescue Ace::Tmux::TargetResolutionError
-          nil
-        end
-
-        def fork_window_name(base_window)
-          base = base_window.to_s.strip.sub(/-fs\z/, "")
-          sanitized = Ace::Tmux::Atoms::WindowNameSanitizer.call(base, fallback: "fork")
-
-          "#{sanitized}-fs"
-        end
-
-        def ensure_window(session:, name:, root:)
-          if (window_id = find_window_id(session: session, name: name))
-            return {created: false, target: window_id, window_id: window_id, name: name}
-          end
-
-          result = executor.capture(
-            Ace::Tmux::Atoms::TmuxCommandBuilder.new_window(
-              session,
-              name: name,
-              root: root,
-              print_format: '#{window_id}',
-              tmux: tmux
-            )
-          )
-          raise Error, "Failed to create tmux fork window #{name}: #{result.stderr}" unless result.success?
-
-          window_id = result.stdout.to_s.strip
-          raise Error, "Failed to create tmux fork window #{name}: empty window id" if window_id.empty?
-
-          {created: true, target: window_id, window_id: window_id, name: name}
-        end
-
-        def prepare_pane(session:, window:, root:, keep_existing:, window_target: nil)
-          target = window_target || "#{session}:#{window}"
-          pane = if keep_existing
-            first_pane(target)
-          else
-            create_pane(target, root)
-          end
-
-          set_pane_remain_on_exit(pane)
-          select_layout(target)
-          pane
-        end
-
-        def select_window(session:, window:, window_target: nil)
-          target = window_target || "#{session}:#{window}"
-          run!(
-            Ace::Tmux::Atoms::TmuxCommandBuilder.select_window(target, tmux: tmux),
-            "select tmux fork window #{window}"
-          )
-        end
-
-        def run_invocation_in_pane(pane_target:, command:, env: nil, working_dir: nil, visible_handoff: nil)
-          shell_command = build_pane_shell_command(
-            command: command,
-            env: env,
-            working_dir: working_dir,
-            visible_handoff: visible_handoff
-          )
-          control_surface.send_command(pane: pane_target, command: shell_command)
-        rescue Ace::Tmux::Error => e
-          raise Error, "Failed to send tmux fork command: #{e.message}"
-        end
-
-        def run_script_in_pane(pane_target:, script_path:)
-          control_surface.send_command(pane: pane_target, command: "bash #{File.expand_path(script_path).shellescape}")
-        rescue Ace::Tmux::Error => e
-          raise Error, "Failed to send tmux fork command: #{e.message}"
-        end
-
-        def capture_recent_output(pane_target:, lines: 40)
-          control_surface.capture_recent_output(pane: pane_target, lines: lines)
-        rescue Ace::Tmux::Error => e
-          raise Error, "Failed to capture pane #{pane_target}: #{e.message}"
-        end
-
-        def merge_tmux_metadata(session_meta_file:, session:, window:, pane:, window_id: nil, callback_pane: nil)
-          data = if File.exist?(session_meta_file)
-            YAML.safe_load_file(session_meta_file) || {}
-          else
-            {}
-          end
-          data["launch_mode"] = "tmux"
-          data["tmux_session"] = session
-          data["tmux_window"] = window
-          data["tmux_window_id"] = window_id if window_id
-          data["tmux_pane_id"] = pane
-          data["callback_pane"] = callback_pane if callback_pane && !callback_pane.empty?
-          File.write(session_meta_file, data.to_yaml)
-        end
-
-        private
-
-        attr_reader :control_surface, :env, :executor, :resolver, :tmux
-
-        def find_window_id(session:, name:)
-          result = executor.capture(
-            Ace::Tmux::Atoms::TmuxCommandBuilder.list_windows(
-              session,
-              format: '#{window_id}' + "\t" + '#{window_name}',
-              tmux: tmux
-            )
-          )
-          return nil unless result.success?
-
-          result.stdout.split("\n").map(&:strip).reject(&:empty?).each do |line|
-            window_id, window_name = line.split("\t", 2)
-            return window_id if window_name == name && !window_id.to_s.empty?
-          end
-
-          nil
-        end
-
-        def first_pane(target)
-          result = executor.capture(
-            Ace::Tmux::Atoms::TmuxCommandBuilder.list_panes(target, format: '#{pane_id}', tmux: tmux)
-          )
-          raise Error, "Failed to inspect panes for #{target}: #{result.stderr}" unless result.success?
-
-          pane = result.stdout.split("\n").map(&:strip).reject(&:empty?).first
-          raise Error, "No panes found for #{target}" if pane.to_s.empty?
-
-          pane
-        end
-
-        def create_pane(target, root)
-          result = executor.capture(
-            Ace::Tmux::Atoms::TmuxCommandBuilder.split_window(
-              target,
-              root: root,
-              print_format: '#{pane_id}',
-              tmux: tmux
-            )
-          )
-          raise Error, "Failed to create tmux fork pane in #{target}: #{result.stderr}" unless result.success?
-
-          pane = result.stdout.to_s.strip
-          raise Error, "Failed to create tmux fork pane in #{target}: empty pane id" if pane.empty?
-
-          pane
-        end
-
-        def set_pane_remain_on_exit(pane_target)
-          run!(
-            Ace::Tmux::Atoms::TmuxCommandBuilder.set_pane_option(pane_target, "remain-on-exit", "on", tmux: tmux),
-            "enable remain-on-exit"
-          )
-        end
-
-        def select_layout(target)
-          run!(
-            Ace::Tmux::Atoms::TmuxCommandBuilder.select_layout(target, "tiled", tmux: tmux),
-            "apply tiled layout"
-          )
-        end
-
-        def run!(cmd, action)
-          return if executor.run(cmd)
-
-          raise Error, "Failed to #{action}"
-        end
-
-        def build_pane_shell_command(command:, env:, working_dir:, visible_handoff:)
-          steps = []
-          resolved_working_dir = working_dir.to_s.strip
-          steps << "cd #{Shellwords.escape(File.expand_path(resolved_working_dir))}" unless resolved_working_dir.empty?
-
-          handoff = visible_handoff.to_s
-          steps << "printf '%s\\n' #{Shellwords.escape(handoff)}" unless handoff.empty?
-
-          steps << "exec #{build_exec_command(command: command, env: env)}"
-          steps.join(" && ")
-        end
-
-        def build_exec_command(command:, env:)
-          cmd = Array(command).map { |part| Shellwords.escape(part.to_s) }.join(" ")
-          env_hash = env.respond_to?(:to_h) ? env.to_h : {}
-          unset_parts = []
-          assign_parts = []
-
-          env_hash.each do |key, value|
-            next if key.to_s.strip.empty?
-
-            if value.nil?
-              unset_parts << "-u #{Shellwords.escape(key.to_s)}"
-            else
-              assign_parts << "#{key}=#{Shellwords.escape(value.to_s)}"
-            end
-          end
-          env_parts = unset_parts + assign_parts
-
-          return cmd if env_parts.empty?
-
-          "env #{env_parts.join(' ')} #{cmd}"
-        end
-      end
-    end
-  end
-end