harnex 0.12.0 → 0.29.0

data/lib/harnex/cli.rb

@@ -37,6 +37,24 @@ module Harnex
         AgentsGuide.new(@argv.drop(1)).run
       when "doctor"
         Doctor.new(@argv.drop(1)).run
+      when "preflight"
+        Preflight.new(@argv.drop(1)).run
+      when "ask"
+        Ask.new(@argv.drop(1)).run
+      when "delegate"
+        Delegate.new(@argv.drop(1)).run
+      when "result"
+        LaneResult.new(@argv.drop(1)).run
+      when "reply"
+        Reply.new(@argv.drop(1)).run
+      when "land"
+        Land.new(@argv.drop(1)).run
+      when "discard"
+        Land.new(@argv.drop(1), discard: true).run
+      when "lanes"
+        LanesCommand.new(@argv.drop(1)).run
+      when "mcp"
+        MCPCommand.new(@argv.drop(1)).run
       when "orchestration"
         OrchestrationCommand.new(@argv.drop(1)).run
       when "artifact-report"
@@ -89,6 +107,24 @@ module Harnex
         AgentsGuide.usage
       when "doctor"
         Doctor.usage
+      when "preflight"
+        Preflight.usage
+      when "ask"
+        Ask.usage
+      when "delegate"
+        Delegate.usage
+      when "result"
+        LaneResult.usage
+      when "reply"
+        Reply.usage
+      when "land"
+        Land.usage
+      when "discard"
+        Land.usage(discard: true)
+      when "lanes"
+        LanesCommand.usage
+      when "mcp"
+        MCPCommand.usage
       when "orchestration"
         OrchestrationCommand.usage
       when "artifact-report"
@@ -102,7 +138,23 @@ module Harnex
 
     def usage
       <<~TEXT
-        Usage:
+        harnex: Pi workers (GPT models) as tools for you and your agents.
+
+        Hand work to a worker (each runs in a visible tmux window):
+          harnex ask QUESTION                 A read-only answer from another model
+          harnex delegate [--worktree NAME] TASK
+                                              A worker does the task; prints its reply
+          harnex delegate --no-wait ...       Start lanes in parallel, then:
+          harnex result [NAME...]             Wait for lanes and print their results
+          harnex reply NAME MESSAGE           Follow up; the worker keeps its context
+          harnex land [NAME...]               Merge worktree lanes, remove the worktrees
+          harnex discard NAME                 Drop a lane and its worktree
+          harnex lanes                        Your lanes and what each needs next
+
+          Blocking commands wait 9m by default and exit 124 if the worker is still
+          going; run `harnex result NAME` to keep waiting. Exit 0 done, 1 failed.
+
+        Low-level session control:
           harnex run <cli> [options] [--] [cli-args...]
           harnex send --id ID [options] [text...]
           harnex wait --id ID [options]
@@ -113,61 +165,27 @@ module Harnex
           harnex events --id ID [options]
           harnex history [options]
           harnex pane --id ID [options]
-          harnex agents-guide [topic]
-          harnex doctor
+
+        The same verbs as native MCP tools (Claude Code, Pi):
+          harnex mcp install                  Register the harnex MCP server
+          harnex mcp                          Serve MCP over stdio (clients run this)
+
+        Setup, docs and telemetry:
+          harnex doctor                       Check Pi and harnex setup
+          harnex preflight ADAPTER [options]  Prove an adapter with one tiny dispatch
+          harnex agents-guide [topic]         Agent guides (dispatch, chain, buddy, monitoring, naming, claude)
+          harnex guide | recipes              Getting started; workflow recipes
           harnex orchestration sample|report [options]
           harnex artifact-report init|validate PATH [options]
           harnex telemetry assert-canonical|reconcile [options]
           harnex help [command]
 
-        Commands:
-          run     Start a wrapped interactive session and local API
-          send    Send text to an active session
-          wait    Block until a session exits or reaches a state
-          watch   Safely watch existing work until done/task_failed/timeout
-          stop    Send the adapter stop sequence to a session
-          status  List live sessions
-          logs    Read session output transcripts
-          events  Stream per-session JSONL runtime events
-          history List completed dispatches from .harnex/dispatch.jsonl
-          pane    Capture the current tmux pane for a live session
-          recipes List and read workflow recipes
-          guide   Show the getting started guide
-          agents-guide
-                  Show agent dispatch, chain, buddy, monitoring, and naming guides
-          doctor  Run preflight checks and optional read-only session sweep
-          orchestration
-                  Emit external primary samples and report orchestration tax
-          artifact-report
-                  Validate harness-authored receipts or initialize legacy v1 documents
-          telemetry
-                  Assert or reconcile canonical dispatch telemetry
-          help    Show command help
-
-        New to harnex? Start with: harnex guide
-        Working with agents (dispatching tasks)? Read: harnex agents-guide
-
-        Notes:
-          CLIs with smart prompt detection: #{Adapters.known.join(', ')}
-          Any other CLI name is launched with generic wrapping.
-
         Examples:
-          harnex run pi
-          harnex run aider --id blue-cat
-          harnex run codex -- --cd /path/to/repo
-          harnex status
-          harnex watch --id main --until done --max-wait 15m
-          harnex logs --id main --follow
-          harnex events --id main --snapshot
-          harnex history --limit 20
-          harnex pane --id main --lines 40
-          harnex agents-guide dispatch
-          harnex doctor
-          harnex orchestration report --dispatch .harnex/dispatch.jsonl --run-id queue-005 --json
-          harnex artifact-report validate /path/from-dispatch-row.json --final
-          harnex artifact-report init .harnex/reports/legacy-v1.json
-          harnex telemetry assert-canonical --canonical .harnex/dispatch.jsonl --json
-          harnex send --id main --message "Summarize current progress."
+          harnex ask "Where is the dispatch row written, and is that path tested?"
+          harnex delegate --worktree word-count "Add TextKit.word_count with a test"
+          harnex land word-count
+          harnex delegate --no-wait --worktree fix-a "Fix A"; harnex delegate --no-wait --worktree fix-b "Fix B"; harnex result
+          harnex run pi --tmux pi-i-42 --id pi-i-42 --context-file /tmp/task-42.md
       TEXT
     end
   end

data/lib/harnex/commands/ask.rb

@@ -0,0 +1,278 @@
+require "fileutils"
+require "json"
+require "open3"
+require "securerandom"
+require "shellwords"
+
+module Harnex
+  # `harnex ask` (#85): hand one question to a Pi worker (a GPT or other
+  # provider model) and print its answer, so a Claude session consults
+  # another model the way it calls any tool. Read-only by default; the
+  # dispatch is a normal harnex run (tmux window, receipt, dispatch rows).
+  class Ask
+    READ_ONLY_TOOLS = "read,grep,find,ls".freeze
+    INTENT = "ask".freeze
+
+    def self.usage
+      <<~TEXT
+        Usage: harnex ask [options] [--] QUESTION...
+               harnex ask --file PATH [--section TEXT] [options]
+               harnex ask --resume ID [--timeout DUR] [--json]
+
+        Ask a Pi worker one question and print its answer on stdout. The worker
+        runs in a visible tmux window, reads the repository (it cannot run
+        commands unless --write; to run things use `harnex delegate`), and stops
+        when it has answered. stderr gets one line naming the lane, its time and model.
+        A read-only ask records its dispatch in the global harnex stream, so the
+        repository stays untouched; --write records in the repository.
+
+        Options:
+          --model NAME     Pi model (provider/model); default: Pi's own default
+                           (`defaultProvider`/`defaultModel` in ~/.pi/agent/settings.json)
+          --fallback-model NAME
+                           Ask once more with NAME when the first model fails on
+                           provider capacity or rate limits (provider_capacity)
+          --effort LEVEL   Reasoning effort / Pi thinking level
+          --cwd DIR        Directory the worker works in (default: current directory)
+          --file PATH      Read the question from PATH (see run --context-file)
+          --section TEXT   With --file: send only that section
+          --write          Let the worker edit files and run commands (default:
+                           read-only tools #{READ_ONLY_TOOLS})
+          --id ID          Session id (default: pi-ask-<random>)
+          --timeout DUR    Cap the wait: 540, 9m or 8m30s (default 9m; `none` waits
+                           without a cap). On 124 the worker keeps going and stderr
+                           names the command that keeps waiting (`harnex result ID`)
+          --resume ID      Same as `harnex result ID` (kept for older callers)
+          --detach         Run headless instead of in a tmux window
+          --json           Print the full result JSON instead of the answer
+          -h, --help       Show this help
+
+        Exit codes: 0 answered, 1 the worker failed (stderr says why), 2 proof
+        rejected or a usage error (usage errors print no JSON and no answer),
+        124 timeout (the worker keeps running).
+
+        Examples:
+          harnex ask "Which module parses the dispatch rows, and is it tested?"
+          harnex ask --model openai/gpt-5.1 --file /tmp/review.md --timeout 9m
+          harnex ask --write --cwd ../lane "Fix the failing test and commit"
+      TEXT
+    end
+
+    def initialize(argv, out: $stdout, err: $stderr, harnex_command: nil)
+      @argv = argv.dup
+      @out = out
+      @err = err
+      @harnex_command = harnex_command || [Gem.ruby, File.expand_path("../../../bin/harnex", __dir__)]
+      @options = { model: nil, fallback_model: nil, effort: nil, cwd: nil, file: nil, section: nil, write: false,
+                   id: nil, timeout: Lanes::DEFAULT_TIMEOUT, detach: false, json: false, help: false, resume: nil,
+                   repo: nil }
+    end
+
+    def run
+      question = parse
+      if @options[:help]
+        @out.puts self.class.usage
+        return 0
+      end
+      started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      return report(*resume_once(@options[:resume]), Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) if @options[:resume]
+
+      if question.empty? && @options[:file].nil?
+        raise OptionParser::MissingArgument, "QUESTION (or --file PATH)"
+      end
+
+      result, exit_code = ask_once(question, @options[:model], @options[:id])
+      if exit_code == 1 && @options[:fallback_model] && result.dig("turn_result", "outcome_class") == "provider_capacity"
+        @err.puts("harnex ask: #{result['id']} hit provider capacity; asking #{@options[:fallback_model]} instead")
+        retry_id = @options[:id] && "#{@options[:id]}-fallback"
+        result, exit_code = ask_once(question, @options[:fallback_model], retry_id)
+      end
+      report(result, exit_code, Process.clock_gettime(Process::CLOCK_MONOTONIC) - started)
+    end
+
+    private
+
+    # Each ask is a lane (#87), so `harnex result ID` keeps waiting on it and
+    # `harnex reply ID "..."` follows up with the worker's context.
+    def ask_once(question, model, id)
+      id ||= "pi-ask-#{SecureRandom.hex(2)}"
+      lane = register_lane(id, model)
+      stdout, status = launch(question, model, id)
+      result = parse_result(stdout)
+      Lanes.settle(lane, result["turn_result"] || {}, status.exitstatus) unless result.empty?
+      [result, status.exitstatus]
+    end
+
+    def register_lane(id, model)
+      cwd = File.expand_path(@options[:cwd] || Dir.pwd)
+      Lanes.save(
+        "name" => id, "kind" => "ask", "repo_root" => Lanes.main_root(cwd) || cwd, "run_root" => run_root,
+        "cwd" => cwd, "read_only" => !@options[:write], "owner" => Harnex.ambient_owner_id,
+        "requested_model" => model, "effort" => @options[:effort], "created_at" => Lanes.now,
+        "launched_at" => Lanes.now, "state" => "running", "turns" => 0
+      )
+    end
+
+    def launch(question, model, id)
+      argv = @harnex_command + ["run", "pi", "--id", id]
+      argv += @options[:detach] ? ["--detach"] : ["--tmux", id]
+      argv += ["--cwd", File.expand_path(@options[:cwd] || Dir.pwd)]
+      # A consult is not repository work: register and record it under a
+      # harnex-owned root (not a git repo, so rows go to the global stream).
+      argv += ["--root", ask_root] unless @options[:write]
+      if @options[:file]
+        argv += ["--context-file", @options[:file]]
+        argv += ["--context-section", @options[:section]] if @options[:section]
+      else
+        argv += ["--context", question]
+      end
+      argv += ["--auto-stop", "--wait-done", "--intent", INTENT]
+      argv += ["--wait-timeout", @options[:timeout].to_s] if @options[:timeout]
+      argv += ["--model", model] if model
+      argv += ["--effort", @options[:effort]] if @options[:effort]
+      argv += ["--", "--no-approve"]
+      argv += ["--tools", READ_ONLY_TOOLS] unless @options[:write]
+      stdout, status = Open3.capture2(*argv)
+      [stdout, status]
+    end
+
+    # A subagent's Bash call is capped at 10 minutes, so a long ask comes back
+    # 124 and the caller re-runs this until the answer lands. `wait` prints the
+    # turn result unnested; nest it so the answer is reported like a fresh ask.
+    def resume_once(id)
+      lane = begin
+        Lanes.resolve(id)
+      rescue OptionParser::InvalidArgument
+        nil
+      end
+      return legacy_resume(id) unless lane
+      return [{ "id" => id, "turn_result" => lane["last_turn"] || {} }, lane["state"] == "failed" ? 1 : 0] unless lane["state"] == "running"
+
+      turn, exit_code = Lanes.wait(lane, @harnex_command, timeout: @options[:timeout])
+      Lanes.settle(lane, turn, exit_code || 1)
+      [{ "id" => id, "turn_result" => turn }, exit_code || 1]
+    end
+
+    # Asks from before lanes (0.21.0) have no record; their resume line named --repo.
+    def legacy_resume(id)
+      raise OptionParser::InvalidArgument, "no lane named #{id.inspect}" unless @options[:repo]
+
+      argv = @harnex_command + ["wait", "--id", id, "--repo", @options[:repo], "--until", "done"]
+      argv += ["--timeout", @options[:timeout].to_s] if @options[:timeout]
+      stdout, status = Open3.capture2(*argv)
+      [{ "id" => id, "turn_result" => parse_result(stdout) }, status.exitstatus]
+    end
+
+    def resume_command(id)
+      "#{Harnex.cli_command} result #{id}"
+    end
+
+    # The root `run` records under: ask_root for a consult, the work
+    # directory for --write (run takes --cwd as the root when --root is absent).
+    def run_root
+      return @options[:repo] if @options[:resume]
+
+      @options[:write] ? File.expand_path(@options[:cwd] || Dir.pwd) : ask_root
+    end
+
+    def parse_result(stdout)
+      JSON.parse(stdout.to_s.lines.last.to_s)
+    rescue JSON::ParserError
+      {}
+    end
+
+    def ask_root
+      root = File.join(Harnex::STATE_DIR, "ask")
+      FileUtils.mkdir_p(root)
+      root
+    end
+
+    def report(result, exit_code, elapsed)
+      if @options[:json]
+        @out.puts JSON.generate(result) unless result.empty?
+        return exit_code
+      end
+
+      turn = result["turn_result"] || {}
+      answer = full_answer(turn)
+      case exit_code
+      when 0
+        @out.puts answer.to_s
+        @err.puts("harnex ask: #{result['id']} answered in #{elapsed.round}s (model #{turn['model'] || 'Pi default'})")
+      when Waiter::DONE_EXIT_TIMEOUT
+        @err.puts("harnex ask: #{result['id']} is still working; keep waiting with: #{resume_command(result['id'])}")
+      else
+        @out.puts answer unless answer.to_s.empty?
+        reason = turn["last_error"] || turn["outcome_class"] || turn["status"] || result["error"] || "no result"
+        @err.puts("harnex ask: #{result['id'] || 'the worker'} did not answer (#{reason})")
+      end
+      exit_code
+    end
+
+    def full_answer(turn)
+      path = turn["final_message_path"].to_s
+      return File.read(path).chomp if turn["final_message_truncated"] && !path.empty? && File.file?(path)
+
+      turn["final_message"]
+    rescue StandardError
+      turn["final_message"]
+    end
+
+    def parse
+      question = []
+      index = 0
+      while index < @argv.length
+        arg = @argv[index]
+        case arg
+        when "--"
+          question.concat(@argv[(index + 1)..] || [])
+          break
+        when "-h", "--help" then @options[:help] = true
+        when "--write" then @options[:write] = true
+        when "--detach" then @options[:detach] = true
+        when "--json" then @options[:json] = true
+        when "--model", "--effort", "--cwd", "--file", "--section", "--id", "--fallback-model", "--resume", "--repo"
+          @options[arg.delete_prefix("--").tr("-", "_").to_sym] = value(index += 1, arg)
+        # Habits from `harnex run` (#87): an ask already runs in a tmux window
+        # named after its id and stops after answering.
+        when "--tmux"
+          following = @argv[index + 1]
+          if following&.match?(Lanes::NAME) && !following.start_with?("-") && @argv.length > index + 2
+            @options[:id] ||= following
+            index += 1
+          end
+        when "--auto-stop", "--wait-done" then nil
+        when "--wait-timeout"
+          @options[:timeout] = Lanes.parse_timeout(value(index += 1, arg), option_name: arg)
+        when "--context" then question << value(index += 1, arg)
+        when "--context-file" then @options[:file] = value(index += 1, arg)
+        when "--timeout"
+          @options[:timeout] = Lanes.parse_timeout(value(index += 1, arg), option_name: arg)
+        when /\A--/
+          raise OptionParser::InvalidOption, "harnex ask: unknown flag #{arg}; see harnex ask --help"
+        else
+          question << arg
+        end
+        index += 1
+      end
+      if @options[:section] && @options[:file].nil?
+        raise OptionParser::InvalidOption, "harnex ask: --section requires --file"
+      end
+      if @options[:resume] && (!question.empty? || @options[:file])
+        raise OptionParser::InvalidOption, "harnex ask: --resume takes a lane id and no question"
+      end
+      if @options[:repo] && @options[:resume].nil?
+        raise OptionParser::InvalidOption, "harnex ask: --repo requires --resume"
+      end
+
+      question.join(" ")
+    end
+
+    def value(index, name)
+      value = @argv[index]
+      raise OptionParser::MissingArgument, name if value.nil? || value.start_with?("--")
+
+      value
+    end
+  end
+end

data/lib/harnex/commands/delegate.rb

@@ -0,0 +1,202 @@
+module Harnex
+  # `harnex delegate` (#87): hand one task to a Pi worker and print its
+  # reply plus a lane footer (state, time, model, cost, commits, next
+  # commands). With --worktree NAME the worker gets its own git worktree on
+  # branch harnex/NAME, so parallel lanes never touch the main checkout.
+  class Delegate
+    def self.usage
+      <<~TEXT
+        Usage: harnex delegate [options] [--] TASK...
+               harnex delegate --file PATH [options]
+
+        Hand a task to a Pi worker (a GPT model by default) and print its reply
+        and a lane summary. The worker runs in a visible tmux window, may edit
+        files and run commands, and stops when it has replied. Follow up with
+        `harnex reply NAME "..."`; it keeps the worker's context.
+
+        Options:
+          --worktree NAME  Work in a new git worktree (.harnex/worktrees/NAME, branch
+                           harnex/NAME); finish with `harnex land NAME` or
+                           `harnex discard NAME`
+          --name NAME      Lane name without a worktree (default: from the task)
+          --cwd DIR        Directory the worker works in (default: current directory)
+          --file PATH      Read the task from PATH
+          --model NAME     Pi model (provider/model); default: Pi's own default
+          --effort LEVEL   Reasoning effort / Pi thinking level
+          --no-wait        Start the lane and return at once; collect with
+                           `harnex result` (all your lanes) or `harnex result NAME`
+          --timeout DUR    Wait at most DUR (default 9m, fits a 10-minute tool cap;
+                           `none` waits without a cap). On 124 the worker keeps going:
+                           run `harnex result NAME`
+          --detach         Run headless instead of in a tmux window
+          --json           Print the lane record and result as JSON
+          -h, --help       Show this help
+
+        Exit codes: 0 done, 1 failed, 2 usage error, 124 still working.
+
+        Examples:
+          harnex delegate --worktree word-count "Add TextKit.word_count with a test"
+          harnex delegate --no-wait --worktree fix-a "Fix A"   # then: harnex result
+          harnex delegate "Run bin/slow-bench and report the score"
+      TEXT
+    end
+
+    def initialize(argv, out: $stdout, err: $stderr, harnex_command: nil)
+      @argv = argv.dup
+      @out = out
+      @err = err
+      @harnex_command = harnex_command || [Gem.ruby, File.expand_path("../../../bin/harnex", __dir__)]
+      @options = { worktree: nil, name: nil, cwd: nil, file: nil, model: nil, effort: nil, wait: true,
+                   timeout: Lanes::DEFAULT_TIMEOUT, detach: false, json: false, help: false }
+    end
+
+    def run
+      task = parse
+      if @options[:help]
+        @out.puts self.class.usage
+        return 0
+      end
+      task = File.read(@options[:file]) if task.empty? && @options[:file]
+      raise OptionParser::MissingArgument, "TASK (or --file PATH)" if task.strip.empty?
+
+      lane = @lane = build_lane(task)
+      brief = Lanes.write_brief(lane, task)
+      turn, exit_code = Lanes.launch(lane, @harnex_command, context_args: ["--context-file", brief],
+                                                            wait: @options[:wait], timeout: @options[:timeout],
+                                                            detach: @options[:detach])
+      return started(lane) unless @options[:wait]
+
+      lane = Lanes.settle(lane, turn, exit_code)
+      report(lane, turn, exit_code)
+    rescue Lanes::LaunchError => e
+      discard_unstarted
+      @err.puts(e.message)
+      1
+    end
+
+    private
+
+    def build_lane(task)
+      workdir = File.expand_path(@options[:cwd] || Dir.pwd)
+      raise OptionParser::InvalidArgument, "--cwd #{workdir} is not a directory" unless File.directory?(workdir)
+
+      root = Lanes.main_root(workdir)
+      raise OptionParser::InvalidArgument, "--worktree needs a git repository (#{workdir} is not in one)" if @options[:worktree] && root.nil?
+
+      Lanes.sweep_merged(root)
+      root ||= workdir
+      name = Lanes.validate_name!(@options[:worktree] || @options[:name] || Lanes.generate_name(root, task))
+      ensure_free!(root, name)
+      lane = {
+        "name" => name, "kind" => "delegate", "repo_root" => root, "run_root" => root, "cwd" => workdir,
+        "owner" => Harnex.ambient_owner_id, "requested_model" => @options[:model], "effort" => @options[:effort],
+        "created_at" => Lanes.now, "turns" => 0
+      }
+      if @options[:worktree]
+        warn_uncommitted(root)
+        lane["worktree"], lane["branch"], lane["base_sha"] = Lanes.create_worktree(root, name)
+        lane["cwd"] = lane["worktree"]
+      else
+        Harnex.ensure_git_excluded(root) if Lanes.main_root(workdir)
+        lane["base_sha"] = Lanes.head_sha(workdir)
+      end
+      lane
+    end
+
+    # A lane that never started leaves nothing behind.
+    def discard_unstarted
+      return unless @lane && @lane["worktree"] && @lane["turns"].to_i.zero?
+
+      Lanes.remove_worktree(@lane, force: true)
+      @lane["state"] = "discarded"
+      Lanes.save(@lane)
+    end
+
+    def ensure_free!(root, name)
+      existing = Lanes.load(root, name)
+      if Lanes.open?(existing)
+        raise OptionParser::InvalidArgument,
+              "lane #{name} already exists (#{existing['state']}): follow up with `harnex reply #{name} \"...\"`, " \
+              "or `harnex land #{name}` / `harnex discard #{name}` first"
+      end
+      return unless Harnex.read_registry(root, name)
+
+      raise OptionParser::InvalidArgument, "a harnex session named #{name} is running; pick another name"
+    end
+
+    def warn_uncommitted(root)
+      dirty = Lanes.dirty_paths(root)
+      return if dirty.empty?
+
+      @err.puts("harnex delegate: the main checkout has #{dirty.length} uncommitted change(s); " \
+                "the worktree starts from HEAD and won't see them")
+    end
+
+    def started(lane)
+      if @options[:json]
+        @out.puts JSON.generate(lane)
+      else
+        where = lane["worktree"] ? " in #{Lanes.relative(lane['repo_root'], lane['worktree'])}" : ""
+        @out.puts "── #{lane['name']}: started#{where}"
+        @out.puts "   collect: harnex result #{lane['name']}   (or `harnex result` for all your lanes)"
+      end
+      0
+    end
+
+    def report(lane, turn, exit_code)
+      if @options[:json]
+        @out.puts JSON.generate(lane: lane, result: turn, exit_code: exit_code)
+      else
+        @out.puts Lanes.render(lane, turn, exit_code)
+      end
+      exit_code
+    end
+
+    def parse
+      task = []
+      index = 0
+      while index < @argv.length
+        arg = @argv[index]
+        case arg
+        when "--"
+          task.concat(@argv[(index + 1)..] || [])
+          break
+        when "-h", "--help" then @options[:help] = true
+        when "--no-wait" then @options[:wait] = false
+        when "--detach" then @options[:detach] = true
+        when "--json" then @options[:json] = true
+        when "--worktree", "--name", "--cwd", "--file", "--model", "--effort"
+          @options[arg.delete_prefix("--").to_sym] = value(index += 1, arg)
+        when "--timeout", "--wait-timeout"
+          @options[:timeout] = Lanes.parse_timeout(value(index += 1, arg))
+        # Habits from `harnex run`: a lane already runs in a tmux window named
+        # after it, stops after its reply and waits for it, so these are
+        # accepted rather than refused.
+        when "--id" then @options[:name] = value(index += 1, arg)
+        when "--tmux" then index += 1 if lane_name_follows?(index) && (@options[:name] ||= @argv[index + 1])
+        when "--auto-stop", "--wait-done" then nil
+        when "--context" then task << value(index += 1, arg)
+        when "--context-file" then @options[:file] = value(index += 1, arg)
+        when /\A--/
+          raise OptionParser::InvalidOption, "harnex delegate: unknown flag #{arg}; see harnex delegate --help"
+        else
+          task << arg
+        end
+        index += 1
+      end
+      task.join(" ")
+    end
+
+    def lane_name_follows?(index)
+      following = @argv[index + 1]
+      !following.nil? && following.match?(Lanes::NAME) && !following.start_with?("-")
+    end
+
+    def value(index, name)
+      value = @argv[index]
+      raise OptionParser::MissingArgument, name if value.nil? || value.start_with?("--")
+
+      value
+    end
+  end
+end